react-chess-explorer 0.0.1

package/LICENSE

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

package/README.md

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

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

@@ -0,0 +1,10 @@
+export type ExplorerPlaceholderProps = {
+    theme?: "light" | "dark";
+    /** Pixel width of the board. */
+    boardWidth?: number;
+};
+/**
+ * Scaffold UI — proves core wiring and Rollup build.
+ * Replace with game replay once requirements are defined.
+ */
+export declare const ExplorerPlaceholder: ({ theme, boardWidth, }: ExplorerPlaceholderProps) => import("react").JSX.Element;

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

@@ -0,0 +1,21 @@
+import type { ReactNode } from "react";
+import type { ExplorerGameReplayApiDto } from "./types";
+export type GameReplayTrainerProps = {
+    gameId: string;
+    startFen: string;
+    fetchGame: (gameId: string) => Promise<ExplorerGameReplayApiDto | null>;
+    onExit?: () => void;
+    theme?: "light" | "dark";
+    boardWidth?: number;
+    renderStatus?: (props: {
+        loading: boolean;
+        error: string | null;
+        complete: boolean;
+        feedback: "correct" | "incorrect" | null;
+        lastExpectedSan: string | null;
+        plyIndex: number;
+        totalPlies: number;
+        game: ExplorerGameReplayApiDto | null;
+    }) => ReactNode;
+};
+export declare const GameReplayTrainer: ({ gameId, startFen, fetchGame, onExit, theme, boardWidth, renderStatus, }: GameReplayTrainerProps) => import("react").JSX.Element;

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

@@ -0,0 +1,4 @@
+import type { PositionReferenceExplorerCoreProps } from "./core/renderProps";
+export type PositionReferenceExplorerProps = PositionReferenceExplorerCoreProps;
+/** Reference explorer with library default layout and renderers (ChessBase-style grid). */
+export declare const PositionReferenceExplorer: (props: PositionReferenceExplorerProps) => import("react").JSX.Element;

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

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

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

@@ -0,0 +1,9 @@
+export type EloRangeFilterProps = {
+    minElo: number;
+    maxElo: number;
+    defaultMinElo: number;
+    defaultMaxElo: number;
+    onMinEloChange: (value: number) => void;
+    onMaxEloChange: (value: number) => void;
+};
+export declare const EloRangeFilter: ({ minElo, maxElo, defaultMinElo, defaultMaxElo, onMinEloChange, onMaxEloChange, }: EloRangeFilterProps) => import("react").JSX.Element;

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

@@ -0,0 +1,5 @@
+export type ExplorerStatusBannerProps = {
+    error: string | null;
+    loading: boolean;
+};
+export declare const ExplorerStatusBanner: ({ error, loading, }: ExplorerStatusBannerProps) => import("react").JSX.Element | null;

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

@@ -0,0 +1,6 @@
+import type { PositionGameRowApiDto } from "../types";
+export type GamesTableProps = {
+    games: PositionGameRowApiDto[];
+    onGameSelect?: (game: PositionGameRowApiDto) => void;
+};
+export declare const GamesTable: ({ games, onGameSelect }: GamesTableProps) => import("react").JSX.Element;

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

@@ -0,0 +1,4 @@
+export type LineHeaderProps = {
+    label: string;
+};
+export declare const LineHeader: ({ label }: LineHeaderProps) => import("react").JSX.Element | null;

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

@@ -0,0 +1,7 @@
+import type { PositionMoveApiDto } from "../types";
+export type MoveStatsTableProps = {
+    moves: PositionMoveApiDto[];
+    selectedUci?: string;
+    onMoveSelect: (move: PositionMoveApiDto) => void;
+};
+export declare const MoveStatsTable: ({ moves, selectedUci, onMoveSelect, }: MoveStatsTableProps) => import("react").JSX.Element;

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

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

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

@@ -0,0 +1,26 @@
+import type { CSSProperties } from "react";
+export declare const panelStyle: CSSProperties;
+export declare const tableStyle: CSSProperties;
+export declare const thStyle: CSSProperties;
+export declare const tdStyle: CSSProperties;
+export declare const sectionTitleStyle: CSSProperties;
+/** Full-width shell: board | reference — no wrap, no footer below. */
+export declare const referenceShellStyle: CSSProperties;
+export declare const boardColumnStyle: CSSProperties;
+export declare const boardNavStyle: CSSProperties;
+export declare const boardNavButtonStyle: CSSProperties;
+export declare const referencePanelStyle: CSSProperties;
+export declare const referenceTabBarStyle: CSSProperties;
+export declare const referenceTabLabelStyle: CSSProperties;
+export declare const moveStatsSectionStyle: CSSProperties;
+export declare const variationsStripStyle: CSSProperties;
+export declare const variationsTabStyle: CSSProperties;
+export declare const gamesSectionStyle: CSSProperties;
+export declare const gamesHeaderStyle: CSSProperties;
+export declare const gamesScrollStyle: CSSProperties;
+export declare const gamesToolbarStyle: CSSProperties;
+export declare const statusInlineStyle: CSSProperties;
+/** @deprecated Use referenceShellStyle — kept for ExplorerPlaceholder */
+export declare const layoutStyle: CSSProperties;
+/** @deprecated Use referencePanelStyle */
+export declare const sidebarStyle: CSSProperties;

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

@@ -0,0 +1,4 @@
+/** Standard start position — placeholder until game replay is implemented. */
+export declare 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. */
+export declare const VARIATION_LINE_STEP_MS = 500;

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

@@ -0,0 +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;

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

@@ -0,0 +1,77 @@
+import type { ReactNode } from "react";
+import type { FetchPositionGamesParams, FetchPositionVariationsParams, PositionApiDto, PositionGameRowApiDto, PositionGamesApiDto, PositionMoveApiDto, PositionVariationLineApiDto, PositionVariationsApiDto } from "../types";
+import type { VariationsTab } from "../variationLines";
+export type ReferenceLayoutRenderProps = {
+    theme: "light" | "dark";
+    board: ReactNode;
+    referencePanel: ReactNode;
+};
+export type BoardNavRenderProps = {
+    canGoBack: boolean;
+    canGoForward: boolean;
+    onBack: () => void;
+    onForward: () => void;
+};
+export type ExplorerStatusRenderProps = {
+    error: string | null;
+    loading: boolean;
+};
+export type MoveStatsRenderProps = {
+    moves: PositionMoveApiDto[];
+    selectedUci?: string;
+    onMoveSelect: (move: PositionMoveApiDto) => void;
+};
+export type LineHeaderRenderProps = {
+    label: string;
+    gameCount: number;
+};
+export type GamesPanelRenderProps = {
+    games: PositionGameRowApiDto[];
+    lineLabel: string;
+    minElo: number;
+    maxElo: number;
+    defaultMinElo: number;
+    defaultMaxElo: number;
+    topOnly: boolean;
+    onMinEloChange: (value: number) => void;
+    onMaxEloChange: (value: number) => void;
+    onTopOnlyChange: (value: boolean) => 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;
+    forwardSans: string[];
+    onLineSelect: (line: PositionVariationLineApiDto) => void;
+};
+export type PositionReferenceExplorerCoreProps = {
+    fen?: string;
+    onFenChange?: (fen: string) => void;
+    /** Seed move history on mount (e.g. from URL). Applied from {@link EXPLORER_START_FEN}. */
+    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>;
+    fetchPositionGames: (params: FetchPositionGamesParams) => Promise<PositionGamesApiDto>;
+    fetchPositionVariations: (params: FetchPositionVariationsParams) => Promise<PositionVariationsApiDto | null>;
+    theme?: "light" | "dark";
+    boardWidth?: number;
+    defaultMinElo?: number;
+    defaultMaxElo?: number;
+    /** When true, shell uses full viewport height (no extra content below the grid). */
+    fillHeight?: boolean;
+    layoutMinHeight?: string;
+    renderLayout?: (props: ReferenceLayoutRenderProps) => ReactNode;
+    renderStatus?: (props: ExplorerStatusRenderProps) => ReactNode;
+    renderMoveStats?: (props: MoveStatsRenderProps) => ReactNode;
+    renderVariationsStrip?: (props: VariationsStripRenderProps) => ReactNode;
+    renderGamesPanel?: (props: GamesPanelRenderProps) => ReactNode;
+    renderBoardNav?: (props: BoardNavRenderProps) => ReactNode;
+    /** When set, games panel can launch per-game replay training. */
+    onGameSelect?: (game: PositionGameRowApiDto) => void;
+};

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

@@ -0,0 +1,3 @@
+import type { ReferenceLayoutRenderProps } from "../core/renderProps";
+export declare const DefaultReferenceLayout: ({ board, referencePanel, }: ReferenceLayoutRenderProps) => import("react").JSX.Element;
+export declare const defaultRenderLayout: (props: ReferenceLayoutRenderProps) => import("react").JSX.Element;

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

@@ -0,0 +1,10 @@
+import type { ReactNode } from "react";
+export type DefaultReferencePanelProps = {
+    theme: "light" | "dark";
+    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;

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

@@ -0,0 +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 defaultRenderVariationsStrip: (props: VariationsStripRenderProps) => import("react").JSX.Element;

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

@@ -0,0 +1,8 @@
+import { defaultRenderBoardNav } from "../components/DefaultBoardNav";
+import type { ExplorerStatusRenderProps, GamesPanelRenderProps, MoveStatsRenderProps } from "../core/renderProps";
+import { defaultRenderLayout } from "./DefaultReferenceLayout";
+import { defaultRenderVariationsStrip } from "./DefaultVariationsStrip";
+export { defaultRenderLayout, defaultRenderVariationsStrip, defaultRenderBoardNav, };
+export declare const defaultRenderStatus: (props: ExplorerStatusRenderProps) => import("react").JSX.Element;
+export declare const defaultRenderMoveStats: (props: MoveStatsRenderProps) => import("react").JSX.Element;
+export declare const defaultRenderGamesPanel: (props: GamesPanelRenderProps) => import("react").JSX.Element;

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

@@ -0,0 +1,7 @@
+export { DEFAULT_REFERENCE_LAYOUT } from "../referenceLayout";
+export type { ReferenceLayoutConfig } from "../referenceLayout";
+export { DefaultReferenceLayout, defaultRenderLayout, } from "./DefaultReferenceLayout";
+export { DefaultReferencePanel } from "./DefaultReferencePanel";
+export { DefaultVariationsStrip, defaultRenderVariationsStrip, } from "./DefaultVariationsStrip";
+export { defaultRenderBoardNav, defaultRenderGamesPanel, defaultRenderMoveStats, defaultRenderStatus, } from "./defaultRenderers";
+export { DefaultBoardNav } from "../components/DefaultBoardNav";

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

@@ -0,0 +1,6 @@
+import { Chess } from "chess.js";
+export declare function fenAtPly(movesUci: string[], ply: number): string;
+/** Index of the next move to play to reach `targetFen`, or 0 if not found. */
+export declare function findPlyIndexForFen(movesUci: string[], targetFen: string): number;
+export declare function applyUci(chess: Chess, uci: string): void;
+export declare function uciFromDrop(fen: string, sourceSquare: string, targetSquare: string, piece: string): string | null;

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

@@ -0,0 +1,22 @@
+import type { ExplorerGameReplayApiDto } from "../types";
+export type GameReplayFeedback = "correct" | "incorrect" | null;
+export type UseGameReplayTrainingOptions = {
+    gameId: string;
+    /** Board FEN when the user picked this game (explorer position). */
+    startFen: string;
+    fetchGame: (gameId: string) => Promise<ExplorerGameReplayApiDto | null>;
+};
+export declare function useGameReplayTraining({ gameId, startFen, fetchGame, }: UseGameReplayTrainingOptions): {
+    game: ExplorerGameReplayApiDto | null;
+    fen: string;
+    plyIndex: number;
+    totalPlies: number;
+    complete: boolean;
+    loading: boolean;
+    error: string | null;
+    feedback: GameReplayFeedback;
+    lastExpectedSan: string | null;
+    expectedSan: string | undefined;
+    handlePieceDrop: (sourceSquare: string, targetSquare: string, piece: string) => boolean;
+    revealMove: () => void;
+};

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

@@ -0,0 +1,19 @@
+export type PositionHistoryEntry = {
+    fen: string;
+    /** SAN of the move played from the previous entry to reach this FEN. */
+    lastSan?: string;
+};
+export declare function usePositionHistory(initialFen: string): {
+    canGoBack: boolean;
+    canGoForward: boolean;
+    lineSans: string[];
+    forwardSans: string[];
+    pushEntry: (fen: string, lastSan?: string) => PositionHistoryEntry;
+    pushEntries: (entries: {
+        fen: string;
+        lastSan: string;
+    }[]) => void;
+    goBack: () => PositionHistoryEntry | null;
+    goForward: () => PositionHistoryEntry | null;
+    resetHistory: (fen: string) => PositionHistoryEntry;
+};

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

@@ -0,0 +1,41 @@
+import type { FetchPositionGamesParams, PositionApiDto, PositionGamesApiDto, PositionMoveApiDto } 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>;
+    fetchPositionGames: (params: FetchPositionGamesParams) => Promise<PositionGamesApiDto>;
+    defaultMinElo: number;
+    defaultMaxElo: number;
+};
+export declare function usePositionReferenceData({ fenProp, onFenChange, initialLineSans, onLineSansChange, fetchPosition, fetchPositionGames, defaultMinElo, defaultMaxElo, }: UsePositionReferenceDataOptions): {
+    fen: string;
+    boardFen: string;
+    position: PositionApiDto | null;
+    games: PositionGamesApiDto | null;
+    gamesMoveFilterUci: string | undefined;
+    minElo: number;
+    maxElo: number;
+    topOnly: boolean;
+    loading: boolean;
+    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>>;
+    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;
+};

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

@@ -0,0 +1,16 @@
+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): {
+    lines: PositionVariationLineApiDto[];
+    loading: boolean;
+};

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

@@ -0,0 +1,15 @@
+export { EXPLORER_START_FEN } from "./constants";
+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 { PositionApiDto, PositionGamesApiDto, PositionGameRowApiDto, PositionMoveApiDto, PositionVariationLineApiDto, PositionVariationsApiDto, FetchPositionGamesParams, FetchPositionVariationsParams, ExplorerGameReplayApiDto, } from "./types";
+export { mockFetchPosition, mockFetchPositionGames, mockFetchPositionVariations, } from "./mocks";
+export { applyLineSans, fenAfterUci, normalizeFen, whiteScorePercent, } from "./positionUtils";
+export { isVariationLineActive } from "./variationLines";
+export { findPlyIndexForFen, fenAtPly } from "./gameReplayUtils";

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

@@ -0,0 +1,4 @@
+import type { FetchPositionGamesParams, FetchPositionVariationsParams, PositionApiDto, PositionGamesApiDto, PositionVariationsApiDto } from "./types";
+export declare function mockFetchPosition(fen: string): 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

@@ -0,0 +1,21 @@
+/** Match endchess-backend / mass-games-import (first four FEN fields). */
+export declare function normalizeFen(fen: string): string;
+export type BoardMoveResult = {
+    fen: string;
+    uci: string;
+    san: string;
+};
+/** Legal move from a board drag/drop (react-chessboard piece string, e.g. wQ). */
+export declare function applyBoardMove(fen: string, sourceSquare: string, targetSquare: string, piece: string): BoardMoveResult | null;
+export type LineSansEntry = {
+    fen: string;
+    lastSan: string;
+};
+/** Play a SAN sequence from a start FEN; returns null if any move is illegal. */
+export declare function applyLineSans(startFen: string, sans: string[]): {
+    fen: string;
+    entries: LineSansEntry[];
+} | null;
+/** 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;

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

@@ -0,0 +1,13 @@
+/** ChessBase Reference–style proportions: wide board column, narrower data column. */
+export type ReferenceLayoutConfig = {
+    /** Pixel width passed to HighlightChessboard (left column centers the board). */
+    boardWidth: number;
+    /** CSS grid track for the board column. */
+    boardColumn: string;
+    /** CSS grid track for the reference panel. */
+    referenceColumn: string;
+    columnGap: number;
+    /** Shell height when {@link PositionReferenceExplorerProps.fillHeight} is true. */
+    minHeight: string;
+};
+export declare const DEFAULT_REFERENCE_LAYOUT: ReferenceLayoutConfig;

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

@@ -0,0 +1,96 @@
+/** Align with endchess-backend GET /positions */
+export type PositionMoveApiDto = {
+    san: string;
+    uci: string;
+    games: number;
+    whiteWins: number;
+    draws: number;
+    blackWins: number;
+    avgElo: number | null;
+};
+export type PositionApiDto = {
+    positionKey: string;
+    fen: string;
+    totalGames: number;
+    moves: PositionMoveApiDto[];
+    sampleGameIds: string[];
+};
+/** Align with endchess-backend GET /positions/games */
+export type PositionGameRowApiDto = {
+    gameId: string;
+    url: string;
+    white: string;
+    black: string;
+    whiteElo: number;
+    blackElo: number;
+    result: string;
+    date?: string;
+    event?: string;
+    timeControl?: string;
+    timeClass?: string;
+    nextSan: string;
+    nextUci: string;
+    avgElo: number;
+};
+export type PositionGamesApiDto = {
+    positionKey: string;
+    fen: string;
+    minElo: number;
+    maxElo: number;
+    uci?: string;
+    topOnly: boolean;
+    games: PositionGameRowApiDto[];
+};
+export type FetchPositionGamesParams = {
+    fen: string;
+    minElo: number;
+    maxElo: number;
+    uci?: string;
+    topOnly: boolean;
+    limit?: number;
+};
+/** Align with endchess-backend GET /positions/variations */
+export type PositionVariationLineApiDto = {
+    key: string;
+    label: string;
+    moves: PositionMoveApiDto[];
+    uciPath: string[];
+    games: number;
+    scorePercent: number | null;
+    lastPlayedYear: number | null;
+    avgElo: number | null;
+};
+export type PositionVariationsApiDto = {
+    positionKey: string;
+    fen: string;
+    mode: "variations" | "popularity";
+    depth: number;
+    lineCount: number;
+    minElo: number;
+    maxElo: number;
+    lines: PositionVariationLineApiDto[];
+};
+export type FetchPositionVariationsParams = {
+    fen: string;
+    mode: "variations" | "popularity";
+    minElo: number;
+    maxElo: number;
+    depth?: number;
+    lineCount?: number;
+};
+/** Align with endchess-backend GET /positions/games/:gameId */
+export type ExplorerGameReplayApiDto = {
+    gameId: string;
+    url: string;
+    white: string;
+    black: string;
+    whiteElo: number;
+    blackElo: number;
+    result: string;
+    date?: string;
+    event?: string;
+    timeControl?: string;
+    timeClass?: string;
+    movesUci: string[];
+    movesSan: string[];
+};

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

@@ -0,0 +1,5 @@
+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;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Game browse / replay kit — depends on react-chess-core only (not puzzle-kit).
+ */
+export * from "./features/explorer";