react-chess-puzzle-kit 1.0.7 → 1.0.9

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

@@ -1,5 +1,5 @@
 import React from 'react';
-import { type BoardThemeId } from 'react-chess-core';
+import { type AnalysisEngineOptions, type BoardThemeId } from 'react-chess-core';
 export type LineTrainSide = 'w' | 'b';
 /** A line to drill: a start position plus the moves to walk, from one side. */
 export interface LineSpec {
@@ -38,6 +38,12 @@ export interface LineBoardWithControlsProps {
     onMove?: (feedback: LineMoveFeedback) => void;
     /** Omit to use {@link defaultRenderLineControls}. */
     renderControls?: (props: LineControlsRenderProps) => React.ReactNode;
+    /** Optional content above the board (e.g. eval bar), inside play-time engine context. */
+    renderAboveBoard?: (props: {
+        fen: string;
+    }) => React.ReactNode;
+    /** Stockfish options when {@link renderAboveBoard} is set. */
+    playTimeEngine?: AnalysisEngineOptions;
     boardWidth?: number;
     /** Delay before auto-playing each opponent move (ms). */
     opponentMoveDelayMs?: number;
@@ -49,4 +55,4 @@ export interface LineBoardWithControlsProps {
  * tactical puzzles. Mount one instance per drill (key it by line) so its
  * internal state resets between lines.
  */
-export declare const LineBoardWithControls: ({ theme, boardTheme, line, onComplete, onMove, renderControls, boardWidth, opponentMoveDelayMs, }: LineBoardWithControlsProps) => React.JSX.Element;
+export declare const LineBoardWithControls: ({ theme, boardTheme, line, onComplete, onMove, renderControls, renderAboveBoard, playTimeEngine, boardWidth, opponentMoveDelayMs, }: LineBoardWithControlsProps) => React.JSX.Element;

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

@@ -82,6 +82,10 @@ export interface PuzzleBoardWithControlsProps {
     renderAnalysisSidebar?: (props: AnalysisSidebarRenderProps) => React.ReactNode;
     renderAnalysisContainer?: (props: AnalysisContainerRenderProps) => React.ReactNode;
     renderEngineEvaluation?: (props: EngineEvaluationRenderProps) => React.ReactNode;
+    /** Optional content above the board (e.g. eval bar), inside play-time engine context. */
+    renderAboveBoard?: (props: {
+        fen: string;
+    }) => React.ReactNode;
     /** Optional label below the board (e.g. side to move). */
     renderBoardCaption?: (props: BoardCaptionRenderProps) => React.ReactNode;
     /** Optional result feedback shown at the bottom of the controls column. */
@@ -95,6 +99,8 @@ export interface PuzzleBoardWithControlsProps {
     /** Custom board/sidebar placement (overrides {@link analysisLayout} grid). */
     renderAnalysisMain?: (props: AnalysisMainRenderProps) => React.ReactNode;
     engine?: AnalysisEngineOptions;
+    /** Background multipv on the setup position for instant refutation (silent on puzzles). */
+    playTimeEngine?: AnalysisEngineOptions;
     /** After a clean solve (no wrong move, hint, or solution reveal), load the next card. */
     autoAdvanceOnComplete?: boolean;
     /** With {@link autoAdvanceOnComplete}, also advance after finishing following a miss or hint. */
@@ -117,4 +123,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, autoAdvanceOnCompleteDelayMs, showCompletionRecap, revealAnswerOnIncorrect, showAnswerArrowOnIncorrect, allowRetryOnIncorrect, showRefutationOnIncorrect, autoShowWrongMoves, refutationEngine, answerArrowColor, }: PuzzleBoardWithControlsProps) => React.JSX.Element;
+export declare const PuzzleBoardWithControls: ({ theme, boardTheme, apiProxy, renderControls, renderAnalysisSidebar, renderAnalysisContainer, renderEngineEvaluation, renderAboveBoard, renderBoardCaption, renderBoardFeedback, puzzleBoardWidth, analysisLayout, analysisBoardWidth, renderAnalysisMain, engine, playTimeEngine, autoAdvanceOnComplete, autoAdvanceOnCompleteAfterIncorrect, autoAdvanceOnCompleteDelayMs, showCompletionRecap, revealAnswerOnIncorrect, showAnswerArrowOnIncorrect, allowRetryOnIncorrect, showRefutationOnIncorrect, autoShowWrongMoves, refutationEngine, answerArrowColor, }: PuzzleBoardWithControlsProps) => React.JSX.Element;

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, useIncorrectMoveFeedback, useMissBoard, HighlightChessboard, DEFAULT_ANSWER_ARROW_COLOR, uciFromDrop, fenAtPlyFromStart, useSolutionLineRecap, lastMoveUciAtPly, ThemeProvider, AnalysisErrorBoundary, AnalysisBoardCore, AnalysisBoardLayout, AnalysisBoard, BoardCompleteCheckOverlay, DEFAULT_ANALYSIS_LAYOUT, AUTO_ADVANCE_ON_COMPLETE_DELAY_MS, evaluateExpectedMoveDrop, fenAfterUci, boardSquareHighlightColors, analysisBoardHighlightColors } from 'react-chess-core';
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+import { useBoardRevision, useCorrectMoveFeedback, useIncorrectMoveFeedback, useMissBoard, HighlightChessboard, DEFAULT_ANSWER_ARROW_COLOR, uciFromDrop, fenAtPlyFromStart, useSolutionLineRecap, lastMoveUciAtPly, isAnalyzableFen, ThemeProvider, AnalysisErrorBoundary, AnalysisBoardCore, AnalysisBoardLayout, AnalysisBoard, PlayTimeEngineProvider, BoardCompleteCheckOverlay, DEFAULT_ANALYSIS_LAYOUT, AUTO_ADVANCE_ON_COMPLETE_DELAY_MS, evaluateExpectedMoveDrop, fenAfterUci, boardSquareHighlightColors, analysisBoardHighlightColors } from 'react-chess-core';
 export { DEFAULT_ANALYSIS_LAYOUT } from 'react-chess-core';
 import { Chess } from 'chess.js';
 
@@ -61,7 +61,7 @@ const EMPTY_BOARD_FEN = '8/8/8/8/8/8/8/8 w - - 0 1';
  * 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, recapBoard = null, }) => {
-    var _a, _b, _c, _d, _e, _f, _g;
+    var _a, _b, _c, _d, _e;
     const [showAnswerArrow, setShowAnswerArrow] = useState(false);
     const [incorrectActive, setIncorrectActive] = useState(false);
     const attemptMissedRef = useRef(false);
@@ -98,16 +98,14 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         autoShowWrongMoves: useRefutation ? true : autoShowWrongMoves,
         engineOptions: refutationEngine,
     });
-    const missPhase = (_c = missBoard.missSequence.sequence) === null || _c === void 0 ? void 0 : _c.phase;
+    const missPhase = missBoard.phase;
     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;
+    const overlayIncorrectSquare = useRefutation && incorrectActive
+        ? missBoard.incorrectMoveSquare
+        : transientIncorrectSquare;
+    const refutationMoveSquare = useRefutation && incorrectActive ? missBoard.refutationMoveSquare : null;
     useEffect(() => {
         setShowAnswerArrow(false);
         setIncorrectActive(false);
@@ -122,14 +120,13 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         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,
+                phase: missBoard.phase,
                 answerArrowVisible,
             });
             return;
@@ -146,7 +143,7 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
     }, [
         answerArrowVisible,
         incorrectActive,
-        (_d = missBoard.missSequence.sequence) === null || _d === void 0 ? void 0 : _d.phase,
+        missBoard.phase,
         missBoard.refutation.refutationSan,
         onMissFeedbackChange,
         showAnswerArrow,
@@ -186,12 +183,8 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         ? recapBoard.lastMoveUci
         : useRefutation && incorrectActive
             ? missBoard.lastMoveUci
-            : ((_e = position === null || position === void 0 ? void 0 : position.getLastMoveUci()) !== null && _e !== void 0 ? _e : null);
-    const missLocked = useRefutation &&
-        incorrectActive &&
-        (missBoard.boardAnimating ||
-            missPhase === 'wrong' ||
-            missPhase === 'refutation');
+            : ((_c = position === null || position === void 0 ? void 0 : position.getLastMoveUci()) !== null && _c !== void 0 ? _c : null);
+    const missLocked = useRefutation && incorrectActive && missBoard.inputLocked;
     const arePiecesDraggable = !isRecapping &&
         position !== null &&
         !positionLocked &&
@@ -221,7 +214,9 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         });
         if (!guess.accepted) {
             attemptMissedRef.current = true;
-            showIncorrectMove(useRefutation ? targetSquare : sourceSquare);
+            if (!useRefutation) {
+                showIncorrectMove(sourceSquare);
+            }
             onFeedback({
                 index: position.getIndex(),
                 guess: { sourceSquare, targetSquare, piece },
@@ -301,7 +296,11 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         showCorrectMove(targetSquare, finishCorrectFeedback);
         return true;
     };
-    return hasBoard ? (jsx(HighlightChessboard, { boardWidth: boardWidth, checkSquare: isRecapping ? '' : ((_f = position === null || position === void 0 ? void 0 : position.getCheckSquare()) !== null && _f !== void 0 ? _f : ''), hintSquare: isRecapping ? null : ((_g = position === null || position === void 0 ? void 0 : position.getHintSquare()) !== null && _g !== void 0 ? _g : null), incorrectMoveSquare: isRecapping ? null : overlayIncorrectSquare, refutationMoveSquare: isRecapping ? null : refutationMoveSquare, correctMoveSquare: isRecapping ? null : correctMoveSquare, customArrows: customArrows, lastMoveUci: lastMoveUci, onPieceDrop: onPieceDrop, position: displayFen, boardOrientation: boardOrientation, arePiecesDraggable: arePiecesDraggable, areArrowsAllowed: false, promotionDialogVariant: "modal", animationDuration: isRecapping ? recapBoard.animationDuration : 0 }, revision)) : null;
+    return hasBoard ? (jsx(HighlightChessboard, { boardWidth: boardWidth, checkSquare: isRecapping ? '' : ((_d = position === null || position === void 0 ? void 0 : position.getCheckSquare()) !== null && _d !== void 0 ? _d : ''), hintSquare: isRecapping ? null : ((_e = position === null || position === void 0 ? void 0 : position.getHintSquare()) !== null && _e !== void 0 ? _e : null), incorrectMoveSquare: isRecapping ? null : overlayIncorrectSquare, refutationMoveSquare: isRecapping ? null : refutationMoveSquare, correctMoveSquare: isRecapping ? null : correctMoveSquare, customArrows: customArrows, lastMoveUci: lastMoveUci, onPieceDrop: onPieceDrop, position: displayFen, boardOrientation: boardOrientation, arePiecesDraggable: arePiecesDraggable, areArrowsAllowed: false, promotionDialogVariant: "modal", animationDuration: isRecapping
+            ? recapBoard.animationDuration
+            : useRefutation && incorrectActive
+                ? missBoard.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 }));
@@ -370,6 +369,7 @@ const usePuzzleCompletionRecap = ({ source, active, onComplete, }) => {
         segmentStartFen: startFen,
         setupUci,
         onComplete,
+        completeImmediatelyWhenNoMisses: true,
         resolveFen,
     });
 };
@@ -879,8 +879,8 @@ const buildCompletionRecapSource = (position, 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 PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls = defaultRenderControls, renderAnalysisSidebar, renderAnalysisContainer, renderEngineEvaluation, renderAboveBoard, renderBoardCaption, renderBoardFeedback, puzzleBoardWidth = DEFAULT_PUZZLE_BOARD_WIDTH, analysisLayout = DEFAULT_ANALYSIS_LAYOUT, analysisBoardWidth, renderAnalysisMain, engine, playTimeEngine, 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, _e;
     const refutationOnIncorrect = showRefutationOnIncorrect !== null && showRefutationOnIncorrect !== void 0 ? showRefutationOnIncorrect : showAnswerArrowOnIncorrect;
     const stackControlsBelow = useStackPuzzleControlsBelow();
     const controlsPlacement = stackControlsBelow
@@ -1176,8 +1176,12 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
             return;
         }
         completionFlowStartedRef.current = true;
+        if (missedMoveIndices.length === 0) {
+            setCompletionRecapDone(true);
+            return;
+        }
         setCompletionCheckVisible(true);
-    }, [loadingNextPuzzle, resultStatus, showCompletionRecap]);
+    }, [loadingNextPuzzle, missedMoveIndices, resultStatus, showCompletionRecap]);
     useEffect(() => {
         if (!completionCheckVisible) {
             return;
@@ -1206,32 +1210,38 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
             (position.isSolutionRevealed() || !position.isFinished()),
     };
     const analysisSnapshot = analysis.isOpen && analysis.snapshot ? analysis.snapshot : null;
+    const setupFen = (_a = position === null || position === void 0 ? void 0 : position.fen()) !== null && _a !== void 0 ? _a : '';
+    const playTimeEnabled = Boolean(position) &&
+        !(position === null || position === void 0 ? void 0 : position.isFinished()) &&
+        !analysisSnapshot &&
+        isAnalyzableFen(setupFen);
+    const resolvedPlayTimeEngine = useMemo(() => (Object.assign({ scriptUrl: engine === null || engine === void 0 ? void 0 : engine.scriptUrl }, playTimeEngine)), [engine === null || engine === void 0 ? void 0 : engine.scriptUrl, playTimeEngine]);
     const resolvedAnalysisBoardWidth = analysisBoardWidth !== null && analysisBoardWidth !== void 0 ? analysisBoardWidth : analysisLayout.boardWidth;
     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: [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,
+    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(PlayTimeEngineProvider, { fen: setupFen, enabled: playTimeEnabled, options: resolvedPlayTimeEngine, children: [renderAboveBoard === null || renderAboveBoard === void 0 ? void 0 : renderAboveBoard({ fen: setupFen }), 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: (_b = position === null || position === void 0 ? void 0 : position.getSideToMove()) !== null && _b !== void 0 ? _b : 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,
+                                refutationSan: (_c = missFeedback === null || missFeedback === void 0 ? void 0 : missFeedback.refutationSan) !== null && _c !== void 0 ? _c : null,
+                                missPhase: (_d = missFeedback === null || missFeedback === void 0 ? void 0 : missFeedback.phase) !== null && _d !== void 0 ? _d : null,
+                                answerArrowVisible: (_e = missFeedback === null || missFeedback === void 0 ? void 0 : missFeedback.answerArrowVisible) !== null && _e !== void 0 ? _e : false,
                                 completedAfterMiss,
                                 hintUsed,
                             }) }))] }), jsxs("div", { style: puzzleControlsSlotStyle(controlsPlacement), children: [renderControls(handleHintRequest, handleShowSolution, handleNextPuzzle, resultStatus, {
@@ -1286,7 +1296,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, boardTheme, 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, renderAboveBoard, playTimeEngine, 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);
@@ -1411,7 +1421,9 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
     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, incorrectMoveSquare: incorrectMoveSquare, lastMoveUci: lastMoveUci, onPieceDrop: handleDrop, boardWidth: boardWidth }) }) }), jsx("div", { style: puzzleControlsSlotStyle(controlsPlacement), children: renderControls({
+    const playTimeEnabled = isAnalyzableFen(boardFen);
+    const boardColumn = (jsxs(Fragment, { children: [renderAboveBoard === null || renderAboveBoard === void 0 ? void 0 : renderAboveBoard({ fen: boardFen }), 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 }) })] }));
+    return (jsx(ThemeProvider, { theme: theme, boardTheme: boardTheme, children: jsxs("div", { style: puzzlePlayRowStyle(controlsPlacement), children: [jsx("div", { style: puzzleBoardColumnStyle(boardWidth, controlsPlacement), children: renderAboveBoard ? (jsx(PlayTimeEngineProvider, { fen: boardFen, enabled: playTimeEnabled, options: playTimeEngine, children: boardColumn })) : (boardColumn) }), jsx("div", { style: puzzleControlsSlotStyle(controlsPlacement), children: renderControls({
                         trainSide: line.trainSide,
                         moveNumber,
                         total,

package/dist/index.js

@@ -62,7 +62,7 @@ const EMPTY_BOARD_FEN = '8/8/8/8/8/8/8/8 w - - 0 1';
  * 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 = reactChessCore.DEFAULT_ANSWER_ARROW_COLOR, positionLocked = false, onMissFeedbackChange, recapBoard = null, }) => {
-    var _a, _b, _c, _d, _e, _f, _g;
+    var _a, _b, _c, _d, _e;
     const [showAnswerArrow, setShowAnswerArrow] = react.useState(false);
     const [incorrectActive, setIncorrectActive] = react.useState(false);
     const attemptMissedRef = react.useRef(false);
@@ -99,16 +99,14 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         autoShowWrongMoves: useRefutation ? true : autoShowWrongMoves,
         engineOptions: refutationEngine,
     });
-    const missPhase = (_c = missBoard.missSequence.sequence) === null || _c === void 0 ? void 0 : _c.phase;
+    const missPhase = missBoard.phase;
     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;
+    const overlayIncorrectSquare = useRefutation && incorrectActive
+        ? missBoard.incorrectMoveSquare
+        : transientIncorrectSquare;
+    const refutationMoveSquare = useRefutation && incorrectActive ? missBoard.refutationMoveSquare : null;
     react.useEffect(() => {
         setShowAnswerArrow(false);
         setIncorrectActive(false);
@@ -123,14 +121,13 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         position,
     ]);
     react.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,
+                phase: missBoard.phase,
                 answerArrowVisible,
             });
             return;
@@ -147,7 +144,7 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
     }, [
         answerArrowVisible,
         incorrectActive,
-        (_d = missBoard.missSequence.sequence) === null || _d === void 0 ? void 0 : _d.phase,
+        missBoard.phase,
         missBoard.refutation.refutationSan,
         onMissFeedbackChange,
         showAnswerArrow,
@@ -187,12 +184,8 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         ? recapBoard.lastMoveUci
         : useRefutation && incorrectActive
             ? missBoard.lastMoveUci
-            : ((_e = position === null || position === void 0 ? void 0 : position.getLastMoveUci()) !== null && _e !== void 0 ? _e : null);
-    const missLocked = useRefutation &&
-        incorrectActive &&
-        (missBoard.boardAnimating ||
-            missPhase === 'wrong' ||
-            missPhase === 'refutation');
+            : ((_c = position === null || position === void 0 ? void 0 : position.getLastMoveUci()) !== null && _c !== void 0 ? _c : null);
+    const missLocked = useRefutation && incorrectActive && missBoard.inputLocked;
     const arePiecesDraggable = !isRecapping &&
         position !== null &&
         !positionLocked &&
@@ -222,7 +215,9 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         });
         if (!guess.accepted) {
             attemptMissedRef.current = true;
-            showIncorrectMove(useRefutation ? targetSquare : sourceSquare);
+            if (!useRefutation) {
+                showIncorrectMove(sourceSquare);
+            }
             onFeedback({
                 index: position.getIndex(),
                 guess: { sourceSquare, targetSquare, piece },
@@ -302,7 +297,11 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         showCorrectMove(targetSquare, finishCorrectFeedback);
         return true;
     };
-    return hasBoard ? (jsxRuntime.jsx(reactChessCore.HighlightChessboard, { boardWidth: boardWidth, checkSquare: isRecapping ? '' : ((_f = position === null || position === void 0 ? void 0 : position.getCheckSquare()) !== null && _f !== void 0 ? _f : ''), hintSquare: isRecapping ? null : ((_g = position === null || position === void 0 ? void 0 : position.getHintSquare()) !== null && _g !== void 0 ? _g : null), incorrectMoveSquare: isRecapping ? null : overlayIncorrectSquare, refutationMoveSquare: isRecapping ? null : refutationMoveSquare, correctMoveSquare: isRecapping ? null : correctMoveSquare, customArrows: customArrows, lastMoveUci: lastMoveUci, onPieceDrop: onPieceDrop, position: displayFen, boardOrientation: boardOrientation, arePiecesDraggable: arePiecesDraggable, areArrowsAllowed: false, promotionDialogVariant: "modal", animationDuration: isRecapping ? recapBoard.animationDuration : 0 }, revision)) : null;
+    return hasBoard ? (jsxRuntime.jsx(reactChessCore.HighlightChessboard, { boardWidth: boardWidth, checkSquare: isRecapping ? '' : ((_d = position === null || position === void 0 ? void 0 : position.getCheckSquare()) !== null && _d !== void 0 ? _d : ''), hintSquare: isRecapping ? null : ((_e = position === null || position === void 0 ? void 0 : position.getHintSquare()) !== null && _e !== void 0 ? _e : null), incorrectMoveSquare: isRecapping ? null : overlayIncorrectSquare, refutationMoveSquare: isRecapping ? null : refutationMoveSquare, correctMoveSquare: isRecapping ? null : correctMoveSquare, customArrows: customArrows, lastMoveUci: lastMoveUci, onPieceDrop: onPieceDrop, position: displayFen, boardOrientation: boardOrientation, arePiecesDraggable: arePiecesDraggable, areArrowsAllowed: false, promotionDialogVariant: "modal", animationDuration: isRecapping
+            ? recapBoard.animationDuration
+            : useRefutation && incorrectActive
+                ? missBoard.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 }));
@@ -371,6 +370,7 @@ const usePuzzleCompletionRecap = ({ source, active, onComplete, }) => {
         segmentStartFen: startFen,
         setupUci,
         onComplete,
+        completeImmediatelyWhenNoMisses: true,
         resolveFen,
     });
 };
@@ -880,8 +880,8 @@ const buildCompletionRecapSource = (position, 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 PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls = defaultRenderControls, renderAnalysisSidebar, renderAnalysisContainer, renderEngineEvaluation, renderAboveBoard, renderBoardCaption, renderBoardFeedback, puzzleBoardWidth = DEFAULT_PUZZLE_BOARD_WIDTH, analysisLayout = reactChessCore.DEFAULT_ANALYSIS_LAYOUT, analysisBoardWidth, renderAnalysisMain, engine, playTimeEngine, 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, _e;
     const refutationOnIncorrect = showRefutationOnIncorrect !== null && showRefutationOnIncorrect !== void 0 ? showRefutationOnIncorrect : showAnswerArrowOnIncorrect;
     const stackControlsBelow = useStackPuzzleControlsBelow();
     const controlsPlacement = stackControlsBelow
@@ -1177,8 +1177,12 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
             return;
         }
         completionFlowStartedRef.current = true;
+        if (missedMoveIndices.length === 0) {
+            setCompletionRecapDone(true);
+            return;
+        }
         setCompletionCheckVisible(true);
-    }, [loadingNextPuzzle, resultStatus, showCompletionRecap]);
+    }, [loadingNextPuzzle, missedMoveIndices, resultStatus, showCompletionRecap]);
     react.useEffect(() => {
         if (!completionCheckVisible) {
             return;
@@ -1207,32 +1211,38 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
             (position.isSolutionRevealed() || !position.isFinished()),
     };
     const analysisSnapshot = analysis.isOpen && analysis.snapshot ? analysis.snapshot : null;
+    const setupFen = (_a = position === null || position === void 0 ? void 0 : position.fen()) !== null && _a !== void 0 ? _a : '';
+    const playTimeEnabled = Boolean(position) &&
+        !(position === null || position === void 0 ? void 0 : position.isFinished()) &&
+        !analysisSnapshot &&
+        reactChessCore.isAnalyzableFen(setupFen);
+    const resolvedPlayTimeEngine = react.useMemo(() => (Object.assign({ scriptUrl: engine === null || engine === void 0 ? void 0 : engine.scriptUrl }, playTimeEngine)), [engine === null || engine === void 0 ? void 0 : engine.scriptUrl, playTimeEngine]);
     const resolvedAnalysisBoardWidth = analysisBoardWidth !== null && analysisBoardWidth !== void 0 ? analysisBoardWidth : analysisLayout.boardWidth;
     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.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,
+    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(reactChessCore.PlayTimeEngineProvider, { fen: setupFen, enabled: playTimeEnabled, options: resolvedPlayTimeEngine, children: [renderAboveBoard === null || renderAboveBoard === void 0 ? void 0 : renderAboveBoard({ fen: setupFen }), 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: (_b = position === null || position === void 0 ? void 0 : position.getSideToMove()) !== null && _b !== void 0 ? _b : 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,
+                                refutationSan: (_c = missFeedback === null || missFeedback === void 0 ? void 0 : missFeedback.refutationSan) !== null && _c !== void 0 ? _c : null,
+                                missPhase: (_d = missFeedback === null || missFeedback === void 0 ? void 0 : missFeedback.phase) !== null && _d !== void 0 ? _d : null,
+                                answerArrowVisible: (_e = missFeedback === null || missFeedback === void 0 ? void 0 : missFeedback.answerArrowVisible) !== null && _e !== void 0 ? _e : false,
                                 completedAfterMiss,
                                 hintUsed,
                             }) }))] }), jsxRuntime.jsxs("div", { style: puzzleControlsSlotStyle(controlsPlacement), children: [renderControls(handleHintRequest, handleShowSolution, handleNextPuzzle, resultStatus, {
@@ -1287,7 +1297,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, boardTheme, 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, renderAboveBoard, playTimeEngine, boardWidth = DEFAULT_PUZZLE_BOARD_WIDTH, opponentMoveDelayMs = DEFAULT_OPPONENT_MOVE_DELAY_MS, }) => {
     const chessRef = react.useRef(new chess_js.Chess(line.startFen));
     const perMoveRef = react.useRef([]);
     const completedRef = react.useRef(false);
@@ -1412,7 +1422,9 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
     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, incorrectMoveSquare: incorrectMoveSquare, lastMoveUci: lastMoveUci, onPieceDrop: handleDrop, boardWidth: boardWidth }) }) }), jsxRuntime.jsx("div", { style: puzzleControlsSlotStyle(controlsPlacement), children: renderControls({
+    const playTimeEnabled = reactChessCore.isAnalyzableFen(boardFen);
+    const boardColumn = (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [renderAboveBoard === null || renderAboveBoard === void 0 ? void 0 : renderAboveBoard({ fen: boardFen }), 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 }) })] }));
+    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: renderAboveBoard ? (jsxRuntime.jsx(reactChessCore.PlayTimeEngineProvider, { fen: boardFen, enabled: playTimeEnabled, options: playTimeEngine, children: boardColumn })) : (boardColumn) }), jsxRuntime.jsx("div", { style: puzzleControlsSlotStyle(controlsPlacement), children: renderControls({
                         trainSide: line.trainSide,
                         moveNumber,
                         total,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-chess-puzzle-kit",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "React chess puzzle kit: play, controls, analysis, and browser Stockfish for endchess.training and other apps",
   "license": "MIT",
   "author": "Robert Blackwell",
@@ -76,7 +76,7 @@
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
     "react": "^18.3.1",
-    "react-chess-core": "^0.1.8",
+    "react-chess-core": "^0.1.12",
     "react-chessboard": "^4.7.1",
     "react-dom": "^18.3.1",
     "storybook": "^8.2.9",