react-chess-puzzle-kit 1.0.2 → 1.0.4

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

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

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

@@ -29,6 +29,8 @@ export type BoardCaptionRenderProps = {
     answerArrowVisible?: boolean;
     /** True when the card finished after a wrong move, hint, or solution reveal. */
     completedAfterMiss?: boolean;
+    /** True when the user requested a hint on the current card. */
+    hintUsed?: boolean;
 };
 export type BoardFeedbackRenderProps = {
     resultStatus: Extract<PuzzleResultStatus, 'complete' | 'incorrect'>;
@@ -42,6 +44,8 @@ export type BoardFeedbackRenderProps = {
     answerArrowVisible?: boolean;
     /** True when the card finished after a wrong move, hint, or solution reveal. */
     completedAfterMiss?: boolean;
+    /** True when the user requested a hint on the current card. */
+    hintUsed?: boolean;
 };
 export type PuzzleFetchResult = {
     fen: string;
@@ -84,6 +88,8 @@ export interface PuzzleBoardWithControlsProps {
     puzzleBoardWidth?: number;
     /** Board + sidebar grid sizes when analysis is open. */
     analysisLayout?: AnalysisLayoutConfig;
+    /** Chessboard pixel width in analysis (defaults to {@link analysisLayout}.boardWidth). */
+    analysisBoardWidth?: number;
     /** Custom board/sidebar placement (overrides {@link analysisLayout} grid). */
     renderAnalysisMain?: (props: AnalysisMainRenderProps) => React.ReactNode;
     engine?: AnalysisEngineOptions;
@@ -105,4 +111,4 @@ export interface PuzzleBoardWithControlsProps {
     refutationEngine?: AnalysisEngineOptions;
     answerArrowColor?: string;
 }
-export declare const PuzzleBoardWithControls: ({ theme, boardTheme, apiProxy, renderControls, renderAnalysisSidebar, renderAnalysisContainer, renderEngineEvaluation, renderBoardCaption, renderBoardFeedback, puzzleBoardWidth, analysisLayout, renderAnalysisMain, engine, autoAdvanceOnComplete, autoAdvanceOnCompleteAfterIncorrect, revealAnswerOnIncorrect, showAnswerArrowOnIncorrect, allowRetryOnIncorrect, showRefutationOnIncorrect, autoShowWrongMoves, refutationEngine, answerArrowColor, }: PuzzleBoardWithControlsProps) => React.JSX.Element;
+export declare const PuzzleBoardWithControls: ({ theme, boardTheme, apiProxy, renderControls, renderAnalysisSidebar, renderAnalysisContainer, renderEngineEvaluation, renderBoardCaption, renderBoardFeedback, puzzleBoardWidth, analysisLayout, analysisBoardWidth, renderAnalysisMain, engine, autoAdvanceOnComplete, autoAdvanceOnCompleteAfterIncorrect, revealAnswerOnIncorrect, showAnswerArrowOnIncorrect, allowRetryOnIncorrect, showRefutationOnIncorrect, autoShowWrongMoves, refutationEngine, answerArrowColor, }: PuzzleBoardWithControlsProps) => React.JSX.Element;

package/dist/index.d.ts

@@ -23,4 +23,7 @@ export declare const squareHighlightColors: {
     readonly check: "rgba(255, 127, 127, 0.8)";
     readonly hint: "rgba(119, 177, 212, 0.75)";
     readonly incorrect: "rgba(140, 38, 38, 0.82)";
+    readonly selected: "rgba(255, 255, 0, 0.45)";
+    readonly moveTarget: "radial-gradient(circle, rgba(0, 0, 0, 0.18) 22%, transparent 22%)";
+    readonly captureTarget: "radial-gradient(circle, rgba(0, 0, 0, 0.18) 72%, transparent 72%)";
 };

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, useMissBoard, ChessboardDnDProvider, HighlightChessboard, uciFromDrop, ThemeProvider, AnalysisErrorBoundary, AnalysisBoardCore, AnalysisBoardLayout, AnalysisBoard, DEFAULT_ANALYSIS_LAYOUT, evaluateExpectedMoveDrop, boardSquareHighlightColors, analysisBoardHighlightColors } from 'react-chess-core';
+import { useBoardRevision, useCorrectMoveFeedback, useMissBoard, ChessboardDnDProvider, HighlightChessboard, uciFromDrop, ThemeProvider, AnalysisErrorBoundary, AnalysisBoardCore, AnalysisBoardLayout, AnalysisBoard, DEFAULT_ANALYSIS_LAYOUT, lastMoveUciAtPly, evaluateExpectedMoveDrop, fenAfterUci, boardSquareHighlightColors, analysisBoardHighlightColors } from 'react-chess-core';
 export { DEFAULT_ANALYSIS_LAYOUT } from 'react-chess-core';
 import { Chess } from 'chess.js';
 
@@ -67,6 +67,7 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
     const [incorrectActive, setIncorrectActive] = useState(false);
     const attemptMissedRef = useRef(false);
     const { revision, bumpRevision } = useBoardRevision();
+    const { correctMoveSquare, showCorrectMove, clearCorrectMoveFeedback, } = useCorrectMoveFeedback();
     const boardOrientationRef = useRef('white');
     const boardFenRef = useRef(EMPTY_BOARD_FEN);
     const notifyHost = () => {
@@ -92,7 +93,9 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         expectedUci: expectedUci || null,
         positionFen,
         answerArrowColor,
-        autoShowWrongMoves,
+        // Refutation + answer-arrow flows must run the full wrong→refutation→answer
+        // sequence; the replay "retry without arrow" setting does not apply here.
+        autoShowWrongMoves: useRefutation ? true : autoShowWrongMoves,
         engineOptions: refutationEngine,
     });
     const missPhase = (_c = missBoard.missSequence.sequence) === null || _c === void 0 ? void 0 : _c.phase;
@@ -103,8 +106,9 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         setShowAnswerArrow(false);
         setIncorrectActive(false);
         attemptMissedRef.current = false;
+        clearCorrectMoveFeedback();
         onMissFeedbackChange === null || onMissFeedbackChange === void 0 ? void 0 : onMissFeedbackChange(null);
-    }, [onMissFeedbackChange, position]);
+    }, [clearCorrectMoveFeedback, onMissFeedbackChange, position]);
     useEffect(() => {
         var _a, _b;
         if (!onMissFeedbackChange) {
@@ -162,7 +166,10 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         (missBoard.boardAnimating ||
             missPhase === 'wrong' ||
             missPhase === 'refutation');
-    const arePiecesDraggable = position !== null && !positionLocked && !missLocked;
+    const arePiecesDraggable = position !== null &&
+        !positionLocked &&
+        !missLocked &&
+        correctMoveSquare === null;
     const onPieceDrop = (sourceSquare, targetSquare, piece) => {
         if (!position || positionLocked || position.isSolutionRevealed()) {
             return false;
@@ -227,6 +234,7 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         setIncorrectActive(false);
         missBoard.missSequence.clearSequence();
         onMissFeedbackChange === null || onMissFeedbackChange === void 0 ? void 0 : onMissFeedbackChange(null);
+        clearCorrectMoveFeedback();
         const assistedByAnswerArrow = answerArrowVisible && attemptMissedRef.current;
         const guessPayload = {
             index: position.getIndex(),
@@ -242,32 +250,31 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         else {
             onFeedback(Object.assign(Object.assign({}, guessPayload), { isCorrect: true, isFinished: guess.finished }));
         }
+        position.next();
+        boardFenRef.current = position.fen();
         notifyHost();
-        setTimeout(() => {
+        const finishCorrectFeedback = () => {
             position.resetInteractions();
             notifyHost();
-        }, 500);
-        if (position.isAlternativeCheckmate()) {
-            notifyHost();
-            return true;
-        }
-        position.next();
-        notifyHost();
-        if (position.hasResumeConfig()) {
-            onResumeCorrect === null || onResumeCorrect === void 0 ? void 0 : onResumeCorrect(position);
-            return true;
-        }
-        setTimeout(() => {
+            if (position.isAlternativeCheckmate()) {
+                return;
+            }
+            if (position.hasResumeConfig()) {
+                onResumeCorrect === null || onResumeCorrect === void 0 ? void 0 : onResumeCorrect(position);
+                return;
+            }
             if (!position.isFinished()) {
                 position.next();
+                boardFenRef.current = position.fen();
             }
             notifyHost();
-        }, 500);
+        };
+        showCorrectMove(targetSquare, finishCorrectFeedback);
         return true;
     };
     return (jsx(ChessboardDnDProvider, { children: hasBoard ? (jsx(HighlightChessboard, { boardWidth: boardWidth, checkSquare: (_e = position === null || position === void 0 ? void 0 : position.getCheckSquare()) !== null && _e !== void 0 ? _e : '', hintSquare: (_f = position === null || position === void 0 ? void 0 : position.getHintSquare()) !== null && _f !== void 0 ? _f : null, incorrectMoveSquare: showAnswerArrowOnIncorrect
                 ? null
-                : ((_g = position === null || position === void 0 ? void 0 : position.getIncorrectMoveSquare()) !== null && _g !== void 0 ? _g : null), customArrows: customArrows, onPieceDrop: onPieceDrop, position: displayFen, boardOrientation: boardOrientation, arePiecesDraggable: arePiecesDraggable, areArrowsAllowed: false, promotionDialogVariant: "modal", animationDuration: 0 }, revision)) : null }));
+                : ((_g = position === null || position === void 0 ? void 0 : position.getIncorrectMoveSquare()) !== null && _g !== void 0 ? _g : null), correctMoveSquare: correctMoveSquare, customArrows: customArrows, onPieceDrop: onPieceDrop, position: displayFen, boardOrientation: boardOrientation, arePiecesDraggable: arePiecesDraggable, areArrowsAllowed: false, promotionDialogVariant: "modal", animationDuration: 0 }, revision)) : null }));
 };
 
 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 }));
@@ -732,7 +739,7 @@ const puzzlePositionFromFetch = (fen, moves, resume) => {
 const AUTO_ADVANCE_ON_COMPLETE_DELAY_MS = 700;
 const SOLUTION_STEP_MS = 500;
 const RESUME_AUTO_STEP_MS = 500;
-const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls = defaultRenderControls, renderAnalysisSidebar, renderAnalysisContainer, renderEngineEvaluation, renderBoardCaption, renderBoardFeedback, puzzleBoardWidth = DEFAULT_PUZZLE_BOARD_WIDTH, analysisLayout = DEFAULT_ANALYSIS_LAYOUT, renderAnalysisMain, engine, autoAdvanceOnComplete = false, autoAdvanceOnCompleteAfterIncorrect = false, revealAnswerOnIncorrect = false, showAnswerArrowOnIncorrect = false, allowRetryOnIncorrect = true, showRefutationOnIncorrect, autoShowWrongMoves = true, refutationEngine, answerArrowColor, }) => {
+const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls = defaultRenderControls, renderAnalysisSidebar, renderAnalysisContainer, renderEngineEvaluation, renderBoardCaption, renderBoardFeedback, puzzleBoardWidth = DEFAULT_PUZZLE_BOARD_WIDTH, analysisLayout = DEFAULT_ANALYSIS_LAYOUT, analysisBoardWidth, renderAnalysisMain, engine, autoAdvanceOnComplete = false, autoAdvanceOnCompleteAfterIncorrect = false, revealAnswerOnIncorrect = false, showAnswerArrowOnIncorrect = false, allowRetryOnIncorrect = true, showRefutationOnIncorrect, autoShowWrongMoves = true, refutationEngine, answerArrowColor, }) => {
     var _a, _b, _c, _d;
     const refutationOnIncorrect = showRefutationOnIncorrect !== null && showRefutationOnIncorrect !== void 0 ? showRefutationOnIncorrect : showAnswerArrowOnIncorrect;
     const stackControlsBelow = useStackPuzzleControlsBelow();
@@ -744,6 +751,7 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
     const [loadingNextPuzzle, setLoadingNextPuzzle] = useState(true);
     const [puzzleNum, setPuzzleNum] = useState(0);
     const [hasIncorrectAttempt, setHasIncorrectAttempt] = useState(false);
+    const [hintUsed, setHintUsed] = useState(false);
     const [puzzleComplete, setPuzzleComplete] = useState(false);
     const [completedAfterMiss, setCompletedAfterMiss] = useState(false);
     const [missFeedback, setMissFeedback] = useState(null);
@@ -769,6 +777,7 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
         let cancelled = false;
         setLoadingNextPuzzle(true);
         setHasIncorrectAttempt(false);
+        setHintUsed(false);
         setPuzzleComplete(false);
         setCompletedAfterMiss(false);
         setMissFeedback(null);
@@ -805,12 +814,18 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
         const incorrectThisFeedback = feedbackData.hintRequested ||
             feedbackData.solutionShown ||
             feedbackData.isCorrect === false;
+        if (feedbackData.hintRequested) {
+            setHintUsed(true);
+        }
         if (incorrectThisFeedback) {
             setHasIncorrectAttempt(true);
         }
         if (feedbackData.isFinished) {
             setPuzzleComplete(true);
-            setCompletedAfterMiss(hasIncorrectAttempt || incorrectThisFeedback);
+            setCompletedAfterMiss((prev) => prev ||
+                hasIncorrectAttempt ||
+                incorrectThisFeedback ||
+                feedbackData.hintRequested === true);
         }
         onFeedback(feedbackData);
     };
@@ -1014,10 +1029,11 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
     };
     const analysis = usePuzzleAnalysis(position, resultStatus, puzzleNum);
     const analysisSnapshot = analysis.isOpen && analysis.snapshot ? analysis.snapshot : null;
+    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: 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({
+    return (jsx(ThemeProvider, { theme: theme, boardTheme: boardTheme, children: analysisSnapshot ? (jsx(AnalysisErrorBoundary, { onClose: analysis.closeAnalysis, children: useHostAnalysisUi ? (jsx(AnalysisBoardCore, { analysisContext: analysisSnapshot, onClose: analysis.closeAnalysis, theme: theme, boardWidth: resolvedAnalysisBoardWidth, engine: engine, renderMain: renderAnalysisMain !== null && renderAnalysisMain !== void 0 ? renderAnalysisMain : (({ board, sidebar, model }) => (jsx(AnalysisBoardLayout, { layout: analysisLayout, model: model, board: board, sidebar: sidebar }))), renderSidebar: renderAnalysisSidebar, renderContainer: renderAnalysisContainer, renderEngineEvaluation: renderEngineEvaluation !== null && renderEngineEvaluation !== void 0 ? renderEngineEvaluation : (() => null) })) : (jsx(AnalysisBoard, { analysisContext: analysisSnapshot, onClose: analysis.closeAnalysis, theme: theme, layout: analysisLayout, engine: engine, renderMain: renderAnalysisMain, renderSidebar: renderAnalysisSidebar, renderContainer: renderAnalysisContainer, renderEngineEvaluation: renderEngineEvaluation })) })) : (jsxs("div", { style: puzzlePlayRowStyle(controlsPlacement), children: [jsxs("div", { style: puzzleBoardColumnStyle(puzzleBoardWidth, controlsPlacement), children: [jsx("div", { style: puzzleBoardSlotWrapperStyle(), children: jsx("div", { style: puzzleBoardSlotStyle(), children: jsx(PuzzlePlaySurface, { position: position, boardWidth: puzzleBoardWidth, onFeedback: handleFeedback, incInteractionNum: incInteractionNum, onResumeCorrect: runResumeAutoAdvance, revealAnswerOnIncorrect: revealAnswerOnIncorrect, showAnswerArrowOnIncorrect: showAnswerArrowOnIncorrect, allowRetryOnIncorrect: allowRetryOnIncorrect, showRefutationOnIncorrect: refutationOnIncorrect, autoShowWrongMoves: autoShowWrongMoves, refutationEngine: refutationEngine !== null && refutationEngine !== void 0 ? refutationEngine : engine, answerArrowColor: answerArrowColor, positionLocked: loadingNextPuzzle, onMissFeedbackChange: setMissFeedback }) }) }), renderBoardCaption && (jsx("div", { style: puzzleBoardCaptionSlotStyle(), children: renderBoardCaption({
                                 sideToMove: (_a = position === null || position === void 0 ? void 0 : position.getSideToMove()) !== null && _a !== void 0 ? _a : null,
                                 playerColor: position
                                     ? position.getPlayerColor()
@@ -1029,6 +1045,7 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
                                 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,
+                                hintUsed,
                             }) }))] }), jsxs("div", { style: puzzleControlsSlotStyle(controlsPlacement), children: [renderControls(handleHintRequest, handleShowSolution, handleNextPuzzle, resultStatus, {
                             visible: analysis.canOpen,
                             openAnalysis: analysis.openAnalysis,
@@ -1037,6 +1054,7 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
                                 cleanSolve: !hasIncorrectAttempt,
                                 refutationSan: missFeedback === null || missFeedback === void 0 ? void 0 : missFeedback.refutationSan,
                                 missPhase: missFeedback === null || missFeedback === void 0 ? void 0 : missFeedback.phase,
+                                hintUsed,
                             }) }))] })] })) }));
 };
 
@@ -1045,7 +1063,7 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
  * side's pieces be dragged. Move validation and sequencing live in
  * {@link LineBoardWithControls}.
  */
-const LineBoard = ({ fen, orientation, trainSide, draggable, onPieceDrop, boardWidth, }) => (jsx(ChessboardDnDProvider, { children: jsx(HighlightChessboard, { boardWidth: boardWidth, checkSquare: "", hintSquare: null, incorrectMoveSquare: null, position: fen, boardOrientation: orientation, arePiecesDraggable: draggable, isDraggablePiece: ({ piece }) => piece[0] === trainSide, onPieceDrop: (source, target, piece) => onPieceDrop(source, target, piece), autoPromoteToQueen: true, areArrowsAllowed: false, customBoardStyle: { borderRadius: 4 } }) }));
+const LineBoard = ({ fen, orientation, trainSide, draggable, correctMoveSquare = null, lastMoveUci = null, onPieceDrop, boardWidth, }) => (jsx(ChessboardDnDProvider, { children: jsx(HighlightChessboard, { boardWidth: boardWidth, checkSquare: "", hintSquare: null, incorrectMoveSquare: null, correctMoveSquare: correctMoveSquare, position: fen, boardOrientation: orientation, arePiecesDraggable: draggable, isDraggablePiece: ({ piece }) => piece[0] === trainSide, onPieceDrop: (source, target, piece) => onPieceDrop(source, target, piece), lastMoveUci: lastMoveUci, autoPromoteToQueen: true, areArrowsAllowed: false, customBoardStyle: { borderRadius: 4 } }) }));
 
 /** Library default line-drill status controls (unstyled). */
 const DefaultLineControls = ({ moveNumber, total, finished, isUserTurn, feedback, }) => (jsxs("div", { style: rowStyle, children: [jsx("span", { style: statusStyle, children: finished ? 'Line complete' : `Move ${moveNumber} of ${total}` }), feedback && !finished && (jsx("span", { style: Object.assign(Object.assign({}, statusStyle), { color: feedback.isCorrect ? '#2e7d32' : '#c62828' }), children: feedback.isCorrect
@@ -1092,6 +1110,8 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
     const [currentIndex, setCurrentIndex] = useState(0);
     const [finished, setFinished] = useState(false);
     const [feedback, setFeedback] = useState(null);
+    const [displayFen, setDisplayFen] = useState(null);
+    const { correctMoveSquare, showCorrectMove, clearCorrectMoveFeedback, isShowingCorrectMove, } = useCorrectMoveFeedback();
     const total = line.movesUci.length;
     const orientation = boardOrientationForLine(line.trainSide);
     const applyMove = useCallback((index) => {
@@ -1116,7 +1136,7 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
     }, [line.movesUci]);
     // Auto-play opponent moves and detect the end of the line.
     useEffect(() => {
-        if (finished) {
+        if (finished || isShowingCorrectMove) {
             return;
         }
         if (currentIndex >= total) {
@@ -1135,6 +1155,7 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
         line.trainSide,
         applyMove,
         opponentMoveDelayMs,
+        isShowingCorrectMove,
     ]);
     // Emit the completion event exactly once.
     useEffect(() => {
@@ -1146,15 +1167,16 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
     }, [finished]);
     const handleDrop = (source, target, piece) => {
         var _a, _b, _c;
-        if (finished) {
+        if (finished || isShowingCorrectMove) {
             return false;
         }
-        if (turnFromFen(chessRef.current.fen()) !== line.trainSide) {
+        const setupFen = displayFen !== null && displayFen !== void 0 ? displayFen : chessRef.current.fen();
+        if (turnFromFen(setupFen) !== line.trainSide) {
             return false;
         }
         const index = currentIndex;
         const expected = line.movesUci[index];
-        const dropResult = evaluateExpectedMoveDrop(chessRef.current.fen(), source, target, piece, expected, true);
+        const dropResult = evaluateExpectedMoveDrop(setupFen, source, target, piece, expected, true);
         if (dropResult.kind === 'illegal' || dropResult.kind === 'ignored') {
             return false;
         }
@@ -1164,16 +1186,38 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
         const moveFeedback = { index, isCorrect, expectedSan };
         setFeedback(moveFeedback);
         (_c = onMoveRef.current) === null || _c === void 0 ? void 0 : _c.call(onMoveRef, moveFeedback);
-        applyMove(index);
+        if (isCorrect) {
+            const nextFen = fenAfterUci(setupFen, dropResult.uci);
+            if (nextFen) {
+                setDisplayFen(nextFen);
+            }
+            showCorrectMove(target, () => {
+                setDisplayFen(null);
+                setFeedback(null);
+                clearCorrectMoveFeedback();
+                applyMove(index);
+            });
+        }
         return isCorrect;
     };
+    const boardFen = displayFen !== null && displayFen !== void 0 ? displayFen : fen;
+    const lastMoveUci = useMemo(() => {
+        var _a;
+        if (displayFen) {
+            return (_a = line.movesUci[currentIndex]) !== null && _a !== void 0 ? _a : null;
+        }
+        return lastMoveUciAtPly(line.movesUci, currentIndex);
+    }, [currentIndex, displayFen, line.movesUci]);
     const moveNumber = Math.min(currentIndex + 1, total);
-    const isUserTurn = !finished && turnFromFen(fen) === line.trainSide && currentIndex < total;
+    const isUserTurn = !finished &&
+        !isShowingCorrectMove &&
+        turnFromFen(boardFen) === line.trainSide &&
+        currentIndex < total;
     const stackControlsBelow = useStackPuzzleControlsBelow();
     const controlsPlacement = stackControlsBelow
         ? 'below'
         : 'beside';
-    return (jsx(ThemeProvider, { theme: theme, boardTheme: boardTheme, children: jsxs("div", { style: puzzlePlayRowStyle(controlsPlacement), children: [jsx("div", { style: puzzleBoardColumnStyle(boardWidth, controlsPlacement), children: jsx("div", { style: puzzleBoardSlotStyle(), children: jsx(LineBoard, { fen: fen, orientation: orientation, trainSide: line.trainSide, draggable: isUserTurn, onPieceDrop: handleDrop, boardWidth: boardWidth }) }) }), jsx("div", { style: puzzleControlsSlotStyle(controlsPlacement), children: renderControls({
+    return (jsx(ThemeProvider, { theme: theme, boardTheme: boardTheme, children: jsxs("div", { style: puzzlePlayRowStyle(controlsPlacement), children: [jsx("div", { style: puzzleBoardColumnStyle(boardWidth, controlsPlacement), children: jsx("div", { style: puzzleBoardSlotStyle(), children: jsx(LineBoard, { fen: boardFen, orientation: orientation, trainSide: line.trainSide, draggable: isUserTurn, correctMoveSquare: correctMoveSquare, lastMoveUci: lastMoveUci, onPieceDrop: handleDrop, boardWidth: boardWidth }) }) }), jsx("div", { style: puzzleControlsSlotStyle(controlsPlacement), children: renderControls({
                         trainSide: line.trainSide,
                         moveNumber,
                         total,

package/dist/index.js

@@ -68,6 +68,7 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
     const [incorrectActive, setIncorrectActive] = react.useState(false);
     const attemptMissedRef = react.useRef(false);
     const { revision, bumpRevision } = reactChessCore.useBoardRevision();
+    const { correctMoveSquare, showCorrectMove, clearCorrectMoveFeedback, } = reactChessCore.useCorrectMoveFeedback();
     const boardOrientationRef = react.useRef('white');
     const boardFenRef = react.useRef(EMPTY_BOARD_FEN);
     const notifyHost = () => {
@@ -93,7 +94,9 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         expectedUci: expectedUci || null,
         positionFen,
         answerArrowColor,
-        autoShowWrongMoves,
+        // Refutation + answer-arrow flows must run the full wrong→refutation→answer
+        // sequence; the replay "retry without arrow" setting does not apply here.
+        autoShowWrongMoves: useRefutation ? true : autoShowWrongMoves,
         engineOptions: refutationEngine,
     });
     const missPhase = (_c = missBoard.missSequence.sequence) === null || _c === void 0 ? void 0 : _c.phase;
@@ -104,8 +107,9 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         setShowAnswerArrow(false);
         setIncorrectActive(false);
         attemptMissedRef.current = false;
+        clearCorrectMoveFeedback();
         onMissFeedbackChange === null || onMissFeedbackChange === void 0 ? void 0 : onMissFeedbackChange(null);
-    }, [onMissFeedbackChange, position]);
+    }, [clearCorrectMoveFeedback, onMissFeedbackChange, position]);
     react.useEffect(() => {
         var _a, _b;
         if (!onMissFeedbackChange) {
@@ -163,7 +167,10 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         (missBoard.boardAnimating ||
             missPhase === 'wrong' ||
             missPhase === 'refutation');
-    const arePiecesDraggable = position !== null && !positionLocked && !missLocked;
+    const arePiecesDraggable = position !== null &&
+        !positionLocked &&
+        !missLocked &&
+        correctMoveSquare === null;
     const onPieceDrop = (sourceSquare, targetSquare, piece) => {
         if (!position || positionLocked || position.isSolutionRevealed()) {
             return false;
@@ -228,6 +235,7 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         setIncorrectActive(false);
         missBoard.missSequence.clearSequence();
         onMissFeedbackChange === null || onMissFeedbackChange === void 0 ? void 0 : onMissFeedbackChange(null);
+        clearCorrectMoveFeedback();
         const assistedByAnswerArrow = answerArrowVisible && attemptMissedRef.current;
         const guessPayload = {
             index: position.getIndex(),
@@ -243,32 +251,31 @@ const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth
         else {
             onFeedback(Object.assign(Object.assign({}, guessPayload), { isCorrect: true, isFinished: guess.finished }));
         }
+        position.next();
+        boardFenRef.current = position.fen();
         notifyHost();
-        setTimeout(() => {
+        const finishCorrectFeedback = () => {
             position.resetInteractions();
             notifyHost();
-        }, 500);
-        if (position.isAlternativeCheckmate()) {
-            notifyHost();
-            return true;
-        }
-        position.next();
-        notifyHost();
-        if (position.hasResumeConfig()) {
-            onResumeCorrect === null || onResumeCorrect === void 0 ? void 0 : onResumeCorrect(position);
-            return true;
-        }
-        setTimeout(() => {
+            if (position.isAlternativeCheckmate()) {
+                return;
+            }
+            if (position.hasResumeConfig()) {
+                onResumeCorrect === null || onResumeCorrect === void 0 ? void 0 : onResumeCorrect(position);
+                return;
+            }
             if (!position.isFinished()) {
                 position.next();
+                boardFenRef.current = position.fen();
             }
             notifyHost();
-        }, 500);
+        };
+        showCorrectMove(targetSquare, finishCorrectFeedback);
         return true;
     };
     return (jsxRuntime.jsx(reactChessCore.ChessboardDnDProvider, { children: hasBoard ? (jsxRuntime.jsx(reactChessCore.HighlightChessboard, { boardWidth: boardWidth, checkSquare: (_e = position === null || position === void 0 ? void 0 : position.getCheckSquare()) !== null && _e !== void 0 ? _e : '', hintSquare: (_f = position === null || position === void 0 ? void 0 : position.getHintSquare()) !== null && _f !== void 0 ? _f : null, incorrectMoveSquare: showAnswerArrowOnIncorrect
                 ? null
-                : ((_g = position === null || position === void 0 ? void 0 : position.getIncorrectMoveSquare()) !== null && _g !== void 0 ? _g : null), customArrows: customArrows, onPieceDrop: onPieceDrop, position: displayFen, boardOrientation: boardOrientation, arePiecesDraggable: arePiecesDraggable, areArrowsAllowed: false, promotionDialogVariant: "modal", animationDuration: 0 }, revision)) : null }));
+                : ((_g = position === null || position === void 0 ? void 0 : position.getIncorrectMoveSquare()) !== null && _g !== void 0 ? _g : null), correctMoveSquare: correctMoveSquare, customArrows: customArrows, onPieceDrop: onPieceDrop, position: displayFen, boardOrientation: boardOrientation, arePiecesDraggable: arePiecesDraggable, areArrowsAllowed: false, promotionDialogVariant: "modal", animationDuration: 0 }, revision)) : null }));
 };
 
 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 }));
@@ -733,7 +740,7 @@ const puzzlePositionFromFetch = (fen, moves, resume) => {
 const AUTO_ADVANCE_ON_COMPLETE_DELAY_MS = 700;
 const SOLUTION_STEP_MS = 500;
 const RESUME_AUTO_STEP_MS = 500;
-const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls = defaultRenderControls, renderAnalysisSidebar, renderAnalysisContainer, renderEngineEvaluation, renderBoardCaption, renderBoardFeedback, puzzleBoardWidth = DEFAULT_PUZZLE_BOARD_WIDTH, analysisLayout = reactChessCore.DEFAULT_ANALYSIS_LAYOUT, renderAnalysisMain, engine, autoAdvanceOnComplete = false, autoAdvanceOnCompleteAfterIncorrect = false, revealAnswerOnIncorrect = false, showAnswerArrowOnIncorrect = false, allowRetryOnIncorrect = true, showRefutationOnIncorrect, autoShowWrongMoves = true, refutationEngine, answerArrowColor, }) => {
+const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls = defaultRenderControls, renderAnalysisSidebar, renderAnalysisContainer, renderEngineEvaluation, renderBoardCaption, renderBoardFeedback, puzzleBoardWidth = DEFAULT_PUZZLE_BOARD_WIDTH, analysisLayout = reactChessCore.DEFAULT_ANALYSIS_LAYOUT, analysisBoardWidth, renderAnalysisMain, engine, autoAdvanceOnComplete = false, autoAdvanceOnCompleteAfterIncorrect = false, revealAnswerOnIncorrect = false, showAnswerArrowOnIncorrect = false, allowRetryOnIncorrect = true, showRefutationOnIncorrect, autoShowWrongMoves = true, refutationEngine, answerArrowColor, }) => {
     var _a, _b, _c, _d;
     const refutationOnIncorrect = showRefutationOnIncorrect !== null && showRefutationOnIncorrect !== void 0 ? showRefutationOnIncorrect : showAnswerArrowOnIncorrect;
     const stackControlsBelow = useStackPuzzleControlsBelow();
@@ -745,6 +752,7 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
     const [loadingNextPuzzle, setLoadingNextPuzzle] = react.useState(true);
     const [puzzleNum, setPuzzleNum] = react.useState(0);
     const [hasIncorrectAttempt, setHasIncorrectAttempt] = react.useState(false);
+    const [hintUsed, setHintUsed] = react.useState(false);
     const [puzzleComplete, setPuzzleComplete] = react.useState(false);
     const [completedAfterMiss, setCompletedAfterMiss] = react.useState(false);
     const [missFeedback, setMissFeedback] = react.useState(null);
@@ -770,6 +778,7 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
         let cancelled = false;
         setLoadingNextPuzzle(true);
         setHasIncorrectAttempt(false);
+        setHintUsed(false);
         setPuzzleComplete(false);
         setCompletedAfterMiss(false);
         setMissFeedback(null);
@@ -806,12 +815,18 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
         const incorrectThisFeedback = feedbackData.hintRequested ||
             feedbackData.solutionShown ||
             feedbackData.isCorrect === false;
+        if (feedbackData.hintRequested) {
+            setHintUsed(true);
+        }
         if (incorrectThisFeedback) {
             setHasIncorrectAttempt(true);
         }
         if (feedbackData.isFinished) {
             setPuzzleComplete(true);
-            setCompletedAfterMiss(hasIncorrectAttempt || incorrectThisFeedback);
+            setCompletedAfterMiss((prev) => prev ||
+                hasIncorrectAttempt ||
+                incorrectThisFeedback ||
+                feedbackData.hintRequested === true);
         }
         onFeedback(feedbackData);
     };
@@ -1015,10 +1030,11 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
     };
     const analysis = usePuzzleAnalysis(position, resultStatus, puzzleNum);
     const analysisSnapshot = analysis.isOpen && analysis.snapshot ? analysis.snapshot : null;
+    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: analysisLayout.boardWidth, engine: engine, renderMain: renderAnalysisMain !== null && renderAnalysisMain !== void 0 ? renderAnalysisMain : (({ board, sidebar, model }) => (jsxRuntime.jsx(reactChessCore.AnalysisBoardLayout, { layout: analysisLayout, model: model, board: board, sidebar: sidebar }))), renderSidebar: renderAnalysisSidebar, renderContainer: renderAnalysisContainer, renderEngineEvaluation: renderEngineEvaluation !== null && renderEngineEvaluation !== void 0 ? renderEngineEvaluation : (() => null) })) : (jsxRuntime.jsx(reactChessCore.AnalysisBoard, { analysisContext: analysisSnapshot, onClose: analysis.closeAnalysis, theme: theme, layout: analysisLayout, engine: engine, renderMain: renderAnalysisMain, renderSidebar: renderAnalysisSidebar, renderContainer: renderAnalysisContainer, renderEngineEvaluation: renderEngineEvaluation })) })) : (jsxRuntime.jsxs("div", { style: puzzlePlayRowStyle(controlsPlacement), children: [jsxRuntime.jsxs("div", { style: puzzleBoardColumnStyle(puzzleBoardWidth, controlsPlacement), children: [jsxRuntime.jsx("div", { style: puzzleBoardSlotWrapperStyle(), children: jsxRuntime.jsx("div", { style: puzzleBoardSlotStyle(), children: jsxRuntime.jsx(PuzzlePlaySurface, { position: position, boardWidth: puzzleBoardWidth, onFeedback: handleFeedback, incInteractionNum: incInteractionNum, onResumeCorrect: runResumeAutoAdvance, revealAnswerOnIncorrect: revealAnswerOnIncorrect, showAnswerArrowOnIncorrect: showAnswerArrowOnIncorrect, allowRetryOnIncorrect: allowRetryOnIncorrect, showRefutationOnIncorrect: refutationOnIncorrect, autoShowWrongMoves: autoShowWrongMoves, refutationEngine: refutationEngine !== null && refutationEngine !== void 0 ? refutationEngine : engine, answerArrowColor: answerArrowColor, positionLocked: loadingNextPuzzle, onMissFeedbackChange: setMissFeedback }) }) }), renderBoardCaption && (jsxRuntime.jsx("div", { style: puzzleBoardCaptionSlotStyle(), children: renderBoardCaption({
+    return (jsxRuntime.jsx(reactChessCore.ThemeProvider, { theme: theme, boardTheme: boardTheme, children: analysisSnapshot ? (jsxRuntime.jsx(reactChessCore.AnalysisErrorBoundary, { onClose: analysis.closeAnalysis, children: useHostAnalysisUi ? (jsxRuntime.jsx(reactChessCore.AnalysisBoardCore, { analysisContext: analysisSnapshot, onClose: analysis.closeAnalysis, theme: theme, boardWidth: resolvedAnalysisBoardWidth, engine: engine, renderMain: renderAnalysisMain !== null && renderAnalysisMain !== void 0 ? renderAnalysisMain : (({ board, sidebar, model }) => (jsxRuntime.jsx(reactChessCore.AnalysisBoardLayout, { layout: analysisLayout, model: model, board: board, sidebar: sidebar }))), renderSidebar: renderAnalysisSidebar, renderContainer: renderAnalysisContainer, renderEngineEvaluation: renderEngineEvaluation !== null && renderEngineEvaluation !== void 0 ? renderEngineEvaluation : (() => null) })) : (jsxRuntime.jsx(reactChessCore.AnalysisBoard, { analysisContext: analysisSnapshot, onClose: analysis.closeAnalysis, theme: theme, layout: analysisLayout, engine: engine, renderMain: renderAnalysisMain, renderSidebar: renderAnalysisSidebar, renderContainer: renderAnalysisContainer, renderEngineEvaluation: renderEngineEvaluation })) })) : (jsxRuntime.jsxs("div", { style: puzzlePlayRowStyle(controlsPlacement), children: [jsxRuntime.jsxs("div", { style: puzzleBoardColumnStyle(puzzleBoardWidth, controlsPlacement), children: [jsxRuntime.jsx("div", { style: puzzleBoardSlotWrapperStyle(), children: jsxRuntime.jsx("div", { style: puzzleBoardSlotStyle(), children: jsxRuntime.jsx(PuzzlePlaySurface, { position: position, boardWidth: puzzleBoardWidth, onFeedback: handleFeedback, incInteractionNum: incInteractionNum, onResumeCorrect: runResumeAutoAdvance, revealAnswerOnIncorrect: revealAnswerOnIncorrect, showAnswerArrowOnIncorrect: showAnswerArrowOnIncorrect, allowRetryOnIncorrect: allowRetryOnIncorrect, showRefutationOnIncorrect: refutationOnIncorrect, autoShowWrongMoves: autoShowWrongMoves, refutationEngine: refutationEngine !== null && refutationEngine !== void 0 ? refutationEngine : engine, answerArrowColor: answerArrowColor, positionLocked: loadingNextPuzzle, onMissFeedbackChange: setMissFeedback }) }) }), renderBoardCaption && (jsxRuntime.jsx("div", { style: puzzleBoardCaptionSlotStyle(), children: renderBoardCaption({
                                 sideToMove: (_a = position === null || position === void 0 ? void 0 : position.getSideToMove()) !== null && _a !== void 0 ? _a : null,
                                 playerColor: position
                                     ? position.getPlayerColor()
@@ -1030,6 +1046,7 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
                                 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,
+                                hintUsed,
                             }) }))] }), jsxRuntime.jsxs("div", { style: puzzleControlsSlotStyle(controlsPlacement), children: [renderControls(handleHintRequest, handleShowSolution, handleNextPuzzle, resultStatus, {
                             visible: analysis.canOpen,
                             openAnalysis: analysis.openAnalysis,
@@ -1038,6 +1055,7 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
                                 cleanSolve: !hasIncorrectAttempt,
                                 refutationSan: missFeedback === null || missFeedback === void 0 ? void 0 : missFeedback.refutationSan,
                                 missPhase: missFeedback === null || missFeedback === void 0 ? void 0 : missFeedback.phase,
+                                hintUsed,
                             }) }))] })] })) }));
 };
 
@@ -1046,7 +1064,7 @@ const PuzzleBoardWithControls = ({ theme, boardTheme, apiProxy, renderControls =
  * side's pieces be dragged. Move validation and sequencing live in
  * {@link LineBoardWithControls}.
  */
-const LineBoard = ({ fen, orientation, trainSide, draggable, onPieceDrop, boardWidth, }) => (jsxRuntime.jsx(reactChessCore.ChessboardDnDProvider, { children: jsxRuntime.jsx(reactChessCore.HighlightChessboard, { boardWidth: boardWidth, checkSquare: "", hintSquare: null, incorrectMoveSquare: null, position: fen, boardOrientation: orientation, arePiecesDraggable: draggable, isDraggablePiece: ({ piece }) => piece[0] === trainSide, onPieceDrop: (source, target, piece) => onPieceDrop(source, target, piece), autoPromoteToQueen: true, areArrowsAllowed: false, customBoardStyle: { borderRadius: 4 } }) }));
+const LineBoard = ({ fen, orientation, trainSide, draggable, correctMoveSquare = null, lastMoveUci = null, onPieceDrop, boardWidth, }) => (jsxRuntime.jsx(reactChessCore.ChessboardDnDProvider, { children: jsxRuntime.jsx(reactChessCore.HighlightChessboard, { boardWidth: boardWidth, checkSquare: "", hintSquare: null, incorrectMoveSquare: null, correctMoveSquare: correctMoveSquare, position: fen, boardOrientation: orientation, arePiecesDraggable: draggable, isDraggablePiece: ({ piece }) => piece[0] === trainSide, onPieceDrop: (source, target, piece) => onPieceDrop(source, target, piece), lastMoveUci: lastMoveUci, autoPromoteToQueen: true, areArrowsAllowed: false, customBoardStyle: { borderRadius: 4 } }) }));
 
 /** Library default line-drill status controls (unstyled). */
 const DefaultLineControls = ({ moveNumber, total, finished, isUserTurn, feedback, }) => (jsxRuntime.jsxs("div", { style: rowStyle, children: [jsxRuntime.jsx("span", { style: statusStyle, children: finished ? 'Line complete' : `Move ${moveNumber} of ${total}` }), feedback && !finished && (jsxRuntime.jsx("span", { style: Object.assign(Object.assign({}, statusStyle), { color: feedback.isCorrect ? '#2e7d32' : '#c62828' }), children: feedback.isCorrect
@@ -1093,6 +1111,8 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
     const [currentIndex, setCurrentIndex] = react.useState(0);
     const [finished, setFinished] = react.useState(false);
     const [feedback, setFeedback] = react.useState(null);
+    const [displayFen, setDisplayFen] = react.useState(null);
+    const { correctMoveSquare, showCorrectMove, clearCorrectMoveFeedback, isShowingCorrectMove, } = reactChessCore.useCorrectMoveFeedback();
     const total = line.movesUci.length;
     const orientation = boardOrientationForLine(line.trainSide);
     const applyMove = react.useCallback((index) => {
@@ -1117,7 +1137,7 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
     }, [line.movesUci]);
     // Auto-play opponent moves and detect the end of the line.
     react.useEffect(() => {
-        if (finished) {
+        if (finished || isShowingCorrectMove) {
             return;
         }
         if (currentIndex >= total) {
@@ -1136,6 +1156,7 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
         line.trainSide,
         applyMove,
         opponentMoveDelayMs,
+        isShowingCorrectMove,
     ]);
     // Emit the completion event exactly once.
     react.useEffect(() => {
@@ -1147,15 +1168,16 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
     }, [finished]);
     const handleDrop = (source, target, piece) => {
         var _a, _b, _c;
-        if (finished) {
+        if (finished || isShowingCorrectMove) {
             return false;
         }
-        if (turnFromFen(chessRef.current.fen()) !== line.trainSide) {
+        const setupFen = displayFen !== null && displayFen !== void 0 ? displayFen : chessRef.current.fen();
+        if (turnFromFen(setupFen) !== line.trainSide) {
             return false;
         }
         const index = currentIndex;
         const expected = line.movesUci[index];
-        const dropResult = reactChessCore.evaluateExpectedMoveDrop(chessRef.current.fen(), source, target, piece, expected, true);
+        const dropResult = reactChessCore.evaluateExpectedMoveDrop(setupFen, source, target, piece, expected, true);
         if (dropResult.kind === 'illegal' || dropResult.kind === 'ignored') {
             return false;
         }
@@ -1165,16 +1187,38 @@ const LineBoardWithControls = ({ theme, boardTheme, line, onComplete, onMove, re
         const moveFeedback = { index, isCorrect, expectedSan };
         setFeedback(moveFeedback);
         (_c = onMoveRef.current) === null || _c === void 0 ? void 0 : _c.call(onMoveRef, moveFeedback);
-        applyMove(index);
+        if (isCorrect) {
+            const nextFen = reactChessCore.fenAfterUci(setupFen, dropResult.uci);
+            if (nextFen) {
+                setDisplayFen(nextFen);
+            }
+            showCorrectMove(target, () => {
+                setDisplayFen(null);
+                setFeedback(null);
+                clearCorrectMoveFeedback();
+                applyMove(index);
+            });
+        }
         return isCorrect;
     };
+    const boardFen = displayFen !== null && displayFen !== void 0 ? displayFen : fen;
+    const lastMoveUci = react.useMemo(() => {
+        var _a;
+        if (displayFen) {
+            return (_a = line.movesUci[currentIndex]) !== null && _a !== void 0 ? _a : null;
+        }
+        return reactChessCore.lastMoveUciAtPly(line.movesUci, currentIndex);
+    }, [currentIndex, displayFen, line.movesUci]);
     const moveNumber = Math.min(currentIndex + 1, total);
-    const isUserTurn = !finished && turnFromFen(fen) === line.trainSide && currentIndex < total;
+    const isUserTurn = !finished &&
+        !isShowingCorrectMove &&
+        turnFromFen(boardFen) === line.trainSide &&
+        currentIndex < total;
     const stackControlsBelow = useStackPuzzleControlsBelow();
     const controlsPlacement = stackControlsBelow
         ? 'below'
         : 'beside';
-    return (jsxRuntime.jsx(reactChessCore.ThemeProvider, { theme: theme, boardTheme: boardTheme, children: jsxRuntime.jsxs("div", { style: puzzlePlayRowStyle(controlsPlacement), children: [jsxRuntime.jsx("div", { style: puzzleBoardColumnStyle(boardWidth, controlsPlacement), children: jsxRuntime.jsx("div", { style: puzzleBoardSlotStyle(), children: jsxRuntime.jsx(LineBoard, { fen: fen, orientation: orientation, trainSide: line.trainSide, draggable: isUserTurn, onPieceDrop: handleDrop, boardWidth: boardWidth }) }) }), jsxRuntime.jsx("div", { style: puzzleControlsSlotStyle(controlsPlacement), children: renderControls({
+    return (jsxRuntime.jsx(reactChessCore.ThemeProvider, { theme: theme, boardTheme: boardTheme, children: jsxRuntime.jsxs("div", { style: puzzlePlayRowStyle(controlsPlacement), children: [jsxRuntime.jsx("div", { style: puzzleBoardColumnStyle(boardWidth, controlsPlacement), children: jsxRuntime.jsx("div", { style: puzzleBoardSlotStyle(), children: jsxRuntime.jsx(LineBoard, { fen: boardFen, orientation: orientation, trainSide: line.trainSide, draggable: isUserTurn, correctMoveSquare: correctMoveSquare, lastMoveUci: lastMoveUci, onPieceDrop: handleDrop, boardWidth: boardWidth }) }) }), 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.2",
+  "version": "1.0.4",
   "description": "React chess puzzle kit: play, controls, analysis, and browser Stockfish for endchess.training and other apps",
   "license": "MIT",
   "author": "Robert Blackwell",
@@ -76,6 +76,7 @@
     "react": "^18.3.1",
     "react-chess-core": "^0.1.1",
     "react-chessboard": "^4.7.1",
+    "react-dom": "^18.3.1",
     "storybook": "^8.2.9",
     "ts-jest": "^29.2.4",
     "vite": "^5.4.11",