gigaboard 1.2.3

package/dist/index.d.ts

@@ -0,0 +1,435 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { C as ChessboardProps, T as Theme, O as Orientation, A as AnimationOptions, R as ResolvedArrowPalette, U as UseChessGameOptions, P as PieceRenderer } from './types-D5eBJGzj.js';
+export { a as ArrowColors, D as DEFAULT_MOVE_HAPTIC_PATTERNS, b as DEFAULT_MOVE_SOUND_SOURCES, H as HapticFeedbackOptions, L as LegalTargetStyle, M as MoveFeedbackKey, c as MoveHapticKey, d as MoveHapticOptions, e as MoveHapticPatterns, f as MoveSoundKey, g as MoveSoundOptions, h as MoveSoundSources, i as PositionTransition, j as PromotionContext, k as RanksPosition, S as SquareContext, l as TriggerMoveHaptic, m as TriggerMoveSound, n as classifyMoveFeedback, t as triggerHaptic, o as triggerMoveHaptic, u as useMoveHaptics, p as useMoveSound, w as warmupHaptics } from './types-D5eBJGzj.js';
+export { c as createGigachessAdapter, p as preloadGigachessAdapter } from './gigachess-DolQlR82.js';
+import { u as BoardModel, w as BoardSnapshot, S as SquareIndex, v as BoardModelOptions, P as PackedMove, t as BoardCell } from './board-model-BvJOtwQ3.js';
+export { z as Color, E as EngineAdapter, a as PieceType, Z as ZobristKey, Y as createBoardModel, a4 as packMove, a6 as unpackMove } from './board-model-BvJOtwQ3.js';
+import { RefObject, ReactNode } from 'react';
+export { HapticInput, TriggerOptions } from 'web-haptics';
+
+/**
+ * Interactive chess board.
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { Chessboard, useChessGame } from "gigaboard";
+ *
+ * export default function Board() {
+ *   const game = useChessGame();
+ *   return <Chessboard game={game} />;
+ * }
+ * ```
+ */
+declare function Chessboard(props: ChessboardProps): react_jsx_runtime.JSX.Element;
+
+/** Keys every Gigaboard board understands. */
+declare const CSS_VARS: {
+    readonly SQ_LIGHT: "--gb-sq-light";
+    readonly SQ_DARK: "--gb-sq-dark";
+    readonly LAST_MOVE: "--gb-last-move";
+    readonly SELECTED: "--gb-selected";
+    readonly LEGAL_TARGET: "--gb-legal-target";
+    readonly LEGAL_TARGET_CAPTURE: "--gb-legal-target-capture";
+    readonly CHECK: "--gb-check";
+    readonly COORDINATE_LIGHT: "--gb-coord-light";
+    readonly COORDINATE_DARK: "--gb-coord-dark";
+    /**
+     * Opacity of the piece left behind at the drag origin while the ghost
+     * is in flight. Default `0.35` (lichess parity). Themes may override
+     * to `0` for a chess.com-style "piece vanishes" effect.
+     */
+    readonly DRAG_GHOST_OPACITY: "--gb-drag-ghost-opacity";
+};
+declare const defaultTheme: Theme;
+/**
+ * Default arrow-channel colours. Close to lichess's palette so arrows feel
+ * familiar to players migrating over.
+ */
+declare const defaultArrowColors: Readonly<{
+    default: "rgba(21, 120, 27, 0.8)";
+    shift: "rgba(153, 40, 40, 0.8)";
+    alt: "rgba(230, 160, 0, 0.8)";
+    ctrl: "rgba(0, 60, 130, 0.8)";
+}>;
+/** Distinct blue tint used to preview pending premoves. */
+declare const DEFAULT_PREMOVE_TINT = "rgba(30, 98, 255, 0.4)";
+/** Red tint used to announce rejected moves. */
+declare const DEFAULT_ILLEGAL_FLASH_TINT = "rgba(220, 40, 40, 0.55)";
+
+/**
+ * WAAPI-driven FLIP animations for piece glides.
+ *
+ * ### Strategy
+ *
+ * After every model commit we know, via `model.lastAnimations`, what
+ * visually changed: a set of {@link AnimDescriptor}s describing `move`,
+ * `capture`, `en-passant`, `castle`, `promotion`, `appear`, or `disappear`.
+ *
+ * For each descriptor that has a source and a destination, we:
+ *
+ * 1. Compute the pixel displacement between the `from` and `to` squares.
+ * 2. Locate the destination `PieceSlot` DOM node (by `data-piece-square`).
+ * 3. Cancel any in-flight animation on that node.
+ * 4. Kick off a WAAPI animation whose first keyframe translates it back
+ *    to the source and whose last keyframe returns to identity.
+ *
+ * The animation runs entirely on the compositor — React never re-renders
+ * during the glide.
+ *
+ * ### FLIP invariants
+ *
+ * - Run inside `useLayoutEffect` so the transform is applied **before**
+ *   the browser paints, preventing a one-frame flash at the destination.
+ * - Skip animation when `prefers-reduced-motion: reduce` is set, or when
+ *   the caller's duration is zero.
+ * - Fall back silently if the destination DOM node is missing (e.g. the
+ *   piece-layer was reparented mid-animation) — never throw.
+ */
+
+/** Runtime hooks exposed to {@link useAnimation}'s caller. */
+interface UseAnimationRuntime {
+    /**
+     * Ref to a boolean flag. If `true` at commit time the next animation is
+     * skipped and the flag is reset to `false` automatically. Used by the
+     * drag handler to suppress the FLIP glide — for a drag-initiated move,
+     * the user has already placed the piece at the target, so animating
+     * from source → target reverses their action and looks jarring.
+     */
+    readonly skipNextRef?: RefObject<boolean>;
+}
+/** Props for {@link AnimationRunner}. */
+interface AnimationRunnerProps {
+    readonly model: BoardModel;
+    readonly containerRef: RefObject<HTMLElement | null>;
+    readonly orientation: Orientation;
+    readonly options?: AnimationOptions;
+    readonly runtime?: UseAnimationRuntime;
+}
+/**
+ * Sibling component that owns the animation subscription. Renders `null`;
+ * its only job is to translate a scalar slice change (`historyPly`) into
+ * a `useLayoutEffect` firing with the descriptors from the just-committed
+ * move. Because the subscription lives here — not in `<Chessboard/>` —
+ * the root board component no longer re-renders once per move.
+ */
+declare function AnimationRunner({ model, containerRef, orientation, options, runtime, }: AnimationRunnerProps): ReactNode;
+
+/** Shape rendered mid-gesture, before the user releases the button. */
+interface PreviewArrow {
+    readonly from: number;
+    readonly to: number;
+    readonly color: string;
+}
+/** Imperative API exposed by `<ArrowsLayer/>` to `useArrowGesture`. */
+interface ArrowsLayerHandle {
+    /** Update the preview arrow (null to clear) and redraw. */
+    setPreview(preview: PreviewArrow | null): void;
+}
+
+/**
+ * Right-click drawing gesture.
+ *
+ * Mirrors the left-click drag hook but listens only for the secondary
+ * button. On `pointerdown` we record the origin square. Each `pointermove`
+ * updates an in-flight preview arrow via `arrowsLayerRef.setPreview` —
+ * **zero React re-renders** per frame, the canvas repaints imperatively.
+ * On `pointerup` we commit the arrow through the board model's
+ * `toggleArrow` (identical start/end toggles the same-square mark).
+ *
+ * Also intercepts the browser context menu so right-click doesn't pop the
+ * OS menu.
+ */
+
+interface UseArrowGestureOptions {
+    readonly game: BoardModel | null;
+    readonly orientation: Orientation;
+    readonly containerRef: RefObject<HTMLElement | null>;
+    readonly arrowsLayerRef: RefObject<ArrowsLayerHandle | null>;
+    readonly enabled: boolean;
+    /** Fully-resolved colour palette (caller merges prop with defaults). */
+    readonly palette: ResolvedArrowPalette;
+    /**
+     * When `true`, an arrow endpoint that lies on a legal move target
+     * from the origin snaps to that target. Typical usage: analysis
+     * boards where the user wants to draw future-move hints that align
+     * with the rules. Default `false`.
+     */
+    readonly snapToValidMove?: boolean;
+}
+/**
+ * Install right-click pointer listeners. Returns nothing — the side effect
+ * is the listener registration. Gesture state lives entirely inside the
+ * effect's closure and is torn down on unmount / dep change.
+ */
+declare function useArrowGesture(options: UseArrowGestureOptions): void;
+
+/** Subscribe to the entire board snapshot. Wakes up on every commit. */
+declare function useBoardSnapshot(model: BoardModel): BoardSnapshot;
+/**
+ * Subscribe to a slice derived from the snapshot. Re-renders only when the
+ * selector's return value changes by `Object.is`.
+ *
+ * The selector is called on every `getSnapshot` tick, so it should be cheap
+ * (a field access) and must return a stable reference when the underlying
+ * data didn't change. Our snapshot store guarantees stability for primitive
+ * fields and for the `legalTargets` / `arrows` / `premoves` collections.
+ */
+declare function useBoardSlice<T>(model: BoardModel, selector: (snapshot: BoardSnapshot) => T): T;
+/**
+ * Subscribe to a single board byte via `subscribeSquare`. The component
+ * receives the byte's current value (0 for empty, 1–12 for a piece) and
+ * wakes up only when that byte changes.
+ *
+ * @remarks
+ * The returned value is a primitive number, so React's default `Object.is`
+ * bailout handles equality. The `useCallback` pins the subscribe function
+ * to `(model, index)` — a Square that re-renders for unrelated reasons
+ * doesn't force a re-subscription.
+ */
+declare function useSquareCell(model: BoardModel | null | undefined, index: SquareIndex): number;
+
+/**
+ * Allocate a board model bound to a fresh `gigachess` engine. The model
+ * is created synchronously on the initial render, lives for the lifetime of
+ * the calling component, and is disposed on unmount.
+ *
+ * @remarks
+ * Synchronous initialization on frame 0 ensures zero layout shift and 0 ms
+ * long tasks during mount. Changing `options.fen` disposes the current model
+ * and allocates a fresh one.
+ */
+declare function useChessGame(options?: UseChessGameOptions & BoardModelOptions): BoardModel;
+
+/**
+ * @param model The board model, or `null` while the engine is loading.
+ * @param onMove Optional callback fired on every successful move.
+ * @param onPromotionNeeded Optional deferred-promotion handler. When
+ *   provided, `tryMove` is not called — the caller resolves the promotion
+ *   piece and invokes `model.tryMove` itself.
+ * @param enabled Gate click-to-move. When `false` the returned callback
+ *   is a no-op — used by `viewOnly` boards and anywhere the caller needs
+ *   a stable identity while suppressing input. Defaults to `true`.
+ */
+declare function useClickToMove(model: BoardModel | null, onMove?: (m: PackedMove) => void, onPromotionNeeded?: (from: SquareIndex, to: SquareIndex) => void, enabled?: boolean): (index: SquareIndex) => void;
+
+/**
+ * Imperative handle exposed by {@link DragLayer}. `useDrag` uses these
+ * methods in its pointer handlers to show the ghost, move it, and hide
+ * it — all without triggering a React render.
+ */
+interface DragLayerHandle {
+    /** Reveal the ghost for the given piece cell (1..12). */
+    show(cell: BoardCell): void;
+    /** Hide the ghost. Safe to call while already hidden. */
+    hide(): void;
+    /** Write the ghost's transform. Called every pointer-move during a drag. */
+    setTransform(x: number, y: number): void;
+    /** Raw wrapper element — kept for legacy callers that measure geometry. */
+    element(): HTMLDivElement | null;
+}
+
+/**
+ * Pointer-driven drag orchestration.
+ *
+ * The hook attaches `pointerdown`/`pointermove`/`pointerup`/`pointercancel`
+ * listeners to a container ref and threads them through the drag state
+ * machine from `gigaboard/core`.
+ *
+ * ### Why event listeners on the container (not per square)
+ *
+ * We need a single source of truth for every pointer sample during a drag:
+ * the pointer naturally crosses square boundaries many times in a single
+ * drag. Attaching per-square `onPointerMove` handlers would register 64
+ * React listeners and re-subscribe every render. A single container
+ * listener is one registration that never re-subscribes.
+ *
+ * ### Zero React renders per frame during drag
+ *
+ * During the `dragging` state we never call `setState`. Instead the hook
+ * writes to `dragLayerRef.current.style.transform` in the pointer-move
+ * handler. React sees nothing change until drag-end, at which point one
+ * commit finishes the interaction (and the model's own commit renders the
+ * new position).
+ *
+ * ### Contract with the caller
+ *
+ * - Provide a `containerRef` to the outermost board container (has 1:1
+ *   geometry with the 8×8 grid).
+ * - Provide a `dragLayerRef` to the single absolutely-positioned element
+ *   that represents the floating piece; the hook writes its `transform`.
+ * - `onDragStart(from, cell)` is called once when the drag crosses the
+ *   activation threshold. The caller should render the piece into the
+ *   drag layer (via React state) and imperatively hide the origin.
+ * - `onDrop(from, to)` is called when a drop lands on a different square.
+ *   Illegal moves are the caller's problem — the hook merely reports the
+ *   user's intent.
+ * - `onDragEnd()` is called on every terminal transition (drop, cancel,
+ *   same-square drop). The caller restores DOM opacity and clears the
+ *   drag-layer render state.
+ */
+
+/** Options passed to {@link useDrag}. */
+interface UseDragOptions {
+    readonly game: BoardModel | null;
+    readonly orientation: Orientation;
+    readonly containerRef: RefObject<HTMLElement | null>;
+    /**
+     * Imperative handle to the always-mounted drag overlay. `useDrag`
+     * calls `show`, `setTransform`, and `hide` here from its pointer
+     * handlers — zero React state changes during the drag loop (and
+     * crucially, none at drag-start either).
+     */
+    readonly dragLayerRef: RefObject<DragLayerHandle | null>;
+    readonly enabled: boolean;
+    /** The activation distance (pixels) for `pending → dragging`. */
+    readonly activationDistance?: number;
+    /** Callbacks — see hook docs above. */
+    readonly onDragStart: (from: SquareIndex, cell: BoardCell) => void;
+    readonly onDragEnd: () => void;
+    readonly onDrop: (from: SquareIndex, to: SquareIndex) => void;
+    /**
+     * Optional per-piece gate. If provided and it returns `false` for the
+     * would-be drag source, pointer-down is silently ignored and no drag
+     * initiates. Called once per attempt, never during a drag.
+     */
+    readonly canDragPiece?: (ctx: {
+        readonly square: SquareIndex;
+        readonly cell: BoardCell;
+    }) => boolean;
+}
+/**
+ * Install pointer listeners for drag-and-drop. Listeners stay registered for
+ * the lifetime of the containing component.
+ */
+declare function useDrag(options: UseDragOptions): void;
+
+/**
+ * Per-square pointer-hover tracker.
+ *
+ * One `pointermove` + `pointerleave` listener on the container diffs the
+ * current square against the previous, firing `onEnter`/`onLeave` once
+ * per transition. Attaching handlers per-square would cost 64 React
+ * listeners and break the "0 re-renders per hover" budget
+ * (STANDARDS.md §4.2).
+ *
+ * Callbacks read through latest-refs so a fresh arrow function each
+ * render doesn't re-install the effect.
+ */
+
+/** Context passed to hover callbacks. */
+interface HoverSquareContext {
+    readonly square: SquareIndex;
+    readonly cell: BoardCell;
+}
+/** Options for {@link useHoverSquare}. */
+interface UseHoverSquareOptions {
+    readonly game: BoardModel | null;
+    readonly orientation: Orientation;
+    readonly containerRef: RefObject<HTMLElement | null>;
+    readonly enabled: boolean;
+    readonly onEnter?: (ctx: HoverSquareContext) => void;
+    readonly onLeave?: (ctx: HoverSquareContext) => void;
+}
+declare function useHoverSquare(options: UseHoverSquareOptions): void;
+
+/**
+ * Keyboard navigation for the 8×8 grid.
+ *
+ * Implements the WAI-ARIA "Grid" authoring pattern:
+ *
+ * - Tab brings focus to the board via a roving tabindex — only the
+ *   currently-focused square has `tabindex=0`; every other cell has
+ *   `tabindex=-1`, so Tab moves straight out of the grid once the user
+ *   is done.
+ * - Arrow keys move the focus between squares (visual up/down/left/right,
+ *   orientation-aware).
+ * - Enter / Space activate the focused square (same path as a mouse click).
+ * - Escape clears the selection + any drawn arrows.
+ * - Home / End jump to the first / last square in the focused rank.
+ * - Ctrl+Home / Ctrl+End jump to the first / last square on the board.
+ *
+ * The hook is controlled: the caller owns `focusedSquare` state. This
+ * lets {@link Chessboard} integrate the keyboard focus with other
+ * board-level state (selection, drag, promotion dialog).
+ */
+
+/** Options accepted by {@link useKeyboardNav}. */
+interface UseKeyboardNavOptions {
+    readonly containerRef: RefObject<HTMLElement | null>;
+    readonly orientation: Orientation;
+    readonly focusedSquare: SquareIndex | null;
+    readonly setFocusedSquare: (square: SquareIndex) => void;
+    readonly onActivate: (square: SquareIndex) => void;
+    readonly onEscape: () => void;
+    readonly enabled: boolean;
+}
+/**
+ * Attach keyboard navigation listeners to the board container. All motion
+ * is expressed via `setFocusedSquare` — the render layer is responsible
+ * for applying `tabindex` and programmatic focus based on that state.
+ */
+declare function useKeyboardNav(options: UseKeyboardNavOptions): void;
+
+/**
+ * Board geometry helpers.
+ *
+ * Pure, framework-agnostic utilities for mapping between viewport pixel
+ * coordinates and `SquareIndex` (LERF 0..63). Single source of truth
+ * consumed by {@link useDrag}, {@link useArrowGesture}, the spare-piece
+ * drag hook, and any consumer who wants to hit-test the board from
+ * custom React code (analysis overlays, piece tooltips, screenshots).
+ *
+ * No DOM mutation; no side effects. Each call reads
+ * `container.getBoundingClientRect()` once — cheap but not free, so
+ * hot-path callers should batch calls per pointer event.
+ */
+
+/**
+ * Resolve a viewport point to the `SquareIndex` it lies inside, or
+ * `null` when the point is outside the board rect.
+ *
+ * The hit-test assumes the container has 1:1 geometry with the 8×8 grid
+ * — i.e. the outer `<div>` of `<Chessboard/>`. Coordinates/edge padding
+ * layers do **not** sit inside a smaller sub-rect; they're overlays on
+ * the same box.
+ *
+ * @param container The board container element.
+ * @param clientX   `MouseEvent.clientX` / `PointerEvent.clientX`.
+ * @param clientY   `MouseEvent.clientY` / `PointerEvent.clientY`.
+ * @param orientation Board orientation (flips file/rank derivation).
+ * @returns The square under the point, or `null` if out of bounds.
+ */
+declare function getSquareAtPoint(container: HTMLElement, clientX: number, clientY: number, orientation: Orientation): SquareIndex | null;
+/**
+ * Inverse of {@link getSquareAtPoint}: the viewport point at the centre
+ * of a given square, expressed in client (viewport) coordinates.
+ *
+ * Useful for drawing tooltips, floating annotations, or anchoring DOM
+ * nodes against a specific square without sampling the actual DOM child.
+ *
+ * @param container The board container element.
+ * @param square    Square index in LERF order.
+ * @param orientation Board orientation.
+ * @returns `{ x, y }` in viewport pixel coordinates.
+ */
+declare function getPointAtSquareCentre(container: HTMLElement, square: SquareIndex, orientation: Orientation): {
+    readonly x: number;
+    readonly y: number;
+};
+
+declare const defaultPieces: PieceRenderer;
+
+/**
+ * `gigaboard` — ultra-fast interactive React chessboard.
+ *
+ * Hand-curated barrel; sub-modules are never re-exported wholesale so
+ * consumers can tree-shake aggressively.
+ *
+ * Server-only entry (static SSR board, zero client JS): `gigaboard/server`.
+ */
+
+/** Package version — keep in sync with `package.json`. */
+declare const PACKAGE_VERSION = "0.1.0-alpha";
+
+export { AnimationOptions, AnimationRunner, BoardCell, BoardModel, BoardSnapshot, CSS_VARS, Chessboard, ChessboardProps, DEFAULT_ILLEGAL_FLASH_TINT, DEFAULT_PREMOVE_TINT, type HoverSquareContext, Orientation, PACKAGE_VERSION, PackedMove, PieceRenderer, ResolvedArrowPalette, SquareIndex, Theme, UseChessGameOptions, defaultArrowColors, defaultPieces, defaultTheme, getPointAtSquareCentre, getSquareAtPoint, useArrowGesture, useBoardSlice, useBoardSnapshot, useChessGame, useClickToMove, useDrag, useHoverSquare, useKeyboardNav, useSquareCell };