react-chess-explorer 0.0.3 → 0.0.5

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Robert Blackwell
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Robert Blackwell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,63 +1,65 @@
-# react-chess-explorer
-
-```bash
-npm install
-npm run build
-```
-
-React components for **browsing and replaying chess games**. This package depends on **`react-chess-core` only** (board + engine primitives), not `react-chess-puzzle-kit`.
-
-**Status:** Phase 5 scaffold — paste requirements into `docs/REQUIREMENTS.md` (or issue) before implementing replay UI.
-
----
-
-## Local setup
-
-```bash
-# Build core first
-cd ../react-chess-core && npm run build
-
-cd ../react-chess-explorer
-npm install
-npm run build
-```
-
-**Peer dependencies:** `react`, `react-chessboard`, `chess.js`, **`react-chess-core`**
-
-```bash
-npm install react-chess-explorer react-chess-core
-```
-
----
-
-## Exports (scaffold)
-
-| Export | Role |
-|--------|------|
-| **`ExplorerPlaceholder`** | Themed board at start position + scaffold label |
-| **`EXPLORER_START_FEN`** | Default FEN constant |
-
----
-
-## Requirements
-
-Add product/API requirements here when ready:
-
-- `docs/REQUIREMENTS.md` (create when you paste the doc)
-
-Planned scope (from migration plan): move list, ply navigation, optional engine — wired to EndChess `/games` routes.
-
----
-
-## Related packages
-
-| Package | Role |
-|---------|------|
-| [react-chess-core](https://github.com/reblackwell3/react-chess-core) | Board theme, highlights, Stockfish |
-| [react-chess-puzzle-kit](https://github.com/reblackwell3/react-chess-puzzle-kit) | Puzzles (separate; not a dependency) |
-
----
-
-## License
-
-MIT © Robert Blackwell
+# react-chess-explorer
+
+```bash
+npm install
+npm run build
+```
+
+React components for **browsing and replaying chess games**. This package depends on **`react-chess-core` only** (board + engine primitives), not `react-chess-puzzle-kit`.
+
+Used in production at [endchess.com](https://endchess.com).
+
+**Status:** Phase 5 scaffold — paste requirements into `docs/REQUIREMENTS.md` (or issue) before implementing replay UI.
+
+---
+
+## Local setup
+
+```bash
+# Build core first
+cd ../react-chess-core && npm run build
+
+cd ../react-chess-explorer
+npm install
+npm run build
+```
+
+**Peer dependencies:** `react`, `react-chessboard`, `chess.js`, **`react-chess-core`**
+
+```bash
+npm install react-chess-explorer react-chess-core
+```
+
+---
+
+## Exports (scaffold)
+
+| Export | Role |
+|--------|------|
+| **`ExplorerPlaceholder`** | Themed board at start position + scaffold label |
+| **`EXPLORER_START_FEN`** | Default FEN constant |
+
+---
+
+## Requirements
+
+Add product/API requirements here when ready:
+
+- `docs/REQUIREMENTS.md` (create when you paste the doc)
+
+Planned scope (from migration plan): move list, ply navigation, optional engine — wired to EndChess `/games` routes.
+
+---
+
+## Related packages
+
+| Package | Role |
+|---------|------|
+| [react-chess-core](https://github.com/reblackwell3/react-chess-core) | Board theme, highlights, Stockfish |
+| [react-chess-puzzle-kit](https://github.com/reblackwell3/react-chess-puzzle-kit) | Puzzles (separate; not a dependency) |
+
+---
+
+## License
+
+MIT © Robert Blackwell

package/dist/features/explorer/hooks/useGameReplayTraining.d.ts

@@ -16,6 +16,7 @@ export declare function useGameReplayTraining({ gameId, startFen, fetchGame, }:
     error: string | null;
     feedback: GameReplayFeedback;
     lastExpectedSan: string | null;
+    lastMoveUci: any;
     expectedSan: string | undefined;
     handlePieceDrop: (sourceSquare: string, targetSquare: string, piece: string) => boolean;
     revealMove: () => void;

package/dist/features/explorer/hooks/usePositionHistory.d.ts

@@ -2,6 +2,8 @@ export type PositionHistoryEntry = {
     fen: string;
     /** SAN of the move played from the previous entry to reach this FEN. */
     lastSan?: string;
+    /** UCI of the move played from the previous entry to reach this FEN. */
+    lastUci?: string;
 };
 export declare function initialHistoryState(initialFen: string, initialLineSans?: string[]): {
     history: PositionHistoryEntry[];
@@ -13,14 +15,17 @@ export declare function usePositionHistory(initialFen: string, initialLineSans?:
     lineSans: string[];
     forwardSans: string[];
     currentFen: string;
-    pushEntry: (fen: string, lastSan?: string) => PositionHistoryEntry;
+    lastMoveUci: string | null;
+    pushEntry: (fen: string, lastSan?: string, lastUci?: string) => PositionHistoryEntry;
     pushEntries: (entries: {
         fen: string;
         lastSan: string;
+        lastUci?: string;
     }[]) => void;
     replaceLineEntries: (startFen: string, entries: {
         fen: string;
         lastSan: string;
+        lastUci?: string;
     }[]) => void;
     goBack: () => PositionHistoryEntry | null;
     goForward: () => PositionHistoryEntry | null;

package/dist/features/explorer/hooks/usePositionReferenceData.d.ts

@@ -28,6 +28,7 @@ export declare function usePositionReferenceData({ fenProp, onFenChange, initial
     canGoForward: boolean;
     forwardSans: string[];
     selectedVariationKey: string | undefined;
+    lastMoveUci: string | null;
     setSources: import("react").Dispatch<import("react").SetStateAction<GameSource[]>>;
     setGamesMoveFilterUci: import("react").Dispatch<import("react").SetStateAction<string | undefined>>;
     handleMoveSelect: (move: PositionMoveApiDto) => void;

package/dist/features/explorer/positionUtils.d.ts

@@ -10,6 +10,7 @@ export declare function applyBoardMove(fen: string, sourceSquare: string, target
 export type LineSansEntry = {
     fen: string;
     lastSan: string;
+    lastUci: string;
 };
 /** Play a SAN sequence from a start FEN; returns null if any move is illegal. */
 export declare function applyLineSans(startFen: string, sans: string[]): {

package/dist/index.esm.js

@@ -1,6 +1,6 @@
 import { Chess } from 'chess.js';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
-import { ThemeProvider, HighlightChessboard, usePositionKeyboardNav, ChessboardDnDProvider } from 'react-chess-core';
+import { ThemeProvider, HighlightChessboard, usePositionKeyboardNav, ChessboardDnDProvider, lastMoveUciAtPly } from 'react-chess-core';
 import { useEffect, useState, useCallback, useRef, useMemo } from 'react';
 
 /** Standard start position — placeholder until game replay is implemented. */
@@ -39,6 +39,7 @@ function applyBoardMove(fen, sourceSquare, targetSquare, piece) {
 }
 /** Play a SAN sequence from a start FEN; returns null if any move is illegal. */
 function applyLineSans(startFen, sans) {
+    var _a;
     const chess = new Chess(startFen);
     const entries = [];
     for (const san of sans) {
@@ -46,9 +47,10 @@ function applyLineSans(startFen, sans) {
             const move = chess.move(san);
             if (!move)
                 return null;
-            entries.push({ fen: chess.fen(), lastSan: move.san });
+            const lastUci = `${move.from}${move.to}${(_a = move.promotion) !== null && _a !== void 0 ? _a : ""}`;
+            entries.push({ fen: chess.fen(), lastSan: move.san, lastUci });
         }
-        catch (_a) {
+        catch (_b) {
             return null;
         }
     }
@@ -432,30 +434,31 @@ function useExplorerPrefetch({ fen, moves, positionReady, sources, fetchPosition
                 return;
             }
             const sourcesParam = sources.length < ALL_GAME_SOURCES.length ? sources : undefined;
-            for (const move of moves.slice(0, childCount)) {
+            const prefetchMove = (move) => {
                 const childFen = fenAfterUci(fen, move.uci);
                 if (!childFen) {
-                    continue;
+                    return Promise.resolve();
                 }
                 const gamesKey = gamesSessionKey({
                     fen: childFen,
                     sources: sourcesParam,
                 });
-                if (!peekSessionGames(gamesKey)) {
-                    void fetchPositionGames({ fen: childFen, sources: sourcesParam })
+                const gamesPromise = peekSessionGames(gamesKey)
+                    ? Promise.resolve()
+                    : fetchPositionGames({ fen: childFen, sources: sourcesParam })
                         .then((games) => {
                         if (!cancelled) {
                             setSessionGames(gamesKey, games);
                         }
                     })
                         .catch(() => undefined);
-                }
                 if (!fetchPositionVariations) {
-                    continue;
+                    return gamesPromise;
                 }
                 const variationsKey = variationsSessionKey(childFen);
-                if (!peekSessionVariations(variationsKey)) {
-                    void fetchPositionVariations({
+                const variationsPromise = peekSessionVariations(variationsKey)
+                    ? Promise.resolve()
+                    : fetchPositionVariations({
                         fen: childFen,
                         mode: "variations",
                         lineCount: EXPLORER_DEFAULT_VARIATION_LINE_COUNT,
@@ -468,8 +471,17 @@ function useExplorerPrefetch({ fen, moves, positionReady, sources, fetchPosition
                         }
                     })
                         .catch(() => undefined);
+                return Promise.all([gamesPromise, variationsPromise]).then(() => undefined);
+            };
+            void (() => __awaiter(this, void 0, void 0, function* () {
+                const movesToPrefetch = moves.slice(0, childCount);
+                for (let index = 0; index < movesToPrefetch.length; index += 2) {
+                    if (cancelled) {
+                        return;
+                    }
+                    yield Promise.all(movesToPrefetch.slice(index, index + 2).map(prefetchMove));
                 }
-            }
+            }))();
         };
         if (typeof window.requestIdleCallback === "function") {
             idleHandle = window.requestIdleCallback(prefetchChildren, {
@@ -513,19 +525,19 @@ function initialHistoryState(initialFen, initialLineSans) {
     };
 }
 function usePositionHistory(initialFen, initialLineSans) {
-    var _a, _b;
+    var _a, _b, _c, _d;
     const [history, setHistory] = useState(() => initialHistoryState(initialFen, initialLineSans).history);
     const [historyIndex, setHistoryIndex] = useState(() => initialHistoryState(initialFen, initialLineSans).historyIndex);
     const canGoBack = historyIndex > 0;
     const canGoForward = historyIndex < history.length - 1;
-    const pushEntry = useCallback((fen, lastSan) => {
+    const pushEntry = useCallback((fen, lastSan, lastUci) => {
         setHistory((prev) => {
             const trimmed = prev.slice(0, historyIndex + 1);
-            const next = [...trimmed, { fen, lastSan }];
+            const next = [...trimmed, { fen, lastSan, lastUci }];
             setHistoryIndex(next.length - 1);
             return next;
         });
-        return { fen, lastSan };
+        return { fen, lastSan, lastUci };
     }, [historyIndex]);
     const goBack = useCallback(() => {
         if (historyIndex <= 0)
@@ -586,12 +598,14 @@ function usePositionHistory(initialFen, initialLineSans) {
         setHistory([{ fen: startFen }, ...entries]);
         setHistoryIndex(entries.length);
     }, []);
+    const lastMoveUci = historyIndex > 0 ? (_d = (_c = history[historyIndex]) === null || _c === void 0 ? void 0 : _c.lastUci) !== null && _d !== void 0 ? _d : null : null;
     return {
         canGoBack,
         canGoForward,
         lineSans,
         forwardSans,
         currentFen,
+        lastMoveUci,
         pushEntry,
         pushEntries,
         replaceLineEntries,
@@ -636,7 +650,7 @@ function usePositionReferenceData({ fenProp, onFenChange, initialLineSans, onLin
         }
         isAnimatingVariationRef.current = false;
     }, []);
-    const { canGoBack, canGoForward, lineSans, forwardSans, currentFen, pushEntry, pushEntries, replaceLineEntries, goBack, goForward, goFirst, goLast, resetHistory, } = usePositionHistory(initialFen, initialLineSans);
+    const { canGoBack, canGoForward, lineSans, forwardSans, currentFen, pushEntry, pushEntries, replaceLineEntries, goBack, goForward, goFirst, goLast, resetHistory, lastMoveUci: historyLastMoveUci, } = usePositionHistory(initialFen, initialLineSans);
     /** FEN used for explorer API queries — follows move history, not animation frames. */
     const queryFen = currentFen;
     const initialLineKey = useMemo(() => { var _a; return (_a = initialLineSans === null || initialLineSans === void 0 ? void 0 : initialLineSans.join("|")) !== null && _a !== void 0 ? _a : ""; }, [initialLineSans]);
@@ -671,6 +685,10 @@ function usePositionReferenceData({ fenProp, onFenChange, initialLineSans, onLin
     }), [sources]);
     const lastAppliedLineKeyRef = useRef(initialLineKey);
     useEffect(() => () => cancelVariationAnimation(), [cancelVariationAnimation]);
+    // Hold URL line callbacks until history catches up after an external line change.
+    useEffect(() => {
+        readyForLineSyncRef.current = false;
+    }, [initialLineKey]);
     // Apply URL line changes only when the external line key changes — not when the
     // user clicks moves (internal lineSans updates must not re-sync from stale props).
     useEffect(() => {
@@ -881,7 +899,7 @@ function usePositionReferenceData({ fenProp, onFenChange, initialLineSans, onLin
         const nextFen = fenAfterUci(queryFen, move.uci);
         if (!nextFen)
             return;
-        pushEntry(nextFen, move.san);
+        pushEntry(nextFen, move.san, move.uci);
         setSelectedVariationKey(undefined);
         applyNavigation(nextFen, true);
     }, [queryFen, pushEntry, applyNavigation, cancelVariationAnimation]);
@@ -895,7 +913,11 @@ function usePositionReferenceData({ fenProp, onFenChange, initialLineSans, onLin
             const nextFen = fenAfterUci(lineFen, line.uciPath[i]);
             if (!nextFen)
                 return;
-            entries.push({ fen: nextFen, lastSan: line.moves[i].san });
+            entries.push({
+                fen: nextFen,
+                lastSan: line.moves[i].san,
+                lastUci: line.uciPath[i],
+            });
             lineFen = nextFen;
         }
         if (entries.length === 0)
@@ -930,7 +952,7 @@ function usePositionReferenceData({ fenProp, onFenChange, initialLineSans, onLin
         const result = applyBoardMove(queryFen, sourceSquare, targetSquare, piece);
         if (!result)
             return false;
-        pushEntry(result.fen, result.san);
+        pushEntry(result.fen, result.san, result.uci);
         setSelectedVariationKey(undefined);
         applyNavigation(result.fen, true);
         return true;
@@ -1007,6 +1029,7 @@ function usePositionReferenceData({ fenProp, onFenChange, initialLineSans, onLin
         canGoForward,
         forwardSans,
         selectedVariationKey,
+        lastMoveUci: historyLastMoveUci,
         setSources,
         setGamesMoveFilterUci,
         handleMoveSelect,
@@ -1105,7 +1128,7 @@ const PositionReferenceExplorerCore = ({ fen: fenProp, onFenChange, initialLineS
         fetchPositionGames,
         fetchPositionVariations,
     });
-    const { fen, boardFen, games, sources, lineSans, loading, showPositionLoading, gamesLoading, positionReady, displayMoves, error, lineLabel, canGoBack, canGoForward, forwardSans, selectedVariationKey, setSources, handleMoveSelect, handleLineSelect, handlePieceDrop, handleBack, handleForward, handleFirst, handleLast, } = referenceData;
+    const { fen, boardFen, games, sources, lineSans, loading, showPositionLoading, gamesLoading, positionReady, displayMoves, error, lineLabel, canGoBack, canGoForward, forwardSans, selectedVariationKey, lastMoveUci, setSources, handleMoveSelect, handleLineSelect, handlePieceDrop, handleBack, handleForward, handleFirst, handleLast, } = referenceData;
     usePositionKeyboardNav({
         enabled: keyboardNav,
         canPrev: canGoBack,
@@ -1169,7 +1192,7 @@ const PositionReferenceExplorerCore = ({ fen: fenProp, onFenChange, initialLineS
         overflow: fillHeight ? "hidden" : "visible",
         boxSizing: "border-box",
     };
-    const board = (jsxs(Fragment, { children: [jsx(ChessboardDnDProvider, { children: jsx(HighlightChessboard, { boardWidth: boardWidth, position: boardFen, boardOrientation: boardOrientation, checkSquare: "", hintSquare: null, incorrectMoveSquare: null, onPieceDrop: handlePieceDrop, promotionDialogVariant: "modal" }, boardOrientation) }), renderBoardNav(boardNavProps)] }));
+    const board = (jsxs(Fragment, { children: [jsx(ChessboardDnDProvider, { children: jsx(HighlightChessboard, { boardWidth: boardWidth, position: boardFen, boardOrientation: boardOrientation, checkSquare: "", hintSquare: null, incorrectMoveSquare: null, lastMoveUci: lastMoveUci, onPieceDrop: handlePieceDrop, promotionDialogVariant: "modal" }, boardOrientation) }), renderBoardNav(boardNavProps)] }));
     const referencePanel = (jsx(DefaultReferencePanel, { theme: theme, fillHeight: fillHeight, status: renderStatus({
             error,
             loading: showPositionLoading,
@@ -1291,6 +1314,7 @@ function useGameReplayTraining({ gameId, startFen, fetchGame, }) {
     const complete = game ? plyIndex >= game.movesUci.length : false;
     const expectedUci = game === null || game === void 0 ? void 0 : game.movesUci[plyIndex];
     const expectedSan = game === null || game === void 0 ? void 0 : game.movesSan[plyIndex];
+    const lastMoveUci = useMemo(() => (game ? lastMoveUciAtPly(game.movesUci, plyIndex) : null), [game, plyIndex]);
     const handlePieceDrop = useCallback((sourceSquare, targetSquare, piece) => {
         if (!game || complete || !expectedUci)
             return false;
@@ -1324,6 +1348,7 @@ function useGameReplayTraining({ gameId, startFen, fetchGame, }) {
         error,
         feedback,
         lastExpectedSan,
+        lastMoveUci,
         expectedSan,
         handlePieceDrop,
         revealMove,
@@ -1344,7 +1369,7 @@ const defaultButtonStyle = {
     cursor: "pointer",
 };
 const GameReplayTrainer = ({ gameId, startFen, fetchGame, onExit, theme = "dark", boardWidth = DEFAULT_REFERENCE_LAYOUT.boardWidth, renderStatus, }) => {
-    const { game, fen, plyIndex, totalPlies, complete, loading, error, feedback, lastExpectedSan, handlePieceDrop, revealMove, } = useGameReplayTraining({ gameId, startFen, fetchGame });
+    const { game, fen, plyIndex, totalPlies, complete, loading, error, feedback, lastExpectedSan, lastMoveUci, handlePieceDrop, revealMove, } = useGameReplayTraining({ gameId, startFen, fetchGame });
     const status = renderStatus === null || renderStatus === void 0 ? void 0 : renderStatus({
         loading,
         error,
@@ -1364,7 +1389,7 @@ const GameReplayTrainer = ({ gameId, startFen, fetchGame, onExit, theme = "dark"
                             !error &&
                             !complete &&
                             feedback === "incorrect" &&
-                            lastExpectedSan && (jsxs("span", { style: { color: "#ef6c00" }, children: ["Expected ", lastExpectedSan] })), !loading && !error && !complete && feedback === null && (jsxs("span", { children: ["Guess move ", plyIndex + 1, " of ", totalPlies] }))] })), jsx(ChessboardDnDProvider, { children: jsx(HighlightChessboard, { boardWidth: boardWidth, position: fen, checkSquare: "", hintSquare: null, incorrectMoveSquare: null, onPieceDrop: handlePieceDrop, promotionDialogVariant: "modal" }) }), !complete && !loading && !error && (jsx("button", { type: "button", style: defaultButtonStyle, onClick: revealMove, children: "Show move" }))] }) }));
+                            lastExpectedSan && (jsxs("span", { style: { color: "#ef6c00" }, children: ["Expected ", lastExpectedSan] })), !loading && !error && !complete && feedback === null && (jsxs("span", { children: ["Guess move ", plyIndex + 1, " of ", totalPlies] }))] })), jsx(ChessboardDnDProvider, { children: jsx(HighlightChessboard, { boardWidth: boardWidth, position: fen, checkSquare: "", hintSquare: null, incorrectMoveSquare: null, lastMoveUci: lastMoveUci, onPieceDrop: handlePieceDrop, promotionDialogVariant: "modal" }) }), !complete && !loading && !error && (jsx("button", { type: "button", style: defaultButtonStyle, onClick: revealMove, children: "Show move" }))] }) }));
 };
 
 const mockPosition = {

package/dist/index.js

@@ -41,6 +41,7 @@ function applyBoardMove(fen, sourceSquare, targetSquare, piece) {
 }
 /** Play a SAN sequence from a start FEN; returns null if any move is illegal. */
 function applyLineSans(startFen, sans) {
+    var _a;
     const chess = new chess_js.Chess(startFen);
     const entries = [];
     for (const san of sans) {
@@ -48,9 +49,10 @@ function applyLineSans(startFen, sans) {
             const move = chess.move(san);
             if (!move)
                 return null;
-            entries.push({ fen: chess.fen(), lastSan: move.san });
+            const lastUci = `${move.from}${move.to}${(_a = move.promotion) !== null && _a !== void 0 ? _a : ""}`;
+            entries.push({ fen: chess.fen(), lastSan: move.san, lastUci });
         }
-        catch (_a) {
+        catch (_b) {
             return null;
         }
     }
@@ -434,30 +436,31 @@ function useExplorerPrefetch({ fen, moves, positionReady, sources, fetchPosition
                 return;
             }
             const sourcesParam = sources.length < ALL_GAME_SOURCES.length ? sources : undefined;
-            for (const move of moves.slice(0, childCount)) {
+            const prefetchMove = (move) => {
                 const childFen = fenAfterUci(fen, move.uci);
                 if (!childFen) {
-                    continue;
+                    return Promise.resolve();
                 }
                 const gamesKey = gamesSessionKey({
                     fen: childFen,
                     sources: sourcesParam,
                 });
-                if (!peekSessionGames(gamesKey)) {
-                    void fetchPositionGames({ fen: childFen, sources: sourcesParam })
+                const gamesPromise = peekSessionGames(gamesKey)
+                    ? Promise.resolve()
+                    : fetchPositionGames({ fen: childFen, sources: sourcesParam })
                         .then((games) => {
                         if (!cancelled) {
                             setSessionGames(gamesKey, games);
                         }
                     })
                         .catch(() => undefined);
-                }
                 if (!fetchPositionVariations) {
-                    continue;
+                    return gamesPromise;
                 }
                 const variationsKey = variationsSessionKey(childFen);
-                if (!peekSessionVariations(variationsKey)) {
-                    void fetchPositionVariations({
+                const variationsPromise = peekSessionVariations(variationsKey)
+                    ? Promise.resolve()
+                    : fetchPositionVariations({
                         fen: childFen,
                         mode: "variations",
                         lineCount: EXPLORER_DEFAULT_VARIATION_LINE_COUNT,
@@ -470,8 +473,17 @@ function useExplorerPrefetch({ fen, moves, positionReady, sources, fetchPosition
                         }
                     })
                         .catch(() => undefined);
+                return Promise.all([gamesPromise, variationsPromise]).then(() => undefined);
+            };
+            void (() => __awaiter(this, void 0, void 0, function* () {
+                const movesToPrefetch = moves.slice(0, childCount);
+                for (let index = 0; index < movesToPrefetch.length; index += 2) {
+                    if (cancelled) {
+                        return;
+                    }
+                    yield Promise.all(movesToPrefetch.slice(index, index + 2).map(prefetchMove));
                 }
-            }
+            }))();
         };
         if (typeof window.requestIdleCallback === "function") {
             idleHandle = window.requestIdleCallback(prefetchChildren, {
@@ -515,19 +527,19 @@ function initialHistoryState(initialFen, initialLineSans) {
     };
 }
 function usePositionHistory(initialFen, initialLineSans) {
-    var _a, _b;
+    var _a, _b, _c, _d;
     const [history, setHistory] = react.useState(() => initialHistoryState(initialFen, initialLineSans).history);
     const [historyIndex, setHistoryIndex] = react.useState(() => initialHistoryState(initialFen, initialLineSans).historyIndex);
     const canGoBack = historyIndex > 0;
     const canGoForward = historyIndex < history.length - 1;
-    const pushEntry = react.useCallback((fen, lastSan) => {
+    const pushEntry = react.useCallback((fen, lastSan, lastUci) => {
         setHistory((prev) => {
             const trimmed = prev.slice(0, historyIndex + 1);
-            const next = [...trimmed, { fen, lastSan }];
+            const next = [...trimmed, { fen, lastSan, lastUci }];
             setHistoryIndex(next.length - 1);
             return next;
         });
-        return { fen, lastSan };
+        return { fen, lastSan, lastUci };
     }, [historyIndex]);
     const goBack = react.useCallback(() => {
         if (historyIndex <= 0)
@@ -588,12 +600,14 @@ function usePositionHistory(initialFen, initialLineSans) {
         setHistory([{ fen: startFen }, ...entries]);
         setHistoryIndex(entries.length);
     }, []);
+    const lastMoveUci = historyIndex > 0 ? (_d = (_c = history[historyIndex]) === null || _c === void 0 ? void 0 : _c.lastUci) !== null && _d !== void 0 ? _d : null : null;
     return {
         canGoBack,
         canGoForward,
         lineSans,
         forwardSans,
         currentFen,
+        lastMoveUci,
         pushEntry,
         pushEntries,
         replaceLineEntries,
@@ -638,7 +652,7 @@ function usePositionReferenceData({ fenProp, onFenChange, initialLineSans, onLin
         }
         isAnimatingVariationRef.current = false;
     }, []);
-    const { canGoBack, canGoForward, lineSans, forwardSans, currentFen, pushEntry, pushEntries, replaceLineEntries, goBack, goForward, goFirst, goLast, resetHistory, } = usePositionHistory(initialFen, initialLineSans);
+    const { canGoBack, canGoForward, lineSans, forwardSans, currentFen, pushEntry, pushEntries, replaceLineEntries, goBack, goForward, goFirst, goLast, resetHistory, lastMoveUci: historyLastMoveUci, } = usePositionHistory(initialFen, initialLineSans);
     /** FEN used for explorer API queries — follows move history, not animation frames. */
     const queryFen = currentFen;
     const initialLineKey = react.useMemo(() => { var _a; return (_a = initialLineSans === null || initialLineSans === void 0 ? void 0 : initialLineSans.join("|")) !== null && _a !== void 0 ? _a : ""; }, [initialLineSans]);
@@ -673,6 +687,10 @@ function usePositionReferenceData({ fenProp, onFenChange, initialLineSans, onLin
     }), [sources]);
     const lastAppliedLineKeyRef = react.useRef(initialLineKey);
     react.useEffect(() => () => cancelVariationAnimation(), [cancelVariationAnimation]);
+    // Hold URL line callbacks until history catches up after an external line change.
+    react.useEffect(() => {
+        readyForLineSyncRef.current = false;
+    }, [initialLineKey]);
     // Apply URL line changes only when the external line key changes — not when the
     // user clicks moves (internal lineSans updates must not re-sync from stale props).
     react.useEffect(() => {
@@ -883,7 +901,7 @@ function usePositionReferenceData({ fenProp, onFenChange, initialLineSans, onLin
         const nextFen = fenAfterUci(queryFen, move.uci);
         if (!nextFen)
             return;
-        pushEntry(nextFen, move.san);
+        pushEntry(nextFen, move.san, move.uci);
         setSelectedVariationKey(undefined);
         applyNavigation(nextFen, true);
     }, [queryFen, pushEntry, applyNavigation, cancelVariationAnimation]);
@@ -897,7 +915,11 @@ function usePositionReferenceData({ fenProp, onFenChange, initialLineSans, onLin
             const nextFen = fenAfterUci(lineFen, line.uciPath[i]);
             if (!nextFen)
                 return;
-            entries.push({ fen: nextFen, lastSan: line.moves[i].san });
+            entries.push({
+                fen: nextFen,
+                lastSan: line.moves[i].san,
+                lastUci: line.uciPath[i],
+            });
             lineFen = nextFen;
         }
         if (entries.length === 0)
@@ -932,7 +954,7 @@ function usePositionReferenceData({ fenProp, onFenChange, initialLineSans, onLin
         const result = applyBoardMove(queryFen, sourceSquare, targetSquare, piece);
         if (!result)
             return false;
-        pushEntry(result.fen, result.san);
+        pushEntry(result.fen, result.san, result.uci);
         setSelectedVariationKey(undefined);
         applyNavigation(result.fen, true);
         return true;
@@ -1009,6 +1031,7 @@ function usePositionReferenceData({ fenProp, onFenChange, initialLineSans, onLin
         canGoForward,
         forwardSans,
         selectedVariationKey,
+        lastMoveUci: historyLastMoveUci,
         setSources,
         setGamesMoveFilterUci,
         handleMoveSelect,
@@ -1107,7 +1130,7 @@ const PositionReferenceExplorerCore = ({ fen: fenProp, onFenChange, initialLineS
         fetchPositionGames,
         fetchPositionVariations,
     });
-    const { fen, boardFen, games, sources, lineSans, loading, showPositionLoading, gamesLoading, positionReady, displayMoves, error, lineLabel, canGoBack, canGoForward, forwardSans, selectedVariationKey, setSources, handleMoveSelect, handleLineSelect, handlePieceDrop, handleBack, handleForward, handleFirst, handleLast, } = referenceData;
+    const { fen, boardFen, games, sources, lineSans, loading, showPositionLoading, gamesLoading, positionReady, displayMoves, error, lineLabel, canGoBack, canGoForward, forwardSans, selectedVariationKey, lastMoveUci, setSources, handleMoveSelect, handleLineSelect, handlePieceDrop, handleBack, handleForward, handleFirst, handleLast, } = referenceData;
     reactChessCore.usePositionKeyboardNav({
         enabled: keyboardNav,
         canPrev: canGoBack,
@@ -1171,7 +1194,7 @@ const PositionReferenceExplorerCore = ({ fen: fenProp, onFenChange, initialLineS
         overflow: fillHeight ? "hidden" : "visible",
         boxSizing: "border-box",
     };
-    const board = (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [jsxRuntime.jsx(reactChessCore.ChessboardDnDProvider, { children: jsxRuntime.jsx(reactChessCore.HighlightChessboard, { boardWidth: boardWidth, position: boardFen, boardOrientation: boardOrientation, checkSquare: "", hintSquare: null, incorrectMoveSquare: null, onPieceDrop: handlePieceDrop, promotionDialogVariant: "modal" }, boardOrientation) }), renderBoardNav(boardNavProps)] }));
+    const board = (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [jsxRuntime.jsx(reactChessCore.ChessboardDnDProvider, { children: jsxRuntime.jsx(reactChessCore.HighlightChessboard, { boardWidth: boardWidth, position: boardFen, boardOrientation: boardOrientation, checkSquare: "", hintSquare: null, incorrectMoveSquare: null, lastMoveUci: lastMoveUci, onPieceDrop: handlePieceDrop, promotionDialogVariant: "modal" }, boardOrientation) }), renderBoardNav(boardNavProps)] }));
     const referencePanel = (jsxRuntime.jsx(DefaultReferencePanel, { theme: theme, fillHeight: fillHeight, status: renderStatus({
             error,
             loading: showPositionLoading,
@@ -1293,6 +1316,7 @@ function useGameReplayTraining({ gameId, startFen, fetchGame, }) {
     const complete = game ? plyIndex >= game.movesUci.length : false;
     const expectedUci = game === null || game === void 0 ? void 0 : game.movesUci[plyIndex];
     const expectedSan = game === null || game === void 0 ? void 0 : game.movesSan[plyIndex];
+    const lastMoveUci = react.useMemo(() => (game ? reactChessCore.lastMoveUciAtPly(game.movesUci, plyIndex) : null), [game, plyIndex]);
     const handlePieceDrop = react.useCallback((sourceSquare, targetSquare, piece) => {
         if (!game || complete || !expectedUci)
             return false;
@@ -1326,6 +1350,7 @@ function useGameReplayTraining({ gameId, startFen, fetchGame, }) {
         error,
         feedback,
         lastExpectedSan,
+        lastMoveUci,
         expectedSan,
         handlePieceDrop,
         revealMove,
@@ -1346,7 +1371,7 @@ const defaultButtonStyle = {
     cursor: "pointer",
 };
 const GameReplayTrainer = ({ gameId, startFen, fetchGame, onExit, theme = "dark", boardWidth = DEFAULT_REFERENCE_LAYOUT.boardWidth, renderStatus, }) => {
-    const { game, fen, plyIndex, totalPlies, complete, loading, error, feedback, lastExpectedSan, handlePieceDrop, revealMove, } = useGameReplayTraining({ gameId, startFen, fetchGame });
+    const { game, fen, plyIndex, totalPlies, complete, loading, error, feedback, lastExpectedSan, lastMoveUci, handlePieceDrop, revealMove, } = useGameReplayTraining({ gameId, startFen, fetchGame });
     const status = renderStatus === null || renderStatus === void 0 ? void 0 : renderStatus({
         loading,
         error,
@@ -1366,7 +1391,7 @@ const GameReplayTrainer = ({ gameId, startFen, fetchGame, onExit, theme = "dark"
                             !error &&
                             !complete &&
                             feedback === "incorrect" &&
-                            lastExpectedSan && (jsxRuntime.jsxs("span", { style: { color: "#ef6c00" }, children: ["Expected ", lastExpectedSan] })), !loading && !error && !complete && feedback === null && (jsxRuntime.jsxs("span", { children: ["Guess move ", plyIndex + 1, " of ", totalPlies] }))] })), jsxRuntime.jsx(reactChessCore.ChessboardDnDProvider, { children: jsxRuntime.jsx(reactChessCore.HighlightChessboard, { boardWidth: boardWidth, position: fen, checkSquare: "", hintSquare: null, incorrectMoveSquare: null, onPieceDrop: handlePieceDrop, promotionDialogVariant: "modal" }) }), !complete && !loading && !error && (jsxRuntime.jsx("button", { type: "button", style: defaultButtonStyle, onClick: revealMove, children: "Show move" }))] }) }));
+                            lastExpectedSan && (jsxRuntime.jsxs("span", { style: { color: "#ef6c00" }, children: ["Expected ", lastExpectedSan] })), !loading && !error && !complete && feedback === null && (jsxRuntime.jsxs("span", { children: ["Guess move ", plyIndex + 1, " of ", totalPlies] }))] })), jsxRuntime.jsx(reactChessCore.ChessboardDnDProvider, { children: jsxRuntime.jsx(reactChessCore.HighlightChessboard, { boardWidth: boardWidth, position: fen, checkSquare: "", hintSquare: null, incorrectMoveSquare: null, lastMoveUci: lastMoveUci, onPieceDrop: handlePieceDrop, promotionDialogVariant: "modal" }) }), !complete && !loading && !error && (jsxRuntime.jsx("button", { type: "button", style: defaultButtonStyle, onClick: revealMove, children: "Show move" }))] }) }));
 };
 
 const mockPosition = {

package/package.json

@@ -1,59 +1,59 @@
-{
-  "name": "react-chess-explorer",
-  "version": "0.0.3",
-  "description": "React components for browsing and replaying chess games (depends on react-chess-core only)",
-  "license": "MIT",
-  "author": "Robert Blackwell",
-  "main": "dist/index.js",
-  "module": "dist/index.esm.js",
-  "types": "dist/index.d.ts",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/reblackwell3/react-chess-explorer.git"
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "rollup -c",
-    "prepublishOnly": "npm run build",
-    "storybook": "storybook dev -p 6008",
-    "build-storybook": "storybook build"
-  },
-  "dependencies": {
-    "rollup": "^4.22.2",
-    "rollup-plugin-peer-deps-external": "^2.2.4",
-    "typescript": "^5.6.2"
-  },
-  "peerDependencies": {
-    "chess.js": "^1.0.0-beta.8",
-    "react": "^18.3.1",
-    "react-chess-core": "^0.1.1",
-    "react-chessboard": "^4.7.1"
-  },
-  "devDependencies": {
-    "@chromatic-com/storybook": "^1.9.0",
-    "@rollup/plugin-commonjs": "^26.0.1",
-    "@rollup/plugin-node-resolve": "^15.2.3",
-    "@rollup/plugin-typescript": "^12.3.0",
-    "@storybook/addon-essentials": "^8.2.9",
-    "@storybook/addon-interactions": "^8.2.9",
-    "@storybook/addon-links": "^8.2.9",
-    "@storybook/addon-onboarding": "^8.2.9",
-    "@storybook/blocks": "^8.2.9",
-    "@storybook/preset-typescript": "^3.0.0",
-    "@storybook/react": "^8.2.9",
-    "@storybook/react-vite": "^8.2.9",
-    "@storybook/test": "^8.2.9",
-    "@types/react": "^18.3.12",
-    "@types/react-dom": "^18.3.1",
-    "@vitejs/plugin-react": "^4.3.1",
-    "chess.js": "^1.0.0-beta.8",
-    "react": "^18.3.1",
-    "react-chess-core": "^0.1.1",
-    "react-chessboard": "^4.7.1",
-    "react-dom": "^18.3.1",
-    "storybook": "^8.2.9",
-    "tslib": "^2.8.1"
-  }
-}
+{
+  "name": "react-chess-explorer",
+  "version": "0.0.5",
+  "description": "React components for browsing and replaying chess games (depends on react-chess-core only)",
+  "license": "MIT",
+  "author": "Robert Blackwell",
+  "main": "dist/index.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reblackwell3/react-chess-explorer.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rollup -c",
+    "prepublishOnly": "npm run build",
+    "storybook": "storybook dev -p 6008",
+    "build-storybook": "storybook build"
+  },
+  "dependencies": {
+    "rollup": "^4.22.2",
+    "rollup-plugin-peer-deps-external": "^2.2.4",
+    "typescript": "^5.6.2"
+  },
+  "peerDependencies": {
+    "chess.js": "^1.0.0-beta.8",
+    "react": "^18.3.1",
+    "react-chess-core": "^0.1.1",
+    "react-chessboard": "^4.7.1"
+  },
+  "devDependencies": {
+    "@chromatic-com/storybook": "^1.9.0",
+    "@rollup/plugin-commonjs": "^26.0.1",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@storybook/addon-essentials": "^8.2.9",
+    "@storybook/addon-interactions": "^8.2.9",
+    "@storybook/addon-links": "^8.2.9",
+    "@storybook/addon-onboarding": "^8.2.9",
+    "@storybook/blocks": "^8.2.9",
+    "@storybook/preset-typescript": "^3.0.0",
+    "@storybook/react": "^8.2.9",
+    "@storybook/react-vite": "^8.2.9",
+    "@storybook/test": "^8.2.9",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^4.3.1",
+    "chess.js": "^1.0.0-beta.8",
+    "react": "^18.3.1",
+    "react-chess-core": "^0.1.1",
+    "react-chessboard": "^4.7.1",
+    "react-dom": "^18.3.1",
+    "storybook": "^8.2.9",
+    "tslib": "^2.8.1"
+  }
+}