react-chess-explorer 0.0.2 → 0.0.4

package/README.md

@@ -7,6 +7,8 @@ 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.
 
 ---

package/dist/features/explorer/components/DefaultBoardNav.d.ts

@@ -1,8 +1,3 @@
-export type BoardNavRenderProps = {
-    canGoBack: boolean;
-    canGoForward: boolean;
-    onBack: () => void;
-    onForward: () => void;
-};
-export declare const DefaultBoardNav: ({ canGoBack, canGoForward, onBack, onForward, }: BoardNavRenderProps) => import("react").JSX.Element;
+import type { BoardNavRenderProps } from "../core/renderProps";
+export declare const DefaultBoardNav: ({ canGoBack, canGoForward, onBack, onForward, onFlipBoard, }: BoardNavRenderProps) => import("react").JSX.Element;
 export declare const defaultRenderBoardNav: (props: BoardNavRenderProps) => import("react").JSX.Element;

package/dist/features/explorer/components/PositionGamesPanel.d.ts

@@ -2,16 +2,9 @@ import type { GameSource, PositionGameRowApiDto } from "../types";
 export type PositionGamesPanelProps = {
     games: PositionGameRowApiDto[];
     lineLabel: string;
-    minElo: number;
-    maxElo: number;
-    defaultMinElo: number;
-    defaultMaxElo: number;
-    topOnly: boolean;
+    lineSans: string[];
     sources: GameSource[];
-    onMinEloChange: (value: number) => void;
-    onMaxEloChange: (value: number) => void;
-    onTopOnlyChange: (value: boolean) => void;
     onSourcesChange: (sources: GameSource[]) => void;
     onGameSelect?: (game: PositionGameRowApiDto) => void;
 };
-export declare const PositionGamesPanel: ({ games, lineLabel, minElo, maxElo, defaultMinElo, defaultMaxElo, topOnly, sources, onMinEloChange, onMaxEloChange, onTopOnlyChange, onSourcesChange, onGameSelect, }: PositionGamesPanelProps) => import("react").JSX.Element;
+export declare const PositionGamesPanel: ({ games, lineLabel, lineSans: _lineSans, sources, onSourcesChange, onGameSelect, }: PositionGamesPanelProps) => import("react").JSX.Element;

package/dist/features/explorer/core/PositionReferenceExplorerCore.d.ts

@@ -1,2 +1,2 @@
 import type { PositionReferenceExplorerCoreProps } from "./renderProps";
-export declare const PositionReferenceExplorerCore: ({ fen: fenProp, onFenChange, initialLineSans, onLineSansChange, fetchPosition, fetchPositionGames, fetchPositionVariations, theme, boardWidth, defaultMinElo, defaultMaxElo, fillHeight, layoutMinHeight, renderLayout, renderStatus, renderMoveStats, renderVariationsStrip, renderGamesPanel, renderBoardNav, onGameSelect, }: PositionReferenceExplorerCoreProps) => import("react").JSX.Element;
+export declare const PositionReferenceExplorerCore: ({ fen: fenProp, onFenChange, initialLineSans, onLineSansChange, fetchPosition, fetchPositionGames, fetchPositionVariations, theme, boardTheme, boardWidth, boardOrientation: boardOrientationProp, defaultBoardOrientation, onBoardOrientationChange, fillHeight, layoutMinHeight, renderLayout, renderStatus, renderMoveStats, renderVariationsStrip, renderGamesPanel, renderBoardNav, onGameSelect, keyboardNav, }: PositionReferenceExplorerCoreProps) => import("react").JSX.Element;

package/dist/features/explorer/core/renderProps.d.ts

@@ -1,16 +1,19 @@
 import type { ReactNode } from "react";
-import type { FetchPositionGamesParams, FetchPositionVariationsParams, GameSource, PositionApiDto, PositionGameRowApiDto, PositionGamesApiDto, PositionMoveApiDto, PositionVariationLineApiDto, PositionVariationsApiDto } from "../types";
-import type { VariationsTab } from "../variationLines";
+import type { FetchPositionGamesParams, FetchPositionParams, FetchPositionVariationsParams, GameSource, PositionApiDto, PositionGameRowApiDto, PositionGamesApiDto, PositionMoveApiDto, PositionVariationLineApiDto, PositionVariationsApiDto } from "../types";
+import type { BoardThemeId } from "react-chess-core";
 export type ReferenceLayoutRenderProps = {
     theme: "light" | "dark";
     board: ReactNode;
     referencePanel: ReactNode;
 };
+export type BoardOrientation = "white" | "black";
 export type BoardNavRenderProps = {
     canGoBack: boolean;
     canGoForward: boolean;
     onBack: () => void;
     onForward: () => void;
+    boardOrientation: BoardOrientation;
+    onFlipBoard: () => void;
 };
 export type ExplorerStatusRenderProps = {
     error: string | null;
@@ -28,23 +31,15 @@ export type LineHeaderRenderProps = {
 export type GamesPanelRenderProps = {
     games: PositionGameRowApiDto[];
     lineLabel: string;
-    minElo: number;
-    maxElo: number;
-    defaultMinElo: number;
-    defaultMaxElo: number;
-    topOnly: boolean;
+    lineSans: string[];
+    loading?: boolean;
     sources: GameSource[];
-    onMinEloChange: (value: number) => void;
-    onMaxEloChange: (value: number) => void;
-    onTopOnlyChange: (value: boolean) => void;
     onSourcesChange: (sources: GameSource[]) => void;
     /** Start replay training for a database game from the current board FEN. */
     onGameSelect?: (game: PositionGameRowApiDto) => void;
 };
 export type VariationsStripRenderProps = {
     theme: "light" | "dark";
-    tab: VariationsTab;
-    onTabChange: (tab: VariationsTab) => void;
     lines: PositionVariationLineApiDto[];
     loading: boolean;
     selectedLineKey?: string;
@@ -58,13 +53,20 @@ export type PositionReferenceExplorerCoreProps = {
     initialLineSans?: string[];
     /** Fired after mount when the played SAN line changes (back/forward/new move). */
     onLineSansChange?: (lineSans: string[]) => void;
-    fetchPosition: (fen: string) => Promise<PositionApiDto | null>;
+    fetchPosition: (params: FetchPositionParams) => Promise<PositionApiDto | null>;
     fetchPositionGames: (params: FetchPositionGamesParams) => Promise<PositionGamesApiDto>;
     fetchPositionVariations: (params: FetchPositionVariationsParams) => Promise<PositionVariationsApiDto | null>;
     theme?: "light" | "dark";
+    boardTheme?: BoardThemeId;
+    /** Reserved for board move sounds (wired when react-chess-core supports it). */
+    boardSoundsEnabled?: boolean;
     boardWidth?: number;
-    defaultMinElo?: number;
-    defaultMaxElo?: number;
+    /** Controlled board orientation. When omitted, orientation is managed internally. */
+    boardOrientation?: BoardOrientation;
+    /** Initial orientation when uncontrolled. Defaults to white. */
+    defaultBoardOrientation?: BoardOrientation;
+    /** Fired when the user flips the board (controlled or uncontrolled). */
+    onBoardOrientationChange?: (orientation: BoardOrientation) => void;
     /** When true, shell uses full viewport height (no extra content below the grid). */
     fillHeight?: boolean;
     layoutMinHeight?: string;
@@ -76,4 +78,9 @@ export type PositionReferenceExplorerCoreProps = {
     renderBoardNav?: (props: BoardNavRenderProps) => ReactNode;
     /** When set, games panel can launch per-game replay training. */
     onGameSelect?: (game: PositionGameRowApiDto) => void;
+    /**
+     * Register ArrowLeft/ArrowRight/Home/End shortcuts while the explorer is mounted.
+     * Default true.
+     */
+    keyboardNav?: boolean;
 };

package/dist/features/explorer/defaults/DefaultReferencePanel.d.ts

@@ -1,10 +1,11 @@
 import type { ReactNode } from "react";
 export type DefaultReferencePanelProps = {
     theme: "light" | "dark";
+    fillHeight?: boolean;
     status: ReactNode;
     moveStats: ReactNode;
     variationsStrip: ReactNode;
     gamesPanel: ReactNode;
 };
 /** Right column shell: tab bar + stacked sections (no page footer below). */
-export declare const DefaultReferencePanel: ({ theme, status, moveStats, variationsStrip, gamesPanel, }: DefaultReferencePanelProps) => import("react").JSX.Element;
+export declare const DefaultReferencePanel: ({ theme, fillHeight, status, moveStats, variationsStrip, gamesPanel, }: DefaultReferencePanelProps) => import("react").JSX.Element;

package/dist/features/explorer/defaults/DefaultVariationsStrip.d.ts

@@ -1,3 +1,3 @@
 import type { VariationsStripRenderProps } from "../core/renderProps";
-export declare const DefaultVariationsStrip: ({ theme, tab, onTabChange, lines, loading, selectedLineKey, forwardSans, onLineSelect, }: VariationsStripRenderProps) => import("react").JSX.Element;
+export declare const DefaultVariationsStrip: ({ theme, lines, loading, selectedLineKey, forwardSans, onLineSelect, }: VariationsStripRenderProps) => import("react").JSX.Element;
 export declare const defaultRenderVariationsStrip: (props: VariationsStripRenderProps) => import("react").JSX.Element;

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

@@ -0,0 +1,15 @@
+import type { FetchPositionGamesParams, PositionGamesApiDto, PositionVariationLineApiDto } from "./types";
+export declare const EXPLORER_PREFETCH_CHILD_COUNT = 4;
+export declare const EXPLORER_DEFAULT_VARIATION_LINE_COUNT = 8;
+export declare const EXPLORER_DEFAULT_VARIATION_DEPTH = 4;
+export declare function gamesSessionKey(params: FetchPositionGamesParams): string;
+export declare function variationsSessionKey(fen: string, lineCount?: number, lineDepth?: number): string;
+type SessionCacheListener = () => void;
+export declare function subscribeExplorerSessionCache(listener: SessionCacheListener): () => void;
+export declare function peekSessionGames(key: string): PositionGamesApiDto | undefined;
+export declare function setSessionGames(key: string, data: PositionGamesApiDto): void;
+export declare function peekSessionVariations(key: string): PositionVariationLineApiDto[] | undefined;
+export declare function setSessionVariations(key: string, lines: PositionVariationLineApiDto[]): void;
+/** @internal Test-only: drop in-memory session caches. */
+export declare function clearExplorerSessionCacheForTests(): void;
+export {};

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

@@ -0,0 +1,11 @@
+import type { FetchPositionGamesParams, FetchPositionVariationsParams, GameSource, PositionGamesApiDto, PositionMoveApiDto, PositionVariationsApiDto } from "../types";
+export type UseExplorerPrefetchOptions = {
+    fen: string;
+    moves: PositionMoveApiDto[];
+    positionReady: boolean;
+    sources: GameSource[];
+    fetchPositionGames: (params: FetchPositionGamesParams) => Promise<PositionGamesApiDto>;
+    fetchPositionVariations?: (params: FetchPositionVariationsParams) => Promise<PositionVariationsApiDto | null>;
+    childCount?: number;
+};
+export declare function useExplorerPrefetch({ fen, moves, positionReady, sources, fetchPositionGames, fetchPositionVariations, childCount, }: UseExplorerPrefetchOptions): void;

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

@@ -3,17 +3,28 @@ export type PositionHistoryEntry = {
     /** SAN of the move played from the previous entry to reach this FEN. */
     lastSan?: string;
 };
-export declare function usePositionHistory(initialFen: string): {
+export declare function initialHistoryState(initialFen: string, initialLineSans?: string[]): {
+    history: PositionHistoryEntry[];
+    historyIndex: number;
+};
+export declare function usePositionHistory(initialFen: string, initialLineSans?: string[]): {
     canGoBack: boolean;
     canGoForward: boolean;
     lineSans: string[];
     forwardSans: string[];
+    currentFen: string;
     pushEntry: (fen: string, lastSan?: string) => PositionHistoryEntry;
     pushEntries: (entries: {
         fen: string;
         lastSan: string;
     }[]) => void;
+    replaceLineEntries: (startFen: string, entries: {
+        fen: string;
+        lastSan: string;
+    }[]) => void;
     goBack: () => PositionHistoryEntry | null;
     goForward: () => PositionHistoryEntry | null;
+    goFirst: () => PositionHistoryEntry | null;
+    goLast: () => PositionHistoryEntry | null;
     resetHistory: (fen: string) => PositionHistoryEntry;
 };

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

@@ -1,43 +1,40 @@
-import { type FetchPositionGamesParams, type GameSource, type PositionApiDto, type PositionGamesApiDto, type PositionMoveApiDto } from "../types";
+import { type FetchPositionGamesParams, type FetchPositionParams, type FetchPositionVariationsParams, type GameSource, type PositionApiDto, type PositionGamesApiDto, type PositionMoveApiDto, type PositionVariationsApiDto } from "../types";
 import type { PositionVariationLineApiDto } from "../types";
-import type { VariationsTab } from "../variationLines";
 export type UsePositionReferenceDataOptions = {
     fenProp?: string;
     onFenChange?: (fen: string) => void;
     initialLineSans?: string[];
     onLineSansChange?: (lineSans: string[]) => void;
-    fetchPosition: (fen: string) => Promise<PositionApiDto | null>;
+    fetchPosition: (params: FetchPositionParams) => Promise<PositionApiDto | null>;
     fetchPositionGames: (params: FetchPositionGamesParams) => Promise<PositionGamesApiDto>;
-    defaultMinElo: number;
-    defaultMaxElo: number;
+    fetchPositionVariations?: (params: FetchPositionVariationsParams) => Promise<PositionVariationsApiDto | null>;
 };
-export declare function usePositionReferenceData({ fenProp, onFenChange, initialLineSans, onLineSansChange, fetchPosition, fetchPositionGames, defaultMinElo, defaultMaxElo, }: UsePositionReferenceDataOptions): {
+export declare function usePositionReferenceData({ fenProp, onFenChange, initialLineSans, onLineSansChange, fetchPosition, fetchPositionGames, fetchPositionVariations, }: UsePositionReferenceDataOptions): {
     fen: string;
     boardFen: string;
     position: PositionApiDto | null;
     games: PositionGamesApiDto | null;
     gamesMoveFilterUci: string | undefined;
-    minElo: number;
-    maxElo: number;
-    topOnly: boolean;
     sources: GameSource[];
+    lineSans: string[];
     loading: boolean;
+    showPositionLoading: boolean;
+    gamesLoading: boolean;
+    positionReady: boolean;
+    displayMoves: PositionMoveApiDto[];
     error: string | null;
     lineLabel: string;
     canGoBack: boolean;
     canGoForward: boolean;
-    variationsTab: VariationsTab;
     forwardSans: string[];
     selectedVariationKey: string | undefined;
-    setMinElo: import("react").Dispatch<import("react").SetStateAction<number>>;
-    setMaxElo: import("react").Dispatch<import("react").SetStateAction<number>>;
-    setTopOnly: import("react").Dispatch<import("react").SetStateAction<boolean>>;
     setSources: import("react").Dispatch<import("react").SetStateAction<GameSource[]>>;
-    setVariationsTab: import("react").Dispatch<import("react").SetStateAction<VariationsTab>>;
     setGamesMoveFilterUci: import("react").Dispatch<import("react").SetStateAction<string | undefined>>;
     handleMoveSelect: (move: PositionMoveApiDto) => void;
     handleLineSelect: (line: PositionVariationLineApiDto) => void;
     handlePieceDrop: (sourceSquare: string, targetSquare: string, piece: string) => boolean;
     handleBack: () => void;
     handleForward: () => void;
+    handleFirst: () => void;
+    handleLast: () => void;
 };

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

@@ -1,16 +1,12 @@
 import type { FetchPositionVariationsParams, PositionVariationLineApiDto, PositionVariationsApiDto } from "../types";
-import type { VariationsTab } from "../variationLines";
 export type UseVariationLinesOptions = {
     fen: string;
-    tab: VariationsTab;
-    minElo: number;
-    maxElo: number;
     fetchPositionVariations: (params: FetchPositionVariationsParams) => Promise<PositionVariationsApiDto | null>;
     lineCount?: number;
     lineDepth?: number;
     enabled?: boolean;
 };
-export declare function useVariationLines({ fen, tab, minElo, maxElo, fetchPositionVariations, lineCount, lineDepth, enabled, }: UseVariationLinesOptions): {
+export declare function useVariationLines({ fen, fetchPositionVariations, lineCount, lineDepth, enabled, }: UseVariationLinesOptions): {
     lines: PositionVariationLineApiDto[];
     loading: boolean;
 };

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

@@ -1,16 +1,17 @@
 export { EXPLORER_START_FEN } from "./constants";
+export { seedExplorerStartSession } from "./seedExplorerStartSession";
+export { EXPLORER_DEFAULT_VARIATION_DEPTH, EXPLORER_DEFAULT_VARIATION_LINE_COUNT, EXPLORER_PREFETCH_CHILD_COUNT, gamesSessionKey, peekSessionGames, peekSessionVariations, setSessionGames, setSessionVariations, subscribeExplorerSessionCache, variationsSessionKey, } from "./explorerSessionCache";
 export { ExplorerPlaceholder, type ExplorerPlaceholderProps, } from "./ExplorerPlaceholder";
 export { PositionReferenceExplorer, type PositionReferenceExplorerProps, } from "./PositionReferenceExplorer";
 export { PositionReferenceExplorerCore } from "./core/PositionReferenceExplorerCore";
 export type { PositionReferenceExplorerCoreProps, ReferenceLayoutRenderProps, ExplorerStatusRenderProps, MoveStatsRenderProps, GamesPanelRenderProps, VariationsStripRenderProps, BoardNavRenderProps, } from "./core/renderProps";
-export type { VariationsTab } from "./variationLines";
 export { DEFAULT_REFERENCE_LAYOUT, DefaultReferenceLayout, DefaultReferencePanel, DefaultVariationsStrip, defaultRenderLayout, defaultRenderStatus, defaultRenderMoveStats, defaultRenderGamesPanel, defaultRenderVariationsStrip, defaultRenderBoardNav, DefaultBoardNav, } from "./defaults";
 export type { ReferenceLayoutConfig } from "./referenceLayout";
 export { GameReplayTrainer, type GameReplayTrainerProps, } from "./GameReplayTrainer";
 export { useGameReplayTraining } from "./hooks/useGameReplayTraining";
-export type { GameSource, PositionApiDto, PositionGamesApiDto, PositionGameRowApiDto, PositionMoveApiDto, PositionVariationLineApiDto, PositionVariationsApiDto, FetchPositionGamesParams, FetchPositionVariationsParams, ExplorerGameReplayApiDto, } from "./types";
+export type { GameSource, PositionApiDto, PositionGamesApiDto, PositionGameRowApiDto, PositionMoveApiDto, PositionVariationLineApiDto, PositionVariationsApiDto, FetchPositionParams, FetchPositionGamesParams, FetchPositionVariationsParams, ExplorerGameReplayApiDto, } from "./types";
 export { ALL_GAME_SOURCES } from "./types";
 export { mockFetchPosition, mockFetchPositionGames, mockFetchPositionVariations, } from "./mocks";
-export { applyLineSans, fenAfterUci, normalizeFen, whiteScorePercent, } from "./positionUtils";
+export { applyLineSans, fenAfterUci, formatNumberedLineSans, normalizeFen, whiteScorePercent, } from "./positionUtils";
 export { isVariationLineActive } from "./variationLines";
 export { findPlyIndexForFen, fenAtPly } from "./gameReplayUtils";

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

@@ -1,4 +1,4 @@
-import type { FetchPositionGamesParams, FetchPositionVariationsParams, PositionApiDto, PositionGamesApiDto, PositionVariationsApiDto } from "./types";
-export declare function mockFetchPosition(fen: string): Promise<PositionApiDto | null>;
+import type { FetchPositionGamesParams, FetchPositionParams, FetchPositionVariationsParams, PositionApiDto, PositionGamesApiDto, PositionVariationsApiDto } from "./types";
+export declare function mockFetchPosition(params: FetchPositionParams): Promise<PositionApiDto | null>;
 export declare function mockFetchPositionVariations(params: FetchPositionVariationsParams): Promise<PositionVariationsApiDto | null>;
 export declare function mockFetchPositionGames(params: FetchPositionGamesParams): Promise<PositionGamesApiDto>;

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

@@ -19,3 +19,5 @@ export declare function applyLineSans(startFen: string, sans: string[]): {
 /** Apply a UCI move to a FEN; returns null if illegal. */
 export declare function fenAfterUci(fen: string, uci: string): string | null;
 export declare function whiteScorePercent(whiteWins: number, draws: number, blackWins: number): number | null;
+/** Format SAN plies from the starting position as `1.d4 Nf6 2.c4 e6`. */
+export declare function formatNumberedLineSans(sans: string[]): string;

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

@@ -0,0 +1,3 @@
+import type { PositionGamesApiDto, PositionVariationsApiDto } from "./types";
+/** Push start-hub payloads into the explorer session cache (used by app preload). */
+export declare function seedExplorerStartSession(games: PositionGamesApiDto, variations: PositionVariationsApiDto): void;

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

@@ -37,19 +37,22 @@ export type PositionGameRowApiDto = {
 export type PositionGamesApiDto = {
     positionKey: string;
     fen: string;
-    minElo: number;
-    maxElo: number;
     uci?: string;
-    topOnly: boolean;
+    offset: number;
+    hasMore: boolean;
     games: PositionGameRowApiDto[];
 };
+export type FetchPositionParams = {
+    fen: string;
+    minElo?: number;
+    maxElo?: number;
+    sources?: GameSource[];
+};
 export type FetchPositionGamesParams = {
     fen: string;
-    minElo: number;
-    maxElo: number;
     uci?: string;
-    topOnly: boolean;
     limit?: number;
+    offset?: number;
     sources?: GameSource[];
 };
 /** Align with endchess-backend GET /positions/variations */
@@ -69,15 +72,15 @@ export type PositionVariationsApiDto = {
     mode: "variations" | "popularity";
     depth: number;
     lineCount: number;
-    minElo: number;
-    maxElo: number;
+    minElo?: number;
+    maxElo?: number;
     lines: PositionVariationLineApiDto[];
 };
 export type FetchPositionVariationsParams = {
     fen: string;
     mode: "variations" | "popularity";
-    minElo: number;
-    maxElo: number;
+    minElo?: number;
+    maxElo?: number;
     depth?: number;
     lineCount?: number;
 };

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

@@ -1,5 +1,4 @@
 import type { PositionVariationLineApiDto } from "./types";
-export type VariationsTab = "variations" | "popularity" | "endgames";
 /** @deprecated Use PositionVariationLineApiDto from ./types */
 export type PositionVariationLine = PositionVariationLineApiDto;
 export declare function isVariationLineActive(line: PositionVariationLineApiDto, selectedLineKey?: string, forwardSans?: string[]): boolean;