react-chess-replay-trainer 0.0.1

package/dist/index.esm.js

@@ -0,0 +1,410 @@
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+import { useState, useRef, useEffect, useMemo, useCallback } from 'react';
+import { ChessboardDnDProvider } from 'react-chessboard';
+import { ThemeProvider, HighlightChessboard, PlyNavigation, AnalysisErrorBoundary, AnalysisBoard } from 'react-chess-core';
+export { AnalysisBoard, AnalysisBoardCore, AnalysisErrorBoundary, DEFAULT_ANALYSIS_LAYOUT, DefaultPlyNavigation, PlyNavigation, defaultRenderPlyNavigation } from 'react-chess-core';
+import { Chess } from 'chess.js';
+
+/** Standard chess starting position; game move lists replay from here. */
+const REPLAY_START_FEN = 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1';
+const DEFAULT_BOARD_WIDTH = 480;
+
+/** Build a core {@link AnalysisContext} for the current replay browse position. */
+function buildReplayAnalysisContext(game, plyIndex, boardOrientation) {
+    return {
+        initialFen: REPLAY_START_FEN,
+        solutionMoves: game.movesUci,
+        currentPly: Math.max(0, Math.min(plyIndex, game.movesUci.length)),
+        boardOrientation,
+    };
+}
+
+/** Compare positions ignoring move clocks (first four FEN fields). */
+function normalizeFen(fen) {
+    return fen.trim().split(/\s+/).slice(0, 4).join(' ');
+}
+function applyUci(chess, uci) {
+    const from = uci.slice(0, 2);
+    const to = uci.slice(2, 4);
+    const promotion = uci.length > 4 ? uci[4] : undefined;
+    const move = chess.move({ from, to, promotion });
+    if (!move) {
+        throw new Error(`Illegal UCI move: ${uci}`);
+    }
+}
+/** FEN after applying the first `ply` moves from the standard start. */
+function fenAtPly(movesUci, ply) {
+    const chess = new Chess(REPLAY_START_FEN);
+    for (let i = 0; i < ply && i < movesUci.length; i++) {
+        applyUci(chess, movesUci[i]);
+    }
+    return chess.fen();
+}
+/** Index of the next move to play to reach `targetFen`, or 0 if not found. */
+function findPlyIndexForFen(movesUci, targetFen) {
+    const target = normalizeFen(targetFen);
+    const chess = new Chess(REPLAY_START_FEN);
+    if (normalizeFen(chess.fen()) === target) {
+        return 0;
+    }
+    for (let i = 0; i < movesUci.length; i++) {
+        applyUci(chess, movesUci[i]);
+        if (normalizeFen(chess.fen()) === target) {
+            return i + 1;
+        }
+    }
+    return 0;
+}
+function sideToMove(fen) {
+    return fen.trim().split(/\s+/)[1] === 'b' ? 'b' : 'w';
+}
+/** Resolve a board drag into a legal UCI string, or null when illegal. */
+function uciFromDrop(fen, sourceSquare, targetSquare, piece) {
+    var _a, _b;
+    const chess = new Chess(fen);
+    const pieceType = (_a = piece[1]) === null || _a === void 0 ? void 0 : _a.toLowerCase();
+    const legal = chess
+        .moves({ square: sourceSquare, verbose: true })
+        .find((move) => move.to === targetSquare &&
+        (!move.promotion || move.promotion === pieceType));
+    if (!legal)
+        return null;
+    return `${legal.from}${legal.to}${(_b = legal.promotion) !== null && _b !== void 0 ? _b : ''}`;
+}
+
+/** Pause (ms) before the opponent's reply is auto-played in single-color drills. */
+const OPPONENT_MOVE_DELAY_MS = 350;
+function useReplayTrainer({ gameId, startFen, fetchGame, onMiss, onComplete, }) {
+    const [game, setGame] = useState(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const [mode, setMode] = useState('browse');
+    const [trainColor, setTrainColor] = useState('both');
+    const [plyIndex, setPlyIndex] = useState(0);
+    const [feedback, setFeedback] = useState(null);
+    const [expectedSan, setExpectedSan] = useState(null);
+    const [expectedUci, setExpectedUci] = useState(null);
+    const fetchGameRef = useRef(fetchGame);
+    fetchGameRef.current = fetchGame;
+    const onMissRef = useRef(onMiss);
+    onMissRef.current = onMiss;
+    const onCompleteRef = useRef(onComplete);
+    onCompleteRef.current = onComplete;
+    const recordedRef = useRef(new Set());
+    const completedFiredRef = useRef(false);
+    useEffect(() => {
+        let cancelled = false;
+        setLoading(true);
+        setError(null);
+        setGame(null);
+        recordedRef.current = new Set();
+        completedFiredRef.current = false;
+        setMode('browse');
+        setTrainColor('both');
+        setFeedback(null);
+        setExpectedSan(null);
+        setExpectedUci(null);
+        fetchGameRef
+            .current(gameId)
+            .then((loaded) => {
+            if (cancelled)
+                return;
+            if (!loaded) {
+                setError('Game not found.');
+                return;
+            }
+            setGame(loaded);
+            setPlyIndex(startFen ? findPlyIndexForFen(loaded.movesUci, startFen) : 0);
+        })
+            .catch((err) => {
+            if (cancelled)
+                return;
+            setError(err instanceof Error ? err.message : 'Failed to load game.');
+        })
+            .finally(() => {
+            if (!cancelled)
+                setLoading(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [gameId, startFen]);
+    const movesUci = useMemo(() => { var _a; return (_a = game === null || game === void 0 ? void 0 : game.movesUci) !== null && _a !== void 0 ? _a : []; }, [game]);
+    const totalPly = movesUci.length;
+    const fen = useMemo(() => fenAtPly(movesUci, plyIndex), [movesUci, plyIndex]);
+    const complete = plyIndex >= totalPly && totalPly > 0;
+    const sideToMove$1 = sideToMove(fen);
+    const isUserTurn = trainColor === 'both' ||
+        (trainColor === 'white' && sideToMove$1 === 'w') ||
+        (trainColor === 'black' && sideToMove$1 === 'b');
+    const clearTransient = useCallback(() => {
+        setFeedback(null);
+        setExpectedSan(null);
+        setExpectedUci(null);
+    }, []);
+    const goTo = useCallback((ply) => {
+        const clamped = Math.max(0, Math.min(ply, totalPly));
+        completedFiredRef.current = clamped >= totalPly ? completedFiredRef.current : false;
+        setPlyIndex(clamped);
+        clearTransient();
+    }, [totalPly, clearTransient]);
+    const goFirst = useCallback(() => goTo(0), [goTo]);
+    const goPrev = useCallback(() => goTo(plyIndex - 1), [goTo, plyIndex]);
+    const goNext = useCallback(() => goTo(plyIndex + 1), [goTo, plyIndex]);
+    const goLast = useCallback(() => goTo(totalPly), [goTo, totalPly]);
+    const startTraining = useCallback((color = 'both') => {
+        setTrainColor(color);
+        setMode('train');
+        clearTransient();
+    }, [clearTransient]);
+    const stopTraining = useCallback(() => {
+        setMode('browse');
+        clearTransient();
+    }, [clearTransient]);
+    const recordMiss = useCallback((index) => {
+        var _a, _b, _c;
+        if (recordedRef.current.has(index))
+            return;
+        recordedRef.current.add(index);
+        const expectedUci = movesUci[index];
+        if (!expectedUci)
+            return;
+        const positionFen = fenAtPly(movesUci, index);
+        const miss = {
+            index,
+            fen: positionFen,
+            expectedUci,
+            expectedSan: (_b = (_a = game === null || game === void 0 ? void 0 : game.movesSan) === null || _a === void 0 ? void 0 : _a[index]) !== null && _b !== void 0 ? _b : expectedUci,
+            sideToMove: sideToMove(positionFen),
+            setupUci: index > 0 ? movesUci[index - 1] : undefined,
+            setupFen: index > 0 ? fenAtPly(movesUci, index - 1) : undefined,
+        };
+        (_c = onMissRef.current) === null || _c === void 0 ? void 0 : _c.call(onMissRef, miss);
+    }, [movesUci, game]);
+    const revealMove = useCallback(() => {
+        var _a, _b;
+        if (complete || !isUserTurn)
+            return;
+        const uci = movesUci[plyIndex];
+        if (!uci)
+            return;
+        setExpectedUci(uci);
+        setExpectedSan((_b = (_a = game === null || game === void 0 ? void 0 : game.movesSan) === null || _a === void 0 ? void 0 : _a[plyIndex]) !== null && _b !== void 0 ? _b : uci);
+        setFeedback('incorrect');
+        recordMiss(plyIndex);
+    }, [complete, game, movesUci, plyIndex, recordMiss, isUserTurn]);
+    const handleDrop = useCallback((source, target, piece) => {
+        var _a, _b;
+        if (mode !== 'train' || complete || !isUserTurn)
+            return false;
+        const expectedUci = movesUci[plyIndex];
+        if (!expectedUci)
+            return false;
+        const uci = uciFromDrop(fen, source, target, piece);
+        if (!uci)
+            return false;
+        if (uci.toLowerCase() === expectedUci.toLowerCase()) {
+            setFeedback('correct');
+            setExpectedSan(null);
+            setExpectedUci(null);
+            setPlyIndex((p) => p + 1);
+            return true;
+        }
+        setFeedback('incorrect');
+        setExpectedSan((_b = (_a = game === null || game === void 0 ? void 0 : game.movesSan) === null || _a === void 0 ? void 0 : _a[plyIndex]) !== null && _b !== void 0 ? _b : expectedUci);
+        setExpectedUci(expectedUci);
+        recordMiss(plyIndex);
+        return false;
+    }, [mode, complete, isUserTurn, movesUci, plyIndex, fen, game, recordMiss]);
+    useEffect(() => {
+        var _a;
+        if (mode === 'train' && complete && !completedFiredRef.current) {
+            completedFiredRef.current = true;
+            (_a = onCompleteRef.current) === null || _a === void 0 ? void 0 : _a.call(onCompleteRef);
+        }
+    }, [mode, complete]);
+    // In single-color drills, auto-play the opponent's reply once it's their turn
+    // (e.g. after the user guesses correctly, or when training starts mid-game).
+    useEffect(() => {
+        if (mode !== 'train' || complete || trainColor === 'both' || isUserTurn) {
+            return;
+        }
+        const id = setTimeout(() => {
+            setPlyIndex((p) => (p < totalPly ? p + 1 : p));
+            clearTransient();
+        }, OPPONENT_MOVE_DELAY_MS);
+        return () => clearTimeout(id);
+    }, [mode, complete, trainColor, isUserTurn, plyIndex, totalPly, clearTransient]);
+    return {
+        game,
+        loading,
+        error,
+        mode,
+        fen,
+        plyIndex,
+        totalPly,
+        complete,
+        sideToMove: sideToMove$1,
+        trainColor,
+        isUserTurn,
+        feedback,
+        expectedSan,
+        expectedUci,
+        canPrev: plyIndex > 0,
+        canNext: plyIndex < totalPly,
+        goFirst,
+        goPrev,
+        goNext,
+        goLast,
+        goTo,
+        startTraining,
+        stopTraining,
+        revealMove,
+        handleDrop,
+    };
+}
+
+const TRAIN_COLOR_LABEL = {
+    white: 'Training White',
+    black: 'Training Black',
+    both: 'Training Both',
+};
+const columnStyle = {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 8,
+};
+const centerStyle = {
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: 12,
+    minHeight: 200,
+};
+const headerStyle = {
+    display: 'flex',
+    justifyContent: 'space-between',
+    alignItems: 'baseline',
+    fontSize: 14,
+};
+const controlsRowStyle = {
+    display: 'flex',
+    flexWrap: 'wrap',
+    gap: 8,
+    justifyContent: 'center',
+};
+const playerNameStyle = {
+    fontWeight: 600,
+};
+const feedbackContainerStyle = {
+    minHeight: 24,
+    textAlign: 'center',
+};
+const customBoardStyle = {
+    borderRadius: 4,
+};
+function palette(theme) {
+    return {
+        text: theme === 'dark' ? '#e8e8e8' : '#1a1a1a',
+        subtle: theme === 'dark' ? '#9aa0a6' : '#5f6368',
+        border: theme === 'dark' ? '#3a3a3a' : '#d0d0d0',
+        surface: theme === 'dark' ? '#262626' : '#f5f5f5',
+        primary: '#3a7bd5',
+        success: '#2e7d32',
+        error: '#c62828',
+    };
+}
+function mainContainerStyle(boardWidth, colors) {
+    return Object.assign(Object.assign({}, columnStyle), { width: boardWidth, color: colors.text });
+}
+function centerContainerStyle(boardWidth, color) {
+    return Object.assign(Object.assign({}, centerStyle), { width: boardWidth, color });
+}
+function subtleTextStyle(colors) {
+    return { color: colors.subtle };
+}
+function statusLineStyle(colors) {
+    return { color: colors.subtle, fontSize: 13, textAlign: 'center' };
+}
+function feedbackMessageStyle(colors, tone) {
+    return {
+        color: tone === 'success' ? colors.success : colors.error,
+        fontWeight: 600,
+    };
+}
+function buttonStyle(colors, variant) {
+    const base = {
+        padding: variant === 'nav' ? '4px 10px' : '8px 14px',
+        borderRadius: 6,
+        cursor: 'pointer',
+        fontSize: 14,
+        fontWeight: 600,
+        border: `1px solid ${colors.border}`,
+        background: colors.surface,
+        color: colors.text,
+    };
+    if (variant === 'primary') {
+        return Object.assign(Object.assign({}, base), { background: colors.primary, borderColor: colors.primary, color: '#fff' });
+    }
+    return base;
+}
+
+/**
+ * Browse a game freely, then drill it from any point. Browsing (first / prev /
+ * next / last / slider) never records anything; once the user hits "Train from
+ * here" each wrong move is reported through {@link ReplayTrainerProps.onMiss}.
+ */
+const ReplayTrainer = ({ gameId, fetchGame, startFen, onMiss, onComplete, onExit, theme = 'dark', boardWidth = DEFAULT_BOARD_WIDTH, orientation = 'white', engine, renderPlyNavigation, showPlyScrubber = true, }) => {
+    var _a, _b, _c;
+    const state = useReplayTrainer({ gameId, startFen, fetchGame, onMiss, onComplete });
+    const colors = palette(theme);
+    const [analysisOpen, setAnalysisOpen] = useState(false);
+    const [analysisSnapshot, setAnalysisSnapshot] = useState(null);
+    const boardOrientation = state.trainColor === 'white'
+        ? 'white'
+        : state.trainColor === 'black'
+            ? 'black'
+            : orientation;
+    const openAnalysis = useCallback(() => {
+        if (!state.game) {
+            return;
+        }
+        setAnalysisSnapshot(buildReplayAnalysisContext(state.game, state.plyIndex, boardOrientation));
+        setAnalysisOpen(true);
+    }, [state.game, state.plyIndex, boardOrientation]);
+    const closeAnalysis = useCallback(() => {
+        setAnalysisOpen(false);
+    }, []);
+    if (state.loading) {
+        return (jsx("div", { style: centerContainerStyle(boardWidth, colors.subtle), children: "Loading game\u2026" }));
+    }
+    if (state.error || !state.game) {
+        return (jsxs("div", { style: centerContainerStyle(boardWidth, colors.error), children: [(_a = state.error) !== null && _a !== void 0 ? _a : 'Game unavailable.', onExit && (jsx("button", { type: "button", onClick: onExit, style: buttonStyle(colors, 'ghost'), children: "Back" }))] }));
+    }
+    const { game } = state;
+    const training = state.mode === 'train';
+    const customArrows = state.expectedUci && (state.feedback === 'incorrect')
+        ? [
+            [
+                state.expectedUci.slice(0, 2),
+                state.expectedUci.slice(2, 4),
+                colors.primary,
+            ],
+        ]
+        : [];
+    const draggable = training && !state.complete;
+    return (jsxs(ThemeProvider, { theme: theme, children: [jsxs("div", { style: mainContainerStyle(boardWidth, colors), children: [jsxs("div", { style: headerStyle, children: [jsxs("span", { style: playerNameStyle, children: [((_b = game.white) !== null && _b !== void 0 ? _b : 'White'), " vs ", ((_c = game.black) !== null && _c !== void 0 ? _c : 'Black')] }), game.result && jsx("span", { style: subtleTextStyle(colors), children: game.result })] }), jsx(ChessboardDnDProvider, { children: jsx(HighlightChessboard, { boardWidth: boardWidth, checkSquare: "", hintSquare: null, incorrectMoveSquare: null, position: state.fen, boardOrientation: boardOrientation, arePiecesDraggable: draggable, isDraggablePiece: ({ piece }) => {
+                                if (state.trainColor === 'white')
+                                    return piece[0] === 'w';
+                                if (state.trainColor === 'black')
+                                    return piece[0] === 'b';
+                                return piece[0] === state.sideToMove;
+                            }, onPieceDrop: (source, target, piece) => state.handleDrop(source, target, piece), customArrows: customArrows, autoPromoteToQueen: true, areArrowsAllowed: false, customBoardStyle: customBoardStyle }) }), jsx(PlyNavigation, { plyIndex: state.plyIndex, totalPly: state.totalPly, canPrev: state.canPrev, canNext: state.canNext, onGoFirst: state.goFirst, onGoPrev: state.goPrev, onGoNext: state.goNext, onGoLast: state.goLast, onGoTo: state.goTo, theme: theme, showScrubber: showPlyScrubber, renderPlyNavigation: renderPlyNavigation }), jsxs("div", { style: statusLineStyle(colors), children: ["Half move ", Math.min(state.plyIndex + (state.complete ? 0 : 1), state.totalPly), " of", ' ', state.totalPly, training && !state.complete && (jsxs(Fragment, { children: [` · ${TRAIN_COLOR_LABEL[state.trainColor]}`, state.trainColor === 'both'
+                                        ? ` · ${state.sideToMove === 'b' ? 'Black' : 'White'} to move`
+                                        : state.isUserTurn
+                                            ? ' · Your move'
+                                            : ' · Opponent replying…'] }))] }), jsxs("div", { style: controlsRowStyle, children: [jsx("button", { type: "button", onClick: openAnalysis, style: buttonStyle(colors, 'primary'), children: "Analyze" }), !training && (jsxs(Fragment, { children: [jsx("button", { type: "button", onClick: () => state.startTraining('white'), disabled: state.complete, style: buttonStyle(colors, 'primary'), children: "Train White" }), jsx("button", { type: "button", onClick: () => state.startTraining('black'), disabled: state.complete, style: buttonStyle(colors, 'primary'), children: "Train Black" }), jsx("button", { type: "button", onClick: () => state.startTraining('both'), disabled: state.complete, style: buttonStyle(colors, 'primary'), children: "Train Both" })] })), training && (jsxs(Fragment, { children: [jsx("button", { type: "button", onClick: state.revealMove, disabled: state.complete || !state.isUserTurn, style: buttonStyle(colors, 'ghost'), children: "Show move" }), jsx("button", { type: "button", onClick: state.stopTraining, style: buttonStyle(colors, 'ghost'), children: "Stop drilling" })] })), onExit && (jsx("button", { type: "button", onClick: onExit, style: buttonStyle(colors, 'ghost'), children: "Exit" }))] }), jsxs("div", { style: feedbackContainerStyle, children: [state.complete && training && (jsx("span", { style: feedbackMessageStyle(colors, 'success'), children: "End of game \u2014 drill complete" })), !state.complete && state.feedback === 'correct' && (jsx("span", { style: feedbackMessageStyle(colors, 'success'), children: "Correct" })), !state.complete && state.feedback === 'incorrect' && (jsxs("span", { style: feedbackMessageStyle(colors, 'error'), children: ["Game move was ", state.expectedSan] }))] })] }), analysisOpen && analysisSnapshot && (jsx(AnalysisErrorBoundary, { onClose: closeAnalysis, children: jsx(AnalysisBoard, { analysisContext: analysisSnapshot, onClose: closeAnalysis, theme: theme, engine: engine }) }))] }));
+};
+
+export { DEFAULT_BOARD_WIDTH, REPLAY_START_FEN, ReplayTrainer, buildReplayAnalysisContext, fenAtPly, findPlyIndexForFen, normalizeFen, sideToMove, uciFromDrop, useReplayTrainer };