react-chess-puzzle-kit 1.0.0

package/dist/index.esm.js

@@ -0,0 +1,861 @@
+import { useState, useEffect, useRef, useCallback } from 'react';
+import { jsx, jsxs } from 'react/jsx-runtime';
+import { ChessboardDnDProvider } from 'react-chessboard';
+import { HighlightChessboard, ThemeProvider, AnalysisErrorBoundary, AnalysisBoardCore, AnalysisBoardLayout, AnalysisBoard, DEFAULT_ANALYSIS_LAYOUT, boardSquareHighlightColors, analysisBoardHighlightColors } from 'react-chess-core';
+export { DEFAULT_ANALYSIS_LAYOUT } from 'react-chess-core';
+import { Chess } from 'chess.js';
+
+const emptyAnalysisContext = () => ({
+    initialFen: '',
+    solutionMoves: [],
+    currentPly: 0,
+    boardOrientation: 'white',
+});
+const buildAnalysisContext = (position) => {
+    if (!position) {
+        return emptyAnalysisContext();
+    }
+    return {
+        initialFen: position.getInitialFen(),
+        solutionMoves: position.getSolutionMoves(),
+        currentPly: position.getIndex(),
+        boardOrientation: position.getPlayerColor(),
+    };
+};
+const isAnalysisAvailable = (position, resultStatus) => {
+    if (!position) {
+        return false;
+    }
+    return (buildAnalysisContext(position).solutionMoves.length > 0 &&
+        resultStatus !== 'none');
+};
+
+const usePuzzleAnalysis = (position, resultStatus, puzzleNum) => {
+    const [isOpen, setIsOpen] = useState(false);
+    const [snapshot, setSnapshot] = useState(null);
+    const canOpen = isAnalysisAvailable(position, resultStatus);
+    useEffect(() => {
+        setIsOpen(false);
+        setSnapshot(null);
+    }, [puzzleNum]);
+    const openAnalysis = () => {
+        if (!canOpen || !position) {
+            return;
+        }
+        setSnapshot(buildAnalysisContext(position));
+        setIsOpen(true);
+    };
+    const closeAnalysis = () => {
+        setIsOpen(false);
+    };
+    return {
+        canOpen,
+        isOpen,
+        snapshot,
+        openAnalysis,
+        closeAnalysis,
+    };
+};
+
+const EMPTY_BOARD_FEN = '8/8/8/8/8/8/8/8 w - - 0 1';
+/**
+ * Single mounted board for puzzle play. Shows an empty board while the next
+ * position loads so the layout and controls do not flicker between cards.
+ */
+const PuzzlePlaySurface = ({ position, onFeedback, incInteractionNum, boardWidth, revealAnswerOnIncorrect = false, }) => {
+    var _a, _b, _c, _d, _e;
+    const onPieceDrop = (sourceSquare, targetSquare, piece) => {
+        if (!position || position.isSolutionRevealed()) {
+            return false;
+        }
+        if (!position.isLegalMove(sourceSquare, targetSquare)) {
+            return false;
+        }
+        const guess = position.tryGuess(sourceSquare, targetSquare, piece);
+        if (!guess.accepted) {
+            onFeedback({
+                index: position.getIndex(),
+                guess: { sourceSquare, targetSquare, piece },
+                isCorrect: false,
+            });
+            incInteractionNum();
+            setTimeout(() => {
+                if (revealAnswerOnIncorrect) {
+                    position.resetInteractions();
+                    position.revealCorrectMove();
+                }
+                else {
+                    position.resetInteractions();
+                }
+                incInteractionNum();
+            }, 500);
+            return false;
+        }
+        onFeedback({
+            index: position.getIndex(),
+            guess: { sourceSquare, targetSquare, piece },
+            isCorrect: true,
+            isFinished: guess.finished,
+        });
+        incInteractionNum();
+        setTimeout(() => {
+            position.resetInteractions();
+            incInteractionNum();
+        }, 500);
+        if (position.isAlternativeCheckmate()) {
+            incInteractionNum();
+            return true;
+        }
+        position.next();
+        incInteractionNum();
+        setTimeout(() => {
+            if (!position.isFinished()) {
+                position.next();
+            }
+            incInteractionNum();
+        }, 500);
+        return true;
+    };
+    return (jsx(ChessboardDnDProvider, { children: jsx(HighlightChessboard, { boardWidth: boardWidth, checkSquare: (_a = position === null || position === void 0 ? void 0 : position.getCheckSquare()) !== null && _a !== void 0 ? _a : '', hintSquare: (_b = position === null || position === void 0 ? void 0 : position.getHintSquare()) !== null && _b !== void 0 ? _b : null, incorrectMoveSquare: (_c = position === null || position === void 0 ? void 0 : position.getIncorrectMoveSquare()) !== null && _c !== void 0 ? _c : null, onPieceDrop: onPieceDrop, position: (_d = position === null || position === void 0 ? void 0 : position.fen()) !== null && _d !== void 0 ? _d : EMPTY_BOARD_FEN, boardOrientation: (_e = position === null || position === void 0 ? void 0 : position.getPlayerColor()) !== null && _e !== void 0 ? _e : 'white', arePiecesDraggable: position !== null, promotionDialogVariant: "modal" }) }));
+};
+
+const PuzzleBoard = ({ position, onFeedback, incInteractionNum, boardWidth, revealAnswerOnIncorrect = false, }) => (jsx(PuzzlePlaySurface, { position: position, onFeedback: onFeedback, incInteractionNum: incInteractionNum, boardWidth: boardWidth, revealAnswerOnIncorrect: revealAnswerOnIncorrect }));
+
+const isAttemptFinished = (resultStatus) => resultStatus === 'complete' || resultStatus === 'incorrect';
+/** Library default hint / next / analysis / result controls (unstyled buttons). */
+const DefaultPuzzleControls = ({ showHint, showSolution, nextPuzzle, resultStatus, analysis, controlState, }) => (jsxs("div", { style: rowStyle$1, children: [jsx("button", { type: "button", onClick: showHint, style: buttonStyle, disabled: !controlState.canShowHint, children: "Hint" }), jsx("button", { type: "button", onClick: showSolution, style: buttonStyle, disabled: !controlState.canShowSolution, children: "Show solution" }), jsx("button", { type: "button", onClick: nextPuzzle, style: buttonStyle, children: "Next puzzle" }), analysis.visible && isAttemptFinished(resultStatus) && (jsx("button", { type: "button", onClick: analysis.openAnalysis, style: buttonStyle, children: "Analysis" })), resultStatus === 'complete' && (jsx("span", { style: statusStyle$1, children: "Complete" })), resultStatus === 'incorrect' && (jsx("span", { style: Object.assign(Object.assign({}, statusStyle$1), { color: '#c62828' }), children: "Incorrect" }))] }));
+const defaultRenderControls = (showHint, showSolution, nextPuzzle, resultStatus, analysis, controlState) => (jsx(DefaultPuzzleControls, { showHint: showHint, showSolution: showSolution, nextPuzzle: nextPuzzle, resultStatus: resultStatus, analysis: analysis, controlState: controlState }));
+const rowStyle$1 = {
+    display: 'flex',
+    flexWrap: 'wrap',
+    alignItems: 'center',
+    gap: 8,
+    width: '100%',
+    minHeight: 96,
+    alignContent: 'flex-start',
+};
+const buttonStyle = {
+    cursor: 'pointer',
+    padding: '6px 12px',
+    fontSize: 14,
+    borderRadius: 4,
+    border: '1px solid #ccc',
+    background: '#f5f5f5',
+};
+const statusStyle$1 = {
+    fontSize: 14,
+    fontWeight: 600,
+    color: '#2e7d32',
+};
+
+/** Default pixel width for the live puzzle board (analysis uses {@link DEFAULT_ANALYSIS_LAYOUT}). */
+const DEFAULT_PUZZLE_BOARD_WIDTH = 480;
+/** Minimum height reserved below the board so controls do not shift when status changes. */
+const PUZZLE_CONTROLS_MIN_HEIGHT = 96;
+const puzzlePlayColumnStyle = (boardWidth) => ({
+    display: 'flex',
+    flexDirection: 'column',
+    width: boardWidth,
+    maxWidth: '100%',
+});
+const puzzleBoardSlotStyle = () => ({
+    width: '100%',
+    aspectRatio: '1 / 1',
+    flexShrink: 0,
+});
+const puzzleControlsSlotStyle = () => ({
+    minHeight: PUZZLE_CONTROLS_MIN_HEIGHT,
+    flexShrink: 0,
+    display: 'flex',
+    alignItems: 'flex-start',
+    marginTop: 8,
+});
+
+/** Apply a UCI move (e.g. `e7e8q`) without throwing. */
+function applyUciMove(chess, uci) {
+    if (!uci || uci.length < 4) {
+        return false;
+    }
+    const from = uci.slice(0, 2);
+    const to = uci.slice(2, 4);
+    const promotion = uci.length > 4 ? uci[4] : undefined;
+    try {
+        return chess.move({ from, to, promotion }) !== null;
+    }
+    catch (_a) {
+        try {
+            chess.move(uci);
+            return true;
+        }
+        catch (_b) {
+            return false;
+        }
+    }
+}
+class Position {
+    constructor() {
+        this.i = 0;
+        this.chess = new Chess();
+        this.moves = [];
+    }
+    getIndex() {
+        return this.i;
+    }
+    // Common methods shared by all positions
+    next() {
+        if (this.i >= this.moves.length) {
+            return false;
+        }
+        const uci = this.moves[this.i];
+        if (!applyUciMove(this.chess, uci)) {
+            return false;
+        }
+        this.i++;
+        return true;
+    }
+    prev() {
+        if (this.i > 0) {
+            this.chess.undo();
+            this.i--;
+            return true;
+        }
+        return false;
+    }
+    isFinished() {
+        return this.i >= this.moves.length;
+    }
+    /** True when a correct guess at the current index completes the puzzle. */
+    isCompletedByCorrectGuess() {
+        return this.i >= this.moves.length - 2;
+    }
+    fen() {
+        return this.chess.fen();
+    }
+    getCheckSquare() {
+        return getCheckSquareFromChess(this.chess);
+    }
+}
+function getCheckSquareFromChess(chess) {
+    if (!chess.inCheck()) {
+        return '';
+    }
+    const turn = chess.turn();
+    const kingPieceType = 'k';
+    const squaresWithPieces = chess.board().flatMap((row, rowIndex) => row.map((piece, colIndex) => ({
+        square: String.fromCharCode(97 + colIndex) + (8 - rowIndex),
+        piece: piece,
+    })));
+    const kingSquare = squaresWithPieces
+        .filter(({ piece }) => piece && piece.type === kingPieceType && piece.color === turn)
+        .map(({ square }) => square)[0];
+    return kingSquare !== null && kingSquare !== void 0 ? kingSquare : '';
+}
+/** Side to move for the final (user) ply in a puzzle line. */
+function playerColorForSolution(initialFen, moves) {
+    const chess = new Chess(initialFen);
+    const setupPlies = Math.max(0, moves.length - 1);
+    for (let j = 0; j < setupPlies; j++) {
+        applyUciMove(chess, moves[j]);
+    }
+    return chess.turn() === 'w' ? 'white' : 'black';
+}
+class PuzzlePosition extends Position {
+    constructor(initialFEN, moves) {
+        super();
+        this.isCorrect = false;
+        this.guessedMove = '';
+        this.isHintWanted = false;
+        this.solutionRevealed = false;
+        this.moveHistory = [];
+        this.usedAlternativeCheckmate = false;
+        this.tryGuess = (sourceSquare, targetSquare, piece) => {
+            var _a;
+            const candidates = this.buildCandidateUcis(sourceSquare, targetSquare);
+            if (candidates.length === 0) {
+                this.isCorrect = false;
+                this.guessedMove = `${sourceSquare}${targetSquare}`;
+                return { accepted: false, finished: false };
+            }
+            for (const uci of candidates) {
+                if (this.moves[this.i] === uci) {
+                    this.isCorrect = true;
+                    this.guessedMove = uci.slice(0, 4);
+                    return {
+                        accepted: true,
+                        finished: this.isCompletedByCorrectGuess(),
+                    };
+                }
+            }
+            for (const uci of candidates) {
+                if (this.isCheckmatingMove(uci) && this.applyCheckmateGuess(uci)) {
+                    this.isCorrect = true;
+                    return { accepted: true, finished: true };
+                }
+            }
+            this.isCorrect = false;
+            this.guessedMove = `${sourceSquare}${targetSquare}`;
+            this.moveHistory.push({
+                ply: this.moveHistory.length,
+                uci: (_a = candidates[candidates.length - 1]) !== null && _a !== void 0 ? _a : this.guessedMove,
+                actor: 'attempt',
+                isCorrect: false,
+            });
+            return { accepted: false, finished: false };
+        };
+        this.judgeGuess = (sourceSquare, targetSquare, piece) => this.tryGuess(sourceSquare, targetSquare, piece).accepted;
+        this.initialFen = initialFEN;
+        this.chess.load(initialFEN);
+        this.moves = moves;
+        this.playerColor = playerColorForSolution(initialFEN, moves);
+    }
+    next() {
+        if (this.i >= this.moves.length) {
+            return false;
+        }
+        const moveUci = this.moves[this.i];
+        const movingColor = this.chess.turn() === 'w' ? 'white' : 'black';
+        const result = super.next();
+        if (result) {
+            const san = this.chess.history().at(-1);
+            this.moveHistory.push({
+                ply: this.moveHistory.length,
+                uci: moveUci,
+                san,
+                actor: movingColor === this.playerColor ? 'player' : 'opponent',
+                isCorrect: true,
+            });
+        }
+        return result;
+    }
+    getInitialFen() {
+        return this.initialFen;
+    }
+    getSolutionMoves() {
+        return [...this.moves];
+    }
+    getMoveHistory() {
+        return [...this.moveHistory];
+    }
+    recordHint() {
+        var _a;
+        this.moveHistory.push({
+            ply: this.moveHistory.length,
+            uci: (_a = this.moves[this.i]) !== null && _a !== void 0 ? _a : '',
+            san: 'Hint',
+            actor: 'attempt',
+            isCorrect: false,
+        });
+    }
+    recordSolutionShown() {
+        this.moveHistory.push({
+            ply: this.moveHistory.length,
+            uci: '',
+            san: 'Solution',
+            actor: 'attempt',
+            isCorrect: false,
+        });
+    }
+    setSolutionRevealed(revealed) {
+        this.solutionRevealed = revealed;
+    }
+    isSolutionRevealed() {
+        return this.solutionRevealed;
+    }
+    /** Reset the board to replay an already-revealed solution walkthrough. */
+    replaySolution() {
+        this.chess.load(this.initialFen);
+        this.i = 0;
+        this.isCorrect = false;
+        this.guessedMove = '';
+        this.isHintWanted = false;
+        this.usedAlternativeCheckmate = false;
+        this.solutionRevealed = true;
+        const solutionIdx = this.moveHistory.findIndex((m) => m.san === 'Solution');
+        if (solutionIdx >= 0) {
+            this.moveHistory = this.moveHistory.slice(0, solutionIdx + 1);
+        }
+    }
+    /** Chess-legal move from the current puzzle position (ignores solution line). */
+    isLegalMove(sourceSquare, targetSquare) {
+        if (sourceSquare === targetSquare) {
+            return false;
+        }
+        return this.chess
+            .moves({ square: sourceSquare, verbose: true })
+            .some((move) => move.to === targetSquare);
+    }
+    buildCandidateUcis(sourceSquare, targetSquare) {
+        const lanMoves = this.chess
+            .moves({ square: sourceSquare, verbose: true })
+            .filter((move) => move.to === targetSquare)
+            .map((move) => move.lan);
+        return [...new Set(lanMoves)];
+    }
+    tryMakeUciMove(chess, uci) {
+        var _a;
+        if (!applyUciMove(chess, uci)) {
+            return null;
+        }
+        return (_a = chess.history({ verbose: true }).at(-1)) !== null && _a !== void 0 ? _a : null;
+    }
+    isCheckmatingMove(uci) {
+        const chess = new Chess(this.chess.fen());
+        return (this.tryMakeUciMove(chess, uci) !== null && chess.isCheckmate());
+    }
+    applyCheckmateGuess(uci) {
+        const result = this.tryMakeUciMove(this.chess, uci);
+        if (result === null || !this.chess.isCheckmate()) {
+            return false;
+        }
+        this.moveHistory.push({
+            ply: this.moveHistory.length,
+            uci,
+            san: result.san,
+            actor: 'player',
+            isCorrect: true,
+        });
+        this.i = this.moves.length;
+        this.guessedMove = uci.slice(0, 4);
+        this.usedAlternativeCheckmate = true;
+        return true;
+    }
+    resetInteractions() {
+        this.guessedMove = '';
+        this.isHintWanted = false;
+    }
+    /** Play the expected move at the current index and lock further input. */
+    revealCorrectMove() {
+        if (this.solutionRevealed || this.i >= this.moves.length) {
+            return false;
+        }
+        const played = this.next();
+        if (played) {
+            this.solutionRevealed = true;
+        }
+        return played;
+    }
+    /** True when the last correct guess applied an alternative checkmate. */
+    isAlternativeCheckmate() {
+        return this.usedAlternativeCheckmate;
+    }
+    wantsHint(wants) {
+        this.isHintWanted = wants;
+    }
+    getHintSquare() {
+        if (!this.isHintWanted) {
+            return '';
+        }
+        return this.hint().slice(0, 2);
+    }
+    hint() {
+        return this.moves[this.i];
+    }
+    getIncorrectMoveSquare() {
+        if (this.isCorrect) {
+            return '';
+        }
+        return this.guessedMove.slice(2, 4);
+    }
+    getPlayerColor() {
+        return this.playerColor;
+    }
+}
+class GamePosition extends Position {
+    constructor(PGN) {
+        super();
+        console.log(`pgn: ${PGN}`);
+        this.chess.loadPgn(PGN);
+        this.moves = this.chess.history();
+        this.chess.reset();
+        // console.log(`pgn: ${PGN}`);
+    }
+}
+
+/** Delay before auto-playing the opponent's opening move (ms). */
+const OPPONENT_OPENING_MOVE_DELAY_MS = 500;
+/** Brief pause so the user sees a correct result before the next card loads. */
+const AUTO_ADVANCE_ON_COMPLETE_DELAY_MS = 700;
+const SOLUTION_STEP_MS = 500;
+const PuzzleBoardWithControls = ({ theme, apiProxy, renderControls = defaultRenderControls, renderAnalysisSidebar, renderAnalysisContainer, renderEngineEvaluation, puzzleBoardWidth = DEFAULT_PUZZLE_BOARD_WIDTH, analysisLayout = DEFAULT_ANALYSIS_LAYOUT, renderAnalysisMain, engine, autoAdvanceOnComplete = false, revealAnswerOnIncorrect = false, }) => {
+    const { onFetch, onFetchError, onFeedback } = apiProxy;
+    const [position, setPosition] = useState(null);
+    const [puzzleNum, setPuzzleNum] = useState(0);
+    const [hasIncorrectAttempt, setHasIncorrectAttempt] = useState(false);
+    const [puzzleComplete, setPuzzleComplete] = useState(false);
+    const [, setInteractionNum] = useState(0);
+    const solutionAnimationRef = useRef({ cancelled: false, timeoutIds: [] });
+    const incInteractionNum = () => {
+        setInteractionNum((prev) => prev + 1);
+    };
+    const clearSolutionAnimation = () => {
+        const anim = solutionAnimationRef.current;
+        anim.cancelled = true;
+        anim.timeoutIds.forEach(clearTimeout);
+        solutionAnimationRef.current = { cancelled: false, timeoutIds: [] };
+    };
+    useEffect(() => {
+        let cancelled = false;
+        let openingMoveTimeoutId;
+        setPosition(null);
+        setHasIncorrectAttempt(false);
+        setPuzzleComplete(false);
+        onFetch()
+            .then((data) => {
+            if (cancelled) {
+                return;
+            }
+            if (!data || !data.fen || !data.moves) {
+                console.error('Invalid data fetched:', data);
+                return;
+            }
+            const newPosition = new PuzzlePosition(data.fen, data.moves);
+            setPosition(newPosition);
+            // Multi-move puzzles lead with an opponent setup ply; single-move lines
+            // (e.g. a first-ply opening trainer) are already on the player to move.
+            if (data.moves.length > 1) {
+                openingMoveTimeoutId = setTimeout(() => {
+                    if (cancelled) {
+                        return;
+                    }
+                    if (newPosition.next()) {
+                        incInteractionNum();
+                    }
+                }, OPPONENT_OPENING_MOVE_DELAY_MS);
+            }
+        })
+            .catch((error) => {
+            if (!cancelled) {
+                onFetchError === null || onFetchError === void 0 ? void 0 : onFetchError(error);
+            }
+        });
+        return () => {
+            cancelled = true;
+            clearSolutionAnimation();
+            if (openingMoveTimeoutId !== undefined) {
+                clearTimeout(openingMoveTimeoutId);
+            }
+        };
+    }, [puzzleNum]);
+    const handleFeedback = (feedbackData) => {
+        if (feedbackData.hintRequested ||
+            feedbackData.solutionShown ||
+            feedbackData.isCorrect === false) {
+            setHasIncorrectAttempt(true);
+        }
+        if (feedbackData.isFinished) {
+            setPuzzleComplete(true);
+        }
+        onFeedback(feedbackData);
+    };
+    const getResultStatus = () => {
+        const finished = puzzleComplete || (position !== null && position.isFinished());
+        if (finished) {
+            return 'complete';
+        }
+        if (!position) {
+            return 'none';
+        }
+        if (hasIncorrectAttempt) {
+            return 'incorrect';
+        }
+        return 'none';
+    };
+    const handleHintRequest = () => {
+        if (!position) {
+            return;
+        }
+        position.recordHint();
+        handleFeedback({ index: position.getIndex(), hintRequested: true });
+        position.wantsHint(true);
+        incInteractionNum();
+        setTimeout(() => {
+            position.resetInteractions();
+            incInteractionNum();
+        }, 500);
+    };
+    const runSolutionWalkthrough = (pos, emitFinishFeedback) => {
+        clearSolutionAnimation();
+        const anim = {
+            cancelled: false,
+            timeoutIds: [],
+        };
+        solutionAnimationRef.current = anim;
+        const schedule = (fn, ms) => {
+            const id = setTimeout(() => {
+                if (anim.cancelled) {
+                    return;
+                }
+                fn();
+            }, ms);
+            anim.timeoutIds.push(id);
+        };
+        const finish = () => {
+            setPuzzleComplete(true);
+            if (emitFinishFeedback) {
+                handleFeedback({
+                    index: pos.getIndex(),
+                    isFinished: true,
+                    isCorrect: false,
+                });
+            }
+            incInteractionNum();
+        };
+        const playNextMove = () => {
+            if (pos.isFinished()) {
+                return false;
+            }
+            const played = pos.next();
+            if (played) {
+                incInteractionNum();
+            }
+            return played;
+        };
+        const advance = () => {
+            if (anim.cancelled || pos.isFinished()) {
+                if (pos.isFinished()) {
+                    finish();
+                }
+                return;
+            }
+            if (!playNextMove()) {
+                if (pos.isFinished()) {
+                    finish();
+                }
+                return;
+            }
+            schedule(() => {
+                if (anim.cancelled) {
+                    return;
+                }
+                playNextMove();
+                if (pos.isFinished()) {
+                    finish();
+                    return;
+                }
+                schedule(advance, SOLUTION_STEP_MS);
+            }, SOLUTION_STEP_MS);
+        };
+        advance();
+    };
+    const handleShowSolution = () => {
+        if (!position) {
+            return;
+        }
+        if (position.isSolutionRevealed()) {
+            position.replaySolution();
+            setPuzzleComplete(false);
+            incInteractionNum();
+            runSolutionWalkthrough(position, false);
+            return;
+        }
+        if (position.isFinished()) {
+            return;
+        }
+        position.recordSolutionShown();
+        position.setSolutionRevealed(true);
+        position.wantsHint(false);
+        handleFeedback({
+            index: position.getIndex(),
+            solutionShown: true,
+            isCorrect: false,
+        });
+        incInteractionNum();
+        runSolutionWalkthrough(position, true);
+    };
+    const handleNextPuzzle = useCallback(() => {
+        setPuzzleNum((prevPuzzleNum) => prevPuzzleNum + 1);
+    }, []);
+    const resultStatus = getResultStatus();
+    useEffect(() => {
+        if (!autoAdvanceOnComplete) {
+            return;
+        }
+        if (resultStatus !== 'complete' || hasIncorrectAttempt) {
+            return;
+        }
+        const timer = setTimeout(() => {
+            handleNextPuzzle();
+        }, AUTO_ADVANCE_ON_COMPLETE_DELAY_MS);
+        return () => {
+            clearTimeout(timer);
+        };
+    }, [
+        autoAdvanceOnComplete,
+        resultStatus,
+        hasIncorrectAttempt,
+        handleNextPuzzle,
+        puzzleNum,
+    ]);
+    const controlState = {
+        canShowHint: position !== null &&
+            resultStatus === 'none' &&
+            !position.isSolutionRevealed(),
+        canShowSolution: position !== null &&
+            (position.isSolutionRevealed() || !position.isFinished()),
+    };
+    const analysis = usePuzzleAnalysis(position, resultStatus, puzzleNum);
+    const analysisSnapshot = analysis.isOpen && analysis.snapshot ? analysis.snapshot : null;
+    const useHostAnalysisUi = Boolean(renderAnalysisSidebar &&
+        renderAnalysisContainer &&
+        (renderEngineEvaluation || (engine === null || engine === void 0 ? void 0 : engine.enabled) === false));
+    return (jsx(ThemeProvider, { theme: theme, children: analysisSnapshot ? (jsx(AnalysisErrorBoundary, { onClose: analysis.closeAnalysis, children: useHostAnalysisUi ? (jsx(AnalysisBoardCore, { analysisContext: analysisSnapshot, onClose: analysis.closeAnalysis, theme: theme, boardWidth: analysisLayout.boardWidth, engine: engine, renderMain: renderAnalysisMain !== null && renderAnalysisMain !== void 0 ? renderAnalysisMain : (({ board, sidebar, model }) => (jsx(AnalysisBoardLayout, { layout: analysisLayout, model: model, board: board, sidebar: sidebar }))), renderSidebar: renderAnalysisSidebar, renderContainer: renderAnalysisContainer, renderEngineEvaluation: renderEngineEvaluation !== null && renderEngineEvaluation !== void 0 ? renderEngineEvaluation : (() => null) })) : (jsx(AnalysisBoard, { analysisContext: analysisSnapshot, onClose: analysis.closeAnalysis, theme: theme, layout: analysisLayout, engine: engine, renderMain: renderAnalysisMain, renderSidebar: renderAnalysisSidebar, renderContainer: renderAnalysisContainer, renderEngineEvaluation: renderEngineEvaluation })) })) : (jsxs("div", { style: puzzlePlayColumnStyle(puzzleBoardWidth), children: [jsx("div", { style: puzzleBoardSlotStyle(), children: jsx(PuzzlePlaySurface, { position: position, boardWidth: puzzleBoardWidth, onFeedback: handleFeedback, incInteractionNum: incInteractionNum, revealAnswerOnIncorrect: revealAnswerOnIncorrect }) }), jsx("div", { style: puzzleControlsSlotStyle(), children: renderControls(handleHintRequest, handleShowSolution, handleNextPuzzle, resultStatus, {
+                        visible: analysis.canOpen,
+                        openAnalysis: analysis.openAnalysis,
+                    }, controlState) })] })) }));
+};
+
+/**
+ * Board view for line drilling: a plain themed board that only lets the trainer
+ * 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 } }) }));
+
+/** 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
+                ? `Correct: ${feedback.expectedSan}`
+                : `Best was ${feedback.expectedSan}` })), isUserTurn && !finished && jsx("span", { style: hintStyle, children: "Your move" })] }));
+const defaultRenderLineControls = (props) => (jsx(DefaultLineControls, Object.assign({}, props)));
+const rowStyle = {
+    display: 'flex',
+    flexWrap: 'wrap',
+    alignItems: 'center',
+    gap: 8,
+    width: '100%',
+    minHeight: 96,
+    alignContent: 'flex-start',
+};
+const statusStyle = {
+    fontSize: 14,
+    fontWeight: 600,
+};
+const hintStyle = {
+    fontSize: 13,
+    color: '#9e9e9e',
+};
+
+const DEFAULT_OPPONENT_MOVE_DELAY_MS = 450;
+const turnFromFen = (fen) => fen.trim().split(/\s+/)[1] === 'b' ? 'b' : 'w';
+const boardOrientationForLine = (side) => side === 'b' ? 'black' : 'white';
+/**
+ * Guided line-drill board: walks a known move sequence, auto-playing the
+ * opponent and grading each of the trainer's moves against the line. Mirrors
+ * {@link PuzzleBoardWithControls} but for opening/line repetition rather than
+ * tactical puzzles. Mount one instance per drill (key it by line) so its
+ * internal state resets between lines.
+ */
+const LineBoardWithControls = ({ theme, line, onComplete, onMove, renderControls = defaultRenderLineControls, boardWidth = DEFAULT_PUZZLE_BOARD_WIDTH, opponentMoveDelayMs = DEFAULT_OPPONENT_MOVE_DELAY_MS, }) => {
+    const chessRef = useRef(new Chess(line.startFen));
+    const perMoveRef = useRef([]);
+    const completedRef = useRef(false);
+    const onCompleteRef = useRef(onComplete);
+    onCompleteRef.current = onComplete;
+    const onMoveRef = useRef(onMove);
+    onMoveRef.current = onMove;
+    const [fen, setFen] = useState(line.startFen);
+    const [currentIndex, setCurrentIndex] = useState(0);
+    const [finished, setFinished] = useState(false);
+    const [feedback, setFeedback] = useState(null);
+    const total = line.movesUci.length;
+    const orientation = boardOrientationForLine(line.trainSide);
+    const applyMove = useCallback((index) => {
+        const uci = line.movesUci[index];
+        if (!uci) {
+            setFinished(true);
+            return;
+        }
+        const from = uci.slice(0, 2);
+        const to = uci.slice(2, 4);
+        const promotion = uci.length > 4 ? uci.slice(4) : undefined;
+        try {
+            chessRef.current.move({ from, to, promotion });
+        }
+        catch (_a) {
+            // Stored line should always be legal; bail out gracefully if not.
+            setFinished(true);
+            return;
+        }
+        setFen(chessRef.current.fen());
+        setCurrentIndex(index + 1);
+    }, [line.movesUci]);
+    // Auto-play opponent moves and detect the end of the line.
+    useEffect(() => {
+        if (finished) {
+            return;
+        }
+        if (currentIndex >= total) {
+            setFinished(true);
+            return;
+        }
+        if (turnFromFen(chessRef.current.fen()) !== line.trainSide) {
+            const timer = setTimeout(() => applyMove(currentIndex), opponentMoveDelayMs);
+            return () => clearTimeout(timer);
+        }
+        return undefined;
+    }, [
+        currentIndex,
+        finished,
+        total,
+        line.trainSide,
+        applyMove,
+        opponentMoveDelayMs,
+    ]);
+    // Emit the completion event exactly once.
+    useEffect(() => {
+        if (!finished || completedRef.current) {
+            return;
+        }
+        completedRef.current = true;
+        onCompleteRef.current(perMoveRef.current);
+    }, [finished]);
+    const handleDrop = (source, target) => {
+        var _a, _b, _c, _d;
+        if (finished) {
+            return false;
+        }
+        if (turnFromFen(chessRef.current.fen()) !== line.trainSide) {
+            return false;
+        }
+        const index = currentIndex;
+        let userUci;
+        try {
+            const probe = new Chess(chessRef.current.fen());
+            const move = probe.move({ from: source, to: target, promotion: 'q' });
+            if (!move) {
+                return false;
+            }
+            userUci = `${move.from}${move.to}${(_a = move.promotion) !== null && _a !== void 0 ? _a : ''}`;
+        }
+        catch (_e) {
+            return false;
+        }
+        const expected = line.movesUci[index];
+        const isCorrect = userUci.toLowerCase() === expected.toLowerCase();
+        const expectedSan = (_c = (_b = line.movesSan) === null || _b === void 0 ? void 0 : _b[index]) !== null && _c !== void 0 ? _c : expected;
+        perMoveRef.current.push({ index, isCorrect });
+        const moveFeedback = { index, isCorrect, expectedSan };
+        setFeedback(moveFeedback);
+        (_d = onMoveRef.current) === null || _d === void 0 ? void 0 : _d.call(onMoveRef, moveFeedback);
+        applyMove(index);
+        return isCorrect;
+    };
+    const moveNumber = Math.min(currentIndex + 1, total);
+    const isUserTurn = !finished && turnFromFen(fen) === line.trainSide && currentIndex < total;
+    return (jsx(ThemeProvider, { theme: theme, children: jsxs("div", { style: puzzlePlayColumnStyle(boardWidth), children: [jsx("div", { style: puzzleBoardSlotStyle(), children: jsx(LineBoard, { fen: fen, orientation: orientation, trainSide: line.trainSide, draggable: isUserTurn, onPieceDrop: handleDrop, boardWidth: boardWidth }) }), jsx("div", { style: puzzleControlsSlotStyle(), children: renderControls({
+                        trainSide: line.trainSide,
+                        moveNumber,
+                        total,
+                        finished,
+                        isUserTurn,
+                        feedback,
+                    }) })] }) }));
+};
+
+/**
+ * Puzzle-kit public API — puzzle play and post-puzzle analysis glue.
+ * Board theme, analysis UI, and Stockfish: import from `react-chess-core`.
+ */
+/** @deprecated Import {@link boardSquareHighlightColors} and {@link analysisBoardHighlightColors} from `react-chess-core`. */
+const squareHighlightColors = Object.assign(Object.assign({}, boardSquareHighlightColors), analysisBoardHighlightColors);
+
+export { DEFAULT_PUZZLE_BOARD_WIDTH, DefaultLineControls, DefaultPuzzleControls, GamePosition, LineBoard, LineBoardWithControls, Position, PuzzleBoard, PuzzleBoardWithControls, PuzzlePosition, applyUciMove, buildAnalysisContext, defaultRenderControls, defaultRenderLineControls, emptyAnalysisContext, getCheckSquareFromChess, isAnalysisAvailable, playerColorForSolution, squareHighlightColors, usePuzzleAnalysis };