Genarrative/packages/shared/src/contracts/puzzleRuntimeSession.ts

import type { CreationAudioAsset } from './creationAudio';

export type PuzzleGridSize = 3 | 4 | 5 | 6 | 7;

export interface PuzzleCellPosition {
  row: number;
  col: number;
}

export interface PuzzlePieceState {
  pieceId: string;
  correctRow: number;
  correctCol: number;
  currentRow: number;
  currentCol: number;
  mergedGroupId: string | null;
}

export interface PuzzleMergedGroupState {
  groupId: string;
  pieceIds: string[];
  occupiedCells: PuzzleCellPosition[];
}

export interface PuzzleLeaderboardEntry {
  rank: number;
  nickname: string;
  elapsedMs: number;
  visibleTags?: string[];
  isCurrentPlayer?: boolean;
}

export type PuzzleRuntimeLevelStatus = 'playing' | 'cleared' | 'failed';

export type PuzzleRuntimePropKind =
  | 'hint'
  | 'reference'
  | 'freezeTime'
  | 'extendTime';

export interface PuzzleBoardSnapshot {
  rows: number;
  cols: number;
  pieces: PuzzlePieceState[];
  mergedGroups: PuzzleMergedGroupState[];
  selectedPieceId: string | null;
  allTilesResolved: boolean;
}

export interface PuzzleRuntimeLevelSnapshot {
  runId: string;
  levelIndex: number;
  levelId: string | null;
  gridSize: PuzzleGridSize;
  profileId: string;
  levelName: string;
  authorDisplayName: string;
  themeTags: string[];
  coverImageSrc: string | null;
  uiBackgroundImageSrc?: string | null;
  uiBackgroundImageObjectKey?: string | null;
  backgroundMusic?: CreationAudioAsset | null;
  board: PuzzleBoardSnapshot;
  status: PuzzleRuntimeLevelStatus;
  startedAtMs: number;
  clearedAtMs: number | null;
  elapsedMs: number | null;
  timeLimitMs: number;
  remainingMs: number;
  pausedAccumulatedMs: number;
  pauseStartedAtMs: number | null;
  freezeAccumulatedMs: number;
  freezeStartedAtMs: number | null;
  freezeUntilMs: number | null;
  leaderboardEntries: PuzzleLeaderboardEntry[];
}

export type PuzzleNextLevelMode = 'sameWork' | 'similarWorks' | 'none';

export interface PuzzleRecommendedNextWork {
  profileId: string;
  levelName: string;
  authorDisplayName: string;
  themeTags: string[];
  coverImageSrc: string | null;
  similarityScore: number;
}

export interface PuzzleRunSnapshot {
  runId: string;
  entryProfileId: string;
  clearedLevelCount: number;
  currentLevelIndex: number;
  currentGridSize: PuzzleGridSize;
  playedProfileIds: string[];
  previousLevelTags: string[];
  currentLevel: PuzzleRuntimeLevelSnapshot | null;
  recommendedNextProfileId: string | null;
  nextLevelMode?: PuzzleNextLevelMode;
  nextLevelProfileId?: string | null;
  nextLevelId?: string | null;
  recommendedNextWorks?: PuzzleRecommendedNextWork[];
  leaderboardEntries: PuzzleLeaderboardEntry[];
}

export interface StartPuzzleRunRequest {
  profileId: string;
  levelId?: string | null;
}

export interface PuzzleRunResponse {
  run: PuzzleRunSnapshot;
}

export interface SubmitPuzzleLeaderboardRequest {
  profileId: string;
  gridSize: PuzzleGridSize;
  elapsedMs: number;
  nickname: string;
}

export interface SwapPuzzlePiecesRequest {
  firstPieceId: string;
  secondPieceId: string;
}

export interface DragPuzzlePieceRequest {
  pieceId: string;
  targetRow: number;
  targetCol: number;
}

export interface AdvancePuzzleNextLevelRequest {
  targetProfileId?: string | null;
}

export interface UsePuzzleRuntimePropRequest {
  propKind: PuzzleRuntimePropKind;
}

export interface UpdatePuzzleRuntimePauseRequest {
  paused: boolean;
}