1

packages/shared/src/contracts/puzzleAgentActions.ts

@@ -43,6 +43,7 @@ export type PuzzleAgentActionRequest =
   | {
       action: 'generate_puzzle_images';
       promptText?: string | null;
+      referenceImageSrc?: string | null;
       candidateCount?: number;
     }
   | {

packages/shared/src/contracts/puzzleRuntimeSession.ts

@@ -20,6 +20,13 @@ export interface PuzzleMergedGroupState {
   occupiedCells: PuzzleCellPosition[];
 }
 
+export interface PuzzleLeaderboardEntry {
+  rank: number;
+  nickname: string;
+  elapsedMs: number;
+  isCurrentPlayer?: boolean;
+}
+
 export interface PuzzleBoardSnapshot {
   rows: number;
   cols: number;
@@ -40,6 +47,10 @@ export interface PuzzleRuntimeLevelSnapshot {
   coverImageSrc: string | null;
   board: PuzzleBoardSnapshot;
   status: 'playing' | 'cleared';
+  startedAtMs: number;
+  clearedAtMs: number | null;
+  elapsedMs: number | null;
+  leaderboardEntries: PuzzleLeaderboardEntry[];
 }
 
 export interface PuzzleRunSnapshot {
@@ -52,6 +63,7 @@ export interface PuzzleRunSnapshot {
   previousLevelTags: string[];
   currentLevel: PuzzleRuntimeLevelSnapshot | null;
   recommendedNextProfileId: string | null;
+  leaderboardEntries: PuzzleLeaderboardEntry[];
 }
 
 export interface StartPuzzleRunRequest {