@sudobility/sudojo_lib 0.0.201 → 0.0.203

package/dist/hooks/usePuzzleProgress.js

@@ -0,0 +1,48 @@
+/**
+ * Hook for the player's puzzle progress (completed puzzles, streak, stats),
+ * persisted in localStorage under PROGRESS_STORAGE_KEY.
+ *
+ * The web ProgressProvider's logic. RN does not track progress today; where
+ * it shims localStorage (as it does for the game store) the hook works there
+ * too.
+ */
+import { useCallback, useMemo } from 'react';
+import { DEFAULT_PROGRESS, PROGRESS_STORAGE_KEY } from '../types/progress';
+import { applyPuzzleCompletion, getCompletedDailyDates, getCompletedLevelIds, isPuzzleCompleted, } from '../utils/progress';
+import { useLocalStorage } from './useLocalStorage';
+/**
+ * @example
+ * ```tsx
+ * const { markCompleted, isCompleted } = usePuzzleProgress();
+ * markCompleted({ type: 'daily', id: '2026-10-05', timeSeconds: 312 });
+ * ```
+ */
+export function usePuzzleProgress(options = {}) {
+    const { storageKey = PROGRESS_STORAGE_KEY } = options;
+    const [progress, setProgress] = useLocalStorage(storageKey, DEFAULT_PROGRESS);
+    const markCompleted = useCallback((puzzle) => {
+        setProgress(prev => applyPuzzleCompletion(prev, puzzle));
+    }, [setProgress]);
+    const isCompleted = useCallback((type, id) => isPuzzleCompleted(progress.completedPuzzles, type, id), [progress.completedPuzzles]);
+    const getLevelIds = useCallback(() => getCompletedLevelIds(progress.completedPuzzles), [progress.completedPuzzles]);
+    const getDailyDates = useCallback(() => getCompletedDailyDates(progress.completedPuzzles), [progress.completedPuzzles]);
+    const resetProgress = useCallback(() => {
+        setProgress(DEFAULT_PROGRESS);
+    }, [setProgress]);
+    return useMemo(() => ({
+        progress,
+        markCompleted,
+        isCompleted,
+        getCompletedLevelIds: getLevelIds,
+        getCompletedDailyDates: getDailyDates,
+        resetProgress,
+    }), [
+        progress,
+        markCompleted,
+        isCompleted,
+        getLevelIds,
+        getDailyDates,
+        resetProgress,
+    ]);
+}
+//# sourceMappingURL=usePuzzleProgress.js.map

package/dist/hooks/usePuzzleProgress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePuzzleProgress.js","sourceRoot":"","sources":["../../src/hooks/usePuzzleProgress.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAE7C,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,GAElB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAsBpD;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,UAAoC,EAAE;IAEtC,MAAM,EAAE,UAAU,GAAG,oBAAoB,EAAE,GAAG,OAAO,CAAC;IACtD,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,eAAe,CAC7C,UAAU,EACV,gBAAgB,CACjB,CAAC;IAEF,MAAM,aAAa,GAAG,WAAW,CAC/B,CAAC,MAAwB,EAAE,EAAE;QAC3B,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,qBAAqB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3D,CAAC,EACD,CAAC,WAAW,CAAC,CACd,CAAC;IAEF,MAAM,WAAW,GAAG,WAAW,CAC7B,CAAC,IAAuB,EAAE,EAAU,EAAE,EAAE,CACtC,iBAAiB,CAAC,QAAQ,CAAC,gBAAgB,EAAE,IAAI,EAAE,EAAE,CAAC,EACxD,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAC5B,CAAC;IAEF,MAAM,WAAW,GAAG,WAAW,CAC7B,GAAG,EAAE,CAAC,oBAAoB,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EACrD,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAC5B,CAAC;IAEF,MAAM,aAAa,GAAG,WAAW,CAC/B,GAAG,EAAE,CAAC,sBAAsB,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EACvD,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAC5B,CAAC;IAEF,MAAM,aAAa,GAAG,WAAW,CAAC,GAAG,EAAE;QACrC,WAAW,CAAC,gBAAgB,CAAC,CAAC;IAChC,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;IAElB,OAAO,OAAO,CACZ,GAAG,EAAE,CAAC,CAAC;QACL,QAAQ;QACR,aAAa;QACb,WAAW;QACX,oBAAoB,EAAE,WAAW;QACjC,sBAAsB,EAAE,aAAa;QACrC,aAAa;KACd,CAAC,EACF;QACE,QAAQ;QACR,aAAa;QACb,WAAW;QACX,WAAW;QACX,aAAa;QACb,aAAa;KACd,CACF,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Hook for the player's puzzle progress (completed puzzles, streak, stats),\n * persisted in localStorage under PROGRESS_STORAGE_KEY.\n *\n * The web ProgressProvider's logic. RN does not track progress today; where\n * it shims localStorage (as it does for the game store) the hook works there\n * too.\n */\n\nimport { useCallback, useMemo } from 'react';\nimport type { UserProgress } from '../types/progress';\nimport { DEFAULT_PROGRESS, PROGRESS_STORAGE_KEY } from '../types/progress';\nimport {\n  applyPuzzleCompletion,\n  getCompletedDailyDates,\n  getCompletedLevelIds,\n  isPuzzleCompleted,\n  type PuzzleCompletion,\n} from '../utils/progress';\nimport { useLocalStorage } from './useLocalStorage';\n\nexport interface UsePuzzleProgressOptions {\n  /** localStorage key (default PROGRESS_STORAGE_KEY, 'sudojo-progress') */\n  storageKey?: string;\n}\n\nexport interface UsePuzzleProgressResult {\n  /** The stored progress */\n  progress: UserProgress;\n  /** Record a completion (no-op when the puzzle is already completed) */\n  markCompleted: (puzzle: PuzzleCompletion) => void;\n  /** Whether a puzzle has been completed */\n  isCompleted: (type: 'daily' | 'level', id: string) => boolean;\n  /** Ids of completed level puzzles */\n  getCompletedLevelIds: () => string[];\n  /** Dates (YYYY-MM-DD) of completed dailies */\n  getCompletedDailyDates: () => string[];\n  /** Reset to DEFAULT_PROGRESS */\n  resetProgress: () => void;\n}\n\n/**\n * @example\n * ```tsx\n * const { markCompleted, isCompleted } = usePuzzleProgress();\n * markCompleted({ type: 'daily', id: '2026-10-05', timeSeconds: 312 });\n * ```\n */\nexport function usePuzzleProgress(\n  options: UsePuzzleProgressOptions = {}\n): UsePuzzleProgressResult {\n  const { storageKey = PROGRESS_STORAGE_KEY } = options;\n  const [progress, setProgress] = useLocalStorage<UserProgress>(\n    storageKey,\n    DEFAULT_PROGRESS\n  );\n\n  const markCompleted = useCallback(\n    (puzzle: PuzzleCompletion) => {\n      setProgress(prev => applyPuzzleCompletion(prev, puzzle));\n    },\n    [setProgress]\n  );\n\n  const isCompleted = useCallback(\n    (type: 'daily' | 'level', id: string) =>\n      isPuzzleCompleted(progress.completedPuzzles, type, id),\n    [progress.completedPuzzles]\n  );\n\n  const getLevelIds = useCallback(\n    () => getCompletedLevelIds(progress.completedPuzzles),\n    [progress.completedPuzzles]\n  );\n\n  const getDailyDates = useCallback(\n    () => getCompletedDailyDates(progress.completedPuzzles),\n    [progress.completedPuzzles]\n  );\n\n  const resetProgress = useCallback(() => {\n    setProgress(DEFAULT_PROGRESS);\n  }, [setProgress]);\n\n  return useMemo(\n    () => ({\n      progress,\n      markCompleted,\n      isCompleted,\n      getCompletedLevelIds: getLevelIds,\n      getCompletedDailyDates: getDailyDates,\n      resetProgress,\n    }),\n    [\n      progress,\n      markCompleted,\n      isCompleted,\n      getLevelIds,\n      getDailyDates,\n      resetProgress,\n    ]\n  );\n}\n"]}

package/dist/hooks/usePuzzleSession.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Game session orchestration for the Daily and Level play screens.
+ *
+ * Combines the saved-game store (useGamePlay), the resume decision
+ * (useResumeGame) and server gamification (useGameSession) into what a play
+ * screen renders: which puzzle to show and how (fresh and scrambled, or
+ * resumed with its saved input), when to save the game and start the server
+ * session, and what to do on completion (clear the save, finish the session,
+ * show achievements, record progress). Platform-neutral: no router, no
+ * dialogs.
+ */
+import type { GameFetchStatus } from '../utils/gameFetchStatus';
+import type { SudojoApiOptions } from '../context/SudojoApiContext';
+import type { CurrentGame } from '../types/currentGame';
+import { type AuthUser } from '../utils/auth';
+import type { PuzzleCompletion } from '../utils/progress';
+import { type GameFinishResult } from './useGameSession';
+import { type PuzzleSessionSource, type UseResumeGameResult } from './useResumeGame';
+/** The fetched puzzle a session plays: a Daily or a Board from the API. */
+export interface SessionPuzzleInput {
+    uuid: string;
+    /** 81-char puzzle */
+    board: string;
+    /** 81-char solution */
+    solution: string;
+    level?: number | null;
+    techniques?: number | null;
+    techniques_bitmask?: string | null;
+    difficulty_score?: number | null;
+    /** A daily's date (YYYY-MM-DD) */
+    date?: string | null;
+}
+/** The puzzle the screen shows (fetched, or rebuilt from the saved game). */
+export interface ActivePuzzle {
+    /** Board/daily uuid (for a resumed game: its boardUuid, else startedAt) */
+    uuid: string;
+    /** 81-char puzzle (a resumed game's is already scrambled) */
+    puzzle: string;
+    /** 81-char solution */
+    solution: string;
+    /** Difficulty level (1-12), when known */
+    level: number | null;
+    /** Solver difficulty score, when known */
+    difficultyScore: number | null;
+    /** A daily's date (YYYY-MM-DD) */
+    dailyDate: string | null;
+    /** Lossy techniques bitmask */
+    techniques: number | null;
+    /** Exact techniques bitmask (base-10 string) */
+    techniques_bitmask: string | null;
+}
+/** Props for the game component (SudokuGame) of either app. */
+export interface PuzzleGameProps {
+    puzzle: string;
+    solution: string;
+    /** false when resuming (the saved puzzle is already scrambled) */
+    scramble: boolean;
+    initialInput?: string | undefined;
+    initialPencilmarks?: string | undefined;
+    initialElapsedTime?: number | undefined;
+    initialAutoPencilmarks?: boolean | undefined;
+}
+export interface UsePuzzleSessionOptions extends SudojoApiOptions {
+    /** 'daily' or 'level' */
+    source: PuzzleSessionSource;
+    /** Level screens: the level number (1-12) */
+    levelNumber?: number | null | undefined;
+    /** Level screens: the level's title (saved in meta for "Continue") */
+    levelTitle?: string | null | undefined;
+    /**
+     * The fetched puzzle (useDailyGame's `daily` / useLevelGame's `board`), or
+     * null while loading. Ignored while resuming.
+     */
+    puzzle: SessionPuzzleInput | null | undefined;
+    /** Dailies: useDailyGame's `dailyDate` (default: the puzzle's `date`) */
+    dailyDate?: string | null | undefined;
+    /** The fetch hook's status (default 'loading' until a puzzle arrives) */
+    fetchStatus?: GameFetchStatus | undefined;
+    /** The signed-in user: server sessions run only for a real (non-anonymous) user */
+    user?: AuthUser | null | undefined;
+    /** The resume decision from useResumeGame (default: computed here) */
+    resume?: UseResumeGameResult | undefined;
+    /** Forwarded to the internal useResumeGame when `resume` is not passed */
+    isStoreHydrated?: boolean | undefined;
+    /** Forwarded to the internal useResumeGame (default true) */
+    clearStaleDaily?: boolean | undefined;
+    /**
+     * Whether a puzzle was already completed (progress). A completed daily is
+     * not saved, started on the server, or recorded again (web DailyPage).
+     */
+    isPuzzleCompleted?: (type: 'daily' | 'level', id: string) => boolean;
+    /** Record a completion in the player's progress (web markCompleted) */
+    onPuzzleCompleted?: (completion: PuzzleCompletion) => void;
+    /**
+     * Start a server session for a resumed game too (RN DailyScreen did; the web
+     * does not). Default false: the session from when the game was started is
+     * still the server's active one, and restarting it resets its clock.
+     */
+    startSessionOnResume?: boolean;
+    /**
+     * Show the achievement modal even when nothing was earned (RN did).
+     * Default false (web: only on level-up, new badges or points).
+     */
+    showEmptyAchievement?: boolean;
+}
+export interface UsePuzzleSessionResult {
+    /**
+     * 'success' once a puzzle is pinned or resumed; otherwise the fetch status
+     * ('loading' until the store is ready and while a fetched puzzle is not
+     * pinned yet)
+     */
+    status: GameFetchStatus;
+    /** Whether the resume decision is made (store hydrated) */
+    isReady: boolean;
+    /** Whether the screen resumes a saved game */
+    isResuming: boolean;
+    /** The saved game being resumed, or null */
+    resumeGame: CurrentGame | null;
+    /** The puzzle to show (pinned once loaded), or null */
+    activePuzzle: ActivePuzzle | null;
+    /**
+     * Props for the game component, or null while there is no puzzle. Render
+     * it with `key={gameKey}` so a new puzzle remounts the game.
+     */
+    gameProps: PuzzleGameProps | null;
+    /** Remount key for the game component (the puzzle's uuid), or null */
+    gameKey: string | null;
+    /** The puzzle's progress id: the daily date, or the board uuid */
+    puzzleId: string | null;
+    /** Whether this puzzle was already completed (isPuzzleCompleted) */
+    alreadyCompleted: boolean;
+    /** Whether server gamification is active (real user with a token) */
+    isAuthenticated: boolean;
+    /** Web SudokuGame's onScrambledReady: saves the fresh game and starts the session */
+    onScrambledReady: (scrambled: {
+        puzzle: string;
+        solution: string;
+    }) => void;
+    /** RN SudokuGame's onBoardReady: same as onScrambledReady */
+    onBoardReady: (scrambledPuzzle: string, scrambledSolution: string) => void;
+    /** The game's onProgressUpdate: saves progress (throttled) */
+    onProgress: (inputString: string, pencilmarksString: string, isPencilMode: boolean, autoPencilmarks: boolean, elapsedTime: number) => void;
+    /**
+     * The game's onComplete: clears the save, finishes the server session
+     * (sets the achievement state), records progress. Resolves to the finish
+     * result (null when not authenticated).
+     */
+    onComplete: (timeSeconds: number) => Promise<GameFinishResult | null>;
+    /**
+     * Abandon the current puzzle: clear the save, stop resuming, unpin. Call the
+     * fetch hook's nextPuzzle()/refetch() too; the old puzzle is not pinned again.
+     */
+    newGame: () => void;
+    /** Achievement result to show, or null */
+    achievementResult: GameFinishResult | null;
+    /** Whether the achievement modal is open */
+    showAchievement: boolean;
+    /** Close the achievement modal */
+    closeAchievement: () => void;
+}
+/**
+ * Orchestrate a Daily or Level play screen.
+ *
+ * Behavior (web DailyPage / LevelPlayPage, with RN's stale-daily rule):
+ * - Resume: a saved game for this screen (see getResumeGame) is shown with
+ *   `scramble: false` and its saved input, pencilmarks, time and auto-pencil.
+ *   A saved daily from another (UTC) day is cleared, not resumed.
+ * - Fresh puzzle: pinned once loaded (refetches cannot unmount the game).
+ *   When the game reports its scrambled board (onScrambledReady /
+ *   onBoardReady) the game is saved once per puzzle uuid with meta (dailyDate
+ *   or levelId/levelTitle, boardUuid, level, difficultyScore, techniques +
+ *   exact techniques_bitmask), and a server session is started once per uuid
+ *   for a real user (a daily only when it has a level). A daily already in
+ *   progress is skipped.
+ * - Completion: clear the save, finish the server session (authenticated),
+ *   open the achievement modal when something was earned, then record
+ *   progress (`onPuzzleCompleted`, not again for a completed daily).
+ *
+ * @example Daily
+ * ```tsx
+ * const resume = useResumeGame({ source: 'daily' });
+ * const { daily, dailyDate, status, refetch } = useDailyGame({ enabled: resume.isReady && !resume.resumeGame });
+ * const { markCompleted, isCompleted } = usePuzzleProgress();
+ * const session = usePuzzleSession({
+ *   source: 'daily', resume, puzzle: daily, dailyDate, fetchStatus: status, user,
+ *   isPuzzleCompleted: isCompleted, onPuzzleCompleted: markCompleted,
+ * });
+ * if (session.status === 'auth_required') return <SignInGate />;
+ * return session.gameProps && (
+ *   <>
+ *     <SudokuGame key={session.gameKey} {...session.gameProps} onScrambledReady={session.onScrambledReady}
+ *       onProgressUpdate={session.onProgress} onComplete={session.onComplete} />
+ *     <AchievementModal show={session.showAchievement} onClose={session.closeAchievement}
+ *       {...session.achievementResult} />
+ *   </>
+ * );
+ * ```
+ *
+ * @example LevelPlay
+ * ```tsx
+ * const resume = useResumeGame({ source: 'level', levelNumber });
+ * const { board, status, nextPuzzle } = useLevelGame({
+ *   level: levelNumber, symmetrical, userEntitlements, levelEntitlement,
+ *   enabled: resume.isReady && !resume.resumeGame,
+ * });
+ * const session = usePuzzleSession({
+ *   source: 'level', levelNumber, levelTitle: level?.title, resume,
+ *   puzzle: board, fetchStatus: status, user, onPuzzleCompleted: markCompleted,
+ * });
+ * const onNewGame = () => { session.newGame(); nextPuzzle(); };
+ * // RN: <SudokuGame key={session.gameKey} {...session.gameProps} onBoardReady={session.onBoardReady} ... />
+ * ```
+ */
+export declare function usePuzzleSession(options: UsePuzzleSessionOptions): UsePuzzleSessionResult;
+//# sourceMappingURL=usePuzzleSession.d.ts.map

package/dist/hooks/usePuzzleSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePuzzleSession.d.ts","sourceRoot":"","sources":["../../src/hooks/usePuzzleSession.ts"],"names":[],"mappings":"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"}

package/dist/hooks/usePuzzleSession.js

@@ -0,0 +1,358 @@
+/**
+ * Game session orchestration for the Daily and Level play screens.
+ *
+ * Combines the saved-game store (useGamePlay), the resume decision
+ * (useResumeGame) and server gamification (useGameSession) into what a play
+ * screen renders: which puzzle to show and how (fresh and scrambled, or
+ * resumed with its saved input), when to save the game and start the server
+ * session, and what to do on completion (clear the save, finish the session,
+ * show achievements, record progress). Platform-neutral: no router, no
+ * dialogs.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useResolvedSudojoApi } from '../context/SudojoApiContext';
+import { isRealUser } from '../utils/auth';
+import { techniqueBitmaskString, techniqueFieldsOf, } from '../utils/techniqueBitmask';
+import { useGameSession } from './useGameSession';
+import { useGamePlay } from './useGamePlay';
+import { useResumeGame, } from './useResumeGame';
+function hasAchievement(result) {
+    return (result.leveledUp ||
+        result.newBadges.length > 0 ||
+        result.totalPointsEarned > 0);
+}
+function puzzleFromResume(game, source, levelNumber) {
+    const meta = game.meta;
+    return {
+        uuid: meta.boardUuid ?? game.startedAt ?? game.updatedAt ?? 'resume',
+        puzzle: game.puzzle,
+        solution: game.solution,
+        level: meta.level ?? (source === 'level' ? (levelNumber ?? null) : null),
+        difficultyScore: meta.difficultyScore ?? null,
+        dailyDate: meta.dailyDate ?? null,
+        ...techniqueFieldsOf(meta),
+    };
+}
+function puzzleFromFetch(input, source, levelNumber, dailyDate) {
+    return {
+        uuid: input.uuid,
+        puzzle: input.board,
+        solution: input.solution,
+        level: input.level ?? (source === 'level' ? (levelNumber ?? null) : null),
+        difficultyScore: input.difficulty_score ?? null,
+        dailyDate: source === 'daily' ? (dailyDate ?? input.date ?? null) : null,
+        ...techniqueFieldsOf(input),
+    };
+}
+/**
+ * Orchestrate a Daily or Level play screen.
+ *
+ * Behavior (web DailyPage / LevelPlayPage, with RN's stale-daily rule):
+ * - Resume: a saved game for this screen (see getResumeGame) is shown with
+ *   `scramble: false` and its saved input, pencilmarks, time and auto-pencil.
+ *   A saved daily from another (UTC) day is cleared, not resumed.
+ * - Fresh puzzle: pinned once loaded (refetches cannot unmount the game).
+ *   When the game reports its scrambled board (onScrambledReady /
+ *   onBoardReady) the game is saved once per puzzle uuid with meta (dailyDate
+ *   or levelId/levelTitle, boardUuid, level, difficultyScore, techniques +
+ *   exact techniques_bitmask), and a server session is started once per uuid
+ *   for a real user (a daily only when it has a level). A daily already in
+ *   progress is skipped.
+ * - Completion: clear the save, finish the server session (authenticated),
+ *   open the achievement modal when something was earned, then record
+ *   progress (`onPuzzleCompleted`, not again for a completed daily).
+ *
+ * @example Daily
+ * ```tsx
+ * const resume = useResumeGame({ source: 'daily' });
+ * const { daily, dailyDate, status, refetch } = useDailyGame({ enabled: resume.isReady && !resume.resumeGame });
+ * const { markCompleted, isCompleted } = usePuzzleProgress();
+ * const session = usePuzzleSession({
+ *   source: 'daily', resume, puzzle: daily, dailyDate, fetchStatus: status, user,
+ *   isPuzzleCompleted: isCompleted, onPuzzleCompleted: markCompleted,
+ * });
+ * if (session.status === 'auth_required') return <SignInGate />;
+ * return session.gameProps && (
+ *   <>
+ *     <SudokuGame key={session.gameKey} {...session.gameProps} onScrambledReady={session.onScrambledReady}
+ *       onProgressUpdate={session.onProgress} onComplete={session.onComplete} />
+ *     <AchievementModal show={session.showAchievement} onClose={session.closeAchievement}
+ *       {...session.achievementResult} />
+ *   </>
+ * );
+ * ```
+ *
+ * @example LevelPlay
+ * ```tsx
+ * const resume = useResumeGame({ source: 'level', levelNumber });
+ * const { board, status, nextPuzzle } = useLevelGame({
+ *   level: levelNumber, symmetrical, userEntitlements, levelEntitlement,
+ *   enabled: resume.isReady && !resume.resumeGame,
+ * });
+ * const session = usePuzzleSession({
+ *   source: 'level', levelNumber, levelTitle: level?.title, resume,
+ *   puzzle: board, fetchStatus: status, user, onPuzzleCompleted: markCompleted,
+ * });
+ * const onNewGame = () => { session.newGame(); nextPuzzle(); };
+ * // RN: <SudokuGame key={session.gameKey} {...session.gameProps} onBoardReady={session.onBoardReady} ... />
+ * ```
+ */
+export function usePuzzleSession(options) {
+    const { source, levelNumber, levelTitle, puzzle: fetched, dailyDate: fetchedDailyDate, fetchStatus, user, isPuzzleCompleted, onPuzzleCompleted, startSessionOnResume = false, showEmptyAchievement = false, } = options;
+    const api = useResolvedSudojoApi(options, 'usePuzzleSession');
+    const slot = source === 'daily' ? 'daily' : 'play';
+    const internalResume = useResumeGame({
+        source,
+        levelNumber,
+        slot,
+        ...(options.clearStaleDaily !== undefined && {
+            clearStaleDaily: options.clearStaleDaily,
+        }),
+        ...(options.isStoreHydrated !== undefined && {
+            isStoreHydrated: options.isStoreHydrated,
+        }),
+    });
+    const resume = options.resume ?? internalResume;
+    const resumeGame = resume.resumeGame;
+    const isResuming = resumeGame !== null;
+    const { startGame, updateProgress, clearGame } = useGamePlay({ slot });
+    const { startSession, finishSession, isAuthenticated } = useGameSession({
+        networkClient: api.networkClient,
+        baseUrl: api.baseUrl,
+        token: api.token,
+        userId: isRealUser(user) && user ? user.uid : null,
+    });
+    // --- Pinned fresh puzzle -------------------------------------------------
+    const screenKey = `${source}|${levelNumber ?? ''}`;
+    const [pinned, setPinned] = useState(null);
+    const excludedUuidRef = useRef(null);
+    const fetchedPuzzle = useMemo(() => fetched && fetched.board?.length === 81 && fetched.solution?.length === 81
+        ? puzzleFromFetch(fetched, source, levelNumber, fetchedDailyDate)
+        : null, [fetched, source, levelNumber, fetchedDailyDate]);
+    useEffect(() => {
+        if (isResuming || !fetchedPuzzle)
+            return;
+        if (fetchStatus !== undefined && fetchStatus !== 'success')
+            return;
+        if (pinned?.key === screenKey)
+            return;
+        if (excludedUuidRef.current === fetchedPuzzle.uuid)
+            return;
+        excludedUuidRef.current = null;
+        setPinned({ key: screenKey, puzzle: fetchedPuzzle });
+    }, [isResuming, fetchedPuzzle, fetchStatus, pinned, screenKey]);
+    const resumedPuzzle = useMemo(() => resumeGame ? puzzleFromResume(resumeGame, source, levelNumber) : null, [resumeGame, source, levelNumber]);
+    const activePuzzle = resumedPuzzle ?? (pinned?.key === screenKey ? pinned.puzzle : null);
+    // 'success' only with a puzzle to show: a fetched puzzle that is not
+    // pinned yet (or was abandoned by newGame) still reads as loading.
+    const status = !resume.isReady || (!activePuzzle && fetchStatus === 'success')
+        ? 'loading'
+        : activePuzzle
+            ? 'success'
+            : (fetchStatus ?? 'loading');
+    const puzzleId = source === 'daily'
+        ? (activePuzzle?.dailyDate ?? null)
+        : (activePuzzle?.uuid ?? null);
+    const alreadyCompleted = source === 'daily' && puzzleId !== null
+        ? (isPuzzleCompleted?.('daily', puzzleId) ?? false)
+        : false;
+    // --- Save the fresh game and start the server session -------------------
+    const [scrambled, setScrambled] = useState(null);
+    const activeUuid = activePuzzle?.uuid ?? null;
+    const onScrambledReady = useCallback((data) => {
+        if (!activeUuid)
+            return;
+        if (data.puzzle.length !== 81 || data.solution.length !== 81)
+            return;
+        setScrambled(prev => prev?.uuid === activeUuid &&
+            prev.puzzle === data.puzzle &&
+            prev.solution === data.solution
+            ? prev
+            : { uuid: activeUuid, ...data });
+    }, [activeUuid]);
+    const onBoardReady = useCallback((scrambledPuzzle, scrambledSolution) => {
+        onScrambledReady({
+            puzzle: scrambledPuzzle,
+            solution: scrambledSolution,
+        });
+    }, [onScrambledReady]);
+    const startedGameRef = useRef('');
+    const startedSessionRef = useRef('');
+    useEffect(() => {
+        startedGameRef.current = '';
+        startedSessionRef.current = '';
+    }, [activeUuid, screenKey]);
+    const sessionRequest = useCallback((p, board, solution) => {
+        const level = source === 'level' ? (levelNumber ?? p.level) : p.level;
+        if (!level)
+            return null;
+        const request = {
+            board,
+            solution,
+            level,
+            techniques: techniqueBitmaskString(p),
+            puzzleType: source,
+        };
+        const id = source === 'daily' ? p.dailyDate : p.uuid;
+        if (id)
+            request.puzzleId = id;
+        return request;
+    }, [source, levelNumber]);
+    useEffect(() => {
+        if (!activePuzzle || status !== 'success')
+            return;
+        const uuid = activePuzzle.uuid;
+        if (isResuming) {
+            // Optional (RN): restart the server session for a resumed game.
+            if (startSessionOnResume &&
+                isAuthenticated &&
+                startedSessionRef.current !== uuid) {
+                const request = sessionRequest(activePuzzle, activePuzzle.puzzle, activePuzzle.solution);
+                if (request) {
+                    startedSessionRef.current = uuid;
+                    void startSession(request);
+                }
+            }
+            return;
+        }
+        if (!scrambled || scrambled.uuid !== uuid)
+            return;
+        if (source === 'daily' && (!activePuzzle.dailyDate || alreadyCompleted)) {
+            return;
+        }
+        if (source === 'level' && levelNumber == null)
+            return;
+        if (startedGameRef.current === uuid)
+            return;
+        startedGameRef.current = uuid;
+        const meta = {
+            boardUuid: uuid,
+            ...techniqueFieldsOf(activePuzzle),
+        };
+        if (source === 'daily' && activePuzzle.dailyDate) {
+            meta.dailyDate = activePuzzle.dailyDate;
+        }
+        if (source === 'level') {
+            meta.levelId = String(levelNumber);
+            if (levelTitle)
+                meta.levelTitle = levelTitle;
+        }
+        if (activePuzzle.level !== null)
+            meta.level = activePuzzle.level;
+        if (activePuzzle.difficultyScore !== null) {
+            meta.difficultyScore = activePuzzle.difficultyScore;
+        }
+        startGame(source, {
+            original: scrambled.puzzle,
+            user: scrambled.puzzle,
+            pencilmark: { numbers: '', autopencil: false },
+        }, scrambled.solution, meta);
+        if (isAuthenticated && startedSessionRef.current !== uuid) {
+            // The server session gets the board as played (scrambled): hints send
+            // that board as `original`, and the API credits a hint to the session
+            // only when the two match exactly.
+            const request = sessionRequest(activePuzzle, scrambled.puzzle, scrambled.solution);
+            if (request) {
+                startedSessionRef.current = uuid;
+                void startSession(request);
+            }
+        }
+    }, [
+        activePuzzle,
+        status,
+        isResuming,
+        scrambled,
+        source,
+        levelNumber,
+        levelTitle,
+        alreadyCompleted,
+        isAuthenticated,
+        startSessionOnResume,
+        startGame,
+        startSession,
+        sessionRequest,
+    ]);
+    // --- Completion ----------------------------------------------------------
+    const [achievementResult, setAchievementResult] = useState(null);
+    const [showAchievement, setShowAchievement] = useState(false);
+    const onComplete = useCallback(async (timeSeconds) => {
+        clearGame();
+        let result = null;
+        if (isAuthenticated) {
+            result = await finishSession(timeSeconds);
+            if (showEmptyAchievement || hasAchievement(result)) {
+                setAchievementResult(result);
+                setShowAchievement(true);
+            }
+        }
+        if (puzzleId && onPuzzleCompleted && !alreadyCompleted) {
+            onPuzzleCompleted({ type: source, id: puzzleId, timeSeconds });
+        }
+        return result;
+    }, [
+        clearGame,
+        isAuthenticated,
+        finishSession,
+        showEmptyAchievement,
+        puzzleId,
+        onPuzzleCompleted,
+        alreadyCompleted,
+        source,
+    ]);
+    const closeAchievement = useCallback(() => {
+        setShowAchievement(false);
+        setAchievementResult(null);
+    }, []);
+    const discardResume = resume.discard;
+    const newGame = useCallback(() => {
+        clearGame();
+        discardResume();
+        excludedUuidRef.current = activeUuid;
+        setPinned(null);
+        setScrambled(null);
+        startedGameRef.current = '';
+        startedSessionRef.current = '';
+    }, [clearGame, discardResume, activeUuid]);
+    // --- Game props ----------------------------------------------------------
+    const gameProps = useMemo(() => {
+        if (!activePuzzle)
+            return null;
+        if (resumeGame) {
+            return {
+                puzzle: activePuzzle.puzzle,
+                solution: activePuzzle.solution,
+                scramble: false,
+                initialInput: resumeGame.inputString,
+                initialPencilmarks: resumeGame.pencilmarksString,
+                initialElapsedTime: resumeGame.elapsedTime,
+                initialAutoPencilmarks: resumeGame.autoPencilmarks,
+            };
+        }
+        return {
+            puzzle: activePuzzle.puzzle,
+            solution: activePuzzle.solution,
+            scramble: true,
+        };
+    }, [activePuzzle, resumeGame]);
+    return {
+        status,
+        isReady: resume.isReady,
+        isResuming,
+        resumeGame,
+        activePuzzle,
+        gameProps,
+        gameKey: activeUuid,
+        puzzleId,
+        alreadyCompleted,
+        isAuthenticated,
+        onScrambledReady,
+        onBoardReady,
+        onProgress: updateProgress,
+        onComplete,
+        newGame,
+        achievementResult,
+        showAchievement,
+        closeAchievement,
+    };
+}
+//# sourceMappingURL=usePuzzleSession.js.map