react-chess-puzzle-kit 1.0.4 → 1.0.5

package/dist/features/board/LineBoard.d.ts

@@ -5,6 +5,7 @@ export interface LineBoardProps {
     trainSide: LineTrainSide;
     draggable: boolean;
     correctMoveSquare?: string | null;
+    incorrectMoveSquare?: string | null;
     lastMoveUci?: string | null;
     onPieceDrop: (source: string, target: string, piece: string) => boolean;
     boardWidth: number;
@@ -14,4 +15,4 @@ export interface LineBoardProps {
  * side's pieces be dragged. Move validation and sequencing live in
  * {@link LineBoardWithControls}.
  */
-export declare const LineBoard: ({ fen, orientation, trainSide, draggable, correctMoveSquare, lastMoveUci, onPieceDrop, boardWidth, }: LineBoardProps) => import("react").JSX.Element;
+export declare const LineBoard: ({ fen, orientation, trainSide, draggable, correctMoveSquare, incorrectMoveSquare, lastMoveUci, onPieceDrop, boardWidth, }: LineBoardProps) => import("react").JSX.Element;

package/dist/features/board/PuzzleBoardWithControls.d.ts

@@ -1,6 +1,7 @@
 import React from 'react';
 import { PuzzleResultStatus } from '../analysis';
 import { AnalysisContainerRenderProps, AnalysisControls, AnalysisEngineOptions, AnalysisLayoutConfig, AnalysisMainRenderProps, AnalysisSidebarRenderProps, EngineEvaluationRenderProps, type BoardThemeId } from 'react-chess-core';
+import { type PuzzleAutoAdvanceState } from './usePuzzleAutoAdvanceCountdown';
 import { type PuzzleControlState } from './defaults/DefaultPuzzleControls';
 import { type PuzzleMissFeedback } from './PuzzlePlaySurface';
 export type { PuzzleMoveRecord } from '../position/moveHistory';
@@ -10,6 +11,7 @@ export { DEFAULT_ANALYSIS_LAYOUT } from 'react-chess-core';
 export { DEFAULT_PUZZLE_BOARD_WIDTH } from './puzzleBoardLayout';
 export { DefaultPuzzleControls, defaultRenderControls, } from './defaults/DefaultPuzzleControls';
 export type { PuzzleControlState, PuzzleControlsRenderProps, } from './defaults/DefaultPuzzleControls';
+export type { PuzzleAutoAdvanceState } from './usePuzzleAutoAdvanceCountdown';
 export type BoardCaptionRenderProps = {
     /** null while the puzzle position is loading */
     sideToMove: 'white' | 'black' | null;
@@ -76,7 +78,7 @@ export interface PuzzleBoardWithControlsProps {
         }) => void;
     };
     /** Omit to use {@link defaultRenderControls} / {@link DefaultPuzzleControls}. */
-    renderControls?: (showHint: () => void, showSolution: () => void, nextPuzzle: () => void, resultStatus: PuzzleResultStatus, analysis: AnalysisControls, controlState: PuzzleControlState) => React.ReactNode;
+    renderControls?: (showHint: () => void, showSolution: () => void, nextPuzzle: () => void, resultStatus: PuzzleResultStatus, analysis: AnalysisControls, controlState: PuzzleControlState, autoAdvance?: PuzzleAutoAdvanceState) => React.ReactNode;
     renderAnalysisSidebar?: (props: AnalysisSidebarRenderProps) => React.ReactNode;
     renderAnalysisContainer?: (props: AnalysisContainerRenderProps) => React.ReactNode;
     renderEngineEvaluation?: (props: EngineEvaluationRenderProps) => React.ReactNode;
@@ -97,6 +99,10 @@ export interface PuzzleBoardWithControlsProps {
     autoAdvanceOnComplete?: boolean;
     /** With {@link autoAdvanceOnComplete}, also advance after finishing following a miss or hint. */
     autoAdvanceOnCompleteAfterIncorrect?: boolean;
+    /** Delay before auto-loading the next card (defaults to {@link AUTO_ADVANCE_ON_COMPLETE_DELAY_MS}). */
+    autoAdvanceOnCompleteDelayMs?: number;
+    /** Replay missed solution plies on the board before auto-advancing. */
+    showCompletionRecap?: boolean;
     /** After a wrong guess, play the correct move and wait for the user to advance. */
     revealAnswerOnIncorrect?: boolean;
     /** After a wrong guess, show an arrow to the correct square. */
@@ -111,4 +117,4 @@ export interface PuzzleBoardWithControlsProps {
     refutationEngine?: AnalysisEngineOptions;
     answerArrowColor?: string;
 }
-export declare const PuzzleBoardWithControls: ({ theme, boardTheme, apiProxy, renderControls, renderAnalysisSidebar, renderAnalysisContainer, renderEngineEvaluation, renderBoardCaption, renderBoardFeedback, puzzleBoardWidth, analysisLayout, analysisBoardWidth, renderAnalysisMain, engine, autoAdvanceOnComplete, autoAdvanceOnCompleteAfterIncorrect, revealAnswerOnIncorrect, showAnswerArrowOnIncorrect, allowRetryOnIncorrect, showRefutationOnIncorrect, autoShowWrongMoves, refutationEngine, answerArrowColor, }: PuzzleBoardWithControlsProps) => React.JSX.Element;
+export declare const PuzzleBoardWithControls: ({ theme, boardTheme, apiProxy, renderControls, renderAnalysisSidebar, renderAnalysisContainer, renderEngineEvaluation, renderBoardCaption, renderBoardFeedback, puzzleBoardWidth, analysisLayout, analysisBoardWidth, renderAnalysisMain, engine, autoAdvanceOnComplete, autoAdvanceOnCompleteAfterIncorrect, autoAdvanceOnCompleteDelayMs, showCompletionRecap, revealAnswerOnIncorrect, showAnswerArrowOnIncorrect, allowRetryOnIncorrect, showRefutationOnIncorrect, autoShowWrongMoves, refutationEngine, answerArrowColor, }: PuzzleBoardWithControlsProps) => React.JSX.Element;

package/dist/features/board/PuzzlePlaySurface.d.ts

@@ -6,6 +6,13 @@ export type PuzzleMissFeedback = {
     /** True while the board shows the correct-move answer arrow. */
     answerArrowVisible: boolean;
 };
+/** Board state driven by the post-completion solution recap animation. */
+export type PuzzleRecapBoardState = {
+    fen: string;
+    lastMoveUci: string | null;
+    customArrows: [string, string, string][];
+    animationDuration: number;
+};
 export interface PuzzlePlaySurfaceProps {
     position: PuzzlePosition | null;
     onFeedback: (feedbackData: {
@@ -41,9 +48,11 @@ export interface PuzzlePlaySurfaceProps {
     positionLocked?: boolean;
     /** Fired when refutation miss feedback changes (for host UI). */
     onMissFeedbackChange?: (feedback: PuzzleMissFeedback | null) => void;
+    /** When set, replaces the live puzzle position with the completion recap board. */
+    recapBoard?: PuzzleRecapBoardState | null;
 }
 /**
  * Single mounted board for puzzle play. Keeps the prior board (and orientation)
  * visible while the next position loads so layout and perspective do not flicker.
  */
-export declare const PuzzlePlaySurface: ({ position, onFeedback, incInteractionNum, boardWidth, onResumeCorrect, revealAnswerOnIncorrect, showAnswerArrowOnIncorrect, allowRetryOnIncorrect, showRefutationOnIncorrect, autoShowWrongMoves, refutationEngine, answerArrowColor, positionLocked, onMissFeedbackChange, }: PuzzlePlaySurfaceProps) => import("react").JSX.Element;
+export declare const PuzzlePlaySurface: ({ position, onFeedback, incInteractionNum, boardWidth, onResumeCorrect, revealAnswerOnIncorrect, showAnswerArrowOnIncorrect, allowRetryOnIncorrect, showRefutationOnIncorrect, autoShowWrongMoves, refutationEngine, answerArrowColor, positionLocked, onMissFeedbackChange, recapBoard, }: PuzzlePlaySurfaceProps) => import("react").JSX.Element | null;

package/dist/features/board/usePuzzleAutoAdvanceCountdown.d.ts

@@ -0,0 +1,6 @@
+export type PuzzleAutoAdvanceState = {
+    active: boolean;
+    secondsRemaining: number;
+};
+/** Countdown overlay state while waiting to auto-load the next puzzle card. */
+export declare function usePuzzleAutoAdvanceCountdown(enabled: boolean, delayMs: number, onAdvance: () => void): PuzzleAutoAdvanceState;

package/dist/features/board/usePuzzleCompletionRecap.d.ts

@@ -0,0 +1,17 @@
+import { type SolutionLineRecapState } from 'react-chess-core';
+/** Pause on the puzzle setup position before the solution recap animates. */
+export declare const PUZZLE_COMPLETION_RECAP_SETUP_MS = 400;
+export type PuzzleCompletionRecapSource = {
+    startFen: string;
+    movesUci: string[];
+    startIndex: number;
+    endIndex: number;
+    missedIndices: number[];
+    setupUci?: string | null;
+};
+export type PuzzleCompletionRecapState = SolutionLineRecapState;
+export declare const usePuzzleCompletionRecap: ({ source, active, onComplete, }: {
+    source: PuzzleCompletionRecapSource | null;
+    active: boolean;
+    onComplete: () => void;
+}) => PuzzleCompletionRecapState;

package/dist/features/position/Position.d.ts

@@ -21,6 +21,10 @@ export declare abstract class Position implements Traversable {
 export declare function getCheckSquareFromChess(chess: Chess): string;
 /** Side to move for the final (user) ply in a puzzle line. */
 export declare function playerColorForSolution(initialFen: string, moves: string[]): 'white' | 'black';
+/** Move indices in `[fromIndex, toIndex)` where the solver is on move. */
+export declare function playerMoveIndicesInRange(initialFen: string, moves: string[], fromIndex: number, toIndex: number): number[];
+/** Auto-play opponent setup plies until the solver is on move. */
+export declare function advanceToPlayerTurn(position: PuzzlePosition): void;
 export type PuzzleResumeConfig = {
     startIndex: number;
     quizAtIndices: number[];

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export * from './features/board/LineBoardWithControls';
 export { DefaultPuzzleControls, defaultRenderControls, } from './features/board/defaults/DefaultPuzzleControls';
 export { DefaultLineControls, defaultRenderLineControls, } from './features/board/defaults/DefaultLineControls';
 export type { PuzzleControlState, PuzzleControlsRenderProps, } from './features/board/defaults/DefaultPuzzleControls';
+export type { PuzzleAutoAdvanceState } from './features/board/usePuzzleAutoAdvanceCountdown';
 export { DEFAULT_PUZZLE_BOARD_WIDTH, PUZZLE_CONTROLS_BESIDE_RESERVE_PX, PUZZLE_CONTROLS_STACK_BREAKPOINT_PX, } from './features/board/puzzleBoardLayout';
 export * from './features/position/moveHistory';
 export * from './features/position/Position';

package/dist/index.esm.js

@@ -1,6 +1,6 @@
 import { useState, useEffect, useRef, useMemo, useCallback } from 'react';
 import { jsx, jsxs } from 'react/jsx-runtime';
-import { useBoardRevision, useCorrectMoveFeedback, useMissBoard, ChessboardDnDProvider, HighlightChessboard, uciFromDrop, ThemeProvider, AnalysisErrorBoundary, AnalysisBoardCore, AnalysisBoardLayout, AnalysisBoard, DEFAULT_ANALYSIS_LAYOUT, lastMoveUciAtPly, evaluateExpectedMoveDrop, fenAfterUci, boardSquareHighlightColors, analysisBoardHighlightColors } from 'react-chess-core';
+import { useBoardRevision, useCorrectMoveFeedback, useIncorrectMoveFeedback, useMissBoard, HighlightChessboard, DEFAULT_ANSWER_ARROW_COLOR, uciFromDrop, fenAtPlyFromStart, useSolutionLineRecap, ThemeProvider, AnalysisErrorBoundary, AnalysisBoardCore, AnalysisBoardLayout, AnalysisBoard, BoardCompleteCheckOverlay, DEFAULT_ANALYSIS_LAYOUT, AUTO_ADVANCE_ON_COMPLETE_DELAY_MS, lastMoveUciAtPly, evaluateExpectedMoveDrop, fenAfterUci, boardSquareHighlightColors, analysisBoardHighlightColors } from 'react-chess-core';
 export { DEFAULT_ANALYSIS_LAYOUT } from 'react-chess-core';
 import { Chess } from 'chess.js';
 
@@ -56,18 +56,18 @@ const usePuzzleAnalysis = (position, resultStatus, puzzleNum) => {
 };
 
 const EMPTY_BOARD_FEN = '8/8/8/8/8/8/8/8 w - - 0 1';
-const DEFAULT_ANSWER_ARROW_COLOR = '#42a5f5';
 /**
  * Single mounted board for puzzle play. Keeps the prior board (and orientation)
  * visible while the next position loads so layout and perspective do not flicker.
  */
-const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth, onResumeCorrect, revealAnswerOnIncorrect = false, showAnswerArrowOnIncorrect = false, allowRetryOnIncorrect = true, showRefutationOnIncorrect = false, autoShowWrongMoves = true, refutationEngine, answerArrowColor = DEFAULT_ANSWER_ARROW_COLOR, positionLocked = false, onMissFeedbackChange, }) => {
-    var _a, _b, _c, _d, _e, _f, _g;
+const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth, onResumeCorrect, revealAnswerOnIncorrect = false, showAnswerArrowOnIncorrect = false, allowRetryOnIncorrect = true, showRefutationOnIncorrect = false, autoShowWrongMoves = true, refutationEngine, answerArrowColor = DEFAULT_ANSWER_ARROW_COLOR, positionLocked = false, onMissFeedbackChange, recapBoard = null, }) => {
+    var _a, _b, _c, _d, _e, _f;
     const [showAnswerArrow, setShowAnswerArrow] = useState(false);
     const [incorrectActive, setIncorrectActive] = useState(false);
     const attemptMissedRef = useRef(false);
     const { revision, bumpRevision } = useBoardRevision();
     const { correctMoveSquare, showCorrectMove, clearCorrectMoveFeedback, } = useCorrectMoveFeedback();
+    const { incorrectMoveSquare: transientIncorrectSquare, showIncorrectMove, clearIncorrectMoveFeedback, } = useIncorrectMoveFeedback();
     const boardOrientationRef = useRef('white');
     const boardFenRef = useRef(EMPTY_BOARD_FEN);
     const notifyHost = () => {
@@ -102,13 +102,25 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
     const answerArrowVisible = useRefutation
         ? incorrectActive && missPhase === 'answer'
         : showAnswerArrow;
+    const overlayIncorrectSquare = transientIncorrectSquare !== null && transientIncorrectSquare !== void 0 ? transientIncorrectSquare : (useRefutation && incorrectActive
+        ? missBoard.missSequence.display.incorrectMoveSquare
+        : null);
+    const refutationMoveSquare = useRefutation && incorrectActive
+        ? missBoard.missSequence.display.refutationMoveSquare
+        : null;
     useEffect(() => {
         setShowAnswerArrow(false);
         setIncorrectActive(false);
         attemptMissedRef.current = false;
         clearCorrectMoveFeedback();
+        clearIncorrectMoveFeedback();
         onMissFeedbackChange === null || onMissFeedbackChange === void 0 ? void 0 : onMissFeedbackChange(null);
-    }, [clearCorrectMoveFeedback, onMissFeedbackChange, position]);
+    }, [
+        clearCorrectMoveFeedback,
+        clearIncorrectMoveFeedback,
+        onMissFeedbackChange,
+        position,
+    ]);
     useEffect(() => {
         var _a, _b;
         if (!onMissFeedbackChange) {
@@ -140,11 +152,13 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         showAnswerArrow,
         useRefutation,
     ]);
+    const boardOrientation = position
+        ? position.getPlayerColor()
+        : boardOrientationRef.current;
     if (position) {
-        boardOrientationRef.current = position.getPlayerColor();
+        boardOrientationRef.current = boardOrientation;
         boardFenRef.current = position.fen();
     }
-    const boardOrientation = boardOrientationRef.current;
     const boardFen = boardFenRef.current;
     const hasBoard = boardFen !== EMPTY_BOARD_FEN;
     const simpleArrows = useMemo(() => {
@@ -157,19 +171,28 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         }
         return [[moveUci.slice(0, 2), moveUci.slice(2, 4), answerArrowColor]];
     }, [showAnswerArrow, position, answerArrowColor, useRefutation]);
-    const customArrows = useRefutation && incorrectActive
-        ? missBoard.customArrows
-        : simpleArrows;
-    const displayFen = useRefutation && incorrectActive ? missBoard.boardPosition : boardFen;
+    const isRecapping = recapBoard !== null;
+    const customArrows = isRecapping
+        ? recapBoard.customArrows
+        : useRefutation && incorrectActive
+            ? missBoard.customArrows
+            : simpleArrows;
+    const displayFen = isRecapping
+        ? recapBoard.fen
+        : useRefutation && incorrectActive
+            ? missBoard.boardPosition
+            : boardFen;
     const missLocked = useRefutation &&
         incorrectActive &&
         (missBoard.boardAnimating ||
             missPhase === 'wrong' ||
             missPhase === 'refutation');
-    const arePiecesDraggable = position !== null &&
+    const arePiecesDraggable = !isRecapping &&
+        position !== null &&
         !positionLocked &&
         !missLocked &&
-        correctMoveSquare === null;
+        correctMoveSquare === null &&
+        overlayIncorrectSquare === null;
     const onPieceDrop = (sourceSquare, targetSquare, piece) => {
         if (!position || positionLocked || position.isSolutionRevealed()) {
             return false;
@@ -183,6 +206,7 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         if (answerArrowVisible &&
             !allowRetryOnIncorrect &&
             !position.isExpectedGuess(sourceSquare, targetSquare)) {
+            showIncorrectMove(sourceSquare);
             position.resetInteractions();
             snapBoardBack();
             return false;
@@ -192,6 +216,7 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         });
         if (!guess.accepted) {
             attemptMissedRef.current = true;
+            showIncorrectMove(useRefutation ? targetSquare : sourceSquare);
             onFeedback({
                 index: position.getIndex(),
                 guess: { sourceSquare, targetSquare, piece },
@@ -205,8 +230,7 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
                     missBoard.missSequence.startSequence(setupFen, attemptedUci);
                 }
                 position.resetInteractions();
-                snapBoardBack();
-                return false;
+                return true;
             }
             const revealIncorrectFeedback = () => {
                 if (showAnswerArrowOnIncorrect) {
@@ -272,13 +296,79 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         showCorrectMove(targetSquare, finishCorrectFeedback);
         return true;
     };
-    return (jsx(ChessboardDnDProvider, { children: hasBoard ? (jsx(HighlightChessboard, { boardWidth: boardWidth, checkSquare: (_e = position === null || position === void 0 ? void 0 : position.getCheckSquare()) !== null && _e !== void 0 ? _e : '', hintSquare: (_f = position === null || position === void 0 ? void 0 : position.getHintSquare()) !== null && _f !== void 0 ? _f : null, incorrectMoveSquare: showAnswerArrowOnIncorrect
-                ? null
-                : ((_g = position === null || position === void 0 ? void 0 : position.getIncorrectMoveSquare()) !== null && _g !== void 0 ? _g : null), correctMoveSquare: correctMoveSquare, customArrows: customArrows, onPieceDrop: onPieceDrop, position: displayFen, boardOrientation: boardOrientation, arePiecesDraggable: arePiecesDraggable, areArrowsAllowed: false, promotionDialogVariant: "modal", animationDuration: 0 }, revision)) : null }));
+    return hasBoard ? (jsx(HighlightChessboard, { boardWidth: boardWidth, checkSquare: isRecapping ? '' : ((_e = position === null || position === void 0 ? void 0 : position.getCheckSquare()) !== null && _e !== void 0 ? _e : ''), hintSquare: isRecapping ? null : ((_f = position === null || position === void 0 ? void 0 : position.getHintSquare()) !== null && _f !== void 0 ? _f : null), incorrectMoveSquare: isRecapping ? null : overlayIncorrectSquare, refutationMoveSquare: isRecapping ? null : refutationMoveSquare, correctMoveSquare: isRecapping ? null : correctMoveSquare, customArrows: customArrows, lastMoveUci: isRecapping ? recapBoard.lastMoveUci : null, onPieceDrop: onPieceDrop, position: displayFen, boardOrientation: boardOrientation, arePiecesDraggable: arePiecesDraggable, areArrowsAllowed: false, promotionDialogVariant: "modal", animationDuration: isRecapping ? recapBoard.animationDuration : 0 }, revision)) : null;
 };
 
 const PuzzleBoard = ({ position, onFeedback, incInteractionNum, boardWidth, revealAnswerOnIncorrect = false, showAnswerArrowOnIncorrect = false, allowRetryOnIncorrect = true, answerArrowColor, }) => (jsx(PuzzlePlaySurface, { position: position, onFeedback: onFeedback, incInteractionNum: incInteractionNum, boardWidth: boardWidth, revealAnswerOnIncorrect: revealAnswerOnIncorrect, showAnswerArrowOnIncorrect: showAnswerArrowOnIncorrect, allowRetryOnIncorrect: allowRetryOnIncorrect, answerArrowColor: answerArrowColor }));
 
+const inactiveAutoAdvance = {
+    active: false,
+    secondsRemaining: -1,
+};
+/** Countdown overlay state while waiting to auto-load the next puzzle card. */
+function usePuzzleAutoAdvanceCountdown(enabled, delayMs, onAdvance) {
+    const [secondsRemaining, setSecondsRemaining] = useState(-1);
+    useEffect(() => {
+        if (!enabled || delayMs <= 0) {
+            setSecondsRemaining(-1);
+            return;
+        }
+        const startedAt = Date.now();
+        const updateCountdown = () => {
+            const elapsed = Date.now() - startedAt;
+            setSecondsRemaining(Math.max(0, Math.ceil((delayMs - elapsed) / 1000)));
+        };
+        updateCountdown();
+        const intervalId = window.setInterval(updateCountdown, 200);
+        const timeoutId = window.setTimeout(() => {
+            window.clearInterval(intervalId);
+            setSecondsRemaining(-1);
+            onAdvance();
+        }, delayMs);
+        return () => {
+            window.clearInterval(intervalId);
+            window.clearTimeout(timeoutId);
+            setSecondsRemaining(-1);
+        };
+    }, [delayMs, enabled, onAdvance]);
+    if (!enabled || secondsRemaining < 0) {
+        return inactiveAutoAdvance;
+    }
+    return {
+        active: true,
+        secondsRemaining,
+    };
+}
+
+/** Pause on the puzzle setup position before the solution recap animates. */
+const PUZZLE_COMPLETION_RECAP_SETUP_MS = 400;
+const usePuzzleCompletionRecap = ({ source, active, onComplete, }) => {
+    var _a, _b, _c, _d, _e, _f;
+    const startFen = (_a = source === null || source === void 0 ? void 0 : source.startFen) !== null && _a !== void 0 ? _a : '';
+    const movesUci = (_b = source === null || source === void 0 ? void 0 : source.movesUci) !== null && _b !== void 0 ? _b : [];
+    const startIndex = (_c = source === null || source === void 0 ? void 0 : source.startIndex) !== null && _c !== void 0 ? _c : 0;
+    const endIndex = (_d = source === null || source === void 0 ? void 0 : source.endIndex) !== null && _d !== void 0 ? _d : 0;
+    const missedIndices = (_e = source === null || source === void 0 ? void 0 : source.missedIndices) !== null && _e !== void 0 ? _e : [];
+    const setupUci = (_f = source === null || source === void 0 ? void 0 : source.setupUci) !== null && _f !== void 0 ? _f : null;
+    const resolveFen = useCallback((moveIndex, afterMove) => {
+        if (!startFen || movesUci.length === 0) {
+            return '';
+        }
+        return fenAtPlyFromStart(startFen, movesUci, afterMove ? moveIndex + 1 : moveIndex);
+    }, [movesUci, startFen]);
+    return useSolutionLineRecap({
+        active: active && source !== null,
+        movesUci,
+        startIndex,
+        endIndex,
+        missedIndices,
+        segmentStartFen: startFen,
+        setupUci,
+        onComplete,
+        resolveFen,
+    });
+};
+
 const isAttemptFinished = (resultStatus) => resultStatus === 'complete' || resultStatus === 'incorrect';
 /** Library default hint / next / analysis / result controls (unstyled buttons). */
 const DefaultPuzzleControls = ({ showHint, showSolution, nextPuzzle, resultStatus, analysis, controlState, }) => (jsxs("div", { style: rowStyle$1, children: [jsx("button", { type: "button", onClick: showHint, style: buttonStyle, disabled: !controlState.canShowHint, children: "Hint" }), jsx("button", { type: "button", onClick: showSolution, style: buttonStyle, disabled: !controlState.canShowSolution, children: "Show solution" }), jsx("button", { type: "button", onClick: nextPuzzle, style: buttonStyle, children: "Next puzzle" }), analysis.visible && isAttemptFinished(resultStatus) && (jsx("button", { type: "button", onClick: analysis.openAnalysis, style: buttonStyle, children: "Analysis" })), resultStatus === 'complete' && (jsx("span", { style: statusStyle$1, children: "Complete" })), resultStatus === 'incorrect' && (jsx("span", { style: Object.assign(Object.assign({}, statusStyle$1), { color: '#c62828' }), children: "Incorrect" }))] }));
@@ -483,6 +573,29 @@ function playerColorForSolution(initialFen, moves) {
     }
     return chess.turn() === 'w' ? 'white' : 'black';
 }
+/** Move indices in `[fromIndex, toIndex)` where the solver is on move. */
+function playerMoveIndicesInRange(initialFen, moves, fromIndex, toIndex) {
+    const playerColor = playerColorForSolution(initialFen, moves);
+    const chess = new Chess(initialFen);
+    const indices = [];
+    for (let i = 0; i < toIndex && i < moves.length; i++) {
+        const side = chess.turn() === 'w' ? 'white' : 'black';
+        if (i >= fromIndex && side === playerColor) {
+            indices.push(i);
+        }
+        applyUciMove(chess, moves[i]);
+    }
+    return indices;
+}
+/** Auto-play opponent setup plies until the solver is on move. */
+function advanceToPlayerTurn(position) {
+    while (!position.isFinished() &&
+        position.getSideToMove() !== position.getPlayerColor()) {
+        if (!position.next()) {
+            break;
+        }
+    }
+}
 class PuzzlePosition extends Position {
     constructor(initialFEN, moves, resumeConfig) {
         super();
@@ -727,19 +840,37 @@ class GamePosition extends Position {
     }
 }
 
-/** Apply the opponent setup ply immediately so the board does not flash on load. */
+/** Apply opponent setup plies immediately so the board does not flash on load. */
 const puzzlePositionFromFetch = (fen, moves, resume) => {
     const newPosition = new PuzzlePosition(fen, moves, resume);
     if (!resume && moves.length > 1) {
         newPosition.next();
+        advanceToPlayerTurn(newPosition);
+    }
+    else if (resume &&
+        newPosition.getSideToMove() !== newPosition.getPlayerColor()) {
+        advanceToPlayerTurn(newPosition);
     }
     return newPosition;
 };
-/** Brief pause so the user sees a correct result before the next card loads. */
-const AUTO_ADVANCE_ON_COMPLETE_DELAY_MS = 700;
 const SOLUTION_STEP_MS = 500;
 const RESUME_AUTO_STEP_MS = 500;
-const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls = defaultRenderControls, renderAnalysisSidebar, renderAnalysisContainer, renderEngineEvaluation, renderBoardCaption, renderBoardFeedback, puzzleBoardWidth = DEFAULT_PUZZLE_BOARD_WIDTH, analysisLayout = DEFAULT_ANALYSIS_LAYOUT, analysisBoardWidth, renderAnalysisMain, engine, autoAdvanceOnComplete = false, autoAdvanceOnCompleteAfterIncorrect = false, revealAnswerOnIncorrect = false, showAnswerArrowOnIncorrect = false, allowRetryOnIncorrect = true, showRefutationOnIncorrect, autoShowWrongMoves = true, refutationEngine, answerArrowColor, }) => {
+const uniqueIndices = (indices) => [...new Set(indices)];
+const buildCompletionRecapSource = (position, missedIndices) => {
+    var _a, _b;
+    const movesUci = position.getSolutionMoves();
+    const initialFen = position.getInitialFen();
+    const startIndex = (_a = playerMoveIndicesInRange(initialFen, movesUci, 0, movesUci.length)[0]) !== null && _a !== void 0 ? _a : 0;
+    return {
+        startFen: initialFen,
+        movesUci,
+        startIndex,
+        endIndex: movesUci.length,
+        missedIndices,
+        setupUci: startIndex > 0 ? (_b = movesUci[startIndex - 1]) !== null && _b !== void 0 ? _b : null : null,
+    };
+};
+const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls = defaultRenderControls, renderAnalysisSidebar, renderAnalysisContainer, renderEngineEvaluation, renderBoardCaption, renderBoardFeedback, puzzleBoardWidth = DEFAULT_PUZZLE_BOARD_WIDTH, analysisLayout = DEFAULT_ANALYSIS_LAYOUT, analysisBoardWidth, renderAnalysisMain, engine, autoAdvanceOnComplete = false, autoAdvanceOnCompleteAfterIncorrect = false, autoAdvanceOnCompleteDelayMs = AUTO_ADVANCE_ON_COMPLETE_DELAY_MS, showCompletionRecap = false, revealAnswerOnIncorrect = false, showAnswerArrowOnIncorrect = false, allowRetryOnIncorrect = true, showRefutationOnIncorrect, autoShowWrongMoves = true, refutationEngine, answerArrowColor, }) => {
     var _a, _b, _c, _d;
     const refutationOnIncorrect = showRefutationOnIncorrect !== null && showRefutationOnIncorrect !== void 0 ? showRefutationOnIncorrect : showAnswerArrowOnIncorrect;
     const stackControlsBelow = useStackPuzzleControlsBelow();
@@ -755,6 +886,11 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
     const [puzzleComplete, setPuzzleComplete] = useState(false);
     const [completedAfterMiss, setCompletedAfterMiss] = useState(false);
     const [missFeedback, setMissFeedback] = useState(null);
+    const [missedMoveIndices, setMissedMoveIndices] = useState([]);
+    const [completionCheckVisible, setCompletionCheckVisible] = useState(false);
+    const [completionRecapActive, setCompletionRecapActive] = useState(false);
+    const [completionRecapDone, setCompletionRecapDone] = useState(false);
+    const completionFlowStartedRef = useRef(false);
     const [, setInteractionNum] = useState(0);
     const solutionAnimationRef = useRef({ cancelled: false, timeoutIds: [] });
     const resumeAnimationRef = useRef({ cancelled: false, timeoutIds: [] });
@@ -781,6 +917,11 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
         setPuzzleComplete(false);
         setCompletedAfterMiss(false);
         setMissFeedback(null);
+        setMissedMoveIndices([]);
+        setCompletionCheckVisible(false);
+        setCompletionRecapActive(false);
+        setCompletionRecapDone(false);
+        completionFlowStartedRef.current = false;
         onFetch()
             .then((data) => {
             if (cancelled) {
@@ -816,10 +957,16 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
             feedbackData.isCorrect === false;
         if (feedbackData.hintRequested) {
             setHintUsed(true);
+            setMissedMoveIndices((prev) => uniqueIndices([...prev, feedbackData.index]));
         }
         if (incorrectThisFeedback) {
             setHasIncorrectAttempt(true);
         }
+        if (feedbackData.isCorrect === false &&
+            !feedbackData.isFinished &&
+            !feedbackData.solutionShown) {
+            setMissedMoveIndices((prev) => uniqueIndices([...prev, feedbackData.index]));
+        }
         if (feedbackData.isFinished) {
             setPuzzleComplete(true);
             setCompletedAfterMiss((prev) => prev ||
@@ -983,6 +1130,10 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
         position.recordSolutionShown();
         position.setSolutionRevealed(true);
         position.wantsHint(false);
+        setMissedMoveIndices((prev) => uniqueIndices([
+            ...prev,
+            ...playerMoveIndicesInRange(position.getInitialFen(), position.getSolutionMoves(), position.getIndex(), position.getSolutionMoves().length),
+        ]));
         handleFeedback({
             index: position.getIndex(),
             solutionShown: true,
@@ -995,30 +1146,46 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
         setPuzzleNum((prevPuzzleNum) => prevPuzzleNum + 1);
     }, []);
     const resultStatus = getResultStatus();
+    const completionRecapSource = useMemo(() => position && showCompletionRecap
+        ? buildCompletionRecapSource(position, missedMoveIndices)
+        : null, [position, showCompletionRecap, missedMoveIndices]);
+    const handleCompletionRecapDone = useCallback(() => {
+        setCompletionRecapActive(false);
+        setCompletionRecapDone(true);
+    }, []);
+    const completionRecap = usePuzzleCompletionRecap({
+        source: completionRecapSource,
+        active: completionRecapActive,
+        onComplete: handleCompletionRecapDone,
+    });
+    const isCompletionRecapping = showCompletionRecap && (completionRecapActive || completionRecap.active);
     useEffect(() => {
-        if (!autoAdvanceOnComplete) {
-            return;
-        }
-        if (resultStatus !== 'complete') {
+        if (!showCompletionRecap ||
+            resultStatus !== 'complete' ||
+            loadingNextPuzzle ||
+            completionFlowStartedRef.current) {
             return;
         }
-        if (hasIncorrectAttempt && !autoAdvanceOnCompleteAfterIncorrect) {
+        completionFlowStartedRef.current = true;
+        setCompletionCheckVisible(true);
+    }, [loadingNextPuzzle, resultStatus, showCompletionRecap]);
+    useEffect(() => {
+        if (!completionCheckVisible) {
             return;
         }
-        const timer = setTimeout(() => {
-            handleNextPuzzle();
-        }, AUTO_ADVANCE_ON_COMPLETE_DELAY_MS);
+        const timer = window.setTimeout(() => {
+            setCompletionCheckVisible(false);
+            setCompletionRecapActive(true);
+        }, PUZZLE_COMPLETION_RECAP_SETUP_MS);
         return () => {
-            clearTimeout(timer);
+            window.clearTimeout(timer);
         };
-    }, [
-        autoAdvanceOnComplete,
-        autoAdvanceOnCompleteAfterIncorrect,
-        resultStatus,
-        hasIncorrectAttempt,
-        handleNextPuzzle,
-        puzzleNum,
-    ]);
+    }, [completionCheckVisible]);
+    const shouldAutoAdvance = autoAdvanceOnComplete &&
+        resultStatus === 'complete' &&
+        !(hasIncorrectAttempt && !autoAdvanceOnCompleteAfterIncorrect) &&
+        (!showCompletionRecap || completionRecapDone);
+    const autoAdvance = usePuzzleAutoAdvanceCountdown(shouldAutoAdvance, autoAdvanceOnCompleteDelayMs, handleNextPuzzle);
     const controlState = {
         canShowHint: position !== null &&
             !position.isFinished() &&
@@ -1033,7 +1200,18 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
     const useHostAnalysisUi = Boolean(renderAnalysisSidebar &&
         renderAnalysisContainer &&
         (renderEngineEvaluation || (engine === null || engine === void 0 ? void 0 : engine.enabled) === false));
-    return (jsx(ThemeProvider, { theme: theme, boardTheme: boardTheme, children: analysisSnapshot ? (jsx(AnalysisErrorBoundary, { onClose: analysis.closeAnalysis, children: useHostAnalysisUi ? (jsx(AnalysisBoardCore, { analysisContext: analysisSnapshot, onClose: analysis.closeAnalysis, theme: theme, boardWidth: resolvedAnalysisBoardWidth, engine: engine, renderMain: renderAnalysisMain !== null && renderAnalysisMain !== void 0 ? renderAnalysisMain : (({ board, sidebar, model }) => (jsx(AnalysisBoardLayout, { layout: analysisLayout, model: model, board: board, sidebar: sidebar }))), renderSidebar: renderAnalysisSidebar, renderContainer: renderAnalysisContainer, renderEngineEvaluation: renderEngineEvaluation !== null && renderEngineEvaluation !== void 0 ? renderEngineEvaluation : (() => null) })) : (jsx(AnalysisBoard, { analysisContext: analysisSnapshot, onClose: analysis.closeAnalysis, theme: theme, layout: analysisLayout, engine: engine, renderMain: renderAnalysisMain, renderSidebar: renderAnalysisSidebar, renderContainer: renderAnalysisContainer, renderEngineEvaluation: renderEngineEvaluation })) })) : (jsxs("div", { style: puzzlePlayRowStyle(controlsPlacement), children: [jsxs("div", { style: puzzleBoardColumnStyle(puzzleBoardWidth, controlsPlacement), children: [jsx("div", { style: puzzleBoardSlotWrapperStyle(), children: jsx("div", { style: puzzleBoardSlotStyle(), children: jsx(PuzzlePlaySurface, { position: position, boardWidth: puzzleBoardWidth, onFeedback: handleFeedback, incInteractionNum: incInteractionNum, onResumeCorrect: runResumeAutoAdvance, revealAnswerOnIncorrect: revealAnswerOnIncorrect, showAnswerArrowOnIncorrect: showAnswerArrowOnIncorrect, allowRetryOnIncorrect: allowRetryOnIncorrect, showRefutationOnIncorrect: refutationOnIncorrect, autoShowWrongMoves: autoShowWrongMoves, refutationEngine: refutationEngine !== null && refutationEngine !== void 0 ? refutationEngine : engine, answerArrowColor: answerArrowColor, positionLocked: loadingNextPuzzle, onMissFeedbackChange: setMissFeedback }) }) }), renderBoardCaption && (jsx("div", { style: puzzleBoardCaptionSlotStyle(), children: renderBoardCaption({
+    return (jsx(ThemeProvider, { theme: theme, boardTheme: boardTheme, children: analysisSnapshot ? (jsx(AnalysisErrorBoundary, { onClose: analysis.closeAnalysis, children: useHostAnalysisUi ? (jsx(AnalysisBoardCore, { analysisContext: analysisSnapshot, onClose: analysis.closeAnalysis, theme: theme, boardWidth: resolvedAnalysisBoardWidth, engine: engine, renderMain: renderAnalysisMain !== null && renderAnalysisMain !== void 0 ? renderAnalysisMain : (({ board, sidebar, model }) => (jsx(AnalysisBoardLayout, { layout: analysisLayout, model: model, board: board, sidebar: sidebar }))), renderSidebar: renderAnalysisSidebar, renderContainer: renderAnalysisContainer, renderEngineEvaluation: renderEngineEvaluation !== null && renderEngineEvaluation !== void 0 ? renderEngineEvaluation : (() => null) })) : (jsx(AnalysisBoard, { analysisContext: analysisSnapshot, onClose: analysis.closeAnalysis, theme: theme, layout: analysisLayout, engine: engine, renderMain: renderAnalysisMain, renderSidebar: renderAnalysisSidebar, renderContainer: renderAnalysisContainer, renderEngineEvaluation: renderEngineEvaluation })) })) : (jsxs("div", { style: puzzlePlayRowStyle(controlsPlacement), children: [jsxs("div", { style: puzzleBoardColumnStyle(puzzleBoardWidth, controlsPlacement), children: [jsxs("div", { style: puzzleBoardSlotWrapperStyle(), children: [jsx("div", { style: puzzleBoardSlotStyle(), children: jsx(PuzzlePlaySurface, { position: position, boardWidth: puzzleBoardWidth, onFeedback: handleFeedback, incInteractionNum: incInteractionNum, onResumeCorrect: runResumeAutoAdvance, revealAnswerOnIncorrect: revealAnswerOnIncorrect, showAnswerArrowOnIncorrect: showAnswerArrowOnIncorrect, allowRetryOnIncorrect: allowRetryOnIncorrect, showRefutationOnIncorrect: refutationOnIncorrect, autoShowWrongMoves: autoShowWrongMoves, refutationEngine: refutationEngine !== null && refutationEngine !== void 0 ? refutationEngine : engine, answerArrowColor: answerArrowColor, positionLocked: loadingNextPuzzle ||
+                                            completionCheckVisible ||
+                                            isCompletionRecapping, onMissFeedbackChange: setMissFeedback, recapBoard: isCompletionRecapping
+                                            ? {
+                                                fen: completionRecap.fen,
+                                                lastMoveUci: completionRecap.lastMoveUci,
+                                                customArrows: completionRecap.customArrows,
+                                                animationDuration: completionRecap.animationDuration,
+                                            }
+                                            : null }) }), completionCheckVisible && (jsx(BoardCompleteCheckOverlay, { variant: hasIncorrectAttempt || completedAfterMiss || hintUsed
+                                        ? 'partial'
+                                        : 'success' }))] }), renderBoardCaption && (jsx("div", { style: puzzleBoardCaptionSlotStyle(), children: renderBoardCaption({
                                 sideToMove: (_a = position === null || position === void 0 ? void 0 : position.getSideToMove()) !== null && _a !== void 0 ? _a : null,
                                 playerColor: position
                                     ? position.getPlayerColor()
@@ -1049,7 +1227,7 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
                             }) }))] }), jsxs("div", { style: puzzleControlsSlotStyle(controlsPlacement), children: [renderControls(handleHintRequest, handleShowSolution, handleNextPuzzle, resultStatus, {
                             visible: analysis.canOpen,
                             openAnalysis: analysis.openAnalysis,
-                        }, controlState), renderBoardFeedback && resultStatus === 'complete' && (jsx("div", { style: puzzleControlsFeedbackStyle(controlsPlacement), children: renderBoardFeedback({
+                        }, controlState, autoAdvance), renderBoardFeedback && resultStatus === 'complete' && (jsx("div", { style: puzzleControlsFeedbackStyle(controlsPlacement), children: renderBoardFeedback({
                                 resultStatus,
                                 cleanSolve: !hasIncorrectAttempt,
                                 refutationSan: missFeedback === null || missFeedback === void 0 ? void 0 : missFeedback.refutationSan,
@@ -1063,7 +1241,7 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
  * side's pieces be dragged. Move validation and sequencing live in
  * {@link LineBoardWithControls}.
  */
-const LineBoard = ({ fen, orientation, trainSide, draggable, correctMoveSquare = null, lastMoveUci = null, onPieceDrop, boardWidth, }) => (jsx(ChessboardDnDProvider, { children: jsx(HighlightChessboard, { boardWidth: boardWidth, checkSquare: "", hintSquare: null, incorrectMoveSquare: null, correctMoveSquare: correctMoveSquare, position: fen, boardOrientation: orientation, arePiecesDraggable: draggable, isDraggablePiece: ({ piece }) => piece[0] === trainSide, onPieceDrop: (source, target, piece) => onPieceDrop(source, target, piece), lastMoveUci: lastMoveUci, autoPromoteToQueen: true, areArrowsAllowed: false, customBoardStyle: { borderRadius: 4 } }) }));
+const LineBoard = ({ fen, orientation, trainSide, draggable, correctMoveSquare = null, incorrectMoveSquare = null, lastMoveUci = null, onPieceDrop, boardWidth, }) => (jsx(HighlightChessboard, { boardWidth: boardWidth, checkSquare: "", hintSquare: null, incorrectMoveSquare: incorrectMoveSquare, correctMoveSquare: correctMoveSquare, position: fen, boardOrientation: orientation, arePiecesDraggable: draggable, isDraggablePiece: ({ piece }) => piece[0] === trainSide, onPieceDrop: (source, target, piece) => onPieceDrop(source, target, piece), lastMoveUci: lastMoveUci, autoPromoteToQueen: true, areArrowsAllowed: false, customBoardStyle: { borderRadius: 4 } }));
 
 /** Library default line-drill status controls (unstyled). */
 const DefaultLineControls = ({ moveNumber, total, finished, isUserTurn, feedback, }) => (jsxs("div", { style: rowStyle, children: [jsx("span", { style: statusStyle, children: finished ? 'Line complete' : `Move ${moveNumber} of ${total}` }), feedback && !finished && (jsx("span", { style: Object.assign(Object.assign({}, statusStyle), { color: feedback.isCorrect ? '#2e7d32' : '#c62828' }), children: feedback.isCorrect
@@ -1112,6 +1290,7 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
     const [feedback, setFeedback] = useState(null);
     const [displayFen, setDisplayFen] = useState(null);
     const { correctMoveSquare, showCorrectMove, clearCorrectMoveFeedback, isShowingCorrectMove, } = useCorrectMoveFeedback();
+    const { incorrectMoveSquare, showIncorrectMove, isShowingIncorrectMove, } = useIncorrectMoveFeedback();
     const total = line.movesUci.length;
     const orientation = boardOrientationForLine(line.trainSide);
     const applyMove = useCallback((index) => {
@@ -1136,7 +1315,7 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
     }, [line.movesUci]);
     // Auto-play opponent moves and detect the end of the line.
     useEffect(() => {
-        if (finished || isShowingCorrectMove) {
+        if (finished || isShowingCorrectMove || isShowingIncorrectMove) {
             return;
         }
         if (currentIndex >= total) {
@@ -1156,6 +1335,7 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
         applyMove,
         opponentMoveDelayMs,
         isShowingCorrectMove,
+        isShowingIncorrectMove,
     ]);
     // Emit the completion event exactly once.
     useEffect(() => {
@@ -1167,7 +1347,7 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
     }, [finished]);
     const handleDrop = (source, target, piece) => {
         var _a, _b, _c;
-        if (finished || isShowingCorrectMove) {
+        if (finished || isShowingCorrectMove || isShowingIncorrectMove) {
             return false;
         }
         const setupFen = displayFen !== null && displayFen !== void 0 ? displayFen : chessRef.current.fen();
@@ -1187,7 +1367,7 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
         setFeedback(moveFeedback);
         (_c = onMoveRef.current) === null || _c === void 0 ? void 0 : _c.call(onMoveRef, moveFeedback);
         if (isCorrect) {
-            const nextFen = fenAfterUci(setupFen, dropResult.uci);
+            const nextFen = fenAfterUci(setupFen, dropResult.attempt.uci);
             if (nextFen) {
                 setDisplayFen(nextFen);
             }
@@ -1198,6 +1378,9 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
                 applyMove(index);
             });
         }
+        else {
+            showIncorrectMove(source);
+        }
         return isCorrect;
     };
     const boardFen = displayFen !== null && displayFen !== void 0 ? displayFen : fen;
@@ -1211,13 +1394,14 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
     const moveNumber = Math.min(currentIndex + 1, total);
     const isUserTurn = !finished &&
         !isShowingCorrectMove &&
+        !isShowingIncorrectMove &&
         turnFromFen(boardFen) === line.trainSide &&
         currentIndex < total;
     const stackControlsBelow = useStackPuzzleControlsBelow();
     const controlsPlacement = stackControlsBelow
         ? 'below'
         : 'beside';
-    return (jsx(ThemeProvider, { theme: theme, boardTheme: boardTheme, children: jsxs("div", { style: puzzlePlayRowStyle(controlsPlacement), children: [jsx("div", { style: puzzleBoardColumnStyle(boardWidth, controlsPlacement), children: jsx("div", { style: puzzleBoardSlotStyle(), children: jsx(LineBoard, { fen: boardFen, orientation: orientation, trainSide: line.trainSide, draggable: isUserTurn, correctMoveSquare: correctMoveSquare, lastMoveUci: lastMoveUci, onPieceDrop: handleDrop, boardWidth: boardWidth }) }) }), jsx("div", { style: puzzleControlsSlotStyle(controlsPlacement), children: renderControls({
+    return (jsx(ThemeProvider, { theme: theme, boardTheme: boardTheme, children: jsxs("div", { style: puzzlePlayRowStyle(controlsPlacement), children: [jsx("div", { style: puzzleBoardColumnStyle(boardWidth, controlsPlacement), children: jsx("div", { style: puzzleBoardSlotStyle(), children: jsx(LineBoard, { fen: boardFen, orientation: orientation, trainSide: line.trainSide, draggable: isUserTurn, correctMoveSquare: correctMoveSquare, incorrectMoveSquare: incorrectMoveSquare, lastMoveUci: lastMoveUci, onPieceDrop: handleDrop, boardWidth: boardWidth }) }) }), jsx("div", { style: puzzleControlsSlotStyle(controlsPlacement), children: renderControls({
                         trainSide: line.trainSide,
                         moveNumber,
                         total,
@@ -1234,4 +1418,4 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
 /** @deprecated Import {@link boardSquareHighlightColors} and {@link analysisBoardHighlightColors} from `react-chess-core`. */
 const squareHighlightColors = Object.assign(Object.assign({}, boardSquareHighlightColors), analysisBoardHighlightColors);
 
-export { DEFAULT_PUZZLE_BOARD_WIDTH, DefaultLineControls, DefaultPuzzleControls, GamePosition, LineBoard, LineBoardWithControls, PUZZLE_CONTROLS_BESIDE_RESERVE_PX, PUZZLE_CONTROLS_STACK_BREAKPOINT_PX, Position, PuzzleBoard, PuzzleBoardWithControls, PuzzlePosition, applyUciMove, buildAnalysisContext, defaultRenderControls, defaultRenderLineControls, emptyAnalysisContext, getCheckSquareFromChess, isAnalysisAvailable, playerColorForSolution, squareHighlightColors, usePuzzleAnalysis };
+export { DEFAULT_PUZZLE_BOARD_WIDTH, DefaultLineControls, DefaultPuzzleControls, GamePosition, LineBoard, LineBoardWithControls, PUZZLE_CONTROLS_BESIDE_RESERVE_PX, PUZZLE_CONTROLS_STACK_BREAKPOINT_PX, Position, PuzzleBoard, PuzzleBoardWithControls, PuzzlePosition, advanceToPlayerTurn, applyUciMove, buildAnalysisContext, defaultRenderControls, defaultRenderLineControls, emptyAnalysisContext, getCheckSquareFromChess, isAnalysisAvailable, playerColorForSolution, playerMoveIndicesInRange, squareHighlightColors, usePuzzleAnalysis };

package/dist/index.js

@@ -57,18 +57,18 @@ const usePuzzleAnalysis = (position, resultStatus, puzzleNum) => {
 };
 
 const EMPTY_BOARD_FEN = '8/8/8/8/8/8/8/8 w - - 0 1';
-const DEFAULT_ANSWER_ARROW_COLOR = '#42a5f5';
 /**
  * Single mounted board for puzzle play. Keeps the prior board (and orientation)
  * visible while the next position loads so layout and perspective do not flicker.
  */
-const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth, onResumeCorrect, revealAnswerOnIncorrect = false, showAnswerArrowOnIncorrect = false, allowRetryOnIncorrect = true, showRefutationOnIncorrect = false, autoShowWrongMoves = true, refutationEngine, answerArrowColor = DEFAULT_ANSWER_ARROW_COLOR, positionLocked = false, onMissFeedbackChange, }) => {
-    var _a, _b, _c, _d, _e, _f, _g;
+const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth, onResumeCorrect, revealAnswerOnIncorrect = false, showAnswerArrowOnIncorrect = false, allowRetryOnIncorrect = true, showRefutationOnIncorrect = false, autoShowWrongMoves = true, refutationEngine, answerArrowColor = reactChessCore.DEFAULT_ANSWER_ARROW_COLOR, positionLocked = false, onMissFeedbackChange, recapBoard = null, }) => {
+    var _a, _b, _c, _d, _e, _f;
     const [showAnswerArrow, setShowAnswerArrow] = react.useState(false);
     const [incorrectActive, setIncorrectActive] = react.useState(false);
     const attemptMissedRef = react.useRef(false);
     const { revision, bumpRevision } = reactChessCore.useBoardRevision();
     const { correctMoveSquare, showCorrectMove, clearCorrectMoveFeedback, } = reactChessCore.useCorrectMoveFeedback();
+    const { incorrectMoveSquare: transientIncorrectSquare, showIncorrectMove, clearIncorrectMoveFeedback, } = reactChessCore.useIncorrectMoveFeedback();
     const boardOrientationRef = react.useRef('white');
     const boardFenRef = react.useRef(EMPTY_BOARD_FEN);
     const notifyHost = () => {
@@ -103,13 +103,25 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
     const answerArrowVisible = useRefutation
         ? incorrectActive && missPhase === 'answer'
         : showAnswerArrow;
+    const overlayIncorrectSquare = transientIncorrectSquare !== null && transientIncorrectSquare !== void 0 ? transientIncorrectSquare : (useRefutation && incorrectActive
+        ? missBoard.missSequence.display.incorrectMoveSquare
+        : null);
+    const refutationMoveSquare = useRefutation && incorrectActive
+        ? missBoard.missSequence.display.refutationMoveSquare
+        : null;
     react.useEffect(() => {
         setShowAnswerArrow(false);
         setIncorrectActive(false);
         attemptMissedRef.current = false;
         clearCorrectMoveFeedback();
+        clearIncorrectMoveFeedback();
         onMissFeedbackChange === null || onMissFeedbackChange === void 0 ? void 0 : onMissFeedbackChange(null);
-    }, [clearCorrectMoveFeedback, onMissFeedbackChange, position]);
+    }, [
+        clearCorrectMoveFeedback,
+        clearIncorrectMoveFeedback,
+        onMissFeedbackChange,
+        position,
+    ]);
     react.useEffect(() => {
         var _a, _b;
         if (!onMissFeedbackChange) {
@@ -141,11 +153,13 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         showAnswerArrow,
         useRefutation,
     ]);
+    const boardOrientation = position
+        ? position.getPlayerColor()
+        : boardOrientationRef.current;
     if (position) {
-        boardOrientationRef.current = position.getPlayerColor();
+        boardOrientationRef.current = boardOrientation;
         boardFenRef.current = position.fen();
     }
-    const boardOrientation = boardOrientationRef.current;
     const boardFen = boardFenRef.current;
     const hasBoard = boardFen !== EMPTY_BOARD_FEN;
     const simpleArrows = react.useMemo(() => {
@@ -158,19 +172,28 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         }
         return [[moveUci.slice(0, 2), moveUci.slice(2, 4), answerArrowColor]];
     }, [showAnswerArrow, position, answerArrowColor, useRefutation]);
-    const customArrows = useRefutation && incorrectActive
-        ? missBoard.customArrows
-        : simpleArrows;
-    const displayFen = useRefutation && incorrectActive ? missBoard.boardPosition : boardFen;
+    const isRecapping = recapBoard !== null;
+    const customArrows = isRecapping
+        ? recapBoard.customArrows
+        : useRefutation && incorrectActive
+            ? missBoard.customArrows
+            : simpleArrows;
+    const displayFen = isRecapping
+        ? recapBoard.fen
+        : useRefutation && incorrectActive
+            ? missBoard.boardPosition
+            : boardFen;
     const missLocked = useRefutation &&
         incorrectActive &&
         (missBoard.boardAnimating ||
             missPhase === 'wrong' ||
             missPhase === 'refutation');
-    const arePiecesDraggable = position !== null &&
+    const arePiecesDraggable = !isRecapping &&
+        position !== null &&
         !positionLocked &&
         !missLocked &&
-        correctMoveSquare === null;
+        correctMoveSquare === null &&
+        overlayIncorrectSquare === null;
     const onPieceDrop = (sourceSquare, targetSquare, piece) => {
         if (!position || positionLocked || position.isSolutionRevealed()) {
             return false;
@@ -184,6 +207,7 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         if (answerArrowVisible &&
             !allowRetryOnIncorrect &&
             !position.isExpectedGuess(sourceSquare, targetSquare)) {
+            showIncorrectMove(sourceSquare);
             position.resetInteractions();
             snapBoardBack();
             return false;
@@ -193,6 +217,7 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         });
         if (!guess.accepted) {
             attemptMissedRef.current = true;
+            showIncorrectMove(useRefutation ? targetSquare : sourceSquare);
             onFeedback({
                 index: position.getIndex(),
                 guess: { sourceSquare, targetSquare, piece },
@@ -206,8 +231,7 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
                     missBoard.missSequence.startSequence(setupFen, attemptedUci);
                 }
                 position.resetInteractions();
-                snapBoardBack();
-                return false;
+                return true;
             }
             const revealIncorrectFeedback = () => {
                 if (showAnswerArrowOnIncorrect) {
@@ -273,13 +297,79 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         showCorrectMove(targetSquare, finishCorrectFeedback);
         return true;
     };
-    return (jsxRuntime.jsx(reactChessCore.ChessboardDnDProvider, { children: hasBoard ? (jsxRuntime.jsx(reactChessCore.HighlightChessboard, { boardWidth: boardWidth, checkSquare: (_e = position === null || position === void 0 ? void 0 : position.getCheckSquare()) !== null && _e !== void 0 ? _e : '', hintSquare: (_f = position === null || position === void 0 ? void 0 : position.getHintSquare()) !== null && _f !== void 0 ? _f : null, incorrectMoveSquare: showAnswerArrowOnIncorrect
-                ? null
-                : ((_g = position === null || position === void 0 ? void 0 : position.getIncorrectMoveSquare()) !== null && _g !== void 0 ? _g : null), correctMoveSquare: correctMoveSquare, customArrows: customArrows, onPieceDrop: onPieceDrop, position: displayFen, boardOrientation: boardOrientation, arePiecesDraggable: arePiecesDraggable, areArrowsAllowed: false, promotionDialogVariant: "modal", animationDuration: 0 }, revision)) : null }));
+    return hasBoard ? (jsxRuntime.jsx(reactChessCore.HighlightChessboard, { boardWidth: boardWidth, checkSquare: isRecapping ? '' : ((_e = position === null || position === void 0 ? void 0 : position.getCheckSquare()) !== null && _e !== void 0 ? _e : ''), hintSquare: isRecapping ? null : ((_f = position === null || position === void 0 ? void 0 : position.getHintSquare()) !== null && _f !== void 0 ? _f : null), incorrectMoveSquare: isRecapping ? null : overlayIncorrectSquare, refutationMoveSquare: isRecapping ? null : refutationMoveSquare, correctMoveSquare: isRecapping ? null : correctMoveSquare, customArrows: customArrows, lastMoveUci: isRecapping ? recapBoard.lastMoveUci : null, onPieceDrop: onPieceDrop, position: displayFen, boardOrientation: boardOrientation, arePiecesDraggable: arePiecesDraggable, areArrowsAllowed: false, promotionDialogVariant: "modal", animationDuration: isRecapping ? recapBoard.animationDuration : 0 }, revision)) : null;
 };
 
 const PuzzleBoard = ({ position, onFeedback, incInteractionNum, boardWidth, revealAnswerOnIncorrect = false, showAnswerArrowOnIncorrect = false, allowRetryOnIncorrect = true, answerArrowColor, }) => (jsxRuntime.jsx(PuzzlePlaySurface, { position: position, onFeedback: onFeedback, incInteractionNum: incInteractionNum, boardWidth: boardWidth, revealAnswerOnIncorrect: revealAnswerOnIncorrect, showAnswerArrowOnIncorrect: showAnswerArrowOnIncorrect, allowRetryOnIncorrect: allowRetryOnIncorrect, answerArrowColor: answerArrowColor }));
 
+const inactiveAutoAdvance = {
+    active: false,
+    secondsRemaining: -1,
+};
+/** Countdown overlay state while waiting to auto-load the next puzzle card. */
+function usePuzzleAutoAdvanceCountdown(enabled, delayMs, onAdvance) {
+    const [secondsRemaining, setSecondsRemaining] = react.useState(-1);
+    react.useEffect(() => {
+        if (!enabled || delayMs <= 0) {
+            setSecondsRemaining(-1);
+            return;
+        }
+        const startedAt = Date.now();
+        const updateCountdown = () => {
+            const elapsed = Date.now() - startedAt;
+            setSecondsRemaining(Math.max(0, Math.ceil((delayMs - elapsed) / 1000)));
+        };
+        updateCountdown();
+        const intervalId = window.setInterval(updateCountdown, 200);
+        const timeoutId = window.setTimeout(() => {
+            window.clearInterval(intervalId);
+            setSecondsRemaining(-1);
+            onAdvance();
+        }, delayMs);
+        return () => {
+            window.clearInterval(intervalId);
+            window.clearTimeout(timeoutId);
+            setSecondsRemaining(-1);
+        };
+    }, [delayMs, enabled, onAdvance]);
+    if (!enabled || secondsRemaining < 0) {
+        return inactiveAutoAdvance;
+    }
+    return {
+        active: true,
+        secondsRemaining,
+    };
+}
+
+/** Pause on the puzzle setup position before the solution recap animates. */
+const PUZZLE_COMPLETION_RECAP_SETUP_MS = 400;
+const usePuzzleCompletionRecap = ({ source, active, onComplete, }) => {
+    var _a, _b, _c, _d, _e, _f;
+    const startFen = (_a = source === null || source === void 0 ? void 0 : source.startFen) !== null && _a !== void 0 ? _a : '';
+    const movesUci = (_b = source === null || source === void 0 ? void 0 : source.movesUci) !== null && _b !== void 0 ? _b : [];
+    const startIndex = (_c = source === null || source === void 0 ? void 0 : source.startIndex) !== null && _c !== void 0 ? _c : 0;
+    const endIndex = (_d = source === null || source === void 0 ? void 0 : source.endIndex) !== null && _d !== void 0 ? _d : 0;
+    const missedIndices = (_e = source === null || source === void 0 ? void 0 : source.missedIndices) !== null && _e !== void 0 ? _e : [];
+    const setupUci = (_f = source === null || source === void 0 ? void 0 : source.setupUci) !== null && _f !== void 0 ? _f : null;
+    const resolveFen = react.useCallback((moveIndex, afterMove) => {
+        if (!startFen || movesUci.length === 0) {
+            return '';
+        }
+        return reactChessCore.fenAtPlyFromStart(startFen, movesUci, afterMove ? moveIndex + 1 : moveIndex);
+    }, [movesUci, startFen]);
+    return reactChessCore.useSolutionLineRecap({
+        active: active && source !== null,
+        movesUci,
+        startIndex,
+        endIndex,
+        missedIndices,
+        segmentStartFen: startFen,
+        setupUci,
+        onComplete,
+        resolveFen,
+    });
+};
+
 const isAttemptFinished = (resultStatus) => resultStatus === 'complete' || resultStatus === 'incorrect';
 /** Library default hint / next / analysis / result controls (unstyled buttons). */
 const DefaultPuzzleControls = ({ showHint, showSolution, nextPuzzle, resultStatus, analysis, controlState, }) => (jsxRuntime.jsxs("div", { style: rowStyle$1, children: [jsxRuntime.jsx("button", { type: "button", onClick: showHint, style: buttonStyle, disabled: !controlState.canShowHint, children: "Hint" }), jsxRuntime.jsx("button", { type: "button", onClick: showSolution, style: buttonStyle, disabled: !controlState.canShowSolution, children: "Show solution" }), jsxRuntime.jsx("button", { type: "button", onClick: nextPuzzle, style: buttonStyle, children: "Next puzzle" }), analysis.visible && isAttemptFinished(resultStatus) && (jsxRuntime.jsx("button", { type: "button", onClick: analysis.openAnalysis, style: buttonStyle, children: "Analysis" })), resultStatus === 'complete' && (jsxRuntime.jsx("span", { style: statusStyle$1, children: "Complete" })), resultStatus === 'incorrect' && (jsxRuntime.jsx("span", { style: Object.assign(Object.assign({}, statusStyle$1), { color: '#c62828' }), children: "Incorrect" }))] }));
@@ -484,6 +574,29 @@ function playerColorForSolution(initialFen, moves) {
     }
     return chess.turn() === 'w' ? 'white' : 'black';
 }
+/** Move indices in `[fromIndex, toIndex)` where the solver is on move. */
+function playerMoveIndicesInRange(initialFen, moves, fromIndex, toIndex) {
+    const playerColor = playerColorForSolution(initialFen, moves);
+    const chess = new chess_js.Chess(initialFen);
+    const indices = [];
+    for (let i = 0; i < toIndex && i < moves.length; i++) {
+        const side = chess.turn() === 'w' ? 'white' : 'black';
+        if (i >= fromIndex && side === playerColor) {
+            indices.push(i);
+        }
+        applyUciMove(chess, moves[i]);
+    }
+    return indices;
+}
+/** Auto-play opponent setup plies until the solver is on move. */
+function advanceToPlayerTurn(position) {
+    while (!position.isFinished() &&
+        position.getSideToMove() !== position.getPlayerColor()) {
+        if (!position.next()) {
+            break;
+        }
+    }
+}
 class PuzzlePosition extends Position {
     constructor(initialFEN, moves, resumeConfig) {
         super();
@@ -728,19 +841,37 @@ class GamePosition extends Position {
     }
 }
 
-/** Apply the opponent setup ply immediately so the board does not flash on load. */
+/** Apply opponent setup plies immediately so the board does not flash on load. */
 const puzzlePositionFromFetch = (fen, moves, resume) => {
     const newPosition = new PuzzlePosition(fen, moves, resume);
     if (!resume && moves.length > 1) {
         newPosition.next();
+        advanceToPlayerTurn(newPosition);
+    }
+    else if (resume &&
+        newPosition.getSideToMove() !== newPosition.getPlayerColor()) {
+        advanceToPlayerTurn(newPosition);
     }
     return newPosition;
 };
-/** Brief pause so the user sees a correct result before the next card loads. */
-const AUTO_ADVANCE_ON_COMPLETE_DELAY_MS = 700;
 const SOLUTION_STEP_MS = 500;
 const RESUME_AUTO_STEP_MS = 500;
-const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls = defaultRenderControls, renderAnalysisSidebar, renderAnalysisContainer, renderEngineEvaluation, renderBoardCaption, renderBoardFeedback, puzzleBoardWidth = DEFAULT_PUZZLE_BOARD_WIDTH, analysisLayout = reactChessCore.DEFAULT_ANALYSIS_LAYOUT, analysisBoardWidth, renderAnalysisMain, engine, autoAdvanceOnComplete = false, autoAdvanceOnCompleteAfterIncorrect = false, revealAnswerOnIncorrect = false, showAnswerArrowOnIncorrect = false, allowRetryOnIncorrect = true, showRefutationOnIncorrect, autoShowWrongMoves = true, refutationEngine, answerArrowColor, }) => {
+const uniqueIndices = (indices) => [...new Set(indices)];
+const buildCompletionRecapSource = (position, missedIndices) => {
+    var _a, _b;
+    const movesUci = position.getSolutionMoves();
+    const initialFen = position.getInitialFen();
+    const startIndex = (_a = playerMoveIndicesInRange(initialFen, movesUci, 0, movesUci.length)[0]) !== null && _a !== void 0 ? _a : 0;
+    return {
+        startFen: initialFen,
+        movesUci,
+        startIndex,
+        endIndex: movesUci.length,
+        missedIndices,
+        setupUci: startIndex > 0 ? (_b = movesUci[startIndex - 1]) !== null && _b !== void 0 ? _b : null : null,
+    };
+};
+const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls = defaultRenderControls, renderAnalysisSidebar, renderAnalysisContainer, renderEngineEvaluation, renderBoardCaption, renderBoardFeedback, puzzleBoardWidth = DEFAULT_PUZZLE_BOARD_WIDTH, analysisLayout = reactChessCore.DEFAULT_ANALYSIS_LAYOUT, analysisBoardWidth, renderAnalysisMain, engine, autoAdvanceOnComplete = false, autoAdvanceOnCompleteAfterIncorrect = false, autoAdvanceOnCompleteDelayMs = reactChessCore.AUTO_ADVANCE_ON_COMPLETE_DELAY_MS, showCompletionRecap = false, revealAnswerOnIncorrect = false, showAnswerArrowOnIncorrect = false, allowRetryOnIncorrect = true, showRefutationOnIncorrect, autoShowWrongMoves = true, refutationEngine, answerArrowColor, }) => {
     var _a, _b, _c, _d;
     const refutationOnIncorrect = showRefutationOnIncorrect !== null && showRefutationOnIncorrect !== void 0 ? showRefutationOnIncorrect : showAnswerArrowOnIncorrect;
     const stackControlsBelow = useStackPuzzleControlsBelow();
@@ -756,6 +887,11 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
     const [puzzleComplete, setPuzzleComplete] = react.useState(false);
     const [completedAfterMiss, setCompletedAfterMiss] = react.useState(false);
     const [missFeedback, setMissFeedback] = react.useState(null);
+    const [missedMoveIndices, setMissedMoveIndices] = react.useState([]);
+    const [completionCheckVisible, setCompletionCheckVisible] = react.useState(false);
+    const [completionRecapActive, setCompletionRecapActive] = react.useState(false);
+    const [completionRecapDone, setCompletionRecapDone] = react.useState(false);
+    const completionFlowStartedRef = react.useRef(false);
     const [, setInteractionNum] = react.useState(0);
     const solutionAnimationRef = react.useRef({ cancelled: false, timeoutIds: [] });
     const resumeAnimationRef = react.useRef({ cancelled: false, timeoutIds: [] });
@@ -782,6 +918,11 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
         setPuzzleComplete(false);
         setCompletedAfterMiss(false);
         setMissFeedback(null);
+        setMissedMoveIndices([]);
+        setCompletionCheckVisible(false);
+        setCompletionRecapActive(false);
+        setCompletionRecapDone(false);
+        completionFlowStartedRef.current = false;
         onFetch()
             .then((data) => {
             if (cancelled) {
@@ -817,10 +958,16 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
             feedbackData.isCorrect === false;
         if (feedbackData.hintRequested) {
             setHintUsed(true);
+            setMissedMoveIndices((prev) => uniqueIndices([...prev, feedbackData.index]));
         }
         if (incorrectThisFeedback) {
             setHasIncorrectAttempt(true);
         }
+        if (feedbackData.isCorrect === false &&
+            !feedbackData.isFinished &&
+            !feedbackData.solutionShown) {
+            setMissedMoveIndices((prev) => uniqueIndices([...prev, feedbackData.index]));
+        }
         if (feedbackData.isFinished) {
             setPuzzleComplete(true);
             setCompletedAfterMiss((prev) => prev ||
@@ -984,6 +1131,10 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
         position.recordSolutionShown();
         position.setSolutionRevealed(true);
         position.wantsHint(false);
+        setMissedMoveIndices((prev) => uniqueIndices([
+            ...prev,
+            ...playerMoveIndicesInRange(position.getInitialFen(), position.getSolutionMoves(), position.getIndex(), position.getSolutionMoves().length),
+        ]));
         handleFeedback({
             index: position.getIndex(),
             solutionShown: true,
@@ -996,30 +1147,46 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
         setPuzzleNum((prevPuzzleNum) => prevPuzzleNum + 1);
     }, []);
     const resultStatus = getResultStatus();
+    const completionRecapSource = react.useMemo(() => position && showCompletionRecap
+        ? buildCompletionRecapSource(position, missedMoveIndices)
+        : null, [position, showCompletionRecap, missedMoveIndices]);
+    const handleCompletionRecapDone = react.useCallback(() => {
+        setCompletionRecapActive(false);
+        setCompletionRecapDone(true);
+    }, []);
+    const completionRecap = usePuzzleCompletionRecap({
+        source: completionRecapSource,
+        active: completionRecapActive,
+        onComplete: handleCompletionRecapDone,
+    });
+    const isCompletionRecapping = showCompletionRecap && (completionRecapActive || completionRecap.active);
     react.useEffect(() => {
-        if (!autoAdvanceOnComplete) {
-            return;
-        }
-        if (resultStatus !== 'complete') {
+        if (!showCompletionRecap ||
+            resultStatus !== 'complete' ||
+            loadingNextPuzzle ||
+            completionFlowStartedRef.current) {
             return;
         }
-        if (hasIncorrectAttempt && !autoAdvanceOnCompleteAfterIncorrect) {
+        completionFlowStartedRef.current = true;
+        setCompletionCheckVisible(true);
+    }, [loadingNextPuzzle, resultStatus, showCompletionRecap]);
+    react.useEffect(() => {
+        if (!completionCheckVisible) {
             return;
         }
-        const timer = setTimeout(() => {
-            handleNextPuzzle();
-        }, AUTO_ADVANCE_ON_COMPLETE_DELAY_MS);
+        const timer = window.setTimeout(() => {
+            setCompletionCheckVisible(false);
+            setCompletionRecapActive(true);
+        }, PUZZLE_COMPLETION_RECAP_SETUP_MS);
         return () => {
-            clearTimeout(timer);
+            window.clearTimeout(timer);
         };
-    }, [
-        autoAdvanceOnComplete,
-        autoAdvanceOnCompleteAfterIncorrect,
-        resultStatus,
-        hasIncorrectAttempt,
-        handleNextPuzzle,
-        puzzleNum,
-    ]);
+    }, [completionCheckVisible]);
+    const shouldAutoAdvance = autoAdvanceOnComplete &&
+        resultStatus === 'complete' &&
+        !(hasIncorrectAttempt && !autoAdvanceOnCompleteAfterIncorrect) &&
+        (!showCompletionRecap || completionRecapDone);
+    const autoAdvance = usePuzzleAutoAdvanceCountdown(shouldAutoAdvance, autoAdvanceOnCompleteDelayMs, handleNextPuzzle);
     const controlState = {
         canShowHint: position !== null &&
             !position.isFinished() &&
@@ -1034,7 +1201,18 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
     const useHostAnalysisUi = Boolean(renderAnalysisSidebar &&
         renderAnalysisContainer &&
         (renderEngineEvaluation || (engine === null || engine === void 0 ? void 0 : engine.enabled) === false));
-    return (jsxRuntime.jsx(reactChessCore.ThemeProvider, { theme: theme, boardTheme: boardTheme, children: analysisSnapshot ? (jsxRuntime.jsx(reactChessCore.AnalysisErrorBoundary, { onClose: analysis.closeAnalysis, children: useHostAnalysisUi ? (jsxRuntime.jsx(reactChessCore.AnalysisBoardCore, { analysisContext: analysisSnapshot, onClose: analysis.closeAnalysis, theme: theme, boardWidth: resolvedAnalysisBoardWidth, engine: engine, renderMain: renderAnalysisMain !== null && renderAnalysisMain !== void 0 ? renderAnalysisMain : (({ board, sidebar, model }) => (jsxRuntime.jsx(reactChessCore.AnalysisBoardLayout, { layout: analysisLayout, model: model, board: board, sidebar: sidebar }))), renderSidebar: renderAnalysisSidebar, renderContainer: renderAnalysisContainer, renderEngineEvaluation: renderEngineEvaluation !== null && renderEngineEvaluation !== void 0 ? renderEngineEvaluation : (() => null) })) : (jsxRuntime.jsx(reactChessCore.AnalysisBoard, { analysisContext: analysisSnapshot, onClose: analysis.closeAnalysis, theme: theme, layout: analysisLayout, engine: engine, renderMain: renderAnalysisMain, renderSidebar: renderAnalysisSidebar, renderContainer: renderAnalysisContainer, renderEngineEvaluation: renderEngineEvaluation })) })) : (jsxRuntime.jsxs("div", { style: puzzlePlayRowStyle(controlsPlacement), children: [jsxRuntime.jsxs("div", { style: puzzleBoardColumnStyle(puzzleBoardWidth, controlsPlacement), children: [jsxRuntime.jsx("div", { style: puzzleBoardSlotWrapperStyle(), children: jsxRuntime.jsx("div", { style: puzzleBoardSlotStyle(), children: jsxRuntime.jsx(PuzzlePlaySurface, { position: position, boardWidth: puzzleBoardWidth, onFeedback: handleFeedback, incInteractionNum: incInteractionNum, onResumeCorrect: runResumeAutoAdvance, revealAnswerOnIncorrect: revealAnswerOnIncorrect, showAnswerArrowOnIncorrect: showAnswerArrowOnIncorrect, allowRetryOnIncorrect: allowRetryOnIncorrect, showRefutationOnIncorrect: refutationOnIncorrect, autoShowWrongMoves: autoShowWrongMoves, refutationEngine: refutationEngine !== null && refutationEngine !== void 0 ? refutationEngine : engine, answerArrowColor: answerArrowColor, positionLocked: loadingNextPuzzle, onMissFeedbackChange: setMissFeedback }) }) }), renderBoardCaption && (jsxRuntime.jsx("div", { style: puzzleBoardCaptionSlotStyle(), children: renderBoardCaption({
+    return (jsxRuntime.jsx(reactChessCore.ThemeProvider, { theme: theme, boardTheme: boardTheme, children: analysisSnapshot ? (jsxRuntime.jsx(reactChessCore.AnalysisErrorBoundary, { onClose: analysis.closeAnalysis, children: useHostAnalysisUi ? (jsxRuntime.jsx(reactChessCore.AnalysisBoardCore, { analysisContext: analysisSnapshot, onClose: analysis.closeAnalysis, theme: theme, boardWidth: resolvedAnalysisBoardWidth, engine: engine, renderMain: renderAnalysisMain !== null && renderAnalysisMain !== void 0 ? renderAnalysisMain : (({ board, sidebar, model }) => (jsxRuntime.jsx(reactChessCore.AnalysisBoardLayout, { layout: analysisLayout, model: model, board: board, sidebar: sidebar }))), renderSidebar: renderAnalysisSidebar, renderContainer: renderAnalysisContainer, renderEngineEvaluation: renderEngineEvaluation !== null && renderEngineEvaluation !== void 0 ? renderEngineEvaluation : (() => null) })) : (jsxRuntime.jsx(reactChessCore.AnalysisBoard, { analysisContext: analysisSnapshot, onClose: analysis.closeAnalysis, theme: theme, layout: analysisLayout, engine: engine, renderMain: renderAnalysisMain, renderSidebar: renderAnalysisSidebar, renderContainer: renderAnalysisContainer, renderEngineEvaluation: renderEngineEvaluation })) })) : (jsxRuntime.jsxs("div", { style: puzzlePlayRowStyle(controlsPlacement), children: [jsxRuntime.jsxs("div", { style: puzzleBoardColumnStyle(puzzleBoardWidth, controlsPlacement), children: [jsxRuntime.jsxs("div", { style: puzzleBoardSlotWrapperStyle(), children: [jsxRuntime.jsx("div", { style: puzzleBoardSlotStyle(), children: jsxRuntime.jsx(PuzzlePlaySurface, { position: position, boardWidth: puzzleBoardWidth, onFeedback: handleFeedback, incInteractionNum: incInteractionNum, onResumeCorrect: runResumeAutoAdvance, revealAnswerOnIncorrect: revealAnswerOnIncorrect, showAnswerArrowOnIncorrect: showAnswerArrowOnIncorrect, allowRetryOnIncorrect: allowRetryOnIncorrect, showRefutationOnIncorrect: refutationOnIncorrect, autoShowWrongMoves: autoShowWrongMoves, refutationEngine: refutationEngine !== null && refutationEngine !== void 0 ? refutationEngine : engine, answerArrowColor: answerArrowColor, positionLocked: loadingNextPuzzle ||
+                                            completionCheckVisible ||
+                                            isCompletionRecapping, onMissFeedbackChange: setMissFeedback, recapBoard: isCompletionRecapping
+                                            ? {
+                                                fen: completionRecap.fen,
+                                                lastMoveUci: completionRecap.lastMoveUci,
+                                                customArrows: completionRecap.customArrows,
+                                                animationDuration: completionRecap.animationDuration,
+                                            }
+                                            : null }) }), completionCheckVisible && (jsxRuntime.jsx(reactChessCore.BoardCompleteCheckOverlay, { variant: hasIncorrectAttempt || completedAfterMiss || hintUsed
+                                        ? 'partial'
+                                        : 'success' }))] }), renderBoardCaption && (jsxRuntime.jsx("div", { style: puzzleBoardCaptionSlotStyle(), children: renderBoardCaption({
                                 sideToMove: (_a = position === null || position === void 0 ? void 0 : position.getSideToMove()) !== null && _a !== void 0 ? _a : null,
                                 playerColor: position
                                     ? position.getPlayerColor()
@@ -1050,7 +1228,7 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
                             }) }))] }), jsxRuntime.jsxs("div", { style: puzzleControlsSlotStyle(controlsPlacement), children: [renderControls(handleHintRequest, handleShowSolution, handleNextPuzzle, resultStatus, {
                             visible: analysis.canOpen,
                             openAnalysis: analysis.openAnalysis,
-                        }, controlState), renderBoardFeedback && resultStatus === 'complete' && (jsxRuntime.jsx("div", { style: puzzleControlsFeedbackStyle(controlsPlacement), children: renderBoardFeedback({
+                        }, controlState, autoAdvance), renderBoardFeedback && resultStatus === 'complete' && (jsxRuntime.jsx("div", { style: puzzleControlsFeedbackStyle(controlsPlacement), children: renderBoardFeedback({
                                 resultStatus,
                                 cleanSolve: !hasIncorrectAttempt,
                                 refutationSan: missFeedback === null || missFeedback === void 0 ? void 0 : missFeedback.refutationSan,
@@ -1064,7 +1242,7 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
  * side's pieces be dragged. Move validation and sequencing live in
  * {@link LineBoardWithControls}.
  */
-const LineBoard = ({ fen, orientation, trainSide, draggable, correctMoveSquare = null, lastMoveUci = null, onPieceDrop, boardWidth, }) => (jsxRuntime.jsx(reactChessCore.ChessboardDnDProvider, { children: jsxRuntime.jsx(reactChessCore.HighlightChessboard, { boardWidth: boardWidth, checkSquare: "", hintSquare: null, incorrectMoveSquare: null, correctMoveSquare: correctMoveSquare, position: fen, boardOrientation: orientation, arePiecesDraggable: draggable, isDraggablePiece: ({ piece }) => piece[0] === trainSide, onPieceDrop: (source, target, piece) => onPieceDrop(source, target, piece), lastMoveUci: lastMoveUci, autoPromoteToQueen: true, areArrowsAllowed: false, customBoardStyle: { borderRadius: 4 } }) }));
+const LineBoard = ({ fen, orientation, trainSide, draggable, correctMoveSquare = null, incorrectMoveSquare = null, lastMoveUci = null, onPieceDrop, boardWidth, }) => (jsxRuntime.jsx(reactChessCore.HighlightChessboard, { boardWidth: boardWidth, checkSquare: "", hintSquare: null, incorrectMoveSquare: incorrectMoveSquare, correctMoveSquare: correctMoveSquare, position: fen, boardOrientation: orientation, arePiecesDraggable: draggable, isDraggablePiece: ({ piece }) => piece[0] === trainSide, onPieceDrop: (source, target, piece) => onPieceDrop(source, target, piece), lastMoveUci: lastMoveUci, autoPromoteToQueen: true, areArrowsAllowed: false, customBoardStyle: { borderRadius: 4 } }));
 
 /** Library default line-drill status controls (unstyled). */
 const DefaultLineControls = ({ moveNumber, total, finished, isUserTurn, feedback, }) => (jsxRuntime.jsxs("div", { style: rowStyle, children: [jsxRuntime.jsx("span", { style: statusStyle, children: finished ? 'Line complete' : `Move ${moveNumber} of ${total}` }), feedback && !finished && (jsxRuntime.jsx("span", { style: Object.assign(Object.assign({}, statusStyle), { color: feedback.isCorrect ? '#2e7d32' : '#c62828' }), children: feedback.isCorrect
@@ -1113,6 +1291,7 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
     const [feedback, setFeedback] = react.useState(null);
     const [displayFen, setDisplayFen] = react.useState(null);
     const { correctMoveSquare, showCorrectMove, clearCorrectMoveFeedback, isShowingCorrectMove, } = reactChessCore.useCorrectMoveFeedback();
+    const { incorrectMoveSquare, showIncorrectMove, isShowingIncorrectMove, } = reactChessCore.useIncorrectMoveFeedback();
     const total = line.movesUci.length;
     const orientation = boardOrientationForLine(line.trainSide);
     const applyMove = react.useCallback((index) => {
@@ -1137,7 +1316,7 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
     }, [line.movesUci]);
     // Auto-play opponent moves and detect the end of the line.
     react.useEffect(() => {
-        if (finished || isShowingCorrectMove) {
+        if (finished || isShowingCorrectMove || isShowingIncorrectMove) {
             return;
         }
         if (currentIndex >= total) {
@@ -1157,6 +1336,7 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
         applyMove,
         opponentMoveDelayMs,
         isShowingCorrectMove,
+        isShowingIncorrectMove,
     ]);
     // Emit the completion event exactly once.
     react.useEffect(() => {
@@ -1168,7 +1348,7 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
     }, [finished]);
     const handleDrop = (source, target, piece) => {
         var _a, _b, _c;
-        if (finished || isShowingCorrectMove) {
+        if (finished || isShowingCorrectMove || isShowingIncorrectMove) {
             return false;
         }
         const setupFen = displayFen !== null && displayFen !== void 0 ? displayFen : chessRef.current.fen();
@@ -1188,7 +1368,7 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
         setFeedback(moveFeedback);
         (_c = onMoveRef.current) === null || _c === void 0 ? void 0 : _c.call(onMoveRef, moveFeedback);
         if (isCorrect) {
-            const nextFen = reactChessCore.fenAfterUci(setupFen, dropResult.uci);
+            const nextFen = reactChessCore.fenAfterUci(setupFen, dropResult.attempt.uci);
             if (nextFen) {
                 setDisplayFen(nextFen);
             }
@@ -1199,6 +1379,9 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
                 applyMove(index);
             });
         }
+        else {
+            showIncorrectMove(source);
+        }
         return isCorrect;
     };
     const boardFen = displayFen !== null && displayFen !== void 0 ? displayFen : fen;
@@ -1212,13 +1395,14 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
     const moveNumber = Math.min(currentIndex + 1, total);
     const isUserTurn = !finished &&
         !isShowingCorrectMove &&
+        !isShowingIncorrectMove &&
         turnFromFen(boardFen) === line.trainSide &&
         currentIndex < total;
     const stackControlsBelow = useStackPuzzleControlsBelow();
     const controlsPlacement = stackControlsBelow
         ? 'below'
         : 'beside';
-    return (jsxRuntime.jsx(reactChessCore.ThemeProvider, { theme: theme, boardTheme: boardTheme, children: jsxRuntime.jsxs("div", { style: puzzlePlayRowStyle(controlsPlacement), children: [jsxRuntime.jsx("div", { style: puzzleBoardColumnStyle(boardWidth, controlsPlacement), children: jsxRuntime.jsx("div", { style: puzzleBoardSlotStyle(), children: jsxRuntime.jsx(LineBoard, { fen: boardFen, orientation: orientation, trainSide: line.trainSide, draggable: isUserTurn, correctMoveSquare: correctMoveSquare, lastMoveUci: lastMoveUci, onPieceDrop: handleDrop, boardWidth: boardWidth }) }) }), jsxRuntime.jsx("div", { style: puzzleControlsSlotStyle(controlsPlacement), children: renderControls({
+    return (jsxRuntime.jsx(reactChessCore.ThemeProvider, { theme: theme, boardTheme: boardTheme, children: jsxRuntime.jsxs("div", { style: puzzlePlayRowStyle(controlsPlacement), children: [jsxRuntime.jsx("div", { style: puzzleBoardColumnStyle(boardWidth, controlsPlacement), children: jsxRuntime.jsx("div", { style: puzzleBoardSlotStyle(), children: jsxRuntime.jsx(LineBoard, { fen: boardFen, orientation: orientation, trainSide: line.trainSide, draggable: isUserTurn, correctMoveSquare: correctMoveSquare, incorrectMoveSquare: incorrectMoveSquare, lastMoveUci: lastMoveUci, onPieceDrop: handleDrop, boardWidth: boardWidth }) }) }), jsxRuntime.jsx("div", { style: puzzleControlsSlotStyle(controlsPlacement), children: renderControls({
                         trainSide: line.trainSide,
                         moveNumber,
                         total,
@@ -1251,6 +1435,7 @@ exports.Position = Position;
 exports.PuzzleBoard = PuzzleBoard;
 exports.PuzzleBoardWithControls = PuzzleBoardWithControls;
 exports.PuzzlePosition = PuzzlePosition;
+exports.advanceToPlayerTurn = advanceToPlayerTurn;
 exports.applyUciMove = applyUciMove;
 exports.buildAnalysisContext = buildAnalysisContext;
 exports.defaultRenderControls = defaultRenderControls;
@@ -1259,5 +1444,6 @@ exports.emptyAnalysisContext = emptyAnalysisContext;
 exports.getCheckSquareFromChess = getCheckSquareFromChess;
 exports.isAnalysisAvailable = isAnalysisAvailable;
 exports.playerColorForSolution = playerColorForSolution;
+exports.playerMoveIndicesInRange = playerMoveIndicesInRange;
 exports.squareHighlightColors = squareHighlightColors;
 exports.usePuzzleAnalysis = usePuzzleAnalysis;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-chess-puzzle-kit",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "React chess puzzle kit: play, controls, analysis, and browser Stockfish for endchess.training and other apps",
   "license": "MIT",
   "author": "Robert Blackwell",
@@ -51,7 +51,7 @@
   "peerDependencies": {
     "chess.js": "^1.0.0-beta.8",
     "react": "^18.3.1",
-    "react-chess-core": "^0.1.1",
+    "react-chess-core": "^0.1.8",
     "react-chessboard": "^4.7.1"
   },
   "devDependencies": {
@@ -74,7 +74,7 @@
     "chess.js": "^1.0.0-beta.8",
     "jest": "^29.7.0",
     "react": "^18.3.1",
-    "react-chess-core": "^0.1.1",
+    "react-chess-core": "^0.1.8",
     "react-chessboard": "^4.7.1",
     "react-dom": "^18.3.1",
     "storybook": "^8.2.9",