gigaboard 1.2.3

package/dist/types-D5eBJGzj.d.ts

@@ -0,0 +1,501 @@
+import { ReactNode, CSSProperties } from 'react';
+import { u as BoardModel, b as Arrow, t as BoardCell, S as SquareIndex, P as PackedMove, a as PieceType, z as Color } from './board-model-BvJOtwQ3.js';
+import { TriggerOptions, HapticInput } from 'web-haptics';
+
+interface HapticFeedbackOptions extends TriggerOptions {
+    /** Master switch. Default `true`. */
+    readonly enabled?: boolean;
+    /** Restrict haptics to coarse-pointer/mobile-like devices. Default `true`. */
+    readonly mobileOnly?: boolean;
+}
+declare function triggerHaptic(input?: HapticInput, options?: HapticFeedbackOptions): void;
+declare function warmupHaptics(options?: HapticFeedbackOptions): void;
+
+/** The shared move-feedback cue categories. */
+type MoveFeedbackKey = "moveSelf" | "moveOpponent" | "capture" | "castle" | "moveCheck" | "promote" | "gameEnd";
+/** Default haptic pattern per move-feedback cue. */
+declare const DEFAULT_MOVE_HAPTIC_PATTERNS: Readonly<Record<MoveFeedbackKey, HapticInput>>;
+/**
+ * Classify the feedback cue that should fire for the given committed move.
+ *
+ * Priority (highest wins):
+ *   1. `gameEnd` if the engine reports `isGameOver`.
+ *   2. `promote` / `castle` because structural moves get their own cue.
+ *   3. `moveCheck` if the side-to-move is now in check.
+ *   4. `capture` if any descriptor is a capture.
+ *   5. `moveSelf` / `moveOpponent` otherwise.
+ */
+declare function classifyMoveFeedback(animations: ReadonlyArray<{
+    readonly kind: string;
+}>, snapshot: {
+    readonly isGameOver: boolean;
+    readonly inCheck: boolean;
+    readonly turn: 0 | 1;
+}, perspective: 0 | 1 | undefined): MoveFeedbackKey;
+
+type MoveHapticKey = MoveFeedbackKey;
+type MoveHapticPatterns = Partial<Readonly<Record<MoveHapticKey, HapticInput>>>;
+type TriggerMoveHaptic = (key: MoveHapticKey) => void;
+interface MoveHapticOptions {
+    /** Master switch. Default `true`. */
+    readonly enabled?: boolean;
+    /** Per-key haptic overrides. Missing keys fall back to the built-in pattern map. */
+    readonly patterns?: MoveHapticPatterns;
+    /**
+     * Viewer perspective. When set, moves played by this colour use `moveSelf`
+     * and moves played by the opponent use `moveOpponent`.
+     */
+    readonly perspective?: 0 | 1;
+    /** Restrict haptics to coarse-pointer/mobile-like devices. Default `true`. */
+    readonly mobileOnly?: boolean;
+    /** Minimum gap between emitted haptic events. Default `14ms`. */
+    readonly minIntervalMs?: number;
+    /** Warm the haptic backend on the first user gesture. Default `true`. */
+    readonly warmupOnFirstInteraction?: boolean;
+    /** Forwarded to `web-haptics` trigger intensity. */
+    readonly intensity?: HapticFeedbackOptions["intensity"];
+}
+declare function triggerMoveHaptic(key: MoveHapticKey, { enabled, patterns, mobileOnly, intensity, }?: Pick<MoveHapticOptions, "enabled" | "patterns" | "mobileOnly" | "intensity">): void;
+declare function useMoveHaptics(model: BoardModel | null, options?: MoveHapticOptions): TriggerMoveHaptic;
+
+/** The seven categories of move cue, mirroring chess.com's default set. */
+type MoveSoundKey = MoveFeedbackKey;
+/** Sparse URL map — any key omitted falls back to the built-in local asset. */
+type MoveSoundSources = Partial<Readonly<Record<MoveSoundKey, string>>>;
+type TriggerMoveSound = (key: MoveSoundKey) => void;
+/**
+ * Default URL map. Points at the MP3 files shipped with this package; the
+ * package build copies them next to the emitted JS under `dist/sounds/`.
+ * Keeping these as static `new URL(..., import.meta.url)` expressions lets
+ * consumer bundlers such as Vite and Next.js rebase/copy the files correctly.
+ *
+ * The `typeof import.meta.url` guard keeps the CommonJS build importable in
+ * Node; browser ESM consumers get the fully resolved asset URLs.
+ */
+declare const DEFAULT_MOVE_SOUND_SOURCES: Readonly<Record<MoveSoundKey, string>>;
+/** Public configuration for the hook (and the `<Chessboard sound/>` prop). */
+interface MoveSoundOptions {
+    /** Master switch. Default `true`. */
+    readonly enabled?: boolean;
+    /** Output volume, `0`–`1`. Default `1`. */
+    readonly volume?: number;
+    /** Audio preload mode used when the lazy pool is first created. Default `"none"`. */
+    readonly preload?: "none" | "metadata" | "auto";
+    /** Per-key URL overrides. Missing keys fall back to {@link DEFAULT_MOVE_SOUND_SOURCES}. */
+    readonly sources?: MoveSoundSources;
+    /**
+     * Viewer perspective. When set, moves played *by* this colour use the
+     * `moveSelf` cue and moves played by the opponent use `moveOpponent`. When
+     * omitted (the default), every non-special move uses `moveSelf`.
+     */
+    readonly perspective?: 0 | 1;
+}
+/**
+ * Drop-in hook. Mount inside a React tree that has a `BoardModel`. Pass
+ * `null` while the engine is still loading — the hook no-ops until the
+ * model is available.
+ *
+ * @example
+ * ```tsx
+ * useMoveSound(game, { enabled: soundOn, volume: 0.6 });
+ * ```
+ */
+declare function useMoveSound(model: BoardModel | null, options?: MoveSoundOptions): TriggerMoveSound;
+
+/**
+ * Public types for `gigaboard`.
+ *
+ * These describe the prop surface a consumer sees when they import
+ * `<Chessboard/>` or any of the exposed hooks. Runtime helpers live with
+ * their respective modules; this file is types-only.
+ */
+
+/** Which way the board is facing. */
+type Orientation = "white" | "black";
+/** CSS custom-property record (e.g. `{ "--gb-sq-light": "#f0d9b5" }`). */
+type Theme = Readonly<Record<string, string>>;
+/** How legal-target squares are visualised when a piece is selected. */
+type LegalTargetStyle = "rings" | "dots" | false;
+/**
+ * Edge the rank labels (1–8) are rendered against. `"left"` matches
+ * lichess and our historic default; `"right"` matches chess.com.
+ */
+type RanksPosition = "left" | "right";
+/**
+ * Renderer for a single piece. Given the packed board cell and its square,
+ * return a React node positioned inside a 12.5% × 12.5% slot of the board.
+ *
+ * @remarks
+ * Renderers must be pure and referentially stable — returning a new element
+ * tree on every call forces per-commit re-rendering. Prefer memoised results
+ * or stateless SVG/Unicode glyphs.
+ */
+type PieceRenderer = (args: {
+    readonly cell: BoardCell;
+    readonly square: SquareIndex;
+}) => ReactNode;
+/** Context passed to a user-supplied `renderSquare` override. */
+interface SquareContext {
+    readonly index: SquareIndex;
+    readonly isLight: boolean;
+    readonly label: string;
+}
+/** Context passed to a user-supplied `onPromote` callback. */
+interface PromotionContext {
+    readonly from: SquareIndex;
+    readonly to: SquareIndex;
+    /** Colour of the promoting pawn (0 = white, 1 = black). */
+    readonly color: 0 | 1;
+}
+/**
+ * Configuration for the piece-glide animations played after every move.
+ *
+ * Animations run entirely on the compositor via the Web Animations API —
+ * they never re-enter React. Honours `prefers-reduced-motion: reduce` by
+ * collapsing the duration to zero regardless of the configured value.
+ */
+interface AnimationOptions {
+    /** Glide duration in ms. Default `60`. Set to `0` to disable. */
+    readonly durationMs?: number;
+    /** CSS easing curve. Default `cubic-bezier(0.22, 0.61, 0.36, 1)` (ease-out). */
+    readonly easing?: string;
+}
+/**
+ * Hint for animating an externally-controlled FEN change.
+ *
+ * `uci` is the move that connects the old and new positions. `direction`
+ * says whether the board is replaying that move or rewinding it. `key`
+ * can be supplied by callers that replay the same UCI more than once in a
+ * line; when omitted, the current `positionFen` still participates in the
+ * effect identity.
+ */
+interface PositionTransition {
+    /** UCI move such as `"e2e4"`, `"e7e8q"`, or castling as `"e1g1"`. */
+    readonly uci: string;
+    /** Direction of travel for replay controls. */
+    readonly direction: "forward" | "backward";
+    /** Optional stable identity for this specific transition. */
+    readonly key?: string;
+}
+/**
+ * CSS colour strings for the four stock right-click-arrow channels
+ * plus any number of user-defined brushes. Modifier keys still map to
+ * the built-in channels at draw time:
+ *
+ *   (no modifier) → `default`
+ *   Shift         → `shift`
+ *   Alt           → `alt`
+ *   Ctrl / Meta   → `ctrl`
+ *
+ * Programmatic arrows (engine annotations via `model.setArrows`, for
+ * instance) can set `arrow.brush = "<key>"` to resolve against any
+ * other key in the palette. Unknown keys fall through to `default`.
+ */
+interface ArrowColors {
+    readonly default?: string;
+    readonly shift?: string;
+    readonly alt?: string;
+    readonly ctrl?: string;
+    /** Any additional palette entry — keyed by the arrow's `brush` field. */
+    readonly [brush: string]: string | undefined;
+}
+/**
+ * Fully-resolved palette consumed by the arrow renderer. The four
+ * modifier channels are guaranteed (defaults applied); user-defined
+ * brushes live alongside with whatever keys the caller supplied.
+ */
+interface ResolvedArrowPalette {
+    readonly default: string;
+    readonly shift: string;
+    readonly alt: string;
+    readonly ctrl: string;
+    readonly [brush: string]: string;
+}
+/** Props accepted by the top-level `<Chessboard/>` component. */
+interface ChessboardProps {
+    /**
+     * The board model produced by {@link useChessGame}. Pass `null` during
+     * initial async engine load — the board renders a visually-identical but
+     * pieceless placeholder. Provide {@link fallbackFen} in addition to
+     * render pieces from that FEN until the real engine arrives.
+     */
+    readonly game: BoardModel | null;
+    /**
+     * Starting-position FEN to render as a static fallback while `game`
+     * is `null`. When supplied, the board paints pieces from this FEN on
+     * the very first commit — no wait for a `useEffect`, no engine
+     * dependency. Once the real `game` resolves the interactive piece
+     * layer takes over without a layout shift (identical DOM shape).
+     *
+     * Only the placement field of the FEN is consumed; side-to-move,
+     * castling flags, and clocks are ignored (they have no visual
+     * effect). Defaults to `undefined`, in which case a `null` `game`
+     * renders a pieceless board.
+     *
+     * Useful for avoiding the "flash of empty board" on cold mount when
+     * the engine is loaded asynchronously (e.g. dynamic-import + WASM
+     * streaming compile).
+     */
+    readonly fallbackFen?: string;
+    /**
+     * Declarative FEN for controlled boards and replay/analysis viewers.
+     *
+     * When supplied, `<Chessboard/>` keeps the provided {@link game} synced
+     * to this FEN by calling `game.load(positionFen)` internally. This is a
+     * programmatic position sync, so it does not call {@link onMove}; user
+     * moves still go through `tryMove` and fire `onMove` normally.
+     *
+     * For adjacent replay steps, pass {@link positionTransition} so the board
+     * can glide the moved piece instead of snapping between FENs.
+     */
+    readonly positionFen?: string;
+    /**
+     * Optional move hint used to animate a `positionFen` sync. Consumers should
+     * pass this for previous/next buttons, PGN scrubbing, and analysis-line
+     * replay where the model is being loaded from external FEN snapshots.
+     */
+    readonly positionTransition?: PositionTransition | null;
+    /**
+     * Application-owned arrows to sync with {@link positionFen}. When supplied,
+     * the board applies the FEN and these managed arrows in one model commit,
+     * avoiding an intermediate "position loaded, arrows cleared" frame.
+     *
+     * Pass `[]` to explicitly clear managed arrows for the current position.
+     * User-drawn arrows remain governed by
+     * {@link preserveUserArrowsOnPositionSync}.
+     */
+    readonly managedArrows?: readonly Arrow[];
+    /**
+     * Preserve user-drawn arrows when a controlled {@link positionFen} changes.
+     * Defaults to `false`, matching the existing `load(fen)` behaviour.
+     */
+    readonly preserveUserArrowsOnPositionSync?: boolean;
+    /** Board orientation (defaults to `"white"`). */
+    readonly orientation?: Orientation;
+    /**
+     * Theme as a CSS custom-property record. Import from `gigaboard/themes/*`.
+     * When omitted the default green theme from `gigaboard/themes` is applied.
+     */
+    readonly theme?: Theme;
+    /**
+     * Piece renderer. Defaults to the `neo` set from `gigaboard/pieces`.
+     */
+    readonly pieces?: PieceRenderer;
+    /** Show algebraic coordinate labels on the edges. Default `true`. */
+    readonly showCoordinates?: boolean;
+    /**
+     * Edge against which rank labels (1–8) are rendered. Default `"left"`
+     * (lichess convention); switch to `"right"` to match chess.com. The
+     * file labels (a–h) always sit on the bottom edge; this prop doesn't
+     * affect them.
+     */
+    readonly ranksPosition?: RanksPosition;
+    /** Style for legal-target square highlights. Default `"rings"`. */
+    readonly showLegalTargets?: LegalTargetStyle;
+    /** Highlight the from / to squares of the most recent move. Default `true`. */
+    readonly highlightLastMove?: boolean;
+    /** Called after every successful move; receives the packed `Move`. */
+    readonly onMove?: (move: PackedMove) => void;
+    /**
+     * Called when a pawn needs to promote. Return (or resolve) the chosen
+     * {@link PieceType}. If omitted, the built-in promotion overlay is shown.
+     *
+     * The returned promise may be rejected (e.g. user clicks outside the
+     * dialog) — in that case the move is abandoned and the board returns to
+     * the pre-drag state.
+     */
+    readonly onPromote?: (ctx: PromotionContext) => PieceType | Promise<PieceType>;
+    /** Animation configuration. Passes through to the WAAPI glide runner. */
+    readonly animation?: AnimationOptions;
+    /**
+     * Whether drag-and-drop is enabled. When `false`, click-to-move still
+     * works but the board ignores pointer-down initiated drags. Default `true`.
+     */
+    readonly allowDrag?: boolean;
+    /**
+     * Fine-grained predicate consulted at the drag-activation boundary —
+     * returning `false` aborts the drag before the ghost appears. Use this
+     * for per-piece gating that can't be modelled by `allowDrag` or the
+     * turn-to-move check: tutorial boards ("you can only move white"),
+     * locked pieces in puzzle trainers, or rating-gated moves in online
+     * play.
+     *
+     * @remarks
+     * Fires once per drag attempt, not per pointer sample — the check
+     * sits on the cold drag-start path. Click-to-move is unaffected;
+     * gate that at the `onMove` callback if the same policy should apply.
+     */
+    readonly canDragPiece?: (ctx: {
+        readonly square: SquareIndex;
+        readonly cell: BoardCell;
+    }) => boolean;
+    /**
+     * Fired when the pointer enters a new square. Fires at most once per
+     * square transition — moving across the board yields `leave(old)`
+     * followed by `enter(new)`. Pointer events so both mouse and touch
+     * report consistently.
+     */
+    readonly onSquareMouseEnter?: (ctx: {
+        readonly square: SquareIndex;
+        readonly cell: BoardCell;
+    }) => void;
+    /**
+     * Fired when the pointer leaves a square — either crossing into a
+     * sibling square or exiting the board rect. Pairs with
+     * {@link onSquareMouseEnter} transition-for-transition.
+     */
+    readonly onSquareMouseLeave?: (ctx: {
+        readonly square: SquareIndex;
+        readonly cell: BoardCell;
+    }) => void;
+    /**
+     * Enable drawing arrows via right-click drag. Default `true`.
+     * Modifier keys select colour channels (see {@link ArrowColors}).
+     */
+    readonly allowDrawingArrows?: boolean;
+    /**
+     * Clear every drawn arrow when the engine accepts a new move. Default
+     * `true` — matches the lichess / chess.com convention.
+     */
+    readonly clearArrowsOnMove?: boolean;
+    /**
+     * Clear every drawn arrow when the user makes any left-pointer
+     * interaction with the board (click or drag start) or presses Escape.
+     * Default `true`. This is how lichess and react-chessboard behave: the
+     * user's next action is treated as "moving on" from any annotations.
+     */
+    readonly clearArrowsOnClick?: boolean;
+    /** Per-channel arrow colour overrides. */
+    readonly arrowColors?: ArrowColors;
+    /**
+     * When drawing arrows by right-click drag, snap the endpoint to the
+     * nearest legal move target from the origin square. Useful for
+     * analysis boards and tutorial UIs where annotations should line up
+     * with real moves. Default `false`.
+     *
+     * @remarks
+     * Same-square marks (circles) are never snapped. When the origin
+     * has no legal moves (empty square, or pinned piece), the endpoint
+     * is left as-is.
+     */
+    readonly snapArrowsToValidMove?: boolean;
+    /**
+     * Queue moves attempted when it's not your turn as premoves instead of
+     * rejecting them. **Default `false`** — premoves are an online-play
+     * affordance, and in local / analysis / tutorial boards the ghost-piece
+     * overlay is more confusing than helpful (looks like the board accepted
+     * a move it shouldn't have).
+     *
+     * Enable explicitly in networked UIs where the opponent's move is
+     * pending. When disabled (default), out-of-turn drags flash red via
+     * {@link showIllegalFlash} the same way any other illegal move does.
+     */
+    readonly allowPremove?: boolean;
+    /**
+     * Paint a red glow under the king when the side-to-move is in check.
+     * Default `true`.
+     */
+    readonly showCheckHighlight?: boolean;
+    /**
+     * Suppress the browser's right-click context menu over the board.
+     * Default `true` — the right-click gesture is reserved for drawing
+     * arrows (see {@link allowDrawingArrows}) and the OS menu would
+     * steal the trailing `pointerup`. Set to `false` only if you need
+     * the browser menu for a custom interaction.
+     *
+     * @remarks
+     * The listener is installed on the board container only; right-clicks
+     * outside the board behave normally. Works independently of
+     * `allowDrawingArrows` so consumers can disable arrows but still block
+     * the OS menu.
+     */
+    readonly disableContextMenu?: boolean;
+    /**
+     * Briefly flash the origin square red when the engine rejects a user
+     * move. Default `true`. Respects `prefers-reduced-motion`.
+     */
+    readonly showIllegalFlash?: boolean;
+    /**
+     * Escape hatch for custom per-square overlays. The callback receives the
+     * square's coordinate and colour and must return a React node that will
+     * render inside the square (absolute-positioned, covering 100% × 100%).
+     */
+    readonly renderSquare?: (ctx: SquareContext) => ReactNode;
+    /**
+     * Optional container style overrides. Applied to the outermost board
+     * element; CSS variables injected by the theme are written on the same
+     * element so inline styles declared here can reference them.
+     */
+    readonly style?: CSSProperties;
+    /** Optional class name on the outer container. */
+    readonly className?: string;
+    /** Accessible label for the board (`aria-label`). Default "Chess board". */
+    readonly ariaLabel?: string;
+    /**
+     * Read-only board. Disables every user-input subsystem at once —
+     * drag, click-to-move, keyboard navigation, arrow drawing — while
+     * preserving the accessible live region, highlights, animations,
+     * coordinates, and check glow. Use this for PGN viewers, position
+     * diagrams, and any surface where the board is purely declarative.
+     *
+     * Equivalent to setting `allowDrag={false}`, `allowDrawingArrows=
+     * {false}`, and wiring a no-op click handler, collapsed into a single
+     * switch that also removes the board from the keyboard tab order.
+     * Default `false`.
+     *
+     * @remarks
+     * The roving-tabindex seed is suppressed while `viewOnly` is true, so
+     * no square receives `tabindex=0` and the grid is skipped entirely by
+     * the browser's focus ring. Programmatic arrow placement (e.g. engine
+     * annotations via `model.addArrow`) continues to paint normally.
+     */
+    readonly viewOnly?: boolean;
+    /**
+     * Move-sound effects. Pass `true` (default) to enable the built-in
+     * chess.com-style cue set, `false` to disable, or a {@link MoveSoundOptions}
+     * object to configure volume, per-key URL overrides, or viewer perspective.
+     *
+     * The seven cues ship as local MP3 assets inside this package; no runtime
+     * CDN dependency. Autoplay policies apply on every major browser — the
+     * first cue may be silent until the user has interacted with the page,
+     * after which playback is immediate.
+     */
+    readonly sound?: boolean | MoveSoundOptions;
+    /**
+     * Move haptic feedback. Pass `true` to enable mobile-only haptics, `false`
+     * (default) to disable, or a {@link MoveHapticOptions} object to configure
+     * per-cue patterns, intensity, viewer perspective, and mobile-only gating.
+     *
+     * Haptics are independent from sound, so consumers can keep `sound={false}`
+     * while still providing tactile feedback on mobile devices.
+     */
+    readonly haptics?: boolean | MoveHapticOptions;
+    /**
+     * Custom accessible label generator for squares.
+     * Allows consumers (e.g. BlindBase) to supply localized, piece-aware
+     * speech descriptions for screen readers.
+     */
+    readonly getSquareAriaLabel?: (square: SquareIndex, cell: BoardCell) => string;
+    /**
+     * Fired when a board square receives keyboard or programmatic focus.
+     * Can be used to pipe focus events into external speech queues.
+     */
+    readonly onSquareFocus?: (square: SquareIndex, cell: BoardCell) => void;
+    /**
+     * Custom accessible label generator for promotion overlay pieces.
+     * Supports multi-language (Russian, Hebrew, English, etc.) screen-reader announcements.
+     */
+    readonly getPromotionPieceAriaLabel?: (piece: PieceType, color: Color) => string;
+}
+/** Options forwarded to {@link useChessGame} on first mount. */
+interface UseChessGameOptions {
+    /**
+     * Initial engine FEN. Defaults to `gigachess`'s standard starting
+     * position. This is a lifecycle input: changing it disposes the current
+     * model and creates a fresh one. For replay/analysis viewers, keep the
+     * model stable and drive `<Chessboard positionFen={...} />` instead.
+     */
+    readonly fen?: string;
+}
+
+export { type AnimationOptions as A, type ChessboardProps as C, DEFAULT_MOVE_HAPTIC_PATTERNS as D, type HapticFeedbackOptions as H, type LegalTargetStyle as L, type MoveFeedbackKey as M, type Orientation as O, type PieceRenderer as P, type ResolvedArrowPalette as R, type SquareContext as S, type Theme as T, type UseChessGameOptions as U, type ArrowColors as a, DEFAULT_MOVE_SOUND_SOURCES as b, type MoveHapticKey as c, type MoveHapticOptions as d, type MoveHapticPatterns as e, type MoveSoundKey as f, type MoveSoundOptions as g, type MoveSoundSources as h, type PositionTransition as i, type PromotionContext as j, type RanksPosition as k, type TriggerMoveHaptic as l, type TriggerMoveSound as m, classifyMoveFeedback as n, triggerMoveHaptic as o, useMoveSound as p, triggerHaptic as t, useMoveHaptics as u, warmupHaptics as w };