react-chess-explorer 0.0.2 → 0.0.4

package/dist/index.esm.js

@@ -1,14 +1,152 @@
-import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
-import { ThemeProvider, HighlightChessboard } from 'react-chess-core';
-import { ChessboardDnDProvider } from 'react-chessboard';
 import { Chess } from 'chess.js';
-import { useState, useCallback, useRef, useMemo, useEffect } from 'react';
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+import { ThemeProvider, HighlightChessboard, usePositionKeyboardNav, ChessboardDnDProvider } from 'react-chess-core';
+import { useEffect, useState, useCallback, useRef, useMemo } from 'react';
 
 /** Standard start position — placeholder until game replay is implemented. */
 const EXPLORER_START_FEN = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1";
 /** Delay between plies when animating a clicked variation line. */
 const VARIATION_LINE_STEP_MS = 500;
 
+/** Match endchess-backend / mass-games-import (first four FEN fields). */
+function normalizeFen(fen) {
+    const parts = fen.trim().split(/\s+/);
+    if (parts.length < 4) {
+        throw new Error(`Invalid FEN: ${fen}`);
+    }
+    return `${parts[0]} ${parts[1]} ${parts[2]} ${parts[3]}`;
+}
+/** Legal move from a board drag/drop (react-chessboard piece string, e.g. wQ). */
+function applyBoardMove(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;
+    const played = chess.move({
+        from: legal.from,
+        to: legal.to,
+        promotion: legal.promotion,
+    });
+    if (!played)
+        return null;
+    const uci = `${played.from}${played.to}${(_b = played.promotion) !== null && _b !== void 0 ? _b : ""}`;
+    return { fen: chess.fen(), uci, san: played.san };
+}
+/** Play a SAN sequence from a start FEN; returns null if any move is illegal. */
+function applyLineSans(startFen, sans) {
+    const chess = new Chess(startFen);
+    const entries = [];
+    for (const san of sans) {
+        try {
+            const move = chess.move(san);
+            if (!move)
+                return null;
+            entries.push({ fen: chess.fen(), lastSan: move.san });
+        }
+        catch (_a) {
+            return null;
+        }
+    }
+    return { fen: chess.fen(), entries };
+}
+/** Apply a UCI move to a FEN; returns null if illegal. */
+function fenAfterUci(fen, uci) {
+    const chess = new Chess(fen);
+    const from = uci.slice(0, 2);
+    const to = uci.slice(2, 4);
+    const promotion = uci.length > 4 ? uci[4] : undefined;
+    try {
+        const move = chess.move({ from, to, promotion });
+        if (!move)
+            return null;
+        return chess.fen();
+    }
+    catch (_a) {
+        return null;
+    }
+}
+function whiteScorePercent(whiteWins, draws, blackWins) {
+    const total = whiteWins + draws + blackWins;
+    if (total === 0)
+        return null;
+    return Math.round((100 * (whiteWins + 0.5 * draws)) / total);
+}
+/** Format SAN plies from the starting position as `1.d4 Nf6 2.c4 e6`. */
+function formatNumberedLineSans(sans) {
+    if (sans.length === 0) {
+        return "";
+    }
+    const parts = [];
+    for (let i = 0; i < sans.length; i += 2) {
+        const moveNumber = i / 2 + 1;
+        const white = sans[i];
+        const black = sans[i + 1];
+        parts.push(black ? `${moveNumber}.${white} ${black}` : `${moveNumber}.${white}`);
+    }
+    return parts.join(" ");
+}
+
+const EXPLORER_PREFETCH_CHILD_COUNT = 4;
+const EXPLORER_DEFAULT_VARIATION_LINE_COUNT = 8;
+const EXPLORER_DEFAULT_VARIATION_DEPTH = 4;
+function gamesSessionKey(params) {
+    var _a, _b, _c, _d, _e;
+    return JSON.stringify({
+        fen: normalizeFen(params.fen),
+        uci: (_a = params.uci) !== null && _a !== void 0 ? _a : "",
+        sources: (_c = (_b = params.sources) === null || _b === void 0 ? void 0 : _b.slice().sort().join(",")) !== null && _c !== void 0 ? _c : "",
+        limit: (_d = params.limit) !== null && _d !== void 0 ? _d : 50,
+        offset: (_e = params.offset) !== null && _e !== void 0 ? _e : 0,
+    });
+}
+function variationsSessionKey(fen, lineCount = EXPLORER_DEFAULT_VARIATION_LINE_COUNT, lineDepth = EXPLORER_DEFAULT_VARIATION_DEPTH) {
+    return JSON.stringify({
+        fen: normalizeFen(fen),
+        mode: "variations",
+        lineCount,
+        lineDepth,
+    });
+}
+const sessionGames = new Map();
+const sessionVariations = new Map();
+const sessionCacheListeners = new Set();
+function subscribeExplorerSessionCache(listener) {
+    sessionCacheListeners.add(listener);
+    return () => {
+        sessionCacheListeners.delete(listener);
+    };
+}
+function notifySessionCacheListeners() {
+    for (const listener of sessionCacheListeners) {
+        listener();
+    }
+}
+function peekSessionGames(key) {
+    return sessionGames.get(key);
+}
+function setSessionGames(key, data) {
+    sessionGames.set(key, data);
+    notifySessionCacheListeners();
+}
+function peekSessionVariations(key) {
+    return sessionVariations.get(key);
+}
+function setSessionVariations(key, lines) {
+    sessionVariations.set(key, lines);
+    notifySessionCacheListeners();
+}
+
+/** Push start-hub payloads into the explorer session cache (used by app preload). */
+function seedExplorerStartSession(games, variations) {
+    setSessionGames(gamesSessionKey({ fen: EXPLORER_START_FEN }), games);
+    setSessionVariations(variationsSessionKey(EXPLORER_START_FEN), variations.lines);
+}
+
 /**
  * Scaffold UI — proves core wiring and Rollup build.
  * Replace with game replay once requirements are defined.
@@ -47,15 +185,8 @@ const thStyle = {
 const tdStyle = {
     padding: "3px 8px",
     borderBottom: "1px solid rgba(128,128,128,0.12)",
-    whiteSpace: "nowrap",
-};
-const sectionTitleStyle = {
-    margin: 0,
-    fontSize: 12,
-    fontWeight: 600,
-    padding: "6px 8px",
-    borderBottom: "1px solid rgba(128,128,128,0.2)",
-    background: "rgba(128,128,128,0.06)",
+    whiteSpace: "normal",
+    wordBreak: "break-word",
 };
 /** Full-width shell: board | reference — no wrap, no footer below. */
 const referenceShellStyle = {
@@ -104,19 +235,6 @@ const referencePanelStyle = {
     borderLeft: "1px solid rgba(128,128,128,0.3)",
     boxSizing: "border-box",
 };
-const referenceTabBarStyle = {
-    flex: "0 0 auto",
-    display: "flex",
-    alignItems: "center",
-    gap: 4,
-    padding: "6px 10px",
-    borderBottom: "1px solid rgba(128,128,128,0.35)",
-    background: "rgba(128,128,128,0.08)",
-    fontSize: 12,
-};
-const referenceTabLabelStyle = {
-    padding: "2px 8px",
-};
 const moveStatsSectionStyle = {
     flex: "0 1 auto",
     maxHeight: "38%",
@@ -134,9 +252,6 @@ const variationsStripStyle = {
     fontSize: 12,
     background: "rgba(128,128,128,0.04)",
 };
-const variationsTabStyle = {
-    cursor: "default",
-};
 const gamesSectionStyle = {
     flex: "1 1 auto",
     display: "flex",
@@ -175,9 +290,11 @@ const statusInlineStyle = {
 };
 
 /** Right column shell: tab bar + stacked sections (no page footer below). */
-const DefaultReferencePanel = ({ theme, status, moveStats, variationsStrip, gamesPanel, }) => (jsxs("div", { style: Object.assign(Object.assign({}, referencePanelStyle), panelStyle), "data-theme": theme, children: [jsx("div", { style: referenceTabBarStyle, children: jsx("span", { style: Object.assign(Object.assign({}, referenceTabLabelStyle), { fontWeight: 600 }), children: "Reference" }) }), status, jsx("div", { style: { flex: "0 0 auto", minHeight: 0 }, children: moveStats }), variationsStrip, gamesPanel] }));
+const DefaultReferencePanel = ({ theme, fillHeight = true, status, moveStats, variationsStrip, gamesPanel, }) => (jsxs("div", { style: Object.assign(Object.assign(Object.assign({}, referencePanelStyle), panelStyle), (fillHeight
+        ? {}
+        : { height: "auto", minHeight: 0, overflow: "visible" })), "data-theme": theme, children: [status, jsx("div", { style: { flex: "0 0 auto", minHeight: 0 }, children: moveStats }), variationsStrip, gamesPanel] }));
 
-const DefaultBoardNav = ({ canGoBack, canGoForward, onBack, onForward, }) => (jsxs("div", { style: boardNavStyle, children: [jsx("button", { type: "button", style: boardNavButtonStyle, onClick: onBack, disabled: !canGoBack, "aria-label": "Previous position", title: "Back", children: "\u25C0" }), jsx("button", { type: "button", style: boardNavButtonStyle, onClick: onForward, disabled: !canGoForward, "aria-label": "Next position", title: "Forward", children: "\u25B6" })] }));
+const DefaultBoardNav = ({ canGoBack, canGoForward, onBack, onForward, onFlipBoard, }) => (jsxs("div", { style: boardNavStyle, children: [jsx("button", { type: "button", style: boardNavButtonStyle, onClick: onBack, disabled: !canGoBack, "aria-label": "Previous position", title: "Back", children: "\u25C0" }), jsx("button", { type: "button", style: boardNavButtonStyle, onClick: onForward, disabled: !canGoForward, "aria-label": "Next position", title: "Forward", children: "\u25B6" }), jsx("button", { type: "button", style: boardNavButtonStyle, onClick: onFlipBoard, "aria-label": "Flip board", title: "Flip board", children: "\u21C5" })] }));
 const defaultRenderBoardNav = (props) => (jsx(DefaultBoardNav, Object.assign({}, props)));
 
 const ExplorerStatusBanner = ({ error, loading, }) => {
@@ -186,97 +303,15 @@ const ExplorerStatusBanner = ({ error, loading, }) => {
     return (jsxs(Fragment, { children: [error && (jsx("p", { style: Object.assign(Object.assign({}, statusInlineStyle), { color: "#e57373" }), role: "alert", children: error })), loading && (jsx("p", { style: Object.assign(Object.assign({}, statusInlineStyle), { opacity: 0.7 }), children: "Loading\u2026" }))] }));
 };
 
-/** Match endchess-backend / mass-games-import (first four FEN fields). */
-function normalizeFen(fen) {
-    const parts = fen.trim().split(/\s+/);
-    if (parts.length < 4) {
-        throw new Error(`Invalid FEN: ${fen}`);
-    }
-    return `${parts[0]} ${parts[1]} ${parts[2]} ${parts[3]}`;
-}
-/** Legal move from a board drag/drop (react-chessboard piece string, e.g. wQ). */
-function applyBoardMove(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;
-    const played = chess.move({
-        from: legal.from,
-        to: legal.to,
-        promotion: legal.promotion,
-    });
-    if (!played)
-        return null;
-    const uci = `${played.from}${played.to}${(_b = played.promotion) !== null && _b !== void 0 ? _b : ""}`;
-    return { fen: chess.fen(), uci, san: played.san };
-}
-/** Play a SAN sequence from a start FEN; returns null if any move is illegal. */
-function applyLineSans(startFen, sans) {
-    const chess = new Chess(startFen);
-    const entries = [];
-    for (const san of sans) {
-        try {
-            const move = chess.move(san);
-            if (!move)
-                return null;
-            entries.push({ fen: chess.fen(), lastSan: move.san });
-        }
-        catch (_a) {
-            return null;
-        }
-    }
-    return { fen: chess.fen(), entries };
-}
-/** Apply a UCI move to a FEN; returns null if illegal. */
-function fenAfterUci(fen, uci) {
-    const chess = new Chess(fen);
-    const from = uci.slice(0, 2);
-    const to = uci.slice(2, 4);
-    const promotion = uci.length > 4 ? uci[4] : undefined;
-    try {
-        const move = chess.move({ from, to, promotion });
-        if (!move)
-            return null;
-        return chess.fen();
-    }
-    catch (_a) {
-        return null;
-    }
-}
-function whiteScorePercent(whiteWins, draws, blackWins) {
-    const total = whiteWins + draws + blackWins;
-    if (total === 0)
-        return null;
-    return Math.round((100 * (whiteWins + 0.5 * draws)) / total);
-}
-
-const MoveStatsTable = ({ moves, selectedUci, onMoveSelect, }) => (jsxs("div", { style: moveStatsSectionStyle, children: [jsx("div", { style: sectionTitleStyle, children: "Moves" }), jsxs("table", { style: tableStyle, children: [jsx("thead", { children: jsxs("tr", { children: [jsx("th", { style: thStyle, children: "Move" }), jsx("th", { style: thStyle, children: "Games" }), jsx("th", { style: Object.assign(Object.assign({}, thStyle), { textAlign: "right" }), children: "Score %" }), jsx("th", { style: Object.assign(Object.assign({}, thStyle), { textAlign: "right" }), children: "Avg" })] }) }), jsx("tbody", { children: moves.map((move) => {
-                        var _a;
-                        const score = whiteScorePercent(move.whiteWins, move.draws, move.blackWins);
-                        const selected = move.uci === selectedUci;
-                        return (jsxs("tr", { onClick: () => onMoveSelect(move), style: {
-                                cursor: "pointer",
-                                background: selected ? "rgba(100,149,237,0.25)" : undefined,
-                            }, children: [jsx("td", { style: tdStyle, children: move.san }), jsx("td", { style: tdStyle, children: move.games.toLocaleString() }), jsx("td", { style: Object.assign(Object.assign({}, tdStyle), { textAlign: "right" }), children: score !== null ? `${score}` : "—" }), jsx("td", { style: Object.assign(Object.assign({}, tdStyle), { textAlign: "right" }), children: (_a = move.avgElo) !== null && _a !== void 0 ? _a : "—" })] }, move.uci));
-                    }) })] })] }));
-
-const inputStyle = {
-    width: 64,
-    padding: "2px 6px",
-    fontSize: 12,
-};
-const rowStyle = {
-    display: "flex",
-    flexWrap: "wrap",
-    gap: 6,
-    alignItems: "center",
-};
-const EloRangeFilter = ({ minElo, maxElo, defaultMinElo, defaultMaxElo, onMinEloChange, onMaxEloChange, }) => (jsxs("div", { style: rowStyle, children: [jsx("span", { style: { fontWeight: 600 }, children: "Filter" }), jsx("input", { type: "number", value: minElo, min: 0, max: 3000, onChange: (e) => onMinEloChange(Number(e.target.value) || defaultMinElo), style: inputStyle, "aria-label": "Minimum Elo" }), jsx("span", { children: "\u2013" }), jsx("input", { type: "number", value: maxElo, min: 0, max: 3000, onChange: (e) => onMaxEloChange(Number(e.target.value) || defaultMaxElo), style: inputStyle, "aria-label": "Maximum Elo" })] }));
+const MoveStatsTable = ({ moves, selectedUci, onMoveSelect, }) => (jsx("div", { style: moveStatsSectionStyle, children: jsxs("table", { style: tableStyle, children: [jsx("thead", { children: jsxs("tr", { children: [jsx("th", { style: thStyle, children: "Move" }), jsx("th", { style: thStyle, children: "Games" }), jsx("th", { style: Object.assign(Object.assign({}, thStyle), { textAlign: "right" }), children: "Score %" }), jsx("th", { style: Object.assign(Object.assign({}, thStyle), { textAlign: "right" }), children: "Avg" })] }) }), jsx("tbody", { children: moves.map((move) => {
+                    var _a;
+                    const score = whiteScorePercent(move.whiteWins, move.draws, move.blackWins);
+                    const selected = move.uci === selectedUci;
+                    return (jsxs("tr", { onClick: () => onMoveSelect(move), style: {
+                            cursor: "pointer",
+                            background: selected ? "rgba(100,149,237,0.25)" : undefined,
+                        }, children: [jsx("td", { style: tdStyle, children: move.san }), jsx("td", { style: tdStyle, children: move.games.toLocaleString() }), jsx("td", { style: Object.assign(Object.assign({}, tdStyle), { textAlign: "right" }), children: score !== null ? `${score}` : "—" }), jsx("td", { style: Object.assign(Object.assign({}, tdStyle), { textAlign: "right" }), children: (_a = move.avgElo) !== null && _a !== void 0 ? _a : "—" })] }, move.uci));
+                }) })] }) }));
 
 const linkStyle = {
     color: "inherit",
@@ -284,12 +319,12 @@ const linkStyle = {
     textUnderlineOffset: 2,
 };
 const LichessGameLink = ({ url, name }) => (jsx("a", { href: url, target: "_blank", rel: "noopener noreferrer", style: linkStyle, children: name }));
-const GamesTable = ({ games, onGameSelect }) => (jsxs("table", { style: tableStyle, children: [jsx("thead", { children: jsxs("tr", { children: [jsx("th", { style: thStyle, children: "White" }), jsx("th", { style: thStyle, children: "Elo" }), jsx("th", { style: thStyle, children: "Black" }), jsx("th", { style: thStyle, children: "Elo" }), jsx("th", { style: thStyle, children: "Result" }), jsx("th", { style: thStyle, children: "Source" }), onGameSelect && jsx("th", { style: thStyle })] }) }), jsx("tbody", { children: games.length === 0 ? (jsx("tr", { children: jsx("td", { colSpan: onGameSelect ? 7 : 6, style: Object.assign(Object.assign({}, tdStyle), { opacity: 0.7, fontStyle: "italic" }), children: "No games match this position and filter. Widen the Elo range or turn off Top games." }) })) : (games.map((g) => (jsxs("tr", { children: [jsx("td", { style: tdStyle, children: jsx(LichessGameLink, { url: g.url, name: g.white }) }), jsx("td", { style: tdStyle, children: g.whiteElo }), jsx("td", { style: tdStyle, children: jsx(LichessGameLink, { url: g.url, name: g.black }) }), jsx("td", { style: tdStyle, children: g.blackElo }), jsx("td", { style: tdStyle, children: g.result }), jsx("td", { style: tdStyle, children: g.source === "twic" ? "Master" : "Lichess" }), onGameSelect && (jsx("td", { style: tdStyle, children: jsx("button", { type: "button", onClick: () => onGameSelect(g), children: "Train" }) }))] }, g.gameId)))) })] }));
+const GamesTable = ({ games, onGameSelect }) => (jsxs("table", { style: tableStyle, children: [jsx("thead", { children: jsxs("tr", { children: [jsx("th", { style: thStyle, children: "White" }), jsx("th", { style: thStyle, children: "Elo" }), jsx("th", { style: thStyle, children: "Black" }), jsx("th", { style: thStyle, children: "Elo" }), jsx("th", { style: thStyle, children: "Result" }), jsx("th", { style: thStyle, children: "Source" }), onGameSelect && jsx("th", { style: thStyle })] }) }), jsx("tbody", { children: games.length === 0 ? (jsx("tr", { children: jsx("td", { colSpan: onGameSelect ? 7 : 6, style: Object.assign(Object.assign({}, tdStyle), { opacity: 0.7, fontStyle: "italic" }), children: "No games match this position and source filter." }) })) : (games.map((g) => (jsxs("tr", { children: [jsx("td", { style: tdStyle, children: jsx(LichessGameLink, { url: g.url, name: g.white }) }), jsx("td", { style: tdStyle, children: g.whiteElo }), jsx("td", { style: tdStyle, children: jsx(LichessGameLink, { url: g.url, name: g.black }) }), jsx("td", { style: tdStyle, children: g.blackElo }), jsx("td", { style: tdStyle, children: g.result }), jsx("td", { style: tdStyle, children: g.source === "twic" ? "Master" : "Lichess" }), onGameSelect && (jsx("td", { style: tdStyle, children: jsx("button", { type: "button", onClick: () => onGameSelect(g), children: "Train" }) }))] }, g.gameId)))) })] }));
 
 const mainLineTitleStyle = {
     fontWeight: 600,
 };
-const PositionGamesPanel = ({ games, lineLabel, minElo, maxElo, defaultMinElo, defaultMaxElo, topOnly, sources, onMinEloChange, onMaxEloChange, onTopOnlyChange, onSourcesChange, onGameSelect, }) => {
+const PositionGamesPanel = ({ games, lineLabel, lineSans: _lineSans, sources, onSourcesChange, onGameSelect, }) => {
     const toggleSource = (source) => {
         if (sources.includes(source)) {
             if (sources.length === 1) {
@@ -300,7 +335,7 @@ const PositionGamesPanel = ({ games, lineLabel, minElo, maxElo, defaultMinElo, d
         }
         onSourcesChange([...sources, source]);
     };
-    return (jsxs("div", { style: gamesSectionStyle, children: [jsx("div", { style: gamesHeaderStyle, children: lineLabel ? (jsxs(Fragment, { children: [jsx("span", { style: mainLineTitleStyle, children: "Main line: " }), lineLabel, jsxs("span", { style: { opacity: 0.75 }, children: [" (", games.length, " games)"] })] })) : (jsxs("span", { children: ["Games ", jsxs("span", { style: { opacity: 0.75 }, children: ["(", games.length, ")"] })] })) }), jsx("div", { style: gamesScrollStyle, children: jsx(GamesTable, { games: games, onGameSelect: onGameSelect }) }), jsxs("div", { style: gamesToolbarStyle, children: [jsx(EloRangeFilter, { minElo: minElo, maxElo: maxElo, defaultMinElo: defaultMinElo, defaultMaxElo: defaultMaxElo, onMinEloChange: onMinEloChange, onMaxEloChange: onMaxEloChange }), jsxs("label", { style: { display: "flex", alignItems: "center", gap: 4 }, children: [jsx("input", { type: "checkbox", checked: topOnly, onChange: (e) => onTopOnlyChange(e.target.checked) }), "Top games"] }), jsxs("label", { style: { display: "flex", alignItems: "center", gap: 4 }, children: [jsx("input", { type: "checkbox", checked: sources.includes("lichess"), onChange: () => toggleSource("lichess") }), "Lichess"] }), jsxs("label", { style: { display: "flex", alignItems: "center", gap: 4 }, children: [jsx("input", { type: "checkbox", checked: sources.includes("twic"), onChange: () => toggleSource("twic") }), "Master"] })] })] }));
+    return (jsxs("div", { style: gamesSectionStyle, children: [jsx("div", { style: gamesHeaderStyle, children: lineLabel ? (jsxs(Fragment, { children: [jsx("span", { style: mainLineTitleStyle, children: "Main line: " }), lineLabel, jsxs("span", { style: { opacity: 0.75 }, children: [" (", games.length, " games)"] })] })) : (jsxs("span", { children: ["Games ", jsxs("span", { style: { opacity: 0.75 }, children: ["(", games.length, ")"] })] })) }), jsx("div", { style: gamesScrollStyle, children: jsx(GamesTable, { games: games, onGameSelect: onGameSelect }) }), jsxs("div", { style: gamesToolbarStyle, children: [jsxs("label", { style: { display: "flex", alignItems: "center", gap: 4 }, children: [jsx("input", { type: "checkbox", checked: sources.includes("lichess"), onChange: () => toggleSource("lichess") }), "Lichess"] }), jsxs("label", { style: { display: "flex", alignItems: "center", gap: 4 }, children: [jsx("input", { type: "checkbox", checked: sources.includes("twic"), onChange: () => toggleSource("twic") }), "Master"] })] })] }));
 };
 
 const DefaultReferenceLayout = ({ board, referencePanel, }) => (jsxs("div", { style: referenceShellStyle, children: [jsx("div", { style: boardColumnStyle, children: board }), referencePanel] }));
@@ -313,34 +348,37 @@ function isVariationLineActive(line, selectedLineKey, forwardSans = []) {
     if (forwardSans.length === 0) {
         return false;
     }
-    return forwardSans.every((san, index) => { var _a; return ((_a = line.moves[index]) === null || _a === void 0 ? void 0 : _a.san) === san; });
+    const moves = line.moves;
+    if (!Array.isArray(moves)) {
+        return false;
+    }
+    return forwardSans.every((san, index) => { var _a; return ((_a = moves[index]) === null || _a === void 0 ? void 0 : _a.san) === san; });
 }
 
-const tabButtonStyle = (active) => (Object.assign(Object.assign({}, variationsTabStyle), { fontWeight: active ? 600 : 400, opacity: active ? 1 : 0.55, cursor: "pointer", border: "none", background: "transparent", padding: 0, color: "inherit", font: "inherit" }));
-const DefaultVariationsStrip = ({ theme, tab, onTabChange, lines, loading, selectedLineKey, forwardSans, onLineSelect, }) => (jsxs("div", { style: Object.assign(Object.assign({}, variationsStripStyle), { flexDirection: "column", alignItems: "stretch", gap: 6 }), "data-theme": theme, children: [jsxs("div", { style: { display: "flex", alignItems: "center", gap: 12 }, children: [jsx("button", { type: "button", style: tabButtonStyle(tab === "variations"), onClick: () => onTabChange("variations"), children: "Variations" }), jsx("button", { type: "button", style: tabButtonStyle(tab === "popularity"), onClick: () => onTabChange("popularity"), children: "Popularity" }), jsx("button", { type: "button", style: tabButtonStyle(tab === "endgames"), onClick: () => onTabChange("endgames"), children: "Endgames" })] }), jsx("div", { style: {
-                minWidth: 0,
-                maxHeight: 132,
-                overflow: "auto",
-            }, children: tab === "endgames" ? (jsx("span", { style: { fontSize: 11, opacity: 0.55 }, children: "Coming soon" })) : loading ? (jsx("span", { style: { fontSize: 11, opacity: 0.55 }, children: "Loading\u2026" })) : lines.length === 0 ? (jsx("span", { style: { fontSize: 11, opacity: 0.55 }, children: "No lines" })) : (lines.map((line) => {
-                var _a, _b;
-                const active = isVariationLineActive(line, selectedLineKey, forwardSans);
-                return (jsxs("button", { type: "button", onClick: () => onLineSelect(line), style: {
-                        display: "flex",
-                        width: "100%",
-                        gap: 12,
-                        alignItems: "baseline",
-                        border: "none",
-                        background: "transparent",
-                        padding: "2px 0",
-                        cursor: "pointer",
-                        textAlign: "left",
-                        color: active ? "#2e7d32" : "inherit",
-                        font: "inherit",
-                        fontSize: 12,
-                    }, children: [jsx("span", { style: { flex: 1, minWidth: 0 }, children: line.label }), jsxs("span", { children: ["N = ", line.games.toLocaleString()] }), jsxs("span", { children: [(_a = line.scorePercent) !== null && _a !== void 0 ? _a : "—", "%"] }), jsx("span", { children: line.lastPlayedYear
-                                ? `Last played ${line.lastPlayedYear}`
-                                : "Last played —" }), jsx("span", { children: (_b = line.avgElo) !== null && _b !== void 0 ? _b : "—" })] }, line.key));
-            })) })] }));
+const DefaultVariationsStrip = ({ theme, lines, loading, selectedLineKey, forwardSans, onLineSelect, }) => (jsx("div", { style: Object.assign(Object.assign({}, variationsStripStyle), { flexDirection: "column", alignItems: "stretch", gap: 6 }), "data-theme": theme, children: jsx("div", { style: {
+            minWidth: 0,
+            maxHeight: 132,
+            overflow: "auto",
+        }, children: loading ? (jsx("span", { style: { fontSize: 11, opacity: 0.55 }, children: "Loading\u2026" })) : lines.length === 0 ? (jsx("span", { style: { fontSize: 11, opacity: 0.55 }, children: "No lines" })) : (lines.map((line) => {
+            var _a, _b;
+            const active = isVariationLineActive(line, selectedLineKey, forwardSans);
+            return (jsxs("button", { type: "button", onClick: () => onLineSelect(line), style: {
+                    display: "flex",
+                    width: "100%",
+                    gap: 12,
+                    alignItems: "baseline",
+                    border: "none",
+                    background: "transparent",
+                    padding: "2px 0",
+                    cursor: "pointer",
+                    textAlign: "left",
+                    color: active ? "#2e7d32" : "inherit",
+                    font: "inherit",
+                    fontSize: 12,
+                }, children: [jsx("span", { style: { flex: 1, minWidth: 0 }, children: line.label }), jsxs("span", { children: ["N = ", line.games.toLocaleString()] }), jsxs("span", { children: [(_a = line.scorePercent) !== null && _a !== void 0 ? _a : "—", "%"] }), jsx("span", { children: line.lastPlayedYear
+                            ? `Last played ${line.lastPlayedYear}`
+                            : "Last played —" }), jsx("span", { children: (_b = line.avgElo) !== null && _b !== void 0 ? _b : "—" })] }, line.key));
+        })) }) }));
 const defaultRenderVariationsStrip = (props) => jsx(DefaultVariationsStrip, Object.assign({}, props));
 
 const defaultRenderStatus = (props) => (jsx(ExplorerStatusBanner, Object.assign({}, props)));
@@ -381,11 +419,113 @@ typeof SuppressedError === "function" ? SuppressedError : function (error, suppr
 
 const ALL_GAME_SOURCES = ["lichess", "twic"];
 
-function usePositionHistory(initialFen) {
-    const [history, setHistory] = useState([
-        { fen: initialFen },
+function useExplorerPrefetch({ fen, moves, positionReady, sources, fetchPositionGames, fetchPositionVariations, childCount = EXPLORER_PREFETCH_CHILD_COUNT, }) {
+    useEffect(() => {
+        if (!positionReady || moves.length === 0) {
+            return;
+        }
+        let cancelled = false;
+        let idleHandle;
+        let deferTimer;
+        const prefetchChildren = () => {
+            if (cancelled) {
+                return;
+            }
+            const sourcesParam = sources.length < ALL_GAME_SOURCES.length ? sources : undefined;
+            const prefetchMove = (move) => {
+                const childFen = fenAfterUci(fen, move.uci);
+                if (!childFen) {
+                    return Promise.resolve();
+                }
+                const gamesKey = gamesSessionKey({
+                    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) {
+                    return gamesPromise;
+                }
+                const variationsKey = variationsSessionKey(childFen);
+                const variationsPromise = peekSessionVariations(variationsKey)
+                    ? Promise.resolve()
+                    : fetchPositionVariations({
+                        fen: childFen,
+                        mode: "variations",
+                        lineCount: EXPLORER_DEFAULT_VARIATION_LINE_COUNT,
+                        depth: EXPLORER_DEFAULT_VARIATION_DEPTH,
+                    })
+                        .then((result) => {
+                        var _a;
+                        if (!cancelled) {
+                            setSessionVariations(variationsKey, (_a = result === null || result === void 0 ? void 0 : result.lines) !== null && _a !== void 0 ? _a : []);
+                        }
+                    })
+                        .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, {
+                timeout: 1500,
+            });
+        }
+        else {
+            deferTimer = setTimeout(prefetchChildren, 750);
+        }
+        return () => {
+            cancelled = true;
+            if (idleHandle !== undefined) {
+                window.cancelIdleCallback(idleHandle);
+            }
+            if (deferTimer !== undefined) {
+                clearTimeout(deferTimer);
+            }
+        };
+    }, [
+        fen,
+        moves,
+        positionReady,
+        sources,
+        fetchPositionGames,
+        fetchPositionVariations,
+        childCount,
     ]);
-    const [historyIndex, setHistoryIndex] = useState(0);
+}
+
+function initialHistoryState(initialFen, initialLineSans) {
+    if (!(initialLineSans === null || initialLineSans === void 0 ? void 0 : initialLineSans.length)) {
+        return { history: [{ fen: initialFen }], historyIndex: 0 };
+    }
+    const result = applyLineSans(initialFen, initialLineSans);
+    if (!result) {
+        return { history: [{ fen: initialFen }], historyIndex: 0 };
+    }
+    return {
+        history: [{ fen: initialFen }, ...result.entries],
+        historyIndex: result.entries.length,
+    };
+}
+function usePositionHistory(initialFen, initialLineSans) {
+    var _a, _b;
+    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) => {
@@ -413,6 +553,20 @@ function usePositionHistory(initialFen) {
         setHistoryIndex(nextIndex);
         return entry;
     }, [history, historyIndex]);
+    const goFirst = useCallback(() => {
+        if (historyIndex <= 0)
+            return null;
+        const entry = history[0];
+        setHistoryIndex(0);
+        return entry;
+    }, [history, historyIndex]);
+    const goLast = useCallback(() => {
+        if (historyIndex >= history.length - 1)
+            return null;
+        const entry = history[history.length - 1];
+        setHistoryIndex(history.length - 1);
+        return entry;
+    }, [history, historyIndex]);
     const resetHistory = useCallback((fen) => {
         const entry = { fen };
         setHistory([entry]);
@@ -437,39 +591,54 @@ function usePositionHistory(initialFen) {
         .slice(historyIndex + 1)
         .map((entry) => entry.lastSan)
         .filter((san) => Boolean(san));
+    const currentFen = (_b = (_a = history[historyIndex]) === null || _a === void 0 ? void 0 : _a.fen) !== null && _b !== void 0 ? _b : initialFen;
+    const replaceLineEntries = useCallback((startFen, entries) => {
+        setHistory([{ fen: startFen }, ...entries]);
+        setHistoryIndex(entries.length);
+    }, []);
     return {
         canGoBack,
         canGoForward,
         lineSans,
         forwardSans,
+        currentFen,
         pushEntry,
         pushEntries,
+        replaceLineEntries,
         goBack,
         goForward,
+        goFirst,
+        goLast,
         resetHistory,
     };
 }
 
-function usePositionReferenceData({ fenProp, onFenChange, initialLineSans, onLineSansChange, fetchPosition, fetchPositionGames, defaultMinElo, defaultMaxElo, }) {
+function usePositionReferenceData({ fenProp, onFenChange, initialLineSans, onLineSansChange, fetchPosition, fetchPositionGames, fetchPositionVariations, }) {
+    var _a, _b, _c;
     const initialFen = fenProp !== null && fenProp !== void 0 ? fenProp : EXPLORER_START_FEN;
-    const [fen, setFen] = useState(initialFen);
-    /** Board display FEN; may lead {@link fen} while a variation line is animating. */
-    const [boardFen, setBoardFen] = useState(initialFen);
+    const bootstrappedRef = useRef(initialHistoryState(initialFen, initialLineSans));
+    const bootstrappedFen = (_b = (_a = bootstrappedRef.current.history[bootstrappedRef.current.historyIndex]) === null || _a === void 0 ? void 0 : _a.fen) !== null && _b !== void 0 ? _b : initialFen;
+    const initialGamesKey = gamesSessionKey({ fen: bootstrappedFen });
+    const initialCachedGames = peekSessionGames(initialGamesKey);
+    const [fen, setFen] = useState(bootstrappedFen);
+    /** Board display FEN; may lead {@link queryFen} while a variation line is animating. */
+    const [boardFen, setBoardFen] = useState(bootstrappedFen);
     const [position, setPosition] = useState(null);
-    const [games, setGames] = useState(null);
+    const [games, setGames] = useState(() => initialCachedGames !== null && initialCachedGames !== void 0 ? initialCachedGames : null);
     /** Filter games to those that played this UCI from the current FEN (optional). */
     const [gamesMoveFilterUci, setGamesMoveFilterUci] = useState();
-    const [minElo, setMinElo] = useState(defaultMinElo);
-    const [maxElo, setMaxElo] = useState(defaultMaxElo);
-    const [topOnly, setTopOnly] = useState(false);
     const [sources, setSources] = useState([...ALL_GAME_SOURCES]);
     const [loading, setLoading] = useState(false);
+    const [gamesLoading, setGamesLoading] = useState(() => initialCachedGames === undefined);
+    /** FEN that {@link position} was loaded for (may lag {@link fen} while fetching). */
+    const [loadedPositionFen, setLoadedPositionFen] = useState(null);
+    const [loadedPositionFilterKey, setLoadedPositionFilterKey] = useState(null);
     const [error, setError] = useState(null);
-    const [variationsTab, setVariationsTab] = useState("variations");
     const [selectedVariationKey, setSelectedVariationKey] = useState();
     const variationAnimationTimerRef = useRef(null);
     const isAnimatingVariationRef = useRef(false);
-    const readyForLineSyncRef = useRef(false);
+    const readyForLineSyncRef = useRef(bootstrappedRef.current.historyIndex > 0 ||
+        ((_c = initialLineSans === null || initialLineSans === void 0 ? void 0 : initialLineSans.length) !== null && _c !== void 0 ? _c : 0) === 0);
     const cancelVariationAnimation = useCallback(() => {
         if (variationAnimationTimerRef.current !== null) {
             clearTimeout(variationAnimationTimerRef.current);
@@ -477,7 +646,17 @@ function usePositionReferenceData({ fenProp, onFenChange, initialLineSans, onLin
         }
         isAnimatingVariationRef.current = false;
     }, []);
-    const { canGoBack, canGoForward, lineSans, forwardSans, pushEntry, pushEntries, goBack, goForward, resetHistory, } = usePositionHistory(initialFen);
+    const { canGoBack, canGoForward, lineSans, forwardSans, currentFen, pushEntry, pushEntries, replaceLineEntries, goBack, goForward, goFirst, goLast, resetHistory, } = 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]);
+    const expectedLineFen = useMemo(() => {
+        var _a, _b;
+        if (!(initialLineSans === null || initialLineSans === void 0 ? void 0 : initialLineSans.length)) {
+            return EXPLORER_START_FEN;
+        }
+        return ((_b = (_a = applyLineSans(EXPLORER_START_FEN, initialLineSans)) === null || _a === void 0 ? void 0 : _a.fen) !== null && _b !== void 0 ? _b : EXPLORER_START_FEN);
+    }, [initialLineKey, initialLineSans]);
     const applyNavigation = useCallback((nextFen, clearMoveFilter = true) => {
         setFen(nextFen);
         setBoardFen(nextFen);
@@ -486,39 +665,72 @@ function usePositionReferenceData({ fenProp, onFenChange, initialLineSans, onLin
         }
         onFenChange === null || onFenChange === void 0 ? void 0 : onFenChange(nextFen);
     }, [onFenChange]);
-    const initialLineKey = useMemo(() => { var _a; return (_a = initialLineSans === null || initialLineSans === void 0 ? void 0 : initialLineSans.join("|")) !== null && _a !== void 0 ? _a : ""; }, [initialLineSans]);
-    const lastAppliedLineKeyRef = useRef(undefined);
+    const queryFenRef = useRef(queryFen);
+    queryFenRef.current = queryFen;
+    const positionsByFenRef = useRef(new Map());
+    const positionCacheKey = useCallback((fenValue) => JSON.stringify({
+        fen: fenValue,
+        sources: sources.length < ALL_GAME_SOURCES.length
+            ? sources.slice().sort().join(",")
+            : "",
+    }), [sources]);
+    const gamesCacheKey = useCallback((fenValue, uci) => gamesSessionKey({
+        fen: fenValue,
+        uci,
+        sources: sources.length < ALL_GAME_SOURCES.length ? sources : undefined,
+    }), [sources]);
+    const lastAppliedLineKeyRef = useRef(initialLineKey);
     useEffect(() => () => cancelVariationAnimation(), [cancelVariationAnimation]);
+    // 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(() => {
-        if (lastAppliedLineKeyRef.current === initialLineKey)
-            return;
-        const currentLineKey = lineSans.join("|");
-        if (currentLineKey === initialLineKey) {
-            lastAppliedLineKeyRef.current = initialLineKey;
+        if (initialLineSans === undefined && onLineSansChange === undefined)
             return;
+        const fenMatches = normalizeFen(queryFen) === normalizeFen(expectedLineFen);
+        if (lastAppliedLineKeyRef.current === initialLineKey) {
+            if (fenMatches)
+                return;
+        }
+        else {
+            const currentLineKey = lineSans.join("|");
+            if (currentLineKey === initialLineKey && fenMatches) {
+                lastAppliedLineKeyRef.current = initialLineKey;
+                return;
+            }
         }
         lastAppliedLineKeyRef.current = initialLineKey;
         cancelVariationAnimation();
-        resetHistory(EXPLORER_START_FEN);
         setSelectedVariationKey(undefined);
         if (initialLineSans === null || initialLineSans === void 0 ? void 0 : initialLineSans.length) {
             const result = applyLineSans(EXPLORER_START_FEN, initialLineSans);
             if (result) {
-                pushEntries(result.entries);
+                replaceLineEntries(EXPLORER_START_FEN, result.entries);
                 applyNavigation(result.fen, true);
                 return;
             }
         }
+        replaceLineEntries(EXPLORER_START_FEN, []);
         applyNavigation(EXPLORER_START_FEN, true);
+        // lineSans / queryFen intentionally omitted — only re-sync when the URL line key changes.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [
         initialLineKey,
         initialLineSans,
-        lineSans,
+        expectedLineFen,
         cancelVariationAnimation,
-        resetHistory,
-        pushEntries,
+        replaceLineEntries,
         applyNavigation,
     ]);
+    // Keep legacy fen state aligned with move history when they drift apart.
+    useEffect(() => {
+        if (isAnimatingVariationRef.current)
+            return;
+        if (normalizeFen(fen) === normalizeFen(queryFen))
+            return;
+        setFen(queryFen);
+        setBoardFen(queryFen);
+        onFenChange === null || onFenChange === void 0 ? void 0 : onFenChange(queryFen);
+    }, [fen, queryFen, onFenChange]);
     useEffect(() => {
         if (readyForLineSyncRef.current)
             return;
@@ -530,90 +742,171 @@ function usePositionReferenceData({ fenProp, onFenChange, initialLineSans, onLin
         }
     }, [lineSans, initialLineSans]);
     useEffect(() => {
+        if (!onLineSansChange)
+            return;
         if (!readyForLineSyncRef.current)
             return;
-        onLineSansChange === null || onLineSansChange === void 0 ? void 0 : onLineSansChange(lineSans);
+        onLineSansChange(lineSans);
     }, [lineSans, onLineSansChange]);
     useEffect(() => {
-        if (fenProp === undefined || fenProp === fen)
+        if (fenProp === undefined)
+            return;
+        if (fenProp === queryFenRef.current)
             return;
         cancelVariationAnimation();
         resetHistory(fenProp);
         applyNavigation(fenProp, true);
-    }, [fenProp, fen, resetHistory, applyNavigation, cancelVariationAnimation]);
+    }, [fenProp, cancelVariationAnimation, resetHistory, applyNavigation]);
     useEffect(() => {
         let cancelled = false;
-        setLoading(true);
-        setError(null);
+        const requestedFen = queryFen;
+        const requestedFilterKey = positionCacheKey(requestedFen);
+        if (positionsByFenRef.current.has(requestedFilterKey)) {
+            setPosition(positionsByFenRef.current.get(requestedFilterKey));
+            setLoadedPositionFen(requestedFen);
+            setLoadedPositionFilterKey(requestedFilterKey);
+            setLoading(false);
+            setError(null);
+        }
+        else {
+            setLoading(true);
+            setError(null);
+        }
         (() => __awaiter(this, void 0, void 0, function* () {
             try {
-                const [pos, gameList] = yield Promise.all([
-                    fetchPosition(fen),
-                    fetchPositionGames({
-                        fen,
-                        minElo,
-                        maxElo,
-                        uci: gamesMoveFilterUci,
-                        topOnly,
-                        sources: sources.length < ALL_GAME_SOURCES.length ? sources : undefined,
-                    }),
-                ]);
-                if (cancelled)
+                const pos = yield fetchPosition({
+                    fen: requestedFen,
+                    sources: sources.length < ALL_GAME_SOURCES.length ? sources : undefined,
+                });
+                if (cancelled || requestedFen !== queryFenRef.current)
                     return;
-                setPosition(pos);
-                setGames(gameList);
-                if (!pos) {
-                    setError("No explorer data for this position yet");
+                if (pos) {
+                    positionsByFenRef.current.set(positionCacheKey(requestedFen), pos);
                 }
+                setPosition(pos);
+                setLoadedPositionFen(requestedFen);
+                setLoadedPositionFilterKey(positionCacheKey(requestedFen));
             }
             catch (e) {
+                if (cancelled || requestedFen !== queryFenRef.current)
+                    return;
+                setPosition(null);
+                setLoadedPositionFen(null);
+                setLoadedPositionFilterKey(null);
+                setError(e instanceof Error ? e.message : "Failed to load explorer data");
+            }
+            finally {
+                if (!cancelled && requestedFen === queryFenRef.current) {
+                    setLoading(false);
+                }
+            }
+        }))();
+        return () => {
+            cancelled = true;
+        };
+    }, [queryFen, sources, fetchPosition, positionCacheKey]);
+    const activePositionFilterKey = positionCacheKey(queryFen);
+    const cachedPosition = positionsByFenRef.current.get(activePositionFilterKey);
+    const positionReady = loadedPositionFen === queryFen &&
+        loadedPositionFilterKey === activePositionFilterKey;
+    const displayPosition = cachedPosition !== null && cachedPosition !== void 0 ? cachedPosition : (positionReady ? position : null);
+    const displayMoves = Array.isArray(displayPosition === null || displayPosition === void 0 ? void 0 : displayPosition.moves)
+        ? displayPosition.moves
+        : [];
+    const showPositionLoading = loading && displayMoves.length === 0;
+    const isStartPosition = normalizeFen(queryFen) === normalizeFen(EXPLORER_START_FEN);
+    useExplorerPrefetch({
+        fen: queryFen,
+        moves: displayMoves,
+        positionReady,
+        sources,
+        fetchPositionGames,
+        fetchPositionVariations,
+    });
+    useEffect(() => {
+        return subscribeExplorerSessionCache(() => {
+            const key = gamesCacheKey(queryFen, gamesMoveFilterUci);
+            const cached = peekSessionGames(key);
+            if (!cached) {
+                return;
+            }
+            setGames(cached);
+            setGamesLoading(false);
+        });
+    }, [queryFen, gamesMoveFilterUci, gamesCacheKey]);
+    useEffect(() => {
+        const canLoadGames = positionReady || (isStartPosition && !gamesMoveFilterUci);
+        if (!canLoadGames)
+            return;
+        let cancelled = false;
+        const requestedKey = gamesCacheKey(queryFen, gamesMoveFilterUci);
+        const cachedGames = peekSessionGames(requestedKey);
+        if (cachedGames) {
+            setGames(cachedGames);
+            setGamesLoading(false);
+        }
+        else {
+            setGamesLoading(true);
+        }
+        void (() => __awaiter(this, void 0, void 0, function* () {
+            try {
+                const gameList = yield fetchPositionGames({
+                    fen: queryFen,
+                    uci: gamesMoveFilterUci,
+                    sources: sources.length < ALL_GAME_SOURCES.length ? sources : undefined,
+                });
+                if (cancelled)
+                    return;
+                setSessionGames(requestedKey, gameList);
+                setGames(gameList);
+            }
+            catch (_a) {
                 if (!cancelled) {
-                    setError(e instanceof Error ? e.message : "Failed to load explorer data");
+                    setGames(null);
                 }
             }
             finally {
                 if (!cancelled)
-                    setLoading(false);
+                    setGamesLoading(false);
             }
         }))();
         return () => {
             cancelled = true;
         };
     }, [
-        fen,
-        minElo,
-        maxElo,
+        queryFen,
+        positionReady,
+        isStartPosition,
         gamesMoveFilterUci,
-        topOnly,
         sources,
-        fetchPosition,
         fetchPositionGames,
+        gamesCacheKey,
     ]);
     const handleMoveSelect = useCallback((move) => {
         if (isAnimatingVariationRef.current) {
             cancelVariationAnimation();
-            setBoardFen(fen);
+            setBoardFen(queryFen);
             setSelectedVariationKey(undefined);
         }
-        const nextFen = fenAfterUci(fen, move.uci);
+        const nextFen = fenAfterUci(queryFen, move.uci);
         if (!nextFen)
             return;
         pushEntry(nextFen, move.san);
         setSelectedVariationKey(undefined);
         applyNavigation(nextFen, true);
-    }, [fen, pushEntry, applyNavigation, cancelVariationAnimation]);
+    }, [queryFen, pushEntry, applyNavigation, cancelVariationAnimation]);
     const handleLineSelect = useCallback((line) => {
         if (isAnimatingVariationRef.current)
             return;
         cancelVariationAnimation();
-        let currentFen = fen;
+        let lineFen = queryFen;
         const entries = [];
         for (let i = 0; i < line.uciPath.length; i += 1) {
-            const nextFen = fenAfterUci(currentFen, line.uciPath[i]);
+            const nextFen = fenAfterUci(lineFen, line.uciPath[i]);
             if (!nextFen)
                 return;
             entries.push({ fen: nextFen, lastSan: line.moves[i].san });
-            currentFen = nextFen;
+            lineFen = nextFen;
         }
         if (entries.length === 0)
             return;
@@ -637,109 +930,162 @@ function usePositionReferenceData({ fenProp, onFenChange, initialLineSans, onLin
             }
         };
         tick();
-    }, [fen, pushEntries, applyNavigation, cancelVariationAnimation]);
+    }, [queryFen, pushEntries, applyNavigation, cancelVariationAnimation]);
     const handlePieceDrop = useCallback((sourceSquare, targetSquare, piece) => {
         if (isAnimatingVariationRef.current) {
             cancelVariationAnimation();
-            setBoardFen(fen);
+            setBoardFen(queryFen);
             setSelectedVariationKey(undefined);
         }
-        const result = applyBoardMove(fen, sourceSquare, targetSquare, piece);
+        const result = applyBoardMove(queryFen, sourceSquare, targetSquare, piece);
         if (!result)
             return false;
         pushEntry(result.fen, result.san);
         setSelectedVariationKey(undefined);
         applyNavigation(result.fen, true);
         return true;
-    }, [fen, pushEntry, applyNavigation, cancelVariationAnimation]);
+    }, [queryFen, pushEntry, applyNavigation, cancelVariationAnimation]);
     const handleBack = useCallback(() => {
         if (isAnimatingVariationRef.current) {
             cancelVariationAnimation();
-            setBoardFen(fen);
+            setBoardFen(queryFen);
             setSelectedVariationKey(undefined);
             return;
         }
         const entry = goBack();
         if (entry)
             applyNavigation(entry.fen, true);
-    }, [fen, goBack, applyNavigation, cancelVariationAnimation]);
+    }, [queryFen, goBack, applyNavigation, cancelVariationAnimation]);
     const handleForward = useCallback(() => {
         if (isAnimatingVariationRef.current) {
             cancelVariationAnimation();
-            setBoardFen(fen);
+            setBoardFen(queryFen);
             setSelectedVariationKey(undefined);
             return;
         }
         const entry = goForward();
         if (entry)
             applyNavigation(entry.fen, true);
-    }, [fen, goForward, applyNavigation, cancelVariationAnimation]);
+    }, [queryFen, goForward, applyNavigation, cancelVariationAnimation]);
+    const handleFirst = useCallback(() => {
+        if (isAnimatingVariationRef.current) {
+            cancelVariationAnimation();
+            setBoardFen(queryFen);
+            setSelectedVariationKey(undefined);
+            return;
+        }
+        const entry = goFirst();
+        if (entry)
+            applyNavigation(entry.fen, true);
+    }, [queryFen, goFirst, applyNavigation, cancelVariationAnimation]);
+    const handleLast = useCallback(() => {
+        if (isAnimatingVariationRef.current) {
+            cancelVariationAnimation();
+            setBoardFen(queryFen);
+            setSelectedVariationKey(undefined);
+            return;
+        }
+        const entry = goLast();
+        if (entry)
+            applyNavigation(entry.fen, true);
+    }, [queryFen, goLast, applyNavigation, cancelVariationAnimation]);
     const lineLabel = useMemo(() => {
         if (lineSans.length > 0) {
-            return lineSans.join(" ");
+            return formatNumberedLineSans(lineSans);
         }
-        if (position) {
+        if (position && typeof position.totalGames === "number") {
             return `Starting position (${position.totalGames.toLocaleString()} games)`;
         }
         return "";
     }, [lineSans, position]);
     return {
-        fen,
+        fen: queryFen,
         boardFen,
         position,
         games,
         gamesMoveFilterUci,
-        minElo,
-        maxElo,
-        topOnly,
         sources,
+        lineSans,
         loading,
+        showPositionLoading,
+        gamesLoading,
+        positionReady,
+        displayMoves,
         error,
         lineLabel,
         canGoBack,
         canGoForward,
-        variationsTab,
         forwardSans,
         selectedVariationKey,
-        setMinElo,
-        setMaxElo,
-        setTopOnly,
         setSources,
-        setVariationsTab,
         setGamesMoveFilterUci,
         handleMoveSelect,
         handleLineSelect,
         handlePieceDrop,
         handleBack,
         handleForward,
+        handleFirst,
+        handleLast,
     };
 }
 
-function useVariationLines({ fen, tab, minElo, maxElo, fetchPositionVariations, lineCount = 8, lineDepth = 4, enabled = true, }) {
-    const [lines, setLines] = useState([]);
-    const [loading, setLoading] = useState(false);
+function useVariationLines({ fen, fetchPositionVariations, lineCount = EXPLORER_DEFAULT_VARIATION_LINE_COUNT, lineDepth = EXPLORER_DEFAULT_VARIATION_DEPTH, enabled = true, }) {
+    const cacheKey = useMemo(() => variationsSessionKey(fen, lineCount, lineDepth), [fen, lineCount, lineDepth]);
+    const [lines, setLines] = useState(() => {
+        var _a;
+        if (!enabled) {
+            return [];
+        }
+        return (_a = peekSessionVariations(cacheKey)) !== null && _a !== void 0 ? _a : [];
+    });
+    const [loading, setLoading] = useState(() => {
+        if (!enabled) {
+            return false;
+        }
+        return peekSessionVariations(cacheKey) === undefined;
+    });
+    useEffect(() => {
+        return subscribeExplorerSessionCache(() => {
+            if (!enabled) {
+                return;
+            }
+            const cachedLines = peekSessionVariations(cacheKey);
+            if (!cachedLines) {
+                return;
+            }
+            setLines(cachedLines);
+            setLoading(false);
+        });
+    }, [enabled, cacheKey]);
     useEffect(() => {
-        if (!enabled || tab === "endgames") {
+        if (!enabled) {
             setLines([]);
             setLoading(false);
             return;
         }
         let cancelled = false;
-        setLoading(true);
-        (() => __awaiter(this, void 0, void 0, function* () {
+        const cachedLines = peekSessionVariations(cacheKey);
+        if (cachedLines) {
+            setLines(cachedLines);
+            setLoading(false);
+        }
+        else {
+            setLoading(true);
+        }
+        void (() => __awaiter(this, void 0, void 0, function* () {
             var _a;
             try {
                 const result = yield fetchPositionVariations({
                     fen,
-                    mode: tab,
-                    minElo,
-                    maxElo,
+                    mode: "variations",
                     lineCount,
                     depth: lineDepth,
                 });
                 if (cancelled)
                     return;
-                setLines((_a = result === null || result === void 0 ? void 0 : result.lines) !== null && _a !== void 0 ? _a : []);
+                const nextLines = (_a = result === null || result === void 0 ? void 0 : result.lines) !== null && _a !== void 0 ? _a : [];
+                setSessionVariations(cacheKey, nextLines);
+                setLines(nextLines);
             }
             catch (_b) {
                 if (!cancelled) {
@@ -755,21 +1101,11 @@ function useVariationLines({ fen, tab, minElo, maxElo, fetchPositionVariations,
         return () => {
             cancelled = true;
         };
-    }, [
-        enabled,
-        fen,
-        tab,
-        minElo,
-        maxElo,
-        fetchPositionVariations,
-        lineCount,
-        lineDepth,
-    ]);
-    return { lines, loading };
+    }, [enabled, fen, fetchPositionVariations, lineCount, lineDepth, cacheKey]);
+    return { lines, loading: enabled ? loading : false };
 }
 
-const PositionReferenceExplorerCore = ({ fen: fenProp, onFenChange, initialLineSans, onLineSansChange, fetchPosition, fetchPositionGames, fetchPositionVariations, theme = "dark", boardWidth = DEFAULT_REFERENCE_LAYOUT.boardWidth, defaultMinElo = 2200, defaultMaxElo = 2800, fillHeight = true, layoutMinHeight, renderLayout = defaultRenderLayout, renderStatus = defaultRenderStatus, renderMoveStats = defaultRenderMoveStats, renderVariationsStrip = defaultRenderVariationsStrip, renderGamesPanel = defaultRenderGamesPanel, renderBoardNav = defaultRenderBoardNav, onGameSelect, }) => {
-    var _a, _b;
+const PositionReferenceExplorerCore = ({ fen: fenProp, onFenChange, initialLineSans, onLineSansChange, fetchPosition, fetchPositionGames, fetchPositionVariations, theme = "dark", boardTheme, boardWidth = DEFAULT_REFERENCE_LAYOUT.boardWidth, boardOrientation: boardOrientationProp, defaultBoardOrientation = "white", onBoardOrientationChange, fillHeight = true, layoutMinHeight, renderLayout = defaultRenderLayout, renderStatus = defaultRenderStatus, renderMoveStats = defaultRenderMoveStats, renderVariationsStrip = defaultRenderVariationsStrip, renderGamesPanel = defaultRenderGamesPanel, renderBoardNav = defaultRenderBoardNav, onGameSelect, keyboardNav = true, }) => {
     const referenceData = usePositionReferenceData({
         fenProp,
         onFenChange,
@@ -777,59 +1113,96 @@ const PositionReferenceExplorerCore = ({ fen: fenProp, onFenChange, initialLineS
         onLineSansChange,
         fetchPosition,
         fetchPositionGames,
-        defaultMinElo,
-        defaultMaxElo,
+        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;
+    usePositionKeyboardNav({
+        enabled: keyboardNav,
+        canPrev: canGoBack,
+        canNext: canGoForward,
+        onPrev: handleBack,
+        onNext: handleForward,
+        onFirst: handleFirst,
+        onLast: handleLast,
     });
-    const { fen, boardFen, position, games, minElo, maxElo, topOnly, sources, loading, error, lineLabel, canGoBack, canGoForward, variationsTab, forwardSans, selectedVariationKey, setMinElo, setMaxElo, setTopOnly, setSources, setVariationsTab, handleMoveSelect, handleLineSelect, handlePieceDrop, handleBack, handleForward, } = referenceData;
+    const [variationsEnabled, setVariationsEnabled] = useState(() => normalizeFen(fen) === normalizeFen(EXPLORER_START_FEN));
+    const isStartPosition = normalizeFen(fen) === normalizeFen(EXPLORER_START_FEN);
+    useEffect(() => {
+        const cachedVariations = peekSessionVariations(variationsSessionKey(fen, EXPLORER_DEFAULT_VARIATION_LINE_COUNT, EXPLORER_DEFAULT_VARIATION_DEPTH));
+        if (cachedVariations) {
+            setVariationsEnabled(true);
+            return;
+        }
+        if (!positionReady && !isStartPosition) {
+            setVariationsEnabled(false);
+            return;
+        }
+        if (loading && !isStartPosition) {
+            setVariationsEnabled(false);
+            return;
+        }
+        setVariationsEnabled(true);
+    }, [fen, positionReady, loading, isStartPosition]);
     const { lines: variationLines, loading: variationLinesLoading } = useVariationLines({
         fen,
-        tab: variationsTab,
-        minElo,
-        maxElo,
         fetchPositionVariations,
-        enabled: Boolean(position),
+        enabled: variationsEnabled && (positionReady || isStartPosition),
     });
+    const [internalBoardOrientation, setInternalBoardOrientation] = useState(defaultBoardOrientation);
+    const boardOrientation = boardOrientationProp !== null && boardOrientationProp !== void 0 ? boardOrientationProp : internalBoardOrientation;
+    const handleFlipBoard = useCallback(() => {
+        const nextOrientation = boardOrientation === "white" ? "black" : "white";
+        if (boardOrientationProp === undefined) {
+            setInternalBoardOrientation(nextOrientation);
+        }
+        onBoardOrientationChange === null || onBoardOrientationChange === void 0 ? void 0 : onBoardOrientationChange(nextOrientation);
+    }, [boardOrientation, boardOrientationProp, onBoardOrientationChange]);
+    const boardNavProps = useMemo(() => ({
+        canGoBack,
+        canGoForward,
+        onBack: handleBack,
+        onForward: handleForward,
+        boardOrientation,
+        onFlipBoard: handleFlipBoard,
+    }), [
+        boardOrientation,
+        canGoBack,
+        canGoForward,
+        handleBack,
+        handleFlipBoard,
+        handleForward,
+    ]);
     const outerStyle = {
         width: "100%",
         height: fillHeight ? "100%" : "auto",
         minHeight: layoutMinHeight !== null && layoutMinHeight !== void 0 ? layoutMinHeight : DEFAULT_REFERENCE_LAYOUT.minHeight,
-        overflow: "hidden",
+        overflow: fillHeight ? "hidden" : "visible",
         boxSizing: "border-box",
     };
-    const board = (jsxs(Fragment, { children: [jsx(ChessboardDnDProvider, { children: jsx(HighlightChessboard, { boardWidth: boardWidth, position: boardFen, checkSquare: "", hintSquare: null, incorrectMoveSquare: null, onPieceDrop: handlePieceDrop, promotionDialogVariant: "modal" }) }), renderBoardNav({
-                canGoBack,
-                canGoForward,
-                onBack: handleBack,
-                onForward: handleForward,
-            })] }));
-    const referencePanel = (jsx(DefaultReferencePanel, { theme: theme, status: renderStatus({ error, loading }), moveStats: renderMoveStats({
-            moves: (_a = position === null || position === void 0 ? void 0 : position.moves) !== null && _a !== void 0 ? _a : [],
+    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 referencePanel = (jsx(DefaultReferencePanel, { theme: theme, fillHeight: fillHeight, status: renderStatus({
+            error,
+            loading: showPositionLoading,
+        }), moveStats: renderMoveStats({
+            moves: displayMoves,
             onMoveSelect: handleMoveSelect,
         }), variationsStrip: renderVariationsStrip({
             theme,
-            tab: variationsTab,
-            onTabChange: setVariationsTab,
             lines: variationLines,
-            loading: variationLinesLoading,
+            loading: !variationsEnabled || variationLinesLoading,
             selectedLineKey: selectedVariationKey,
             forwardSans,
             onLineSelect: handleLineSelect,
         }), gamesPanel: renderGamesPanel({
-            games: (_b = games === null || games === void 0 ? void 0 : games.games) !== null && _b !== void 0 ? _b : [],
+            games: Array.isArray(games === null || games === void 0 ? void 0 : games.games) ? games.games : [],
+            loading: gamesLoading,
             lineLabel,
-            minElo,
-            maxElo,
-            defaultMinElo,
-            defaultMaxElo,
-            topOnly,
+            lineSans,
             sources,
-            onMinEloChange: setMinElo,
-            onMaxEloChange: setMaxElo,
-            onTopOnlyChange: setTopOnly,
             onSourcesChange: setSources,
             onGameSelect,
         }) }));
-    return (jsx(ThemeProvider, { theme: theme, children: jsx("div", { style: outerStyle, children: renderLayout({ theme, board, referencePanel }) }) }));
+    return (jsx(ThemeProvider, { theme: theme, boardTheme: boardTheme, children: jsx("div", { style: outerStyle, children: renderLayout({ theme, board, referencePanel }) }) }));
 };
 
 /** Reference explorer with library default layout and renderers (ChessBase-style grid). */
@@ -1040,10 +1413,6 @@ const mockPosition = {
 };
 const mockGames = {
     positionKey: "mock-start",
-    fen: EXPLORER_START_FEN,
-    minElo: 2200,
-    maxElo: 2800,
-    topOnly: false,
     games: [
         {
             gameId: "abc123",
@@ -1075,7 +1444,7 @@ const mockGames = {
         },
     ],
 };
-function mockFetchPosition(fen) {
+function mockFetchPosition(params) {
     return __awaiter(this, void 0, void 0, function* () {
         return mockPosition;
     });
@@ -1109,7 +1478,11 @@ function mockVariationLines(params, position) {
 }
 function mockFetchPositionVariations(params) {
     return __awaiter(this, void 0, void 0, function* () {
-        const position = yield mockFetchPosition(params.fen);
+        const position = yield mockFetchPosition({
+            fen: params.fen,
+            minElo: params.minElo,
+            maxElo: params.maxElo,
+        });
         if (!position)
             return null;
         return mockVariationLines(params, position);
@@ -1117,15 +1490,26 @@ function mockFetchPositionVariations(params) {
 }
 function mockFetchPositionGames(params) {
     return __awaiter(this, void 0, void 0, function* () {
-        var _a;
+        var _a, _b, _c;
         let filtered = params.uci
             ? mockGames.games.filter((g) => g.nextUci === params.uci)
             : mockGames.games;
         if ((_a = params.sources) === null || _a === void 0 ? void 0 : _a.length) {
             filtered = filtered.filter((game) => params.sources.includes(game.source));
         }
-        return Object.assign(Object.assign({}, mockGames), { fen: params.fen, minElo: params.minElo, maxElo: params.maxElo, uci: params.uci, topOnly: params.topOnly, games: params.topOnly ? filtered.filter((g) => g.avgElo >= 2500) : filtered });
+        const offset = (_b = params.offset) !== null && _b !== void 0 ? _b : 0;
+        const limit = (_c = params.limit) !== null && _c !== void 0 ? _c : filtered.length;
+        const page = filtered.slice(offset, offset + limit);
+        const hasMore = offset + limit < filtered.length;
+        return {
+            positionKey: mockGames.positionKey,
+            fen: params.fen,
+            uci: params.uci,
+            offset,
+            hasMore,
+            games: page,
+        };
     });
 }
 
-export { ALL_GAME_SOURCES, DEFAULT_REFERENCE_LAYOUT, DefaultBoardNav, DefaultReferenceLayout, DefaultReferencePanel, DefaultVariationsStrip, EXPLORER_START_FEN, ExplorerPlaceholder, GameReplayTrainer, PositionReferenceExplorer, PositionReferenceExplorerCore, applyLineSans, defaultRenderBoardNav, defaultRenderGamesPanel, defaultRenderLayout, defaultRenderMoveStats, defaultRenderStatus, defaultRenderVariationsStrip, fenAfterUci, fenAtPly, findPlyIndexForFen, isVariationLineActive, mockFetchPosition, mockFetchPositionGames, mockFetchPositionVariations, normalizeFen, useGameReplayTraining, whiteScorePercent };
+export { ALL_GAME_SOURCES, DEFAULT_REFERENCE_LAYOUT, DefaultBoardNav, DefaultReferenceLayout, DefaultReferencePanel, DefaultVariationsStrip, EXPLORER_DEFAULT_VARIATION_DEPTH, EXPLORER_DEFAULT_VARIATION_LINE_COUNT, EXPLORER_PREFETCH_CHILD_COUNT, EXPLORER_START_FEN, ExplorerPlaceholder, GameReplayTrainer, PositionReferenceExplorer, PositionReferenceExplorerCore, applyLineSans, defaultRenderBoardNav, defaultRenderGamesPanel, defaultRenderLayout, defaultRenderMoveStats, defaultRenderStatus, defaultRenderVariationsStrip, fenAfterUci, fenAtPly, findPlyIndexForFen, formatNumberedLineSans, gamesSessionKey, isVariationLineActive, mockFetchPosition, mockFetchPositionGames, mockFetchPositionVariations, normalizeFen, peekSessionGames, peekSessionVariations, seedExplorerStartSession, setSessionGames, setSessionVariations, subscribeExplorerSessionCache, useGameReplayTraining, variationsSessionKey, whiteScorePercent };