react-chess-core 0.1.0 → 0.1.2

package/README.md

@@ -7,6 +7,8 @@ npm run build
 
 Shared **chessboard** (theme + `HighlightChessboard`) and **browser Stockfish** utilities. Used by `react-chess-puzzle-kit` and (planned) `react-chess-explorer`.
 
+Used in production at [endchess.com](https://endchess.com).
+
 Storybook: `npm run storybook` → http://localhost:6007
 
 ---

package/dist/features/analysis/core/AnalysisBoardCore.d.ts

@@ -4,6 +4,11 @@ import { AnalysisEngineOptions } from '../../engine/types';
 import { AnalysisBoardModel, UseAnalysisBoardModelArgs } from './useAnalysisBoardModel';
 export type AnalysisBoardCoreProps = UseAnalysisBoardModelArgs & {
     engine?: AnalysisEngineOptions;
+    /**
+     * Register ArrowLeft/ArrowRight/Home/End shortcuts while analysis is open.
+     * Default true.
+     */
+    keyboardNav?: boolean;
     /** Host-owned shell (modal, page layout, etc.). */
     renderContainer: (props: AnalysisContainerRenderProps) => React.ReactNode;
     /** Host-owned grid/placement of board + sidebar (no library default). */
@@ -15,14 +20,15 @@ export type AnalysisBoardCoreProps = UseAnalysisBoardModelArgs & {
  * Analysis logic + composition only: hook, board node, sidebar/engine slots.
  * No layout divs — use {@link renderMain} (e.g. `AnalysisBoardLayout` from `analysis/defaults` or a host layout).
  */
-export declare const AnalysisBoardCore: ({ renderContainer, renderMain, renderSidebar, renderEngineEvaluation, ...modelArgs }: AnalysisBoardCoreProps) => React.JSX.Element;
+export declare const AnalysisBoardCore: ({ renderContainer, renderMain, renderSidebar, renderEngineEvaluation, keyboardNav, ...modelArgs }: AnalysisBoardCoreProps) => React.JSX.Element;
 type AnalysisBoardCoreViewProps = {
     model: AnalysisBoardModel;
+    keyboardNav: boolean;
     renderContainer: AnalysisBoardCoreProps['renderContainer'];
     renderMain: AnalysisBoardCoreProps['renderMain'];
     renderSidebar: AnalysisBoardCoreProps['renderSidebar'];
     renderEngineEvaluation: AnalysisBoardCoreProps['renderEngineEvaluation'];
 };
 /** Pure composition (no layout styles) for testing and reuse. */
-export declare const AnalysisBoardCoreView: ({ model, renderContainer, renderMain, renderSidebar, renderEngineEvaluation, }: AnalysisBoardCoreViewProps) => React.ReactNode;
+export declare const AnalysisBoardCoreView: ({ model, keyboardNav, renderContainer, renderMain, renderSidebar, renderEngineEvaluation, }: AnalysisBoardCoreViewProps) => React.ReactNode;
 export type { AnalysisBoardModel, UseAnalysisBoardModelArgs };

package/dist/features/chessboard/ChessboardDnDProvider.d.ts

@@ -0,0 +1,9 @@
+import type { ReactNode } from 'react';
+/**
+ * HTML5 for mouse (desktop + Chrome device emulation), touch backend for real
+ * mobile devices. react-chessboard alone picks TouchBackend whenever
+ * `ontouchstart` is in window, which breaks mouse drags in DevTools emulation.
+ */
+export declare const ChessboardDnDProvider: ({ children, }: {
+    children: ReactNode;
+}) => import("react").JSX.Element;

package/dist/features/chessboard/boardThemes.d.ts

@@ -0,0 +1,19 @@
+export declare const BOARD_THEME_IDS: readonly ["classic", "forest", "marine", "marble", "ivory", "ocean", "copper", "bubblegum", "sunset"];
+export type BoardThemeId = (typeof BOARD_THEME_IDS)[number];
+export type BoardThemeDefinition = {
+    label: string;
+    darkSquare: string;
+    lightSquare: string;
+};
+export declare const DEFAULT_BOARD_THEME: BoardThemeId;
+export declare const BOARD_THEMES: Record<BoardThemeId, BoardThemeDefinition>;
+export declare function isBoardThemeId(value: unknown): value is BoardThemeId;
+export declare function boardThemeFromLegacyUiTheme(_theme: 'light' | 'dark'): BoardThemeId;
+export declare function getBoardThemeStyles(boardTheme: BoardThemeId): {
+    customDarkSquareStyle: {
+        backgroundColor: string;
+    };
+    customLightSquareStyle: {
+        backgroundColor: string;
+    };
+};

package/dist/features/chessboard/chessboardTheme.d.ts

@@ -1,4 +1,5 @@
 import { ReactNode } from 'react';
+import { type BoardThemeId } from './boardThemes';
 interface ChessboardThemeContextType {
     customDarkSquareStyle: {
         backgroundColor: string;
@@ -11,6 +12,7 @@ export declare const ChessboardThemeContext: import("react").Context<ChessboardT
 export declare const useChessboardTheme: () => ChessboardThemeContextType;
 /** @deprecated Use {@link useChessboardTheme}. */
 export declare const useTheme: () => ChessboardThemeContextType;
+/** @deprecated Use {@link getBoardThemeStyles}. */
 export declare const getStylesForTheme: (theme: "light" | "dark") => {
     customDarkSquareStyle: {
         backgroundColor: string;
@@ -21,7 +23,9 @@ export declare const getStylesForTheme: (theme: "light" | "dark") => {
 };
 export type ThemeProviderProps = {
     children?: ReactNode;
-    theme: 'light' | 'dark';
+    /** UI chrome palette; used when `boardTheme` is omitted. */
+    theme?: 'light' | 'dark';
+    boardTheme?: BoardThemeId;
 };
-export declare const ThemeProvider: ({ children, theme }: ThemeProviderProps) => import("react").JSX.Element;
+export declare const ThemeProvider: ({ children, theme, boardTheme, }: ThemeProviderProps) => import("react").JSX.Element;
 export {};

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

@@ -1,3 +1,5 @@
+export * from './boardThemes';
 export * from './chessboardTheme';
+export * from './ChessboardDnDProvider';
 export * from './HighlightChessboard';
 export * from './boardSquareHighlightColors';

package/dist/features/engine/AnalysisEngineContext.d.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+import { AnalysisEngineOptions, EngineEvaluation } from './types';
+export type SubscriberOptions = {
+    fen: string;
+    enabled: boolean;
+    depth: number;
+    multiPv: number;
+    priority: number;
+};
+type AnalysisEngineContextValue = {
+    register: (options: SubscriberOptions, listener: (evaluation: EngineEvaluation) => void) => number;
+    update: (id: number, options: SubscriberOptions) => void;
+    unregister: (id: number) => void;
+};
+export declare const useAnalysisEngineContext: () => AnalysisEngineContextValue | null;
+export declare const normalizeSubscriberOptions: (fen: string, options?: AnalysisEngineOptions) => SubscriberOptions;
+export type AnalysisEngineProviderProps = {
+    scriptUrl?: string;
+    children: React.ReactNode;
+};
+export declare const AnalysisEngineProvider: ({ scriptUrl, children, }: AnalysisEngineProviderProps) => React.JSX.Element;
+export {};

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

@@ -4,4 +4,5 @@ export * from './formatEvaluation';
 export * from './parseUciInfo';
 export * from './StockfishBrowserEngine';
 export * from './isAnalyzableFen';
+export * from './AnalysisEngineContext';
 export * from './useAnalysisEngine';

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

@@ -23,5 +23,15 @@ export type AnalysisEngineOptions = {
     multiPv?: number;
     /** URL to stockfish-18-lite-single.js (host must serve .wasm alongside it). */
     scriptUrl?: string;
+    /**
+     * Higher priority wins when multiple hooks share an {@link AnalysisEngineProvider}.
+     * Default 0.
+     */
+    priority?: number;
+    /**
+     * When false, uses a dedicated worker even inside AnalysisEngineProvider
+     * (e.g. refutation comparing two positions at once).
+     */
+    shared?: boolean;
 };
 export declare const DEFAULT_STOCKFISH_SCRIPT_URL = "/stockfish/stockfish-18-lite-single.js";

package/dist/features/engine/useAnalysisEngine.d.ts

@@ -1,2 +1,4 @@
+import { AnalysisEngineProvider } from './AnalysisEngineContext';
 import { AnalysisEngineOptions, EngineEvaluation } from './types';
 export declare const useAnalysisEngine: (fen: string, options?: AnalysisEngineOptions) => EngineEvaluation;
+export { AnalysisEngineProvider };

package/dist/features/navigation/PlyNavigation.d.ts

@@ -3,4 +3,4 @@ import type { PlyNavigationProps } from './types';
  * Step through a fixed move list. Omit {@link PlyNavigationProps.renderPlyNavigation}
  * for the default inline-styled UI, or pass a custom renderer (e.g. MUI controls).
  */
-export declare const PlyNavigation: ({ plyIndex, totalPly, canPrev, canNext, onGoFirst, onGoPrev, onGoNext, onGoLast, onGoTo, theme, showScrubber, showPlyLabel, renderPlyNavigation, }: PlyNavigationProps) => import("react").ReactNode;
+export declare const PlyNavigation: ({ plyIndex, totalPly, canPrev, canNext, onGoFirst, onGoPrev, onGoNext, onGoLast, onGoTo, theme, keyboardNav, showScrubber, showPlyLabel, renderPlyNavigation, }: PlyNavigationProps) => import("react").ReactNode;

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

@@ -1,4 +1,6 @@
 export { PlyNavigation } from './PlyNavigation';
 export { DefaultPlyNavigation, defaultRenderPlyNavigation, } from './DefaultPlyNavigation';
+export { isEditableKeyboardTarget, type PositionKeyboardNavOptions, } from './positionKeyboardNav';
+export { usePositionKeyboardNav } from './usePositionKeyboardNav';
 export { navRowStyle, navButtonStyle, scrubberInputStyle, plyLabelStyle, palette as plyNavigationPalette, } from './plyNavigationStyles';
 export type { PlyNavigationModel, PlyNavigationProps, PlyNavigationRenderProps, PlyNavigationTheme, } from './types';

package/dist/features/navigation/positionKeyboardNav.d.ts

@@ -0,0 +1,12 @@
+/** True when the event target is a field where arrow keys should type, not navigate. */
+export declare function isEditableKeyboardTarget(target: EventTarget | null): boolean;
+export type PositionKeyboardNavOptions = {
+    /** When false, keyboard shortcuts are not registered. Default true. */
+    enabled?: boolean;
+    canPrev: boolean;
+    canNext: boolean;
+    onPrev: () => void;
+    onNext: () => void;
+    onFirst?: () => void;
+    onLast?: () => void;
+};

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

@@ -24,6 +24,11 @@ export type PlyNavigationRenderProps = PlyNavigationModel & {
 };
 export type PlyNavigationProps = PlyNavigationModel & {
     theme?: PlyNavigationTheme;
+    /**
+     * Register ArrowLeft/ArrowRight/Home/End shortcuts while this nav is mounted.
+     * Default true.
+     */
+    keyboardNav?: boolean;
     /** Range scrubber between prev/next. Default true. */
     showScrubber?: boolean;
     /**

package/dist/features/navigation/usePositionKeyboardNav.d.ts

@@ -0,0 +1,12 @@
+import { type PositionKeyboardNavOptions } from './positionKeyboardNav';
+/**
+ * Global keyboard shortcuts for browsing positions:
+ * - ArrowLeft: previous
+ * - ArrowRight: next
+ * - Home: first (when {@link PositionKeyboardNavOptions.onFirst} is provided)
+ * - End: last (when {@link PositionKeyboardNavOptions.onLast} is provided)
+ *
+ * Ignores keypresses while focus is in an input, textarea, select, or
+ * contenteditable element, and ignores modified keys (Alt/Ctrl/Meta).
+ */
+export declare function usePositionKeyboardNav({ enabled, canPrev, canNext, onPrev, onNext, onFirst, onLast, }: PositionKeyboardNavOptions): void;

package/dist/features/training/expectedMoveDrop.d.ts

@@ -0,0 +1,24 @@
+export type ExpectedMoveDropResult = {
+    kind: 'ignored';
+} | {
+    kind: 'illegal';
+} | {
+    kind: 'correct';
+    uci: string;
+} | {
+    kind: 'incorrect';
+    uci: string;
+};
+export type CreateExpectedMoveDropHandlerOptions = {
+    fen: string;
+    expectedUci: string | null | undefined;
+    enabled: boolean;
+    onCorrect: (uci: string) => void;
+    onIncorrect: (uci: string) => void;
+};
+/**
+ * Evaluate a training drop without mutating board position.
+ * Returns `false` for incorrect attempts so react-chessboard snaps the piece back.
+ */
+export declare function evaluateExpectedMoveDrop(fen: string, sourceSquare: string, targetSquare: string, piece: string, expectedUci: string | null | undefined, enabled: boolean): ExpectedMoveDropResult;
+export declare function createExpectedMoveDropHandler({ fen, expectedUci, enabled, onCorrect, onIncorrect, }: CreateExpectedMoveDropHandlerOptions): (sourceSquare: string, targetSquare: string, piece: string) => boolean;

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

@@ -0,0 +1,4 @@
+export * from './uciFromDrop';
+export * from './expectedMoveDrop';
+export * from './useBoardRevision';
+export * from './miss';

package/dist/features/training/miss/index.d.ts

@@ -0,0 +1,5 @@
+export { REFUTATION_EVAL_GAP_CP, REFUTATION_EVAL_GAP_PAWNS, fenAfterUci, lineEvalCpForGap, refutationEngineOptions, refutationEvalGapCp, refutationFromEvaluation, type RefutationResult, } from './refutation';
+export { MISS_MOVE_ANIMATION_MS, MISS_REFUTATION_MAX_WAIT_MS, MISS_REFUTATION_PAUSE_MS, MISS_WRONG_PAUSE_MS, getMissDisplay, type MissDisplay, type MissSequencePhase, type MissSequenceState, } from './missDisplay';
+export { useMissRefutation } from './useMissRefutation';
+export { useMissSequence } from './useMissSequence';
+export { useMissBoard } from './useMissBoard';

package/dist/features/training/miss/missDisplay.d.ts

@@ -0,0 +1,16 @@
+export type MissSequencePhase = 'wrong' | 'refutation' | 'answer' | 'retry';
+export type MissSequenceState = {
+    setupFen: string;
+    attemptedUci: string;
+    phase: MissSequencePhase;
+};
+export type MissDisplay = {
+    fen: string | null;
+    arrows: [string, string, string][];
+    animating: boolean;
+};
+export declare const MISS_WRONG_PAUSE_MS = 450;
+export declare const MISS_REFUTATION_PAUSE_MS = 900;
+export declare const MISS_REFUTATION_MAX_WAIT_MS = 4000;
+export declare const MISS_MOVE_ANIMATION_MS = 220;
+export declare function getMissDisplay(sequence: MissSequenceState | null, expectedUci: string | null, refutationUci: string | null, answerArrowColor: string): MissDisplay;

package/dist/features/training/miss/refutation.d.ts

@@ -0,0 +1,19 @@
+import type { AnalysisEngineOptions, EngineEvaluation, EngineLine } from '../../engine/types';
+/** Minimum eval loss (pawns) from the wrong move before showing a refutation. */
+export declare const REFUTATION_EVAL_GAP_PAWNS = 0.5;
+export declare const REFUTATION_EVAL_GAP_CP: number;
+export type RefutationResult = {
+    fenAfterWrong: string | null;
+    refutationUci: string | null;
+    refutationSan: string | null;
+    refutationLine: string | null;
+    loading: boolean;
+    error: string | null;
+};
+export declare const refutationEngineOptions: AnalysisEngineOptions;
+export declare function fenAfterUci(fen: string, uci: string): string | null;
+/** Centipawn score from side to move, comparable across sibling positions. */
+export declare function lineEvalCpForGap(line: EngineLine | undefined): number | null;
+/** How much better the opponent's eval is after the wrong move vs the correct one. */
+export declare function refutationEvalGapCp(evalAfterWrong: EngineEvaluation, evalAfterCorrect: EngineEvaluation): number | null;
+export declare function refutationFromEvaluation(fenAfterWrong: string, evaluation: EngineEvaluation, evalGapCp: number | null, evalGapApplies: boolean, evalGapLoading: boolean): Omit<RefutationResult, 'fenAfterWrong'>;

package/dist/features/training/miss/useMissBoard.d.ts

@@ -0,0 +1,28 @@
+import type { AnalysisEngineOptions } from '../../engine/types';
+type MissFeedback = 'correct' | 'incorrect' | null;
+export declare function useMissBoard({ feedback, expectedUci, positionFen, answerArrowColor, autoShowWrongMoves, engineOptions, }: {
+    feedback: MissFeedback;
+    expectedUci: string | null;
+    positionFen: string;
+    answerArrowColor: string;
+    autoShowWrongMoves?: boolean;
+    engineOptions?: AnalysisEngineOptions;
+}): {
+    missSequence: {
+        sequence: import("./missDisplay").MissSequenceState | null;
+        refutation: import("./refutation").RefutationResult;
+        display: import("./missDisplay").MissDisplay;
+        startSequence: (setupFen: string, attemptedUci: string) => void;
+        clearSequence: () => void;
+    };
+    refutation: import("./refutation").RefutationResult;
+    customArrows: [string, string, string][];
+    boardPosition: string;
+    boardAnimating: boolean;
+    wrapDropHandler: (onDrop: (source: string, target: string, piece: string) => boolean, { enabled, dropFen, expectedMoveUci, }: {
+        enabled: boolean;
+        dropFen?: string;
+        expectedMoveUci?: string | null;
+    }) => (source: string, target: string, piece: string) => boolean;
+};
+export {};

package/dist/features/training/miss/useMissRefutation.d.ts

@@ -0,0 +1,3 @@
+import type { AnalysisEngineOptions } from '../../engine/types';
+import { type RefutationResult } from './refutation';
+export declare function useMissRefutation(setupFen: string | null, attemptedUci: string | null, expectedUci: string | null, enabled: boolean, engineOptions: AnalysisEngineOptions): RefutationResult;

package/dist/features/training/miss/useMissSequence.d.ts

@@ -0,0 +1,10 @@
+import type { AnalysisEngineOptions } from '../../engine/types';
+import { type MissDisplay, type MissSequencePhase, type MissSequenceState } from './missDisplay';
+export type { MissSequencePhase, MissDisplay };
+export declare function useMissSequence(feedback: 'correct' | 'incorrect' | null, expectedUci: string | null, engineOptions: AnalysisEngineOptions, answerArrowColor: string, autoShowWrongMoves: boolean): {
+    sequence: MissSequenceState | null;
+    refutation: import("./refutation").RefutationResult;
+    display: MissDisplay;
+    startSequence: (setupFen: string, attemptedUci: string) => void;
+    clearSequence: () => void;
+};

package/dist/features/training/uciFromDrop.d.ts

@@ -0,0 +1,3 @@
+/** 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;
+export declare function matchesExpectedUci(uci: string, expectedUci: string): boolean;

package/dist/features/training/useBoardRevision.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Bump the revision counter to force a controlled chessboard re-render after a
+ * rejected drop. Pair with returning `false` from `onPieceDrop` so the board
+ * snaps back without changing the controlled `position` FEN.
+ */
+export declare function useBoardRevision(): {
+    revision: number;
+    bumpRevision: () => void;
+};

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export * from './features/chessboard';
 export * from './features/engine';
 export * from './features/analysis';
 export * from './features/navigation';
+export * from './features/training';