react-chess-puzzle-kit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-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,331 @@
+# react-chess-puzzle-kit
+
+```bash
+npm install
+npm run build
+```
+
+Build output: `dist/` (`index.js`, `index.esm.js`, `index.d.ts`). Re-run after source changes when consuming this package via `file:../react-chess-puzzle-kit`.
+
+React components for **interactive chess puzzles** and **post-puzzle analysis**, built on [react-chessboard](https://github.com/Clariity/react-chessboard) and [chess.js](https://github.com/jhlywa/chess.js). Used in production at [endchess.training](https://endchess.training).
+
+The library owns puzzle logic, move history, themes, and optional Stockfish analysis. **Defaults are included** for a full demo (controls + analysis UI); production apps usually replace those with custom render props.
+
+---
+
+## Install
+
+```bash
+npm install react-chess-puzzle-kit
+```
+
+**Peer dependencies:** `react`, `react-chessboard`, `chess.js`, **`react-chess-core`** (required — see `package.json`).
+
+Install both packages in your app:
+
+```bash
+npm install react-chess-puzzle-kit react-chess-core
+```
+
+Local development: `file:../react-chess-core` and `file:../react-chess-puzzle-kit` — build core first (`npm run build` in that repo), then puzzle-kit, then `npm install` in the app.
+
+**Board theme, `HighlightChessboard`, Stockfish hooks, and eval formatters** are exported from **`react-chess-core`**, not re-exported from puzzle-kit. Puzzle-kit covers puzzle play, analysis orchestration, and optional default analysis UI.
+
+For engine analysis in the browser, also install Stockfish and copy WASM into your app’s static folder (see [Stockfish](#stockfish-browser-engine) below).
+
+---
+
+## See it in action (Storybook)
+
+Storybook is the living docs and playground for every export.
+
+```bash
+git clone https://github.com/reblackwell3/react-chess-puzzle-kit.git
+cd react-chess-puzzle-kit
+npm install
+npm run storybook          # http://localhost:6006
+```
+
+| Story | What it demonstrates |
+|-------|----------------------|
+| **PuzzleBoardWithControls** | Full puzzle flow with default controls (via decorator) |
+| **PuzzleBoardWithControls → All library defaults** | Default controls + default analysis modal, sidebar, engine panel |
+| **PuzzleBoard** | Puzzle board only (drag-and-drop, feedback highlights) |
+| **Analysis / AnalysisBoard (defaults)** | Default modal, sidebar, grid, and engine panel |
+| **HighlightChessboard** | Themed board with check / hint / incorrect square styles |
+
+Optional: `npm run copy:stockfish` then open **Analysis → WithStockfishEngine** to exercise the worker.
+
+Build a static catalog: `npm run build-storybook` → `npm run serve-storybook`.
+
+---
+
+## Quick start
+
+`PuzzleBoardWithControls` is the main integration point: puzzle play, then analysis when the puzzle is finished or failed.
+
+### All library defaults
+
+Omit every render prop to use built-in puzzle controls and analysis UI. This matches **PuzzleBoardWithControls → All library defaults** in Storybook.
+
+```tsx
+import { PuzzleBoardWithControls } from 'react-chess-puzzle-kit';
+
+export function PuzzleDemo() {
+  return (
+    <PuzzleBoardWithControls
+      theme="dark"
+      apiProxy={{
+        onFetch: () => fetchPuzzleFromApi(),
+        onFeedback: (data) => sendFeedbackToApi(data),
+      }}
+      engine={{ enabled: false }}
+    />
+  );
+}
+```
+
+Defaults used when props are omitted:
+
+| Prop | Default |
+|------|---------|
+| `renderControls` | `DefaultPuzzleControls` (hint, next, analysis, result labels) |
+| `renderAnalysis*` | `AnalysisBoard` modal, sidebar, and `EngineEvaluationPanel` |
+| `puzzleBoardWidth` | `DEFAULT_PUZZLE_BOARD_WIDTH` (480) |
+| `analysisLayout` | `DEFAULT_ANALYSIS_LAYOUT` |
+
+Reuse the controls alone:
+
+```tsx
+import {
+  DefaultPuzzleControls,
+  defaultRenderControls,
+} from 'react-chess-puzzle-kit';
+
+// Inside your own layout:
+<DefaultPuzzleControls
+  showHint={showHint}
+  nextPuzzle={nextPuzzle}
+  resultStatus={resultStatus}
+  analysis={analysis}
+/>;
+```
+
+In Storybook, the `withDefaultPuzzleControls` decorator does the same for stories that leave `renderControls` unset (see `src/stories/withDefaultPuzzleControls.tsx`).
+
+### Custom UI (production)
+
+```tsx
+import {
+  PuzzleBoardWithControls,
+  DEFAULT_ANALYSIS_LAYOUT,
+} from 'react-chess-puzzle-kit';
+
+export function PuzzlePage() {
+  return (
+    <PuzzleBoardWithControls
+      theme="dark"
+      puzzleBoardWidth={560}
+      analysisLayout={DEFAULT_ANALYSIS_LAYOUT}
+      apiProxy={{
+        onFetch: () => fetchPuzzleFromApi(),
+        onFeedback: (data) => sendFeedbackToApi(data),
+      }}
+      renderControls={(showHint, nextPuzzle, resultStatus, analysis) => (
+        <YourControls
+          onHint={showHint}
+          onNext={nextPuzzle}
+          onOpenAnalysis={analysis.openAnalysis}
+          canOpenAnalysis={analysis.visible}
+        />
+      )}
+      renderAnalysisContainer={(props) => <YourAnalysisDialog {...props} />}
+      renderAnalysisSidebar={(props) => <YourMoveList {...props} />}
+      renderEngineEvaluation={(props) => <YourEnginePanel {...props} />}
+      engine={{ depth: 16, multiPv: 2 }}
+    />
+  );
+}
+```
+
+---
+
+## What’s in the package
+
+### Puzzle play
+
+| Export | Role |
+|--------|------|
+| **`PuzzleBoardWithControls`** | Orchestrates fetch, puzzle board, controls slot, and analysis mode |
+| **`DefaultPuzzleControls`** | Default hint / next / analysis button row |
+| **`defaultRenderControls`** | Render-prop function wired to `DefaultPuzzleControls` |
+| **`PuzzleBoard`** | Draggable puzzle board with correct/incorrect/hint feedback |
+| **`PuzzlePosition`** | FEN + solution line, move index, guess judging |
+| **`analysisSidebarColors`** | Default analysis move-list striping (override in your app) |
+
+**From `react-chess-core` (install separately):** `HighlightChessboard`, `ThemeProvider`, `boardSquareHighlightColors`, `useAnalysisEngine`, `formatEvaluation`, `DEFAULT_STOCKFISH_SCRIPT_URL`, etc.
+
+### Analysis
+
+Analysis is split so apps can use **presets** or go **fully headless**:
+
+| Layer | Location | Use when |
+|-------|----------|----------|
+| **Core** | `src/features/analysis/core/` | You want full control of layout and UI |
+| **Defaults** | `src/features/analysis/defaults/` | You want a working modal + sidebar out of the box |
+
+| Export | Role |
+|--------|------|
+| **`usePuzzleAnalysis`** | When analysis can open; snapshot of puzzle state |
+| **`useAnalysisBoardModel`** | FEN, ply navigation, history, engine hook, drop handler (no JSX) |
+| **`AnalysisBoardCore`** | Wires model + board; **requires** all `render*` props |
+| **`AnalysisBoard`** | Same as core but fills missing render props with library defaults |
+| **`AnalysisBoardLayout`** | Optional CSS grid: board column + sidebar column |
+| **`AnalysisLayoutConfig`** | `{ boardWidth, sidebarWidth, columnGap }` |
+
+### Engine
+
+| Export | Package | Role |
+|--------|---------|------|
+| **`useAnalysisEngine`**, eval helpers | `react-chess-core` | Stockfish hook + PV formatting |
+| **`EngineEvaluationPanel`** | puzzle-kit | Default engine UI (`AnalysisBoard` preset) |
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  PuzzleBoardWithControls (host app)                         │
+│  ├─ puzzle play → PuzzleBoard (puzzleBoardWidth)           │
+│  └─ analysis open → AnalysisBoardCore | AnalysisBoard       │
+│       ├─ renderContainer  (modal / page shell)              │
+│       ├─ renderMain       (board + sidebar placement)       │
+│       ├─ renderSidebar    (move list, nav)                  │
+│       └─ renderEngineEvaluation (Stockfish lines)           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Separation of concerns**
+
+- **Logic** — puzzle position, analysis context, ply navigation (`analysis/core/`); engine hook from **`react-chess-core`**.
+- **UI** — host render props, or `defaults/` (`AnalysisBoard`, `DefaultAnalysisSidebar`, `DefaultAnalysisContainer`, `EngineEvaluationPanel`).
+
+Production apps (e.g. endchess-frontend) typically pass custom `renderAnalysis*` implementations and sizes via `puzzleBoardWidth` + `analysisLayout`, while reusing `useAnalysisBoardModel` behavior through `AnalysisBoardCore`.
+
+---
+
+## Board sizing
+
+Puzzle and analysis boards can use **different pixel widths**:
+
+```tsx
+<PuzzleBoardWithControls
+  puzzleBoardWidth={560}           // live puzzle
+  analysisLayout={{
+    boardWidth: 480,                 // analysis chessboard
+    sidebarWidth: 500,
+    columnGap: 16,
+  }}
+/>
+```
+
+Defaults: `DEFAULT_PUZZLE_BOARD_WIDTH` (480) and `DEFAULT_ANALYSIS_LAYOUT`. Override `renderAnalysisMain` for a fully custom layout (flex, MUI grid, etc.).
+
+---
+
+## Stockfish (browser engine)
+
+Analysis runs Stockfish in a **Web Worker**. The host must serve the engine assets:
+
+```bash
+npm install stockfish --save-optional   # or a regular dependency
+npm run copy:stockfish                  # copies to public/stockfish/ in this repo
+```
+
+In your app, copy the same files to `public/stockfish/` (or equivalent). Default script URL:
+
+`/stockfish/stockfish-18-lite-single.js` (`.wasm` must sit beside it).
+
+```tsx
+<PuzzleBoardWithControls
+  engine={{
+    enabled: true,
+    depth: 18,
+    multiPv: 2,
+    scriptUrl: '/stockfish/stockfish-18-lite-single.js',
+  }}
+/>
+```
+
+Disable the worker when you only need move replay: `engine={{ enabled: false }}`.
+
+---
+
+## Headless analysis example
+
+Use `AnalysisBoardCore` when every visual piece comes from the host:
+
+```tsx
+import {
+  AnalysisBoardCore,
+  AnalysisBoardLayout,
+  DEFAULT_ANALYSIS_LAYOUT,
+} from 'react-chess-puzzle-kit';
+
+<AnalysisBoardCore
+  analysisContext={snapshot}
+  theme="dark"
+  boardWidth={layout.boardWidth}
+  onClose={close}
+  renderContainer={(p) => <MyDialog {...p} />}
+  renderMain={({ board, sidebar, model }) => (
+    <AnalysisBoardLayout layout={layout} model={model} board={board} sidebar={sidebar} />
+  )}
+  renderSidebar={(p) => <MySidebar {...p} />}
+  renderEngineEvaluation={(p) => <MyEngine {...p} />}
+/>;
+```
+
+---
+
+## Development
+
+```bash
+npm run build              # Rollup → dist/
+npm run storybook          # component docs & examples
+npm run build-storybook    # static Storybook export
+npm run copy:stockfish     # engine binaries for local Storybook
+```
+
+---
+
+## Migration: engine/board imports
+
+If you previously imported these from `react-chess-puzzle-kit`, switch to `react-chess-core`:
+
+```diff
+- import { useAnalysisEngine, formatEvaluation, ThemeProvider } from 'react-chess-puzzle-kit';
++ import { useAnalysisEngine, formatEvaluation, ThemeProvider } from 'react-chess-core';
+```
+
+Keep puzzle-specific imports on puzzle-kit (`PuzzleBoardWithControls`, `usePuzzleAnalysis`, `AnalysisBoardCore`, render-prop types, etc.).
+
+---
+
+## Migration from `react-chessboard-with-controls`
+
+The package was renamed to **`react-chess-puzzle-kit`** (v1.0.0). Update imports:
+
+```diff
+- import { PuzzleBoardWithControls } from 'react-chessboard-with-controls';
++ import { PuzzleBoardWithControls } from 'react-chess-puzzle-kit';
+```
+
+Component export names are unchanged for now. Rename the local clone folder to `react-chess-puzzle-kit` and point `file:../react-chess-puzzle-kit` in consuming apps.
+
+---
+
+## License
+
+MIT © 2022–2026 Robert Blackwell

package/dist/features/analysis/AnalysisBoard.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+import { AnalysisBoardCoreProps } from './AnalysisBoardCore';
+import { AnalysisContainerRenderProps, AnalysisMainRenderProps, AnalysisSidebarRenderProps, EngineEvaluationRenderProps } from './renderProps';
+export type { AnalysisBoardCoreProps, AnalysisBoardModel } from './AnalysisBoardCore';
+export { ANALYSIS_BOARD_WIDTH, ANALYSIS_BODY_GAP, ANALYSIS_SIDEBAR_WIDTH, } from './analysisLayout';
+export { AnalysisBoardLayout } from './AnalysisBoardLayout';
+export { useAnalysisBoardModel } from './useAnalysisBoardModel';
+export interface AnalysisBoardProps extends Omit<AnalysisBoardCoreProps, 'renderContainer' | 'renderMain' | 'renderSidebar' | 'renderEngineEvaluation'> {
+    renderContainer?: (props: AnalysisContainerRenderProps) => React.ReactNode;
+    renderMain?: (props: AnalysisMainRenderProps) => React.ReactNode;
+    renderSidebar?: (props: AnalysisSidebarRenderProps) => React.ReactNode;
+    renderEngineEvaluation?: (props: EngineEvaluationRenderProps) => React.ReactNode;
+}
+/**
+ * Full analysis UI with library defaults: modal shell, grid layout, sidebar, engine panel.
+ * For host-owned UI only, use {@link AnalysisBoardCore} and pass all render props.
+ */
+export declare const AnalysisBoard: ({ renderContainer, renderMain, renderSidebar, renderEngineEvaluation, engine, ...modelArgs }: AnalysisBoardProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,28 @@
+import React from 'react';
+import { AnalysisContainerRenderProps, AnalysisMainRenderProps, AnalysisSidebarRenderProps, EngineEvaluationRenderProps } from './renderProps';
+import { AnalysisEngineOptions } from '../engine/types';
+import { AnalysisBoardModel, UseAnalysisBoardModelArgs } from './useAnalysisBoardModel';
+export type AnalysisBoardCoreProps = UseAnalysisBoardModelArgs & {
+    engine?: AnalysisEngineOptions;
+    /** Host-owned shell (modal, page layout, etc.). */
+    renderContainer: (props: AnalysisContainerRenderProps) => React.ReactNode;
+    /** Host-owned grid/placement of board + sidebar (no library default). */
+    renderMain: (props: AnalysisMainRenderProps) => React.ReactNode;
+    renderSidebar: (props: AnalysisSidebarRenderProps) => React.ReactNode;
+    renderEngineEvaluation: (props: EngineEvaluationRenderProps) => React.ReactNode;
+};
+/**
+ * Analysis logic + composition only: hook, board node, sidebar/engine slots.
+ * No layout divs — use {@link renderMain} (e.g. {@link AnalysisBoardLayout} from the host or default {@link AnalysisBoard}).
+ */
+export declare const AnalysisBoardCore: ({ renderContainer, renderMain, renderSidebar, renderEngineEvaluation, ...modelArgs }: AnalysisBoardCoreProps) => import("react/jsx-runtime").JSX.Element;
+type AnalysisBoardCoreViewProps = {
+    model: AnalysisBoardModel;
+    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 type { AnalysisBoardModel, UseAnalysisBoardModelArgs };

package/dist/features/analysis/AnalysisBoardLayout.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import { AnalysisBoardModel } from './useAnalysisBoardModel';
+export type AnalysisBoardLayoutProps = {
+    model: AnalysisBoardModel;
+    board: React.ReactNode;
+    sidebar: React.ReactNode;
+};
+/**
+ * Default analysis layout: board column + sidebar column.
+ * Used by {@link AnalysisBoard}; hosts may reuse via {@link defaultAnalysisMainLayout}.
+ */
+export declare const AnalysisBoardLayout: ({ model, board, sidebar, }: AnalysisBoardLayoutProps) => import("react/jsx-runtime").JSX.Element;

package/dist/features/analysis/AnalysisChessboardView.d.ts

@@ -0,0 +1,5 @@
+import { AnalysisBoardModel } from './useAnalysisBoardModel';
+/** Draggable analysis board (no surrounding layout chrome). */
+export declare const AnalysisChessboardView: ({ model }: {
+    model: AnalysisBoardModel;
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/features/analysis/AnalysisPosition.d.ts

@@ -0,0 +1,53 @@
+import { PuzzleAnalysisContext } from './analysisContext';
+export type SolutionMoveDisplay = {
+    ply: number;
+    uci: string;
+    san: string;
+};
+export type AnalysisHistoryRow = {
+    key: string;
+    label: string;
+    indent: number;
+    kind: 'start' | 'main' | 'variation';
+    mainPly: number;
+    variationIndex: number;
+};
+export declare class AnalysisPosition {
+    private chess;
+    private readonly initialFen;
+    private readonly solutionMoves;
+    private readonly solutionSans;
+    private mainPly;
+    private variation;
+    private variationCursor;
+    constructor(context: PuzzleAnalysisContext);
+    private static buildSolutionSans;
+    private fenAtMainPly;
+    private rebuildChess;
+    private findLegalMove;
+    private uciFromVerboseMove;
+    private matchesMainMove;
+    getNavPly(): number;
+    getMaxNavPly(): number;
+    /** @deprecated Use getNavPly */
+    getPly(): number;
+    /** @deprecated Use getMaxNavPly */
+    getMaxPly(): number;
+    getSolutionSans(): SolutionMoveDisplay[];
+    getHistoryRows(): AnalysisHistoryRow[];
+    isHistoryRowSelected(row: AnalysisHistoryRow): boolean;
+    selectHistoryRow(row: AnalysisHistoryRow): void;
+    selectMainLine(ply: number): void;
+    /** @deprecated Use selectMainLine or goToNavPly */
+    goToPly(ply: number): void;
+    goToNavPly(navPly: number): void;
+    tryPlayMove(sourceSquare: string, targetSquare: string, piece: string): boolean;
+    next(): boolean;
+    prev(): boolean;
+    getLastMoveSquares(): {
+        from: string;
+        to: string;
+    } | null;
+    fen(): string;
+    getCheckSquare(): string;
+}

package/dist/features/analysis/AnalysisTrigger.d.ts

@@ -0,0 +1,6 @@
+export interface AnalysisTriggerProps {
+    visible: boolean;
+    onClick: () => void;
+    theme: 'light' | 'dark';
+}
+export declare const AnalysisTrigger: ({ visible, onClick, theme, }: AnalysisTriggerProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/features/analysis/DefaultAnalysisContainer.d.ts

@@ -0,0 +1,3 @@
+import { AnalysisContainerRenderProps } from './renderProps';
+/** Default full-screen modal shell for analysis (library preset UI). */
+export declare const DefaultAnalysisContainer: ({ theme, onClose, onBackdropMouseDown, children, }: AnalysisContainerRenderProps) => import("react/jsx-runtime").JSX.Element;

package/dist/features/analysis/DefaultAnalysisSidebar.d.ts

@@ -0,0 +1,2 @@
+import { AnalysisSidebarRenderProps } from './renderProps';
+export declare const DefaultAnalysisSidebar: ({ historyRows, isHistoryRowSelected, onSelectHistoryRow, ply, maxPly, onSelectPly, theme, engineEvaluationPanel, }: AnalysisSidebarRenderProps) => import("react/jsx-runtime").JSX.Element;

package/dist/features/analysis/analysisBoardHighlightColors.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Square overlay colors for analysis board replay (last move highlight).
+ */
+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;
+}>;

package/dist/features/analysis/analysisContext.d.ts

@@ -0,0 +1,8 @@
+import type { AnalysisContext } from 'react-chess-core';
+import { PuzzlePosition } from '../position/Position';
+export type PuzzleResultStatus = 'none' | 'incorrect' | 'complete';
+/** @deprecated Use {@link AnalysisContext} from `react-chess-core`. */
+export type PuzzleAnalysisContext = AnalysisContext;
+export declare const emptyAnalysisContext: () => AnalysisContext;
+export declare const buildAnalysisContext: (position: PuzzlePosition | null) => AnalysisContext;
+export declare const isAnalysisAvailable: (position: PuzzlePosition | null, resultStatus: PuzzleResultStatus) => boolean;

package/dist/features/analysis/analysisLayout.d.ts

@@ -0,0 +1,5 @@
+/** Board column width in analysis grid (matches endchess-frontend sidebar layout). */
+export declare const ANALYSIS_BOARD_WIDTH = 480;
+/** Sidebar column width (move list + engine). */
+export declare const ANALYSIS_SIDEBAR_WIDTH = 500;
+export declare const ANALYSIS_BODY_GAP = 16;

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

@@ -0,0 +1,28 @@
+import React from 'react';
+import { AnalysisContainerRenderProps, AnalysisMainRenderProps, AnalysisSidebarRenderProps, EngineEvaluationRenderProps } from './renderProps';
+import { AnalysisEngineOptions } from 'react-chess-core';
+import { AnalysisBoardModel, UseAnalysisBoardModelArgs } from './useAnalysisBoardModel';
+export type AnalysisBoardCoreProps = UseAnalysisBoardModelArgs & {
+    engine?: AnalysisEngineOptions;
+    /** Host-owned shell (modal, page layout, etc.). */
+    renderContainer: (props: AnalysisContainerRenderProps) => React.ReactNode;
+    /** Host-owned grid/placement of board + sidebar (no library default). */
+    renderMain: (props: AnalysisMainRenderProps) => React.ReactNode;
+    renderSidebar: (props: AnalysisSidebarRenderProps) => React.ReactNode;
+    renderEngineEvaluation: (props: EngineEvaluationRenderProps) => React.ReactNode;
+};
+/**
+ * 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;
+type AnalysisBoardCoreViewProps = {
+    model: AnalysisBoardModel;
+    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 type { AnalysisBoardModel, UseAnalysisBoardModelArgs };

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

@@ -0,0 +1,5 @@
+import { AnalysisBoardModel } from './useAnalysisBoardModel';
+/** Draggable analysis board (no surrounding layout chrome). */
+export declare const AnalysisChessboardView: ({ model }: {
+    model: AnalysisBoardModel;
+}) => import("react").JSX.Element;

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

@@ -0,0 +1,14 @@
+import { Component, ReactNode } from 'react';
+type AnalysisErrorBoundaryProps = {
+    children: ReactNode;
+    onClose?: () => void;
+};
+type AnalysisErrorBoundaryState = {
+    error: Error | null;
+};
+export declare class AnalysisErrorBoundary extends Component<AnalysisErrorBoundaryProps, AnalysisErrorBoundaryState> {
+    state: AnalysisErrorBoundaryState;
+    static getDerivedStateFromError(error: Error): AnalysisErrorBoundaryState;
+    render(): string | number | boolean | Iterable<ReactNode> | import("react").JSX.Element | null | undefined;
+}
+export {};

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

@@ -0,0 +1,54 @@
+import { PuzzleAnalysisContext } from './analysisContext';
+export type SolutionMoveDisplay = {
+    ply: number;
+    uci: string;
+    san: string;
+};
+export type AnalysisHistoryRow = {
+    key: string;
+    label: string;
+    indent: number;
+    kind: 'start' | 'main' | 'variation';
+    mainPly: number;
+    variationIndex: number;
+};
+export declare class AnalysisPosition {
+    private chess;
+    private readonly initialFen;
+    private readonly solutionMoves;
+    private readonly solutionSans;
+    private mainPly;
+    private variation;
+    private variationCursor;
+    constructor(context: PuzzleAnalysisContext);
+    private static buildSolutionSans;
+    private static applySolutionMove;
+    private fenAtMainPly;
+    private rebuildChess;
+    private findLegalMove;
+    private uciFromVerboseMove;
+    private matchesMainMove;
+    getNavPly(): number;
+    getMaxNavPly(): number;
+    /** @deprecated Use getNavPly */
+    getPly(): number;
+    /** @deprecated Use getMaxNavPly */
+    getMaxPly(): number;
+    getSolutionSans(): SolutionMoveDisplay[];
+    getHistoryRows(): AnalysisHistoryRow[];
+    isHistoryRowSelected(row: AnalysisHistoryRow): boolean;
+    selectHistoryRow(row: AnalysisHistoryRow): void;
+    selectMainLine(ply: number): void;
+    /** @deprecated Use selectMainLine or goToNavPly */
+    goToPly(ply: number): void;
+    goToNavPly(navPly: number): void;
+    tryPlayMove(sourceSquare: string, targetSquare: string, piece: string): boolean;
+    next(): boolean;
+    prev(): boolean;
+    getLastMoveSquares(): {
+        from: string;
+        to: string;
+    } | null;
+    fen(): string;
+    getCheckSquare(): string;
+}

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

@@ -0,0 +1,13 @@
+import { PuzzleMoveRecord } from '../../position/moveHistory';
+import { PuzzlePosition } from '../../position/Position';
+export type PuzzleResultStatus = 'none' | 'incorrect' | 'complete';
+export type PuzzleAnalysisContext = {
+    initialFen: string;
+    solutionMoves: string[];
+    moveHistory: PuzzleMoveRecord[];
+    currentPly: number;
+    boardOrientation: 'white' | 'black';
+};
+export declare const emptyAnalysisContext: () => PuzzleAnalysisContext;
+export declare const buildAnalysisContext: (position: PuzzlePosition | null) => PuzzleAnalysisContext;
+export declare const isAnalysisAvailable: (position: PuzzlePosition | null, resultStatus: PuzzleResultStatus) => boolean;

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

@@ -0,0 +1,5 @@
+/** Board column width in analysis grid (matches endchess-frontend sidebar layout). */
+export declare const ANALYSIS_BOARD_WIDTH = 480;
+/** Sidebar column width (move list + engine). */
+export declare const ANALYSIS_SIDEBAR_WIDTH = 500;
+export declare const ANALYSIS_BODY_GAP = 16;

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

@@ -0,0 +1,6 @@
+/** Host-provided dimensions for analysis board + sidebar grid (defaults package only). */
+export type AnalysisLayoutConfig = {
+    boardWidth: number;
+    sidebarWidth: number;
+    columnGap: number;
+};

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

@@ -0,0 +1,9 @@
+export * from './AnalysisErrorBoundary';
+export * from './analysisContext';
+export * from './analysisLayoutConfig';
+export * from './AnalysisBoardCore';
+export * from './AnalysisChessboardView';
+export * from './AnalysisPosition';
+export * from './renderProps';
+export * from './useAnalysisBoardModel';
+export * from './usePuzzleAnalysis';