gigaboard 1.2.3

package/dist/board-model-BvJOtwQ3.d.ts

@@ -0,0 +1,675 @@
+/**
+ * Public types and branded primitives for `gigaboard/core`.
+ *
+ * Design goals:
+ * - Primitives carry their meaning in the type (`SquareIndex` never silently
+ *   mixes with a piece code or a file number).
+ * - Encoding of a board cell is a single byte suitable for `Uint8Array(64)`.
+ * - Every symbol exported here is a type or a zero-cost helper — no classes,
+ *   no allocations per call, nothing that would eat into the budget.
+ */
+/**
+ * A square on the board, in LERF indexing: `0 = a1`, `7 = h1`, `56 = a8`,
+ * `63 = h8`. Aligned with standard 0..63 square indexing.
+ */
+type SquareIndex = number & {
+    readonly __brand: "SquareIndex";
+};
+/**
+ * A packed u16 move conforming to the 16-bit Move2 wire format:
+ * bits 0–5: from square index (0..63)
+ * bits 6–11: to square index (0..63)
+ * bits 12–15: promotion code (0 = none, 1 = Knight, 2 = Bishop, 3 = Rook, 4 = Queen).
+ */
+type PackedMove = number & {
+    readonly __brand: "PackedMove";
+};
+/** Move2 promotion codes */
+declare const MOVE2_PROMO_NONE = 0;
+declare const MOVE2_PROMO_KNIGHT = 1;
+declare const MOVE2_PROMO_BISHOP = 2;
+declare const MOVE2_PROMO_ROOK = 3;
+declare const MOVE2_PROMO_QUEEN = 4;
+/**
+ * Packs from/to/promo into one 16-bit Move2 word.
+ */
+declare function packMove(from: number, to: number, promo?: number): PackedMove;
+/**
+ * Unpacks a 16-bit Move2 word into its from/to/promo fields.
+ */
+declare function unpackMove(move: PackedMove | number): {
+    from: SquareIndex;
+    to: SquareIndex;
+    promo: number;
+};
+/**
+ * 64-bit Zobrist key represented as two 32-bit unsigned integers (zero-BigInt).
+ */
+type ZobristKey = {
+    readonly lo: number;
+    readonly hi: number;
+};
+/**
+ * A single byte representing one square of the board. `0` is empty; values
+ * `1..12` encode a piece. The encoding is a stable contract: consumers may
+ * rely on `BOARD_CELL_*` constants (below) instead of remembering numbers.
+ */
+type BoardCell = number & {
+    readonly __brand: "BoardCell";
+};
+/** Piece color (White = 0, Black = 1). */
+declare const Color: {
+    readonly White: 0;
+    readonly Black: 1;
+};
+/** Colour value. */
+type Color = (typeof Color)[keyof typeof Color];
+/** Piece type (0 = Pawn .. 5 = King). */
+declare const PieceType: {
+    readonly Pawn: 0;
+    readonly Knight: 1;
+    readonly Bishop: 2;
+    readonly Rook: 3;
+    readonly Queen: 4;
+    readonly King: 5;
+};
+/** Piece-type value (0 = Pawn .. 5 = King). */
+type PieceType = (typeof PieceType)[keyof typeof PieceType];
+/** Board-cell constants for readability at call sites. */
+declare const BOARD_CELL_EMPTY: BoardCell;
+declare const BOARD_CELL_WP: BoardCell;
+declare const BOARD_CELL_WN: BoardCell;
+declare const BOARD_CELL_WB: BoardCell;
+declare const BOARD_CELL_WR: BoardCell;
+declare const BOARD_CELL_WQ: BoardCell;
+declare const BOARD_CELL_WK: BoardCell;
+declare const BOARD_CELL_BP: BoardCell;
+declare const BOARD_CELL_BN: BoardCell;
+declare const BOARD_CELL_BB: BoardCell;
+declare const BOARD_CELL_BR: BoardCell;
+declare const BOARD_CELL_BQ: BoardCell;
+declare const BOARD_CELL_BK: BoardCell;
+/** Narrow a number into a `SquareIndex`. Validates in dev, no-op at runtime. */
+declare function toSquareIndex(n: number): SquareIndex;
+/** Type-guard: is `n` a valid square index? */
+declare function isSquareIndex(n: number): n is SquareIndex;
+/**
+ * Pack a `(color, type)` pair into a `BoardCell`.
+ *
+ * @remarks Inlined constant arithmetic — stays zero-allocation.
+ */
+declare function encodeBoardCell(color: Color, type: PieceType): BoardCell;
+/** `true` if the cell is empty. */
+declare function isEmptyCell(cell: BoardCell): boolean;
+/** Extract the color from a non-empty `BoardCell`. Undefined for empty cells. */
+declare function colorOf(cell: BoardCell): Color;
+/** Extract the piece type from a non-empty `BoardCell`. Undefined for empty. */
+declare function pieceTypeOf(cell: BoardCell): PieceType;
+/**
+ * Optional text label rendered alongside an arrow. Positioned at the
+ * endpoint by default; use `ArrowShape["labelCenter"]` to anchor it on
+ * `"orig"` (source square) or at the arrow's midpoint instead.
+ */
+interface ArrowLabel {
+    readonly text: string;
+    /** CSS color for the label glyph. Defaults to the arrow's `color`. */
+    readonly fill?: string;
+}
+/**
+ * Arbitrary inline SVG payload rendered on top of the canvas overlay.
+ * `html` is injected into an `<svg>` group as a `foreignObject`-free
+ * child so downstream CSS animations and `stroke-dasharray` tricks
+ * work as-is. The renderer never parses or sanitises the string —
+ * consumers are responsible for trusting the source. Typical uses:
+ *   - Stockfish best-move numerals ("+1.2", "♔")
+ *   - Coach annotations (stars, exclamations, `!!`/`??`)
+ *   - Custom variation markers
+ */
+interface ArrowCustomSvg {
+    /** SVG fragment injected as-is. Must be safe markup — no sanitisation. */
+    readonly html: string;
+    /**
+     * Anchor point for the fragment. Default `"dest"`. `"orig"` is useful
+     * for same-square marks (circles); `"label"` centres on the midpoint.
+     */
+    readonly center?: "orig" | "dest" | "label";
+}
+/**
+ * An on-board arrow annotation. Identity is the tuple
+ * `(from, to, color, brush, label.text, customSvg.html, below)` — two
+ * arrows that agree on every field are considered equal.
+ *
+ * @remarks
+ * The original `(from, to, color)` identity is preserved: any arrow
+ * that doesn't carry the optional decorations behaves exactly as in
+ * M1. Additive-only extension.
+ */
+interface Arrow {
+    readonly from: SquareIndex;
+    readonly to: SquareIndex;
+    /** Any CSS-legal color string. Common values: `"green"`, `"red"`, `"blue"`. */
+    readonly color: string;
+    /**
+     * Optional palette key that lets the renderer resolve the arrow's
+     * visual style (colour, stroke width, opacity) from a user-supplied
+     * `ArrowColors` map at draw time. When absent, `color` is used as-is
+     * and the modifier-key channels (`default`/`shift`/`alt`/`ctrl`)
+     * continue to work.
+     */
+    readonly brush?: string;
+    /** Optional text label. See {@link ArrowLabel}. */
+    readonly label?: ArrowLabel;
+    /** Optional custom SVG payload. See {@link ArrowCustomSvg}. */
+    readonly customSvg?: ArrowCustomSvg;
+    /**
+     * When `true`, the arrow renders **beneath** the piece layer instead
+     * of on top. Useful for "heatmap" tints that shouldn't occlude pieces
+     * (analysis boards, pawn-structure overlays).
+     */
+    readonly below?: boolean;
+    /**
+     * Marks an arrow as owned by the application rather than the user.
+     * "Managed" arrows survive the two reflex-clearing hooks
+     * (`clearArrowsOnClick`, `clearArrowsOnMove`) — the idiomatic use-case
+     * is an engine best-move hint on an analysis board, where the hint
+     * should update when the position changes but ignore the user's
+     * click-to-dismiss gesture on the board.
+     *
+     * User-drawn arrows (right-click gesture) always land with
+     * `managed: false`; programmatic callers opt in explicitly.
+     *
+     * A nuclear `model.clearArrows()` still wipes managed arrows —
+     * consumers who want a stricter partition call `clearUserArrows()`
+     * instead. Default `false` (unset).
+     */
+    readonly managed?: boolean;
+}
+/** A queued premove awaiting the opponent's reply. */
+interface Premove {
+    readonly from: SquareIndex;
+    readonly to: SquareIndex;
+    readonly promotion?: PieceType;
+}
+/**
+ * Immutable snapshot of the board at a single instant. Produced by the store
+ * on every commit; never mutated. React's `useSyncExternalStore` relies on
+ * referential equality here — a new snapshot object is emitted per commit,
+ * but bytes of `board` that didn't change share values with the previous one
+ * (read as primitives), so per-square subscribers skip untouched squares.
+ */
+interface BoardSnapshot {
+    /** 64-byte board, LERF-indexed. See {@link BoardCell}. */
+    readonly board: Readonly<Uint8Array>;
+    /** Side to move. */
+    readonly turn: Color;
+    /** Zobrist hash of the position (from the engine). */
+    readonly hash: ZobristKey | bigint;
+    /** The packed move that produced this position, or `null` for the initial. */
+    readonly lastMove: PackedMove | null;
+    /** Currently-selected square (UI state), or `null`. */
+    readonly selected: SquareIndex | null;
+    /** Legal target squares from `selected`. Empty set if nothing is selected. */
+    readonly legalTargets: ReadonlySet<SquareIndex>;
+    /** `true` if the side to move is in check. */
+    readonly inCheck: boolean;
+    /** `true` if the position ends the game (mate, stalemate, draw). */
+    readonly isGameOver: boolean;
+    /** How many plies from the initial position we are (includes undos). */
+    readonly historyPly: number;
+    /** Total history length, including any plies we've undone. */
+    readonly historyLength: number;
+    /** Active arrows drawn on the board. */
+    readonly arrows: readonly Arrow[];
+    /** Queued premoves, in FIFO order. */
+    readonly premoves: readonly Premove[];
+}
+/** Descriptor classifying one animated change between two snapshots. */
+type AnimDescriptor = {
+    readonly kind: "move";
+    readonly from: SquareIndex;
+    readonly to: SquareIndex;
+    readonly piece: BoardCell;
+} | {
+    readonly kind: "capture";
+    readonly from: SquareIndex;
+    readonly to: SquareIndex;
+    readonly piece: BoardCell;
+    readonly captured: BoardCell;
+} | {
+    readonly kind: "en-passant";
+    readonly from: SquareIndex;
+    readonly to: SquareIndex;
+    readonly capturedSquare: SquareIndex;
+    readonly piece: BoardCell;
+    readonly captured: BoardCell;
+} | {
+    readonly kind: "castle";
+    readonly kingFrom: SquareIndex;
+    readonly kingTo: SquareIndex;
+    readonly rookFrom: SquareIndex;
+    readonly rookTo: SquareIndex;
+} | {
+    readonly kind: "promotion";
+    readonly from: SquareIndex;
+    readonly to: SquareIndex;
+    readonly pieceBefore: BoardCell;
+    readonly pieceAfter: BoardCell;
+    readonly captured: BoardCell | null;
+} | {
+    readonly kind: "appear";
+    readonly at: SquareIndex;
+    readonly piece: BoardCell;
+} | {
+    readonly kind: "disappear";
+    readonly at: SquareIndex;
+    readonly piece: BoardCell;
+};
+/** Pointer-driven drag state. Used by `drag-controller`. */
+type DragState = {
+    readonly kind: "idle";
+} | {
+    readonly kind: "pending";
+    readonly from: SquareIndex;
+    readonly pointerId: number;
+    readonly originX: number;
+    readonly originY: number;
+} | {
+    readonly kind: "dragging";
+    readonly from: SquareIndex;
+    readonly pointerId: number;
+    readonly x: number;
+    readonly y: number;
+};
+
+/**
+ * Abstract engine protocol.
+ *
+ * The board model speaks to a chess engine exclusively through an
+ * `EngineAdapter`. Swapping the default `gigachess` adapter for another
+ * (chess.js, a variant engine, a custom server-backed validator) should not
+ * require changes to `board-model` or any React code.
+ *
+ * All methods are synchronous: adapter construction absorbs any async init.
+ * Every call is expected to be cheap in the steady state. Long-running adapters
+ * should cache aggressively on their own side.
+ */
+
+/** The engine protocol. */
+interface EngineAdapter {
+    /**
+     * Play a legal move. Returns the packed move on success, `null` if the move
+     * is illegal in the current position. Never throws on illegal input —
+     * callers may pass arbitrary from/to pairs (e.g. drag-and-drop drops onto
+     * any square).
+     */
+    makeMove(from: SquareIndex, to: SquareIndex, promotion?: PieceType): PackedMove | null;
+    /** Undo the most recent move. Returns the undone move, or `null` if none. */
+    undo(): PackedMove | null;
+    /**
+     * Legal moves from a single origin square (`from` provided) or all legal
+     * moves (`from` omitted). The returned array is fresh on every call; the
+     * caller is free to retain or discard it.
+     */
+    legalMoves(from?: SquareIndex): readonly PackedMove[];
+    /**
+     * Fill `out` with the current position as 64 `BoardCell` bytes (LERF). The
+     * caller supplies the buffer so adapters can avoid allocating per commit;
+     * `out.length` must be `64`.
+     */
+    readBoard(out: Uint8Array): void;
+    /** Current FEN. */
+    fen(): string;
+    /** Side to move. */
+    turn(): Color;
+    /** Zobrist hash of the current position. */
+    hash(): ZobristKey | bigint;
+    /** `true` if the side to move is in check. */
+    inCheck(): boolean;
+    /**
+     * Render a packed move as SAN (e.g. `"Nf3"`, `"O-O"`, `"exd5"`, `"e8=Q+"`).
+     * Used by the React layer's screen-reader announcer.
+     *
+     * Must be called BEFORE the move is played — SAN depends on the
+     * pre-move position for disambiguation and check markers.
+     */
+    san(move: PackedMove): string;
+    /** `true` if the position ends the game (mate, stalemate, draw). */
+    isGameOver(): boolean;
+    /** Load a FEN into the engine, replacing the current position and history. */
+    load(fen: string): void;
+    /** Reset to the starting position. Clears history. */
+    reset(): void;
+    /** Release engine resources. */
+    dispose(): void;
+}
+/**
+ * Opaque board-cell setter — lets adapters paint individual bytes into `out`
+ * without repeatedly importing `types.ts`'s `encodeBoardCell`.
+ *
+ * @param out Target 64-byte buffer.
+ * @param index LERF square index.
+ * @param cell The pre-encoded board cell value.
+ */
+declare function writeBoardCell(out: Uint8Array, index: SquareIndex, cell: BoardCell): void;
+
+/**
+ * Pointer-driven drag state machine.
+ *
+ * States: `idle → pending → dragging → idle`.
+ *
+ * - `pointerDown` on a source square moves us from `idle` to `pending`. We
+ *   don't commit to "this is a drag" yet — a tap that releases without moving
+ *   should remain a click.
+ * - Once the pointer has moved more than `activationDistance` pixels (default
+ *   `4`), we transition to `dragging` and emit a `drag-start` event. From
+ *   there, every `pointerMove` updates the live `(x, y)`.
+ * - `pointerUp` in `dragging` emits a `drop` event and returns to `idle`.
+ *   `pointerUp` in `pending` (no drag happened) returns to `idle` silently.
+ * - `cancel()` at any time returns to `idle` and emits a `cancel` event if a
+ *   drag or pending pick was in flight.
+ *
+ * Events other than `pointerDown` that arrive with the "wrong" `pointerId`
+ * are ignored — necessary on touch devices where multiple pointers may be
+ * live simultaneously.
+ *
+ * The controller is a pure reducer that returns its output events. It does
+ * **not** subscribe to the board model, and it performs zero DOM reads or
+ * writes. The React layer is responsible for wiring `PointerEvent`s to these
+ * methods and reacting to the returned events.
+ */
+
+/** Emitted when the pointer crosses `activationDistance` from its origin. */
+interface DragStartEvent {
+    readonly kind: "drag-start";
+    readonly from: SquareIndex;
+}
+/** Emitted while dragging, on every `pointerMove`. Coordinates are whatever
+ *  the caller passed in (no DOM awareness — typically `clientX`/`clientY`). */
+interface DragMoveEvent {
+    readonly kind: "drag-move";
+    readonly from: SquareIndex;
+    readonly x: number;
+    readonly y: number;
+}
+/** Emitted on `pointerUp` in `dragging`. `wasDrag` is always `true` here. */
+interface DropEvent {
+    readonly kind: "drop";
+    readonly from: SquareIndex;
+    readonly x: number;
+    readonly y: number;
+    readonly wasDrag: true;
+}
+/** Emitted on `pointerUp` in `pending` — the user clicked without dragging. */
+interface ClickEvent {
+    readonly kind: "click";
+    readonly from: SquareIndex;
+}
+/** Emitted by `cancel()` when a pending pick or an in-flight drag existed. */
+interface CancelEvent {
+    readonly kind: "cancel";
+    readonly from: SquareIndex;
+}
+/** Any event emitted by the drag controller. */
+type DragEvent = DragStartEvent | DragMoveEvent | DropEvent | ClickEvent | CancelEvent;
+/** Controller options. */
+interface DragControllerOptions {
+    /** Distance threshold (in CSS pixels) for `pending → dragging`. Default 4. */
+    readonly activationDistance?: number;
+}
+/** Public controller API. */
+interface DragController {
+    /** The current drag state. Read-only. */
+    readonly state: DragState;
+    /**
+     * Handle a pointer-down on a source square. Returns `true` if the event was
+     * consumed (i.e. we were `idle` and are now `pending`); `false` otherwise.
+     */
+    pointerDown(from: SquareIndex, pointerId: number, x: number, y: number): boolean;
+    /**
+     * Handle a pointer-move. Returns the emitted event (`drag-start` on the
+     * first crossing of the threshold, `drag-move` afterwards) or `null` if
+     * the move did not produce one.
+     */
+    pointerMove(pointerId: number, x: number, y: number): DragStartEvent | DragMoveEvent | null;
+    /**
+     * Handle a pointer-up. Returns `drop` when a drag was in flight, `click`
+     * when the user released without crossing the threshold, or `null` if the
+     * event does not concern us.
+     */
+    pointerUp(pointerId: number, x: number, y: number): DropEvent | ClickEvent | null;
+    /** Abort any pending or in-flight drag. Returns the emitted event, or
+     *  `null` if there was nothing to cancel. */
+    cancel(): CancelEvent | null;
+}
+/** Construct a fresh drag controller. */
+declare function createDragController(options?: DragControllerOptions): DragController;
+
+/**
+ * `hash()`-keyed LRU cache for `(position, from-square) → to-squares`.
+ *
+ * Every time the user picks up a piece we need the list of legal target squares
+ * to paint rings on the board. The engine's `legalMoves(from)` call is cheap
+ * but crosses the WASM boundary; caching on `engine.hash()` makes every repeat
+ * selection free.
+ *
+ * Keyed as `(hash << 6n) | BigInt(from)` — 70 bits total, carried as a single
+ * `bigint` key. LRU order is preserved by `Map` iteration order: on hit we
+ * `delete` + `set` to bump the entry to the most-recently-used end; on write
+ * past capacity we evict the oldest (the first key in iteration order).
+ */
+
+/** Lookup outcome from {@link LegalMoveIndex.get}. */
+type LegalMoveEntry = Readonly<Uint8Array>;
+/** Position hash representation: zero-BigInt { lo, hi } pair or bigint. */
+type PositionHash = bigint | ZobristKey;
+/** The cache API. */
+interface LegalMoveIndex {
+    /** Return cached target squares for `(hash, from)`, or `undefined` on miss. */
+    get(hash: PositionHash, from: SquareIndex): LegalMoveEntry | undefined;
+    /** Store target squares for `(hash, from)`. */
+    set(hash: PositionHash, from: SquareIndex, tos: Uint8Array): void;
+    /** Drop every entry. */
+    clear(): void;
+    /** Current number of entries. */
+    readonly size: number;
+    /** Configured maximum entry count. */
+    readonly capacity: number;
+    /** Cumulative hit count since construction (or last `resetStats`). */
+    readonly hits: number;
+    /** Cumulative miss count since construction (or last `resetStats`). */
+    readonly misses: number;
+    /** Reset `hits` / `misses` to zero. Does not affect stored entries. */
+    resetStats(): void;
+}
+/** Options for {@link createLegalMoveIndex}. */
+interface LegalMoveIndexOptions {
+    /** Maximum number of entries retained. Must be ≥ 1. Defaults to `1024`. */
+    readonly capacity?: number;
+}
+/** Create an LRU cache. */
+declare function createLegalMoveIndex(options?: LegalMoveIndexOptions): LegalMoveIndex;
+
+/**
+ * `useSyncExternalStore`-compatible store with byte-level per-square diff.
+ *
+ * Global listeners fire on every commit. Per-square listeners fire **only** when
+ * their byte of `snapshot.board` changed — so a move that touches 2–4 squares
+ * wakes only 2–4 Square components instead of all 64.
+ */
+
+/** Cleanup returned from a subscription. Idempotent. */
+type Unsubscribe = () => void;
+/** Internal listener type: a void-returning callback. */
+type Listener = () => void;
+/**
+ * The store API. Surface area is intentionally minimal; everything else lives
+ * in `board-model`.
+ */
+interface BoardStore {
+    /** Return the current frozen snapshot. Same reference between commits. */
+    getSnapshot(): BoardSnapshot;
+    /** Subscribe to every commit. Returns an unsubscribe function. */
+    subscribe(listener: Listener): Unsubscribe;
+    /**
+     * Subscribe to commits in which `board[index]` changed. Useful from a
+     * per-square React component via `useSyncExternalStore`.
+     */
+    subscribeSquare(index: SquareIndex, listener: Listener): Unsubscribe;
+    /**
+     * Install a new snapshot. Diffs `board` bytes against the previous snapshot
+     * and fires only the per-square listeners whose byte actually changed, plus
+     * every global listener.
+     *
+     * @remarks
+     * Callers must build a fresh snapshot object — mutating the previous one in
+     * place would make `getSnapshot()` return `=== previous`, which React treats
+     * as "no change" and skips the render.
+     */
+    commit(next: BoardSnapshot): void;
+}
+/** Create a new board store initialised with `initial`. */
+declare function createBoardStore(initial: BoardSnapshot): BoardStore;
+
+/**
+ * Board model: the orchestrator.
+ *
+ * Owns the engine adapter, the subscribe store, the legal-move cache, the
+ * arrow set, the premove buffer, and the redo stack. Every public action
+ * funnels here: `tryMove`, `undo`, `redo`, `goto`, `load`, `reset`,
+ * `selectSquare`, and arrow / premove mutators. Each action produces **at
+ * most one** snapshot commit so that React subscribers receive a single,
+ * coherent update per user intent.
+ *
+ * The model is intentionally framework-agnostic: no React, no DOM, no
+ * `useState`. Consumers drive it imperatively and subscribe to the store
+ * for state.
+ */
+
+/** Constructor options for {@link createBoardModel}. */
+interface BoardModelOptions {
+    /** Options forwarded to the legal-move cache. */
+    readonly legalMoveIndex?: LegalMoveIndexOptions;
+    /** Options forwarded to the drag controller. */
+    readonly dragController?: DragControllerOptions;
+    /**
+     * In development, freeze every emitted `BoardSnapshot` to catch accidental
+     * mutation. Defaults to `true` when `NODE_ENV !== "production"`. Turning
+     * this off is reserved for profiling; leave it alone otherwise.
+     */
+    readonly freezeSnapshots?: boolean;
+}
+/** Options for one coherent controlled-position update. */
+interface SyncPositionOptions {
+    /** FEN to load into the underlying engine. */
+    readonly fen: string;
+    /**
+     * Managed, application-owned arrows to install with the position. When
+     * omitted, managed arrows are left alone if the FEN is already current
+     * and cleared on a real position load, matching `load(fen)` semantics.
+     */
+    readonly managedArrows?: readonly Arrow[];
+    /**
+     * Preserve user-drawn arrows across a position load. Defaults to `false`
+     * because arrows usually describe the previous position.
+     */
+    readonly preserveUserArrows?: boolean;
+}
+/** The orchestrator API consumed by React. */
+interface BoardModel {
+    /** Current snapshot. Stable between commits. */
+    getSnapshot(): BoardSnapshot;
+    /** Subscribe to every commit. */
+    subscribe(listener: () => void): Unsubscribe;
+    /** Subscribe to commits that changed `board[index]`. */
+    subscribeSquare(index: SquareIndex, listener: () => void): Unsubscribe;
+    /** Select a square. Passing `null` clears the selection. No-op if unchanged. */
+    selectSquare(index: SquareIndex | null): void;
+    /** Attempt a move. Returns the packed move on success, `null` on illegal. */
+    tryMove(from: SquareIndex, to: SquareIndex, promotion?: PieceType): PackedMove | null;
+    /** Undo the most recent move. */
+    undo(): PackedMove | null;
+    /** Redo the most recently undone move. */
+    redo(): PackedMove | null;
+    /** Jump to ply `n` in the history (0 = initial position). */
+    goto(ply: number): void;
+    /** Load a FEN; clears history, redo, arrows, and premoves. */
+    load(fen: string): void;
+    /**
+     * Controlled-position sync for analysis/replay viewers. Loads the FEN
+     * and replaces the managed arrow subset in the same snapshot commit.
+     */
+    syncPosition(options: SyncPositionOptions): void;
+    /** Reset to the starting position; clears history, redo, arrows, premoves. */
+    reset(): void;
+    /** `true` if a move `from → to` (optionally promoting) is legal right now. */
+    isLegal(from: SquareIndex, to: SquareIndex, promotion?: PieceType): boolean;
+    /** Legal target squares from `from`, cached by position hash. */
+    legalFrom(from: SquareIndex): ReadonlySet<SquareIndex>;
+    addArrow(arrow: Arrow): void;
+    removeArrow(arrow: Arrow): void;
+    toggleArrow(arrow: Arrow): void;
+    /** Drop every arrow, managed or not. Nuclear option. */
+    clearArrows(): void;
+    /**
+     * Drop only **user-drawn** arrows (anything without `managed: true`).
+     * The board uses this for its click-to-dismiss behaviour so engine /
+     * app-owned hints survive user interaction.
+     */
+    clearUserArrows(): void;
+    /** Drop only **managed** arrows. Leaves user drawings untouched. */
+    clearManagedArrows(): void;
+    /**
+     * Atomic replace of the **entire** arrow set (managed and user). Use
+     * this when the board is a pure programmatic surface with no human
+     * drawing — a review / replay viewer, a puzzle diagram, tests.
+     *
+     * For analysis-style boards that stream engine hints alongside human
+     * arrow drawings, prefer {@link setManagedArrows}: it replaces only
+     * the managed subset and preserves whatever the user has drawn by
+     * right-clicking.
+     *
+     * @remarks
+     * Arrows whose identity tuple already exists are preserved by
+     * reference across the call, so React subscribers that compare
+     * per-arrow references skip unchanged entries. A true no-op (same set
+     * in the same order) commits nothing.
+     */
+    setArrows(arrows: readonly Arrow[]): void;
+    /**
+     * Atomic replace of **only** the managed subset. User-drawn arrows
+     * are untouched; every incoming arrow is implicitly marked
+     * `managed: true`. Idiomatic for engine-annotation feeds (Stockfish
+     * best-moves, multi-PV fans): the arrow set turns over as a whole per
+     * position without racing the user's right-click gesture.
+     *
+     * @example
+     * ```ts
+     * game.setManagedArrows(bestLine ? [uciToArrow(bestLine[0])] : []);
+     * ```
+     */
+    setManagedArrows(arrows: readonly Arrow[]): void;
+    queuePremove(premove: Premove): void;
+    clearPremoves(): void;
+    /** The drag controller; React layer binds pointer events to it. */
+    readonly drag: DragController;
+    /** Statistics view of the legal-move cache (for benchmarks). */
+    readonly legalMoveCache: LegalMoveIndex;
+    /** The underlying engine adapter, for escape-hatch callers. */
+    readonly engine: EngineAdapter;
+    /**
+     * The animation descriptors produced by the most recent commit. Empty on
+     * the initial snapshot. Consumed by the React layer's `useAnimation` hook.
+     */
+    readonly lastAnimations: readonly AnimDescriptor[];
+    /** Release engine resources and drop all subscriptions. */
+    dispose(): void;
+}
+/**
+ * Construct a board model around an engine adapter.
+ *
+ * The model does **not** create the adapter — the caller does.
+ * See `createGigachessAdapter` for standard adapter construction.
+ */
+declare function createBoardModel(engine: EngineAdapter, options?: BoardModelOptions): BoardModel;
+
+export { createDragController as $, type AnimDescriptor as A, BOARD_CELL_BB as B, type CancelEvent as C, type DragController as D, type EngineAdapter as E, type DragControllerOptions as F, type DragEvent as G, type DragMoveEvent as H, type DragStartEvent as I, type DragState as J, type DropEvent as K, type LegalMoveEntry as L, type LegalMoveIndex as M, type LegalMoveIndexOptions as N, MOVE2_PROMO_BISHOP as O, type PackedMove as P, MOVE2_PROMO_KNIGHT as Q, MOVE2_PROMO_NONE as R, type SquareIndex as S, MOVE2_PROMO_QUEEN as T, MOVE2_PROMO_ROOK as U, type PositionHash as V, type SyncPositionOptions as W, type Unsubscribe as X, createBoardModel as Y, type ZobristKey as Z, createBoardStore as _, PieceType as a, createLegalMoveIndex as a0, encodeBoardCell as a1, isEmptyCell as a2, isSquareIndex as a3, packMove as a4, toSquareIndex as a5, unpackMove as a6, writeBoardCell as a7, type Arrow as b, colorOf as c, type Premove as d, type ArrowCustomSvg as e, type ArrowLabel as f, BOARD_CELL_BK as g, BOARD_CELL_BN as h, BOARD_CELL_BP as i, BOARD_CELL_BQ as j, BOARD_CELL_BR as k, BOARD_CELL_EMPTY as l, BOARD_CELL_WB as m, BOARD_CELL_WK as n, BOARD_CELL_WN as o, pieceTypeOf as p, BOARD_CELL_WP as q, BOARD_CELL_WQ as r, BOARD_CELL_WR as s, type BoardCell as t, type BoardModel as u, type BoardModelOptions as v, type BoardSnapshot as w, type BoardStore as x, type ClickEvent as y, Color as z };

package/dist/canvas.cjs

@@ -0,0 +1,8 @@
+'use strict';
+
+// src/renderers/canvas.ts
+var CANVAS_RENDERER_VERSION = "0.0.0";
+
+exports.CANVAS_RENDERER_VERSION = CANVAS_RENDERER_VERSION;
+//# sourceMappingURL=canvas.cjs.map
+//# sourceMappingURL=canvas.cjs.map

package/dist/canvas.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/renderers/canvas.ts"],"names":[],"mappings":";;;AAYO,IAAM,uBAAA,GAA0B","file":"canvas.cjs","sourcesContent":["/**\n * gigaboard/canvas — opt-in full-canvas renderer.\n *\n * For stress use cases: very large boards (fairy chess), many simultaneous arrows,\n * or low-end devices where per-square DOM nodes become a cost. Drops some DOM\n * superpowers (ARIA grid, CSS theming of individual squares, `renderSquare` escape\n * hatches). The default DOM renderer is recommended for almost all applications.\n *\n * @remarks\n * Lands in M8 (post-1.0). This is a scaffolding placeholder.\n */\n\nexport const CANVAS_RENDERER_VERSION = \"0.0.0\";\n"]}