react-chess-puzzle-kit 1.0.0 → 1.0.2

package/dist/index.esm.js

@@ -1,7 +1,6 @@
-import { useState, useEffect, useRef, useCallback } from 'react';
+import { useState, useEffect, useRef, useMemo, useCallback } from 'react';
 import { jsx, jsxs } from 'react/jsx-runtime';
-import { ChessboardDnDProvider } from 'react-chessboard';
-import { HighlightChessboard, ThemeProvider, AnalysisErrorBoundary, AnalysisBoardCore, AnalysisBoardLayout, AnalysisBoard, DEFAULT_ANALYSIS_LAYOUT, boardSquareHighlightColors, analysisBoardHighlightColors } from 'react-chess-core';
+import { useBoardRevision, useMissBoard, ChessboardDnDProvider, HighlightChessboard, uciFromDrop, ThemeProvider, AnalysisErrorBoundary, AnalysisBoardCore, AnalysisBoardLayout, AnalysisBoard, DEFAULT_ANALYSIS_LAYOUT, evaluateExpectedMoveDrop, boardSquareHighlightColors, analysisBoardHighlightColors } from 'react-chess-core';
 export { DEFAULT_ANALYSIS_LAYOUT } from 'react-chess-core';
 import { Chess } from 'chess.js';
 
@@ -22,18 +21,17 @@ const buildAnalysisContext = (position) => {
         boardOrientation: position.getPlayerColor(),
     };
 };
-const isAnalysisAvailable = (position, resultStatus) => {
+const isAnalysisAvailable = (position, _resultStatus) => {
     if (!position) {
         return false;
     }
-    return (buildAnalysisContext(position).solutionMoves.length > 0 &&
-        resultStatus !== 'none');
+    return buildAnalysisContext(position).solutionMoves.length > 0;
 };
 
 const usePuzzleAnalysis = (position, resultStatus, puzzleNum) => {
     const [isOpen, setIsOpen] = useState(false);
     const [snapshot, setSnapshot] = useState(null);
-    const canOpen = isAnalysisAvailable(position, resultStatus);
+    const canOpen = isAnalysisAvailable(position);
     useEffect(() => {
         setIsOpen(false);
         setSnapshot(null);
@@ -58,68 +56,221 @@ 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. Shows an empty board while the next
- * position loads so the layout and controls do not flicker between cards.
+ * 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, revealAnswerOnIncorrect = false, }) => {
-    var _a, _b, _c, _d, _e;
+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 [showAnswerArrow, setShowAnswerArrow] = useState(false);
+    const [incorrectActive, setIncorrectActive] = useState(false);
+    const attemptMissedRef = useRef(false);
+    const { revision, bumpRevision } = useBoardRevision();
+    const boardOrientationRef = useRef('white');
+    const boardFenRef = useRef(EMPTY_BOARD_FEN);
+    const notifyHost = () => {
+        incInteractionNum();
+    };
+    const expectedUci = (_a = position === null || position === void 0 ? void 0 : position.getExpectedMoveUci()) !== null && _a !== void 0 ? _a : null;
+    const positionFen = (_b = position === null || position === void 0 ? void 0 : position.fen()) !== null && _b !== void 0 ? _b : boardFenRef.current;
+    const useRefutation = showRefutationOnIncorrect && showAnswerArrowOnIncorrect;
+    /**
+     * Force a chessboard remount after a rejected drop so pieces snap back.
+     * Skip when refutation feedback drives `displayFen` — remounting blinks the
+     * whole board without helping snap-back.
+     */
+    const snapBoardBack = () => {
+        if (useRefutation) {
+            return;
+        }
+        bumpRevision();
+        incInteractionNum();
+    };
+    const missBoard = useMissBoard({
+        feedback: useRefutation && incorrectActive ? 'incorrect' : null,
+        expectedUci: expectedUci || null,
+        positionFen,
+        answerArrowColor,
+        autoShowWrongMoves,
+        engineOptions: refutationEngine,
+    });
+    const missPhase = (_c = missBoard.missSequence.sequence) === null || _c === void 0 ? void 0 : _c.phase;
+    const answerArrowVisible = useRefutation
+        ? incorrectActive && missPhase === 'answer'
+        : showAnswerArrow;
+    useEffect(() => {
+        setShowAnswerArrow(false);
+        setIncorrectActive(false);
+        attemptMissedRef.current = false;
+        onMissFeedbackChange === null || onMissFeedbackChange === void 0 ? void 0 : onMissFeedbackChange(null);
+    }, [onMissFeedbackChange, position]);
+    useEffect(() => {
+        var _a, _b;
+        if (!onMissFeedbackChange) {
+            return;
+        }
+        if (useRefutation && incorrectActive) {
+            onMissFeedbackChange({
+                refutationSan: missBoard.refutation.refutationSan,
+                phase: (_b = (_a = missBoard.missSequence.sequence) === null || _a === void 0 ? void 0 : _a.phase) !== null && _b !== void 0 ? _b : null,
+                answerArrowVisible,
+            });
+            return;
+        }
+        if (showAnswerArrow) {
+            onMissFeedbackChange({
+                refutationSan: null,
+                phase: null,
+                answerArrowVisible: true,
+            });
+            return;
+        }
+        onMissFeedbackChange(null);
+    }, [
+        answerArrowVisible,
+        incorrectActive,
+        (_d = missBoard.missSequence.sequence) === null || _d === void 0 ? void 0 : _d.phase,
+        missBoard.refutation.refutationSan,
+        onMissFeedbackChange,
+        showAnswerArrow,
+        useRefutation,
+    ]);
+    if (position) {
+        boardOrientationRef.current = position.getPlayerColor();
+        boardFenRef.current = position.fen();
+    }
+    const boardOrientation = boardOrientationRef.current;
+    const boardFen = boardFenRef.current;
+    const hasBoard = boardFen !== EMPTY_BOARD_FEN;
+    const simpleArrows = useMemo(() => {
+        if (!showAnswerArrow || !position || useRefutation) {
+            return [];
+        }
+        const moveUci = position.getExpectedMoveUci();
+        if (moveUci.length < 4) {
+            return [];
+        }
+        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 missLocked = useRefutation &&
+        incorrectActive &&
+        (missBoard.boardAnimating ||
+            missPhase === 'wrong' ||
+            missPhase === 'refutation');
+    const arePiecesDraggable = position !== null && !positionLocked && !missLocked;
     const onPieceDrop = (sourceSquare, targetSquare, piece) => {
-        if (!position || position.isSolutionRevealed()) {
+        if (!position || positionLocked || position.isSolutionRevealed()) {
+            return false;
+        }
+        if (position.hasResumeConfig() && !position.isQuizIndex()) {
             return false;
         }
         if (!position.isLegalMove(sourceSquare, targetSquare)) {
             return false;
         }
-        const guess = position.tryGuess(sourceSquare, targetSquare, piece);
+        if (answerArrowVisible &&
+            !allowRetryOnIncorrect &&
+            !position.isExpectedGuess(sourceSquare, targetSquare)) {
+            position.resetInteractions();
+            snapBoardBack();
+            return false;
+        }
+        const guess = position.tryGuess(sourceSquare, targetSquare, piece, {
+            recordIfIncorrect: !(answerArrowVisible && !allowRetryOnIncorrect),
+        });
         if (!guess.accepted) {
+            attemptMissedRef.current = true;
             onFeedback({
                 index: position.getIndex(),
                 guess: { sourceSquare, targetSquare, piece },
                 isCorrect: false,
             });
-            incInteractionNum();
-            setTimeout(() => {
-                if (revealAnswerOnIncorrect) {
+            if (useRefutation) {
+                const setupFen = position.fen();
+                const attemptedUci = uciFromDrop(setupFen, sourceSquare, targetSquare, piece);
+                setIncorrectActive(true);
+                if (attemptedUci) {
+                    missBoard.missSequence.startSequence(setupFen, attemptedUci);
+                }
+                position.resetInteractions();
+                snapBoardBack();
+                return false;
+            }
+            const revealIncorrectFeedback = () => {
+                if (showAnswerArrowOnIncorrect) {
+                    position.resetInteractions();
+                    setShowAnswerArrow(true);
+                }
+                else if (revealAnswerOnIncorrect) {
                     position.resetInteractions();
                     position.revealCorrectMove();
                 }
                 else {
                     position.resetInteractions();
                 }
-                incInteractionNum();
-            }, 500);
+                snapBoardBack();
+            };
+            if (showAnswerArrowOnIncorrect && !allowRetryOnIncorrect) {
+                revealIncorrectFeedback();
+            }
+            else {
+                setTimeout(revealIncorrectFeedback, 500);
+            }
             return false;
         }
-        onFeedback({
+        setShowAnswerArrow(false);
+        setIncorrectActive(false);
+        missBoard.missSequence.clearSequence();
+        onMissFeedbackChange === null || onMissFeedbackChange === void 0 ? void 0 : onMissFeedbackChange(null);
+        const assistedByAnswerArrow = answerArrowVisible && attemptMissedRef.current;
+        const guessPayload = {
             index: position.getIndex(),
             guess: { sourceSquare, targetSquare, piece },
-            isCorrect: true,
-            isFinished: guess.finished,
-        });
-        incInteractionNum();
+        };
+        if (assistedByAnswerArrow) {
+            // Miss feedback for this ply is already saved; dragging along the answer
+            // arrow only continues the line — it must not count as a clean solve.
+            if (guess.finished) {
+                onFeedback(Object.assign(Object.assign({}, guessPayload), { isCorrect: false, isFinished: true }));
+            }
+        }
+        else {
+            onFeedback(Object.assign(Object.assign({}, guessPayload), { isCorrect: true, isFinished: guess.finished }));
+        }
+        notifyHost();
         setTimeout(() => {
             position.resetInteractions();
-            incInteractionNum();
+            notifyHost();
         }, 500);
         if (position.isAlternativeCheckmate()) {
-            incInteractionNum();
+            notifyHost();
             return true;
         }
         position.next();
-        incInteractionNum();
+        notifyHost();
+        if (position.hasResumeConfig()) {
+            onResumeCorrect === null || onResumeCorrect === void 0 ? void 0 : onResumeCorrect(position);
+            return true;
+        }
         setTimeout(() => {
             if (!position.isFinished()) {
                 position.next();
             }
-            incInteractionNum();
+            notifyHost();
         }, 500);
         return true;
     };
-    return (jsx(ChessboardDnDProvider, { children: jsx(HighlightChessboard, { boardWidth: boardWidth, checkSquare: (_a = position === null || position === void 0 ? void 0 : position.getCheckSquare()) !== null && _a !== void 0 ? _a : '', hintSquare: (_b = position === null || position === void 0 ? void 0 : position.getHintSquare()) !== null && _b !== void 0 ? _b : null, incorrectMoveSquare: (_c = position === null || position === void 0 ? void 0 : position.getIncorrectMoveSquare()) !== null && _c !== void 0 ? _c : null, onPieceDrop: onPieceDrop, position: (_d = position === null || position === void 0 ? void 0 : position.fen()) !== null && _d !== void 0 ? _d : EMPTY_BOARD_FEN, boardOrientation: (_e = position === null || position === void 0 ? void 0 : position.getPlayerColor()) !== null && _e !== void 0 ? _e : 'white', arePiecesDraggable: position !== null, promotionDialogVariant: "modal" }) }));
+    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), customArrows: customArrows, onPieceDrop: onPieceDrop, position: displayFen, boardOrientation: boardOrientation, arePiecesDraggable: arePiecesDraggable, areArrowsAllowed: false, promotionDialogVariant: "modal", animationDuration: 0 }, revision)) : null }));
 };
 
-const PuzzleBoard = ({ position, onFeedback, incInteractionNum, boardWidth, revealAnswerOnIncorrect = false, }) => (jsx(PuzzlePlaySurface, { position: position, onFeedback: onFeedback, incInteractionNum: incInteractionNum, boardWidth: boardWidth, revealAnswerOnIncorrect: revealAnswerOnIncorrect }));
+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 isAttemptFinished = (resultStatus) => resultStatus === 'complete' || resultStatus === 'incorrect';
 /** Library default hint / next / analysis / result controls (unstyled buttons). */
@@ -127,12 +278,10 @@ const DefaultPuzzleControls = ({ showHint, showSolution, nextPuzzle, resultStatu
 const defaultRenderControls = (showHint, showSolution, nextPuzzle, resultStatus, analysis, controlState) => (jsx(DefaultPuzzleControls, { showHint: showHint, showSolution: showSolution, nextPuzzle: nextPuzzle, resultStatus: resultStatus, analysis: analysis, controlState: controlState }));
 const rowStyle$1 = {
     display: 'flex',
-    flexWrap: 'wrap',
-    alignItems: 'center',
+    flexDirection: 'column',
+    alignItems: 'stretch',
     gap: 8,
     width: '100%',
-    minHeight: 96,
-    alignContent: 'flex-start',
 };
 const buttonStyle = {
     cursor: 'pointer',
@@ -150,27 +299,92 @@ const statusStyle$1 = {
 
 /** Default pixel width for the live puzzle board (analysis uses {@link DEFAULT_ANALYSIS_LAYOUT}). */
 const DEFAULT_PUZZLE_BOARD_WIDTH = 480;
-/** Minimum height reserved below the board so controls do not shift when status changes. */
-const PUZZLE_CONTROLS_MIN_HEIGHT = 96;
-const puzzlePlayColumnStyle = (boardWidth) => ({
+/** Width reserved for the vertical controls column beside the board. */
+const PUZZLE_CONTROLS_COLUMN_WIDTH = 160;
+/** Gap between the board column and controls column. */
+const PUZZLE_BOARD_CONTROLS_GAP = 16;
+/** Viewports at or below this width stack controls under the board (through tablet landscape). */
+const PUZZLE_CONTROLS_STACK_BREAKPOINT_PX = 1365;
+/** Horizontal space taken by the controls column when it sits beside the board. */
+const PUZZLE_CONTROLS_BESIDE_RESERVE_PX = PUZZLE_CONTROLS_COLUMN_WIDTH + PUZZLE_BOARD_CONTROLS_GAP;
+/** Minimum height reserved below the board so the caption slot does not shift between loads. */
+const PUZZLE_BOARD_CAPTION_MIN_HEIGHT = 24;
+const puzzlePlayRowStyle = (placement = 'beside') => ({
+    display: 'flex',
+    flexDirection: placement === 'below' ? 'column' : 'row',
+    alignItems: placement === 'below' ? 'stretch' : 'flex-start',
+    gap: PUZZLE_BOARD_CONTROLS_GAP,
+    width: placement === 'below' ? '100%' : 'fit-content',
+    maxWidth: '100%',
+});
+const puzzleBoardColumnStyle = (boardWidth, placement = 'beside') => ({
     display: 'flex',
     flexDirection: 'column',
     width: boardWidth,
     maxWidth: '100%',
+    flexShrink: 0,
+    alignSelf: placement === 'below' ? 'center' : undefined,
+});
+const puzzleBoardCaptionSlotStyle = () => ({
+    width: '100%',
+    minHeight: PUZZLE_BOARD_CAPTION_MIN_HEIGHT,
+    flexShrink: 0,
+    display: 'flex',
+    justifyContent: 'center',
+    alignItems: 'center',
+    marginTop: 4,
+});
+const puzzleBoardSlotWrapperStyle = () => ({
+    position: 'relative',
+    width: '100%',
+    flexShrink: 0,
 });
 const puzzleBoardSlotStyle = () => ({
     width: '100%',
     aspectRatio: '1 / 1',
     flexShrink: 0,
 });
-const puzzleControlsSlotStyle = () => ({
-    minHeight: PUZZLE_CONTROLS_MIN_HEIGHT,
-    flexShrink: 0,
+const puzzleControlsFeedbackStyle = (placement = 'beside') => ({
     display: 'flex',
-    alignItems: 'flex-start',
-    marginTop: 8,
+    flexDirection: 'column',
+    alignItems: placement === 'below' ? 'center' : 'flex-end',
+    gap: 4,
+    marginTop: placement === 'below' ? 0 : 'auto',
+    pointerEvents: 'none',
+});
+const puzzleControlsSlotStyle = (placement = 'beside') => ({
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'stretch',
+    gap: 8,
+    flexShrink: 0,
+    minWidth: placement === 'below' ? undefined : PUZZLE_CONTROLS_COLUMN_WIDTH,
+    width: placement === 'below' ? '100%' : undefined,
+    alignSelf: 'stretch',
 });
 
+const stackControlsQuery = `(max-width: ${PUZZLE_CONTROLS_STACK_BREAKPOINT_PX}px)`;
+const readStackControlsBelow = () => {
+    if (typeof window === 'undefined') {
+        return false;
+    }
+    return window.matchMedia(stackControlsQuery).matches;
+};
+/** True when hint / next controls should sit below the board instead of beside it. */
+const useStackPuzzleControlsBelow = () => {
+    const [stackBelow, setStackBelow] = useState(readStackControlsBelow);
+    useEffect(() => {
+        const mediaQueryList = window.matchMedia(stackControlsQuery);
+        const onChange = (event) => {
+            setStackBelow(event.matches);
+        };
+        mediaQueryList.addEventListener('change', onChange);
+        setStackBelow(mediaQueryList.matches);
+        return () => mediaQueryList.removeEventListener('change', onChange);
+    }, []);
+    return stackBelow;
+};
+
 /** Apply a UCI move (e.g. `e7e8q`) without throwing. */
 function applyUciMove(chess, uci) {
     if (!uci || uci.length < 4) {
@@ -231,6 +445,9 @@ class Position {
     fen() {
         return this.chess.fen();
     }
+    getSideToMove() {
+        return this.chess.turn() === 'w' ? 'white' : 'black';
+    }
     getCheckSquare() {
         return getCheckSquareFromChess(this.chess);
     }
@@ -260,7 +477,7 @@ function playerColorForSolution(initialFen, moves) {
     return chess.turn() === 'w' ? 'white' : 'black';
 }
 class PuzzlePosition extends Position {
-    constructor(initialFEN, moves) {
+    constructor(initialFEN, moves, resumeConfig) {
         super();
         this.isCorrect = false;
         this.guessedMove = '';
@@ -268,7 +485,7 @@ class PuzzlePosition extends Position {
         this.solutionRevealed = false;
         this.moveHistory = [];
         this.usedAlternativeCheckmate = false;
-        this.tryGuess = (sourceSquare, targetSquare, piece) => {
+        this.tryGuess = (sourceSquare, targetSquare, piece, options) => {
             var _a;
             const candidates = this.buildCandidateUcis(sourceSquare, targetSquare);
             if (candidates.length === 0) {
@@ -294,12 +511,14 @@ class PuzzlePosition extends Position {
             }
             this.isCorrect = false;
             this.guessedMove = `${sourceSquare}${targetSquare}`;
-            this.moveHistory.push({
-                ply: this.moveHistory.length,
-                uci: (_a = candidates[candidates.length - 1]) !== null && _a !== void 0 ? _a : this.guessedMove,
-                actor: 'attempt',
-                isCorrect: false,
-            });
+            if ((options === null || options === void 0 ? void 0 : options.recordIfIncorrect) !== false) {
+                this.moveHistory.push({
+                    ply: this.moveHistory.length,
+                    uci: (_a = candidates[candidates.length - 1]) !== null && _a !== void 0 ? _a : this.guessedMove,
+                    actor: 'attempt',
+                    isCorrect: false,
+                });
+            }
             return { accepted: false, finished: false };
         };
         this.judgeGuess = (sourceSquare, targetSquare, piece) => this.tryGuess(sourceSquare, targetSquare, piece).accepted;
@@ -307,6 +526,12 @@ class PuzzlePosition extends Position {
         this.chess.load(initialFEN);
         this.moves = moves;
         this.playerColor = playerColorForSolution(initialFEN, moves);
+        this.resumeConfig = resumeConfig;
+        if (resumeConfig) {
+            for (let j = 0; j < resumeConfig.startIndex; j++) {
+                super.next();
+            }
+        }
     }
     next() {
         if (this.i >= this.moves.length) {
@@ -419,6 +644,12 @@ class PuzzlePosition extends Position {
         this.usedAlternativeCheckmate = true;
         return true;
     }
+    /** True when dragging from/to matches the expected move at the current index. */
+    isExpectedGuess(sourceSquare, targetSquare) {
+        const candidates = this.buildCandidateUcis(sourceSquare, targetSquare);
+        const expectedUci = this.moves[this.i];
+        return candidates.some((uci) => uci === expectedUci);
+    }
     resetInteractions() {
         this.guessedMove = '';
         this.isHintWanted = false;
@@ -456,9 +687,27 @@ class PuzzlePosition extends Position {
         }
         return this.guessedMove.slice(2, 4);
     }
+    /** UCI of the move the player should play at the current index. */
+    getExpectedMoveUci() {
+        var _a;
+        return (_a = this.moves[this.i]) !== null && _a !== void 0 ? _a : '';
+    }
     getPlayerColor() {
         return this.playerColor;
     }
+    hasResumeConfig() {
+        return this.resumeConfig !== undefined;
+    }
+    getResumeConfig() {
+        return this.resumeConfig;
+    }
+    /** True when the user must find the move at the current index. */
+    isQuizIndex() {
+        if (!this.resumeConfig) {
+            return !this.isFinished();
+        }
+        return this.resumeConfig.quizAtIndices.includes(this.i);
+    }
 }
 class GamePosition extends Position {
     constructor(PGN) {
@@ -471,19 +720,36 @@ class GamePosition extends Position {
     }
 }
 
-/** Delay before auto-playing the opponent's opening move (ms). */
-const OPPONENT_OPENING_MOVE_DELAY_MS = 500;
+/** Apply the opponent setup ply 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();
+    }
+    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 PuzzleBoardWithControls = ({ theme, apiProxy, renderControls = defaultRenderControls, renderAnalysisSidebar, renderAnalysisContainer, renderEngineEvaluation, puzzleBoardWidth = DEFAULT_PUZZLE_BOARD_WIDTH, analysisLayout = DEFAULT_ANALYSIS_LAYOUT, renderAnalysisMain, engine, autoAdvanceOnComplete = false, revealAnswerOnIncorrect = false, }) => {
+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, renderAnalysisMain, engine, autoAdvanceOnComplete = false, autoAdvanceOnCompleteAfterIncorrect = 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();
+    const controlsPlacement = stackControlsBelow
+        ? 'below'
+        : 'beside';
     const { onFetch, onFetchError, onFeedback } = apiProxy;
     const [position, setPosition] = useState(null);
+    const [loadingNextPuzzle, setLoadingNextPuzzle] = useState(true);
     const [puzzleNum, setPuzzleNum] = useState(0);
     const [hasIncorrectAttempt, setHasIncorrectAttempt] = useState(false);
     const [puzzleComplete, setPuzzleComplete] = useState(false);
+    const [completedAfterMiss, setCompletedAfterMiss] = useState(false);
+    const [missFeedback, setMissFeedback] = useState(null);
     const [, setInteractionNum] = useState(0);
     const solutionAnimationRef = useRef({ cancelled: false, timeoutIds: [] });
+    const resumeAnimationRef = useRef({ cancelled: false, timeoutIds: [] });
     const incInteractionNum = () => {
         setInteractionNum((prev) => prev + 1);
     };
@@ -493,57 +759,58 @@ const PuzzleBoardWithControls = ({ theme, apiProxy, renderControls = defaultRend
         anim.timeoutIds.forEach(clearTimeout);
         solutionAnimationRef.current = { cancelled: false, timeoutIds: [] };
     };
+    const clearResumeAnimation = () => {
+        const anim = resumeAnimationRef.current;
+        anim.cancelled = true;
+        anim.timeoutIds.forEach(clearTimeout);
+        resumeAnimationRef.current = { cancelled: false, timeoutIds: [] };
+    };
     useEffect(() => {
         let cancelled = false;
-        let openingMoveTimeoutId;
-        setPosition(null);
+        setLoadingNextPuzzle(true);
         setHasIncorrectAttempt(false);
         setPuzzleComplete(false);
+        setCompletedAfterMiss(false);
+        setMissFeedback(null);
         onFetch()
             .then((data) => {
             if (cancelled) {
                 return;
             }
-            if (!data || !data.fen || !data.moves) {
+            if (!(data === null || data === void 0 ? void 0 : data.fen) || !Array.isArray(data.moves) || data.moves.length === 0) {
                 console.error('Invalid data fetched:', data);
+                setLoadingNextPuzzle(false);
                 return;
             }
-            const newPosition = new PuzzlePosition(data.fen, data.moves);
-            setPosition(newPosition);
-            // Multi-move puzzles lead with an opponent setup ply; single-move lines
-            // (e.g. a first-ply opening trainer) are already on the player to move.
-            if (data.moves.length > 1) {
-                openingMoveTimeoutId = setTimeout(() => {
-                    if (cancelled) {
-                        return;
-                    }
-                    if (newPosition.next()) {
-                        incInteractionNum();
-                    }
-                }, OPPONENT_OPENING_MOVE_DELAY_MS);
-            }
+            setPosition(puzzlePositionFromFetch(data.fen, data.moves, data.resume));
+            requestAnimationFrame(() => {
+                if (!cancelled) {
+                    setLoadingNextPuzzle(false);
+                }
+            });
         })
             .catch((error) => {
             if (!cancelled) {
+                setLoadingNextPuzzle(false);
                 onFetchError === null || onFetchError === void 0 ? void 0 : onFetchError(error);
             }
         });
         return () => {
             cancelled = true;
             clearSolutionAnimation();
-            if (openingMoveTimeoutId !== undefined) {
-                clearTimeout(openingMoveTimeoutId);
-            }
+            clearResumeAnimation();
         };
     }, [puzzleNum]);
     const handleFeedback = (feedbackData) => {
-        if (feedbackData.hintRequested ||
+        const incorrectThisFeedback = feedbackData.hintRequested ||
             feedbackData.solutionShown ||
-            feedbackData.isCorrect === false) {
+            feedbackData.isCorrect === false;
+        if (incorrectThisFeedback) {
             setHasIncorrectAttempt(true);
         }
         if (feedbackData.isFinished) {
             setPuzzleComplete(true);
+            setCompletedAfterMiss(hasIncorrectAttempt || incorrectThisFeedback);
         }
         onFeedback(feedbackData);
     };
@@ -637,6 +904,53 @@ const PuzzleBoardWithControls = ({ theme, apiProxy, renderControls = defaultRend
         };
         advance();
     };
+    const runResumeAutoAdvance = (pos) => {
+        clearResumeAnimation();
+        const anim = {
+            cancelled: false,
+            timeoutIds: [],
+        };
+        resumeAnimationRef.current = anim;
+        const schedule = (fn, ms) => {
+            const id = setTimeout(() => {
+                if (anim.cancelled) {
+                    return;
+                }
+                fn();
+            }, ms);
+            anim.timeoutIds.push(id);
+        };
+        const finish = () => {
+            setPuzzleComplete(true);
+            handleFeedback({
+                index: pos.getIndex(),
+                isCorrect: true,
+                isFinished: true,
+            });
+            incInteractionNum();
+        };
+        const step = () => {
+            if (anim.cancelled) {
+                return;
+            }
+            if (pos.isFinished()) {
+                finish();
+                return;
+            }
+            if (pos.isQuizIndex()) {
+                return;
+            }
+            if (!pos.next()) {
+                if (pos.isFinished()) {
+                    finish();
+                }
+                return;
+            }
+            incInteractionNum();
+            schedule(step, RESUME_AUTO_STEP_MS);
+        };
+        schedule(step, RESUME_AUTO_STEP_MS);
+    };
     const handleShowSolution = () => {
         if (!position) {
             return;
@@ -670,7 +984,10 @@ const PuzzleBoardWithControls = ({ theme, apiProxy, renderControls = defaultRend
         if (!autoAdvanceOnComplete) {
             return;
         }
-        if (resultStatus !== 'complete' || hasIncorrectAttempt) {
+        if (resultStatus !== 'complete') {
+            return;
+        }
+        if (hasIncorrectAttempt && !autoAdvanceOnCompleteAfterIncorrect) {
             return;
         }
         const timer = setTimeout(() => {
@@ -681,6 +998,7 @@ const PuzzleBoardWithControls = ({ theme, apiProxy, renderControls = defaultRend
         };
     }, [
         autoAdvanceOnComplete,
+        autoAdvanceOnCompleteAfterIncorrect,
         resultStatus,
         hasIncorrectAttempt,
         handleNextPuzzle,
@@ -688,8 +1006,9 @@ const PuzzleBoardWithControls = ({ theme, apiProxy, renderControls = defaultRend
     ]);
     const controlState = {
         canShowHint: position !== null &&
-            resultStatus === 'none' &&
-            !position.isSolutionRevealed(),
+            !position.isFinished() &&
+            !position.isSolutionRevealed() &&
+            !(hasIncorrectAttempt && showAnswerArrowOnIncorrect && !allowRetryOnIncorrect),
         canShowSolution: position !== null &&
             (position.isSolutionRevealed() || !position.isFinished()),
     };
@@ -698,10 +1017,27 @@ const PuzzleBoardWithControls = ({ theme, apiProxy, renderControls = defaultRend
     const useHostAnalysisUi = Boolean(renderAnalysisSidebar &&
         renderAnalysisContainer &&
         (renderEngineEvaluation || (engine === null || engine === void 0 ? void 0 : engine.enabled) === false));
-    return (jsx(ThemeProvider, { theme: theme, children: analysisSnapshot ? (jsx(AnalysisErrorBoundary, { onClose: analysis.closeAnalysis, children: useHostAnalysisUi ? (jsx(AnalysisBoardCore, { analysisContext: analysisSnapshot, onClose: analysis.closeAnalysis, theme: theme, boardWidth: analysisLayout.boardWidth, 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: puzzlePlayColumnStyle(puzzleBoardWidth), children: [jsx("div", { style: puzzleBoardSlotStyle(), children: jsx(PuzzlePlaySurface, { position: position, boardWidth: puzzleBoardWidth, onFeedback: handleFeedback, incInteractionNum: incInteractionNum, revealAnswerOnIncorrect: revealAnswerOnIncorrect }) }), jsx("div", { style: puzzleControlsSlotStyle(), children: renderControls(handleHintRequest, handleShowSolution, handleNextPuzzle, resultStatus, {
-                        visible: analysis.canOpen,
-                        openAnalysis: analysis.openAnalysis,
-                    }, controlState) })] })) }));
+    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: analysisLayout.boardWidth, 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({
+                                sideToMove: (_a = position === null || position === void 0 ? void 0 : position.getSideToMove()) !== null && _a !== void 0 ? _a : null,
+                                playerColor: position
+                                    ? position.getPlayerColor()
+                                    : null,
+                                incorrectAttempt: resultStatus === 'incorrect',
+                                complete: resultStatus === 'complete',
+                                cleanSolve: !hasIncorrectAttempt,
+                                refutationSan: (_b = missFeedback === null || missFeedback === void 0 ? void 0 : missFeedback.refutationSan) !== null && _b !== void 0 ? _b : null,
+                                missPhase: (_c = missFeedback === null || missFeedback === void 0 ? void 0 : missFeedback.phase) !== null && _c !== void 0 ? _c : null,
+                                answerArrowVisible: (_d = missFeedback === null || missFeedback === void 0 ? void 0 : missFeedback.answerArrowVisible) !== null && _d !== void 0 ? _d : false,
+                                completedAfterMiss,
+                            }) }))] }), 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({
+                                resultStatus,
+                                cleanSolve: !hasIncorrectAttempt,
+                                refutationSan: missFeedback === null || missFeedback === void 0 ? void 0 : missFeedback.refutationSan,
+                                missPhase: missFeedback === null || missFeedback === void 0 ? void 0 : missFeedback.phase,
+                            }) }))] })] })) }));
 };
 
 /**
@@ -744,7 +1080,7 @@ const boardOrientationForLine = (side) => side === 'b' ? 'black' : 'white';
  * tactical puzzles. Mount one instance per drill (key it by line) so its
  * internal state resets between lines.
  */
-const LineBoardWithControls = ({ theme, line, onComplete, onMove, renderControls = defaultRenderLineControls, boardWidth = DEFAULT_PUZZLE_BOARD_WIDTH, opponentMoveDelayMs = DEFAULT_OPPONENT_MOVE_DELAY_MS, }) => {
+const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, renderControls = defaultRenderLineControls, boardWidth = DEFAULT_PUZZLE_BOARD_WIDTH, opponentMoveDelayMs = DEFAULT_OPPONENT_MOVE_DELAY_MS, }) => {
     const chessRef = useRef(new Chess(line.startFen));
     const perMoveRef = useRef([]);
     const completedRef = useRef(false);
@@ -808,8 +1144,8 @@ const LineBoardWithControls = ({ theme, line, onComplete, onMove, renderControls
         completedRef.current = true;
         onCompleteRef.current(perMoveRef.current);
     }, [finished]);
-    const handleDrop = (source, target) => {
-        var _a, _b, _c, _d;
+    const handleDrop = (source, target, piece) => {
+        var _a, _b, _c;
         if (finished) {
             return false;
         }
@@ -817,31 +1153,27 @@ const LineBoardWithControls = ({ theme, line, onComplete, onMove, renderControls
             return false;
         }
         const index = currentIndex;
-        let userUci;
-        try {
-            const probe = new Chess(chessRef.current.fen());
-            const move = probe.move({ from: source, to: target, promotion: 'q' });
-            if (!move) {
-                return false;
-            }
-            userUci = `${move.from}${move.to}${(_a = move.promotion) !== null && _a !== void 0 ? _a : ''}`;
-        }
-        catch (_e) {
+        const expected = line.movesUci[index];
+        const dropResult = evaluateExpectedMoveDrop(chessRef.current.fen(), source, target, piece, expected, true);
+        if (dropResult.kind === 'illegal' || dropResult.kind === 'ignored') {
             return false;
         }
-        const expected = line.movesUci[index];
-        const isCorrect = userUci.toLowerCase() === expected.toLowerCase();
-        const expectedSan = (_c = (_b = line.movesSan) === null || _b === void 0 ? void 0 : _b[index]) !== null && _c !== void 0 ? _c : expected;
+        const isCorrect = dropResult.kind === 'correct';
+        const expectedSan = (_b = (_a = line.movesSan) === null || _a === void 0 ? void 0 : _a[index]) !== null && _b !== void 0 ? _b : expected;
         perMoveRef.current.push({ index, isCorrect });
         const moveFeedback = { index, isCorrect, expectedSan };
         setFeedback(moveFeedback);
-        (_d = onMoveRef.current) === null || _d === void 0 ? void 0 : _d.call(onMoveRef, moveFeedback);
+        (_c = onMoveRef.current) === null || _c === void 0 ? void 0 : _c.call(onMoveRef, moveFeedback);
         applyMove(index);
         return isCorrect;
     };
     const moveNumber = Math.min(currentIndex + 1, total);
     const isUserTurn = !finished && turnFromFen(fen) === line.trainSide && currentIndex < total;
-    return (jsx(ThemeProvider, { theme: theme, children: jsxs("div", { style: puzzlePlayColumnStyle(boardWidth), children: [jsx("div", { style: puzzleBoardSlotStyle(), children: jsx(LineBoard, { fen: fen, orientation: orientation, trainSide: line.trainSide, draggable: isUserTurn, onPieceDrop: handleDrop, boardWidth: boardWidth }) }), jsx("div", { style: puzzleControlsSlotStyle(), children: renderControls({
+    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: fen, orientation: orientation, trainSide: line.trainSide, draggable: isUserTurn, onPieceDrop: handleDrop, boardWidth: boardWidth }) }) }), jsx("div", { style: puzzleControlsSlotStyle(controlsPlacement), children: renderControls({
                         trainSide: line.trainSide,
                         moveNumber,
                         total,
@@ -858,4 +1190,4 @@ const LineBoardWithControls = ({ theme, line, onComplete, onMove, renderControls
 /** @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, 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, applyUciMove, buildAnalysisContext, defaultRenderControls, defaultRenderLineControls, emptyAnalysisContext, getCheckSquareFromChess, isAnalysisAvailable, playerColorForSolution, squareHighlightColors, usePuzzleAnalysis };