react-chess-replay-trainer 0.0.1

package/README.md

@@ -0,0 +1,44 @@
+# react-chess-replay-trainer
+
+A React component for replaying a chess game move-by-move and drilling it.
+
+- **Browse** freely through the game (first / prev / next / last / jump) without
+  recording anything, so you can pick the part of the game you want to study.
+- **Train White / Train Black / Train Both** start a drill at the current ply:
+  you guess each move, and every mistake is reported via `onMiss` so the host can
+  (for example) enroll the missed position into a spaced-repetition deck.
+  - With **Train White** or **Train Black** you only guess that side's moves; the
+    opponent's reply is played automatically after each correct guess, and the
+    board is rotated so the trained side is on the bottom.
+  - With **Train Both** you drill every ply for both colors.
+- **Analyze** opens the built-in analysis board (`AnalysisBoard` from
+  `react-chess-core`) at the current position.
+
+Depends on `react-chess-core` (board, engine, analysis board), `react-chessboard`,
+and `chess.js`.
+
+## Usage
+
+```tsx
+import { ReplayTrainer } from 'react-chess-replay-trainer';
+
+<ReplayTrainer
+  gameId={gameId}
+  startFen={fenWhereUserWasBrowsing}
+  fetchGame={fetchGame}
+  onMiss={(miss) => enrollMissedPosition(miss)}
+  onExit={() => setTraining(null)}
+  theme="dark"
+  engine={{ depth: 18, multiPv: 3 }}
+/>;
+```
+
+For a custom shell, use `useReplayTrainer` with `AnalysisBoard` from the same package:
+
+```tsx
+import {
+  useReplayTrainer,
+  buildReplayAnalysisContext,
+  AnalysisBoard,
+} from 'react-chess-replay-trainer';
+```

package/dist/features/replay/ReplayTrainer.d.ts

@@ -0,0 +1,31 @@
+import { type ReactNode } from 'react';
+import { type AnalysisEngineOptions, type PlyNavigationRenderProps } from 'react-chess-core';
+import type { ReplayGame, ReplayMiss } from './types';
+export interface ReplayTrainerProps {
+    gameId: string;
+    fetchGame: (gameId: string) => Promise<ReplayGame | null>;
+    /** Position to open at; browse mode starts here. Defaults to the game start. */
+    startFen?: string;
+    /** Reported once per ply when the user plays the wrong move or reveals it. */
+    onMiss?: (miss: ReplayMiss) => void;
+    /** Called when a drill reaches the end of the game. */
+    onComplete?: () => void;
+    /** Called when the user leaves the trainer. */
+    onExit?: () => void;
+    theme?: 'light' | 'dark';
+    boardWidth?: number;
+    /** Side shown at the bottom of the board. Defaults to white. */
+    orientation?: 'white' | 'black';
+    /** Stockfish options for the built-in analysis board. Set `enabled: false` to hide engine lines. */
+    engine?: AnalysisEngineOptions;
+    /** Custom ply navigation UI (e.g. MUI). Omit for the core default with scrubber. */
+    renderPlyNavigation?: (props: PlyNavigationRenderProps) => ReactNode;
+    /** Range scrubber on ply navigation. Default true. */
+    showPlyScrubber?: boolean;
+}
+/**
+ * Browse a game freely, then drill it from any point. Browsing (first / prev /
+ * next / last / slider) never records anything; once the user hits "Train from
+ * here" each wrong move is reported through {@link ReplayTrainerProps.onMiss}.
+ */
+export declare const ReplayTrainer: ({ gameId, fetchGame, startFen, onMiss, onComplete, onExit, theme, boardWidth, orientation, engine, renderPlyNavigation, showPlyScrubber, }: ReplayTrainerProps) => import("react").JSX.Element;

package/dist/features/replay/analysis/ReplayAnalysisBoard.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+import { AnalysisEngineOptions } from 'react-chess-core';
+import { type UseReplayAnalysisBoardArgs } from './hooks/useReplayAnalysisBoard';
+import type { ReplayAnalysisContext } from './types';
+export declare const DEFAULT_ANALYSIS_BOARD_WIDTH = 400;
+export declare const DEFAULT_ANALYSIS_SIDEBAR_WIDTH = 280;
+export declare const DEFAULT_ANALYSIS_COLUMN_GAP = 16;
+export interface ReplayAnalysisBoardProps extends Omit<UseReplayAnalysisBoardArgs, 'boardWidth'> {
+    boardWidth?: number;
+    sidebarWidth?: number;
+    columnGap?: number;
+}
+/**
+ * Full-screen modal analysis board: draggable exploration, move list,
+ * variations, and Stockfish evaluation via react-chess-core.
+ */
+export declare const ReplayAnalysisBoard: ({ boardWidth, sidebarWidth, columnGap, ...modelArgs }: ReplayAnalysisBoardProps) => React.JSX.Element;
+export type { ReplayAnalysisContext, AnalysisEngineOptions };

package/dist/features/replay/analysis/ReplayAnalysisPosition.d.ts

@@ -0,0 +1,32 @@
+import type { ReplayAnalysisContext, ReplayAnalysisHistoryRow, ReplaySolutionMoveDisplay } from './types';
+export declare class ReplayAnalysisPosition {
+    private chess;
+    private readonly initialFen;
+    private readonly solutionMoves;
+    private readonly solutionSans;
+    private mainPly;
+    private variation;
+    private variationCursor;
+    constructor(context: ReplayAnalysisContext);
+    private static buildSolutionSans;
+    private fenAtMainPly;
+    private rebuildChess;
+    private findLegalMove;
+    private uciFromVerboseMove;
+    private matchesMainMove;
+    getNavPly(): number;
+    getMaxNavPly(): number;
+    getSolutionSans(): ReplaySolutionMoveDisplay[];
+    getHistoryRows(): ReplayAnalysisHistoryRow[];
+    isHistoryRowSelected(row: ReplayAnalysisHistoryRow): boolean;
+    selectHistoryRow(row: ReplayAnalysisHistoryRow): void;
+    selectMainLine(ply: number): void;
+    goToNavPly(navPly: number): void;
+    tryPlayMove(sourceSquare: string, targetSquare: string, piece: string): boolean;
+    getLastMoveSquares(): {
+        from: string;
+        to: string;
+    } | null;
+    fen(): string;
+    getCheckSquare(): string;
+}

package/dist/features/replay/analysis/ReplayEngineEvaluationPanel.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+import { type EngineEvaluation } from 'react-chess-core';
+export interface ReplayEngineEvaluationPanelProps {
+    fen: string;
+    evaluation: EngineEvaluation;
+    theme: 'light' | 'dark';
+}
+export declare const ReplayEngineEvaluationPanel: ({ fen, evaluation, theme, }: ReplayEngineEvaluationPanelProps) => React.JSX.Element;

package/dist/features/replay/analysis/analysisBoardStyles.d.ts

@@ -0,0 +1,63 @@
+export declare const analysisBoardHighlightColors: {
+    readonly lastMove: {
+        readonly light: "rgba(253, 216, 53, 0.55)";
+        readonly dark: "rgba(144, 202, 249, 0.5)";
+    };
+};
+export declare const getLastMoveSquareStyles: (from: string, to: string, theme: "light" | "dark") => Record<string, {
+    backgroundColor: string;
+}>;
+export declare const analysisSidebarColors: {
+    readonly activeMove: {
+        readonly light: "rgba(58, 123, 213, 0.25)";
+        readonly dark: "rgba(58, 123, 213, 0.35)";
+    };
+    readonly mainBand: {
+        readonly light: readonly ["rgba(0,0,0,0.02)", "rgba(0,0,0,0.05)"];
+        readonly dark: readonly ["rgba(255,255,255,0.03)", "rgba(255,255,255,0.06)"];
+    };
+    readonly variationBand: {
+        readonly light: readonly ["rgba(0,0,0,0.04)", "rgba(0,0,0,0.07)"];
+        readonly dark: readonly ["rgba(255,255,255,0.05)", "rgba(255,255,255,0.08)"];
+    };
+};
+export declare function getSidebarRowBackground(theme: 'light' | 'dark', row: {
+    kind: 'start' | 'main' | 'variation';
+}, bandCounters: {
+    main: number;
+    variation: number;
+}): string;
+export declare function createSidebarRowBandCounters(): {
+    main: number;
+    variation: number;
+};
+export declare const analysisModalColors: {
+    readonly light: {
+        readonly panel: {
+            readonly backgroundColor: "#fafafa";
+            readonly color: "#1a1a1a";
+        };
+        readonly title: {
+            readonly color: "#1a1a1a";
+        };
+        readonly closeButton: {
+            readonly backgroundColor: "#eee";
+            readonly border: "1px solid #ccc";
+            readonly color: "#333";
+        };
+    };
+    readonly dark: {
+        readonly panel: {
+            readonly backgroundColor: "#2a2a2a";
+            readonly color: "#e8e8e8";
+        };
+        readonly title: {
+            readonly color: "#e8e8e8";
+        };
+        readonly closeButton: {
+            readonly backgroundColor: "#3a3a3a";
+            readonly border: "1px solid #555";
+            readonly color: "#e8e8e8";
+        };
+    };
+};

package/dist/features/replay/analysis/buildReplayAnalysisContext.d.ts

@@ -0,0 +1,4 @@
+import type { ReplayGame } from '../types';
+import type { ReplayAnalysisContext } from './types';
+/** Build analysis context from the current replay browse position. */
+export declare function buildReplayAnalysisContext(game: ReplayGame, plyIndex: number, boardOrientation: 'white' | 'black'): ReplayAnalysisContext;

package/dist/features/replay/analysis/hooks/useReplayAnalysisBoard.d.ts

@@ -0,0 +1,34 @@
+import { AnalysisEngineOptions, EngineEvaluation } from 'react-chess-core';
+import type { ReplayAnalysisContext, ReplayAnalysisHistoryRow, ReplaySolutionMoveDisplay } from '../types';
+export type UseReplayAnalysisBoardArgs = {
+    analysisContext: ReplayAnalysisContext;
+    onClose: () => void;
+    theme: 'light' | 'dark';
+    boardWidth: number;
+    engine?: AnalysisEngineOptions;
+};
+export type ReplayAnalysisBoardModel = {
+    theme: 'light' | 'dark';
+    boardWidth: number;
+    analysisContext: ReplayAnalysisContext;
+    fen: string;
+    ply: number;
+    maxPly: number;
+    historyRows: ReplayAnalysisHistoryRow[];
+    solutionSans: ReplaySolutionMoveDisplay[];
+    boardOrientation: 'white' | 'black';
+    engineEvaluation: EngineEvaluation;
+    engineEnabled: boolean;
+    lastMove: {
+        from: string;
+        to: string;
+    } | null;
+    checkSquare: string | null;
+    onSelectPly: (ply: number) => void;
+    onSelectHistoryRow: (row: ReplayAnalysisHistoryRow) => void;
+    isHistoryRowSelected: (row: ReplayAnalysisHistoryRow) => boolean;
+    onPieceDrop: (sourceSquare: string, targetSquare: string, piece: string) => boolean;
+    onBackdropMouseDown: () => void;
+    onClose: () => void;
+};
+export declare function useReplayAnalysisBoard({ analysisContext, onClose, theme, boardWidth, engine, }: UseReplayAnalysisBoardArgs): ReplayAnalysisBoardModel;

package/dist/features/replay/analysis/index.d.ts

@@ -0,0 +1,6 @@
+export { ReplayAnalysisBoard, DEFAULT_ANALYSIS_BOARD_WIDTH, DEFAULT_ANALYSIS_SIDEBAR_WIDTH, DEFAULT_ANALYSIS_COLUMN_GAP, type ReplayAnalysisBoardProps, } from './ReplayAnalysisBoard';
+export { ReplayEngineEvaluationPanel } from './ReplayEngineEvaluationPanel';
+export { buildReplayAnalysisContext } from './buildReplayAnalysisContext';
+export { ReplayAnalysisPosition } from './ReplayAnalysisPosition';
+export { useReplayAnalysisBoard, type UseReplayAnalysisBoardArgs, type ReplayAnalysisBoardModel, } from './hooks/useReplayAnalysisBoard';
+export type { ReplayAnalysisContext, ReplayAnalysisHistoryRow, ReplaySolutionMoveDisplay, } from './types';

package/dist/features/replay/analysis/replayAnalysisUtils.d.ts

@@ -0,0 +1,3 @@
+import { Chess } from 'chess.js';
+export declare function tryApplyUci(chess: Chess, uci: string): boolean;
+export declare function getCheckSquareFromChess(chess: Chess): string;

package/dist/features/replay/analysis/types.d.ts

@@ -0,0 +1,22 @@
+/** Context for opening the replay analysis board at a point in the game. */
+export type ReplayAnalysisContext = {
+    initialFen: string;
+    /** Full game main line in UCI notation. */
+    solutionMoves: string[];
+    /** Ply index to open at (0 = start position). */
+    startPly: number;
+    boardOrientation: 'white' | 'black';
+};
+export type ReplayAnalysisHistoryRow = {
+    key: string;
+    label: string;
+    indent: number;
+    kind: 'start' | 'main' | 'variation';
+    mainPly: number;
+    variationIndex: number;
+};
+export type ReplaySolutionMoveDisplay = {
+    ply: number;
+    uci: string;
+    san: string;
+};

package/dist/features/replay/buildReplayAnalysisContext.d.ts

@@ -0,0 +1,4 @@
+import type { AnalysisContext } from 'react-chess-core';
+import type { ReplayGame } from './types';
+/** Build a core {@link AnalysisContext} for the current replay browse position. */
+export declare function buildReplayAnalysisContext(game: ReplayGame, plyIndex: number, boardOrientation: 'white' | 'black'): AnalysisContext;

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

@@ -0,0 +1,3 @@
+/** Standard chess starting position; game move lists replay from here. */
+export declare const REPLAY_START_FEN = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1";
+export declare const DEFAULT_BOARD_WIDTH = 480;

package/dist/features/replay/hooks/useReplayTrainer.d.ts

@@ -0,0 +1,43 @@
+import type { ReplayFeedback, ReplayGame, ReplayMiss, ReplayMode, ReplaySide, TrainColor } from '../types';
+export interface UseReplayTrainerOptions {
+    gameId: string;
+    /** Position to open at (browse mode starts here). Defaults to the start. */
+    startFen?: string;
+    fetchGame: (gameId: string) => Promise<ReplayGame | null>;
+    onMiss?: (miss: ReplayMiss) => void;
+    onComplete?: () => void;
+}
+export interface ReplayTrainerState {
+    game: ReplayGame | null;
+    loading: boolean;
+    error: string | null;
+    mode: ReplayMode;
+    /** Current FEN shown on the board. */
+    fen: string;
+    /** 0-based ply index = number of moves played from the start. */
+    plyIndex: number;
+    /** Total half-moves (plies) in the loaded game. */
+    totalPly: number;
+    complete: boolean;
+    sideToMove: ReplaySide;
+    /** Which side(s) the user is drilling. */
+    trainColor: TrainColor;
+    /** True when the side to move is the user's (i.e. they should guess now). */
+    isUserTurn: boolean;
+    feedback: ReplayFeedback;
+    /** Revealed/expected move at the current ply (set after a miss or reveal). */
+    expectedSan: string | null;
+    expectedUci: string | null;
+    canPrev: boolean;
+    canNext: boolean;
+    goFirst: () => void;
+    goPrev: () => void;
+    goNext: () => void;
+    goLast: () => void;
+    goTo: (ply: number) => void;
+    startTraining: (color?: TrainColor) => void;
+    stopTraining: () => void;
+    revealMove: () => void;
+    handleDrop: (source: string, target: string, piece: string) => boolean;
+}
+export declare function useReplayTrainer({ gameId, startFen, fetchGame, onMiss, onComplete, }: UseReplayTrainerOptions): ReplayTrainerState;

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

@@ -0,0 +1,7 @@
+export { ReplayTrainer, type ReplayTrainerProps } from './ReplayTrainer';
+export { useReplayTrainer, type UseReplayTrainerOptions, type ReplayTrainerState, } from './hooks/useReplayTrainer';
+export type { ReplayGame, ReplayMiss, ReplayMode, ReplayFeedback, ReplaySide, TrainColor, } from './types';
+export { REPLAY_START_FEN, DEFAULT_BOARD_WIDTH } from './constants';
+export { fenAtPly, findPlyIndexForFen, sideToMove, uciFromDrop, normalizeFen, } from './replayUtils';
+export { buildReplayAnalysisContext } from './buildReplayAnalysisContext';
+export { AnalysisBoard, AnalysisBoardCore, AnalysisErrorBoundary, DEFAULT_ANALYSIS_LAYOUT, DefaultPlyNavigation, PlyNavigation, defaultRenderPlyNavigation, type AnalysisContext, type AnalysisBoardProps, type AnalysisLayoutConfig, type PlyNavigationModel, type PlyNavigationProps, type PlyNavigationRenderProps, } from 'react-chess-core';

package/dist/features/replay/replayTrainerStyles.d.ts

@@ -0,0 +1,28 @@
+import type { CSSProperties } from 'react';
+import type { TrainColor } from './types';
+export type ReplayTheme = 'light' | 'dark';
+export type ReplayPalette = {
+    text: string;
+    subtle: string;
+    border: string;
+    surface: string;
+    primary: string;
+    success: string;
+    error: string;
+};
+export type ButtonVariant = 'primary' | 'ghost' | 'nav';
+export declare const TRAIN_COLOR_LABEL: Record<TrainColor, string>;
+export declare const columnStyle: CSSProperties;
+export declare const centerStyle: CSSProperties;
+export declare const headerStyle: CSSProperties;
+export declare const controlsRowStyle: CSSProperties;
+export declare const playerNameStyle: CSSProperties;
+export declare const feedbackContainerStyle: CSSProperties;
+export declare const customBoardStyle: CSSProperties;
+export declare function palette(theme: ReplayTheme): ReplayPalette;
+export declare function mainContainerStyle(boardWidth: number, colors: ReplayPalette): CSSProperties;
+export declare function centerContainerStyle(boardWidth: number, color: string): CSSProperties;
+export declare function subtleTextStyle(colors: ReplayPalette): CSSProperties;
+export declare function statusLineStyle(colors: ReplayPalette): CSSProperties;
+export declare function feedbackMessageStyle(colors: ReplayPalette, tone: 'success' | 'error'): CSSProperties;
+export declare function buttonStyle(colors: ReplayPalette, variant: ButtonVariant): CSSProperties;

package/dist/features/replay/replayUtils.d.ts

@@ -0,0 +1,12 @@
+import { Chess } from 'chess.js';
+import type { ReplaySide } from './types';
+/** Compare positions ignoring move clocks (first four FEN fields). */
+export declare function normalizeFen(fen: string): string;
+export declare function applyUci(chess: Chess, uci: string): void;
+/** FEN after applying the first `ply` moves from the standard start. */
+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 sideToMove(fen: string): ReplaySide;
+/** Resolve a board drag into a legal UCI string, or null when illegal. */
+export declare function uciFromDrop(fen: string, sourceSquare: string, targetSquare: string, piece: string): string | null;

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

@@ -0,0 +1,36 @@
+export type ReplaySide = 'w' | 'b';
+/** A game to replay/drill. Move lists are parallel (UCI + optional SAN). */
+export type ReplayGame = {
+    gameId?: string;
+    white?: string;
+    black?: string;
+    whiteElo?: number;
+    blackElo?: number;
+    result?: string;
+    timeControl?: string;
+    timeClass?: string;
+    movesUci: string[];
+    movesSan?: string[];
+};
+/** Reported when the user plays the wrong move (or reveals) during a drill. */
+export type ReplayMiss = {
+    /** 0-based ply index into {@link ReplayGame.movesUci}. */
+    index: number;
+    /** FEN of the missed position (the trainer is to move here). */
+    fen: string;
+    /** Correct move at this position. */
+    expectedUci: string;
+    expectedSan: string;
+    /** Side to move at {@link fen}. */
+    sideToMove: ReplaySide;
+    /** Opponent's prior ply that produced {@link fen}, when one exists. */
+    setupFen?: string;
+    setupUci?: string;
+};
+export type ReplayMode = 'browse' | 'train';
+export type ReplayFeedback = 'correct' | 'incorrect' | null;
+/**
+ * Which side the user drills. With a single color the opponent's replies are
+ * played automatically after each correct guess; `'both'` drills every ply.
+ */
+export type TrainColor = 'white' | 'black' | 'both';

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Replay a chess game move-by-move and drill it, reporting misses.
+ * Depends on react-chess-core only (not the puzzle kit or explorer).
+ */
+export * from './features/replay';