hyperchess-wasm 0.1.0

package/dist/nodejs/hyperchess_wasm_bg.wasm.d.ts

@@ -0,0 +1,56 @@
+/* tslint:disable */
+/* eslint-disable */
+export const memory: WebAssembly.Memory;
+export const __wbg_wasmboard_free: (a: number, b: number) => void;
+export const calibrate_piece: (a: number, b: number, c: number, d: number, e: number) => number;
+export const wasmboard_adjudicate_material: (a: number) => number;
+export const wasmboard_apply_move: (a: number, b: number, c: number) => number;
+export const wasmboard_best_move: (a: number, b: number) => [number, number];
+export const wasmboard_best_move_guided: (a: number, b: number) => [number, number];
+export const wasmboard_best_move_guided_iterative: (a: number, b: number) => [number, number];
+export const wasmboard_best_move_iterative: (a: number, b: number) => [number, number];
+export const wasmboard_best_move_mcts: (a: number, b: number) => [number, number];
+export const wasmboard_best_move_pro: (a: number, b: number) => [number, number];
+export const wasmboard_best_move_strategic: (a: number, b: number) => [number, number];
+export const wasmboard_best_move_timed: (a: number, b: number, c: number, d: number) => [number, number];
+export const wasmboard_best_move_timed_profile: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number];
+export const wasmboard_encode: (a: number) => [number, number];
+export const wasmboard_from_hfen: (a: number, b: number) => number;
+export const wasmboard_hfen: (a: number) => [number, number];
+export const wasmboard_in_check: (a: number) => number;
+export const wasmboard_is_game_over: (a: number) => number;
+export const wasmboard_king_square: (a: number) => number;
+export const wasmboard_legal_moves: (a: number) => [number, number];
+export const wasmboard_new: () => number;
+export const wasmboard_result: (a: number) => number;
+export const wasmboard_result_adjudicated: (a: number, b: number) => number;
+export const wasmboard_set_hfen_history: (a: number, b: number, c: number) => void;
+export const wasmboard_termination: (a: number) => [number, number];
+export const wasmboard_turn: (a: number) => [number, number];
+export const wasmboard_set_search_history: (a: number, b: number, c: number) => void;
+export const __wbg_scene3d_free: (a: number, b: number) => void;
+export const init: () => void;
+export const scene3d_animate_move: (a: number, b: number, c: number) => void;
+export const scene3d_create: (a: any) => any;
+export const scene3d_is_animating: (a: number) => number;
+export const scene3d_orbit: (a: number, b: number, c: number) => void;
+export const scene3d_pick: (a: number, b: number, c: number) => number;
+export const scene3d_render: (a: number) => void;
+export const scene3d_resize: (a: number, b: number, c: number) => void;
+export const scene3d_set_board: (a: number, b: number, c: number, d: number) => void;
+export const scene3d_set_selection: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+export const scene3d_zoom: (a: number, b: number) => void;
+export const wasm_bindgen__convert__closures_____invoke__hb0b40ee7dfd77fc5: (a: number, b: number, c: any) => [number, number];
+export const wasm_bindgen__convert__closures_____invoke__h050ffcb604d90a8a: (a: number, b: number, c: any) => [number, number];
+export const wasm_bindgen__convert__closures_____invoke__h050ffcb604d90a8a_2: (a: number, b: number, c: any) => [number, number];
+export const wasm_bindgen__convert__closures_____invoke__h050ffcb604d90a8a_3: (a: number, b: number, c: any) => [number, number];
+export const wasm_bindgen__convert__closures_____invoke__h73e935f3b365ecab: (a: number, b: number, c: any, d: any) => void;
+export const __wbindgen_malloc: (a: number, b: number) => number;
+export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+export const __wbindgen_exn_store: (a: number) => void;
+export const __externref_table_alloc: () => number;
+export const __wbindgen_externrefs: WebAssembly.Table;
+export const __wbindgen_free: (a: number, b: number, c: number) => void;
+export const __wbindgen_destroy_closure: (a: number, b: number) => void;
+export const __externref_table_dealloc: (a: number) => void;
+export const __wbindgen_start: () => void;

package/dist/nodejs/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "hyperchess-wasm",
+  "description": "HyperChess WASM bindings — WasmBoard (rules+search, from src/hyperchess/src/wasm.rs) and Scene3D (WebGPU/WebGL board renderer, from the former standalone hyperchess_3d crate), one wasm-pack build target",
+  "version": "0.1.0",
+  "license": "GPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/KyrpyDev/hyperchess-core"
+  },
+  "files": [
+    "hyperchess_wasm_bg.wasm",
+    "hyperchess_wasm.js",
+    "hyperchess_wasm.d.ts"
+  ],
+  "main": "hyperchess_wasm.js",
+  "homepage": "https://github.com/KyrpyDev/hyperchess-core",
+  "types": "hyperchess_wasm.d.ts",
+  "keywords": [
+    "chess",
+    "wasm",
+    "webgpu",
+    "hyperchess"
+  ]
+}

package/dist/web/README.md

@@ -0,0 +1,37 @@
+# hyperchess-wasm
+
+Two independent wasm-bindgen surfaces, one wasm-pack build target:
+
+- **`WasmBoard`** — rules + search bindings (legal moves, apply-move, every searcher entry
+  point). Depends on `hyperchess-rules` + `hyperchess-search`.
+- **`Scene3D`** — WebGPU/WebGL board/piece renderer. Zero dependency on the rules engine —
+  takes a 144-byte board encoding as raw bytes (the same format `WasmBoard::encode()`
+  produces), not a `Board` reference. The two communicate via that shared byte protocol, not
+  Rust-level coupling.
+
+The source repo keeps these as genuinely separate crates/build pipelines (`src/hyperchess`
+built directly with `--features wasm`, and a standalone `hyperchess_3d` consumed only by the
+private web app's own hand-loaded WASM, never integrated into the npm SDK workspace). Merging
+them here is a deliberate improvement, not a copy of existing structure — see
+[`docs/hyperchess-core-extraction-plan.md`](../../../docs/hyperchess-core-extraction-plan.md)
+§12 Phase 6. It's also why `hyperchess-rules`/`hyperchess-search` have no wasm-bindgen
+dependency of their own (Phase 1/3) — that lives only here, in the crate whose whole purpose
+is WASM bindings.
+
+`geometry`/`pieces` are plain portable math, native-buildable, and used by the `gen_assets`
+dev-tool binary (`cargo run --bin gen_assets`) as well as the wasm32-only renderer — everything
+else here (`board`, `camera`, `gpu`, `obj`, `scene`) is `#[cfg(target_arch = "wasm32")]`, so a
+plain `cargo build`/`cargo test` (no wasm32 target) only touches the portable half.
+
+## Known trade-off: bundle size
+
+Verified via a real `wasm-pack build --target nodejs` + Node.js smoke test (not just
+`cargo build`): the resulting `.wasm` binary is **~4.5MB**, because `wgpu` (pulled in for
+`Scene3D`) compiles into the same module as `WasmBoard`, even for consumers who only want 2D
+legal-move validation and never touch the 3D renderer. The source repo's `hyperchess-wasm`
+package (rules-only, no 3D) was necessarily smaller. This is the direct cost of the "one
+wasm-pack build target" merge decision (§12 Phase 6) — worth reconsidering once
+`packages/board-3d` (§12 Phase 8) is built: a `scene3d` Cargo feature gating `wgpu`/`camera`/
+`gpu`/`obj`/`scene` out of the default build would let a `WasmBoard`-only consumer opt out of
+the 3D weight, at the cost of no longer being strictly "one build for everything." Flagged as
+an open item, not solved here.

package/dist/web/hyperchess_wasm.d.ts

@@ -0,0 +1,310 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * JS-facing handle. Board state is a 144-byte array: 0 = empty, else
+ * `(color << 4) | kind` with kind 1..=8 indexing
+ * `[pawn, knight, bishop, rook, queen, king, eagle, hawk]` and color
+ * 0 = white, 1 = black (see `board3d.js` for the encoder).
+ */
+export class Scene3D {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Starts a glide animation for the piece on `from` moving to `to`. Call
+     * this *before* `set_board` with the post-move position — it snapshots
+     * the pre-move board to know what to animate (and what's being captured).
+     */
+    animate_move(from: number, to: number): void;
+    /**
+     * Creates the renderer against the given canvas. Async because adapter/device
+     * acquisition is a browser Promise under the hood. JS calls this as a static
+     * factory (`await Scene3D.create(canvas)`), not `new Scene3D(...)`.
+     */
+    static create(canvas: HTMLCanvasElement): Promise<Scene3D>;
+    /**
+     * True while a move animation is still in flight — keep calling
+     * `render()` on every frame until this goes false, then it's fine to
+     * idle the render loop until the next interaction.
+     */
+    is_animating(): boolean;
+    /**
+     * Rotate the camera around the board by a *delta* in radians;
+     * pitch is clamped internally so the camera cannot flip over the pole.
+     */
+    orbit(dyaw: number, dpitch: number): void;
+    /**
+     * Canvas-space pixel coordinates -> square index (0-143), or -1 if off-board.
+     */
+    pick(x: number, y: number): number;
+    /**
+     * Draw one frame. JS drives the render loop, so this must be called
+     * from `requestAnimationFrame` — the renderer never schedules itself.
+     */
+    render(): void;
+    /**
+     * Match the swapchain to a new canvas size, in physical pixels.
+     */
+    resize(width: number, height: number): void;
+    /**
+     * `board` must be exactly 144 bytes (see the encoding note on `Scene3D`).
+     */
+    set_board(board: Uint8Array, flipped: boolean): void;
+    /**
+     * `-1` means "none" for `selected`/`last_from`/`last_to`/`checked_king`.
+     */
+    set_selection(selected: number, legal: Uint8Array, last_from: number, last_to: number, checked_king: number): void;
+    /**
+     * Scale the camera distance by `factor` (`>1` pulls back, `<1` moves
+     * in), clamped to the scene's usable range.
+     */
+    zoom(factor: number): void;
+}
+
+/**
+ * JS-facing wrapper around a [`Board`].
+ *
+ * Every method takes and returns plain strings or primitives rather than
+ * exposing engine types across the wasm boundary, so the JS side never needs
+ * to mirror the Rust move or piece encodings.
+ */
+export class WasmBoard {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Material-only adjudication of the current position: 1 = White wins,
+     * 2 = Black wins, 3 = draw (within one pawn of equal material).
+     */
+    adjudicate_material(): number;
+    /**
+     * Apply a move given as a UCI string. Returns false if the move is not legal.
+     */
+    apply_move(uci: string): boolean;
+    /**
+     * Run alpha-beta search at the given depth and return the best move as UCI.
+     * Returns an empty string if there are no legal moves.
+     */
+    best_move(depth: number): string;
+    /**
+     * Compatibility guided alpha-beta label. Uses the canonical timed search.
+     */
+    best_move_guided(depth: number): string;
+    /**
+     * Compatibility guided iterative label. Uses the canonical timed search.
+     */
+    best_move_guided_iterative(depth: number): string;
+    /**
+     * Run iterative deepening (with transposition table) at the given depth.
+     * Better than `best_move` for the same depth budget — TT avoids re-searching
+     * positions seen at shallower iterations.
+     */
+    best_move_iterative(depth: number): string;
+    /**
+     * Run MCTS with the given number of simulations and return the best move as UCI.
+     * Returns an empty string if there are no legal moves.
+     */
+    best_move_mcts(simulations: number): string;
+    /**
+     * Run the "aggressive" profile (PVS, aspiration windows and the
+     * speculative pruning family — reverse futility, frontier futility, delta
+     * pruning). The strongest fixed-depth option.
+     */
+    best_move_pro(depth: number): string;
+    /**
+     * Run the stronger strategic-style tactical profile.
+     */
+    best_move_strategic(depth: number): string;
+    /**
+     * Anytime iterative-deepening search with a **wall-clock budget** (and an
+     * optional node cap as a deterministic backstop).
+     *
+     * This is the recommended interactive search: it deepens until `max_depth`,
+     * the time budget, or the node cap is hit, then returns the best move from the
+     * deepest *completed* depth. The search watches the clock itself
+     * (`js_sys::Date::now()`) — essential in the browser, where JS cannot interrupt
+     * a running synchronous WASM call, so an external timeout would never fire.
+     *
+     * * `movetime_ms == 0` → no time cap.
+     * * `node_limit == 0`  → no node cap.
+     *   (At least one of `movetime_ms` / `node_limit` / a small `max_depth` should
+     *   be set, or the search runs to `max_depth` which may be very deep.)
+     */
+    best_move_timed(max_depth: number, movetime_ms: number, node_limit: number): string;
+    /**
+     * Anytime search with a wall-clock budget under a named profile:
+     * `"balanced"` (default), `"strategic"`, or `"aggressive"`. Same anytime semantics
+     * as [`Self::best_move_timed`] — this is what interactive strategic/aggressive
+     * callers should use so the computed move timeout is actually honoured
+     * (the fixed-depth `best_move_strategic` / `best_move_pro` wrappers ignore it).
+     */
+    best_move_timed_profile(max_depth: number, movetime_ms: number, node_limit: number, profile: string): string;
+    /**
+     * Returns the board as a 144-byte Uint8Array for WebGPU evaluation.
+     * Each byte is the Piece discriminant: 0=empty, 1-8=white, 9-16=black.
+     * Piece order: P=1, N=2, B=3, R=4, Q=5, K=6, Eagle=7, Hawk=8 (+ 8 for black).
+     */
+    encode(): Uint8Array;
+    /**
+     * Create a board from a HFEN string. Returns null on parse error.
+     */
+    static from_hfen(hfen: string): WasmBoard | undefined;
+    /**
+     * Returns the current position as a HFEN string.
+     */
+    hfen(): string;
+    /**
+     * Returns true if the side to move is currently in check.
+     */
+    in_check(): boolean;
+    /**
+     * Returns true if the game has ended (checkmate, stalemate, or draw).
+     */
+    is_game_over(): boolean;
+    /**
+     * Returns the square index (0-143) of the king for the side to move, or 255 if not found.
+     */
+    king_square(): number;
+    /**
+     * Returns all legal moves as a space-separated UCI string (e.g. "a3a4 b3b4 ...").
+     */
+    legal_moves(): string;
+    /**
+     * Create a board at the starting position.
+     */
+    constructor();
+    /**
+     * Returns the game result: 0=ongoing, 1=white wins, 2=black wins, 3=draw.
+     */
+    result(): number;
+    /**
+     * [`Self::result`] with material adjudication for move-limit endings:
+     * a draw by the internal no-progress rule — and, when `capped` is true, an
+     * ongoing position stopped by an external per-game move cap — is decided
+     * by material (≥ 1 pawn wins) instead of collapsing to a draw. Genuine
+     * draws (stalemate, repetition, insufficient material) are unchanged.
+     */
+    result_adjudicated(capped: boolean): number;
+    /**
+     * Populate game history for draw-rule and search repetition checks.
+     *
+     * Contract (see `Board::repetition_count`): `history` stores **prior**
+     * positions only. Callers pass the full ordered HFEN list of the game
+     * (typically including the current position last); a trailing entry equal
+     * to the current position is dropped so it is never double-counted.
+     * Threefold then fires at `repetition_count() >= 2` (2 prior + current).
+     */
+    set_hfen_history(hfens: string): void;
+    /**
+     * Alias of [`Self::set_hfen_history`] — kept for older callers. Both draw
+     * rules and search now share the same prior-positions-only contract.
+     */
+    set_search_history(hfens: string): void;
+    /**
+     * Returns why the game ended: "checkmate", "stalemate", "move_limit",
+     * "fivefold_repetition", "threefold_repetition", "insufficient_material", or
+     * "ongoing". Delegates to `Board::termination_reason`, the single source of
+     * truth also used by the server's termination endpoint, so the WASM/local-game
+     * path reports the same specific reason as server-backed games.
+     */
+    termination(): string;
+    /**
+     * Returns whose turn it is: "white" or "black".
+     */
+    turn(): string;
+}
+
+/**
+ * Which new piece to calibrate.  JS passes `"eagle"` or `"hawk"`.
+ */
+export function calibrate_piece(piece: string, games: number, depth: number, max_half_moves: number): number;
+
+/**
+ * Single combined init for both wasm-bindgen surfaces in this crate —
+ * wasm-bindgen only allows one `#[wasm_bindgen(start)]` function per
+ * crate. Merges what were two separate inits in the source repo
+ * (`hyperchess::wasm`'s panic hook + `Helper::init()`, and
+ * `hyperchess_3d`'s panic hook + `console_log` setup).
+ */
+export function init(): void;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_wasmboard_free: (a: number, b: number) => void;
+    readonly calibrate_piece: (a: number, b: number, c: number, d: number, e: number) => number;
+    readonly wasmboard_adjudicate_material: (a: number) => number;
+    readonly wasmboard_apply_move: (a: number, b: number, c: number) => number;
+    readonly wasmboard_best_move: (a: number, b: number) => [number, number];
+    readonly wasmboard_best_move_guided: (a: number, b: number) => [number, number];
+    readonly wasmboard_best_move_guided_iterative: (a: number, b: number) => [number, number];
+    readonly wasmboard_best_move_iterative: (a: number, b: number) => [number, number];
+    readonly wasmboard_best_move_mcts: (a: number, b: number) => [number, number];
+    readonly wasmboard_best_move_pro: (a: number, b: number) => [number, number];
+    readonly wasmboard_best_move_strategic: (a: number, b: number) => [number, number];
+    readonly wasmboard_best_move_timed: (a: number, b: number, c: number, d: number) => [number, number];
+    readonly wasmboard_best_move_timed_profile: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number];
+    readonly wasmboard_encode: (a: number) => [number, number];
+    readonly wasmboard_from_hfen: (a: number, b: number) => number;
+    readonly wasmboard_hfen: (a: number) => [number, number];
+    readonly wasmboard_in_check: (a: number) => number;
+    readonly wasmboard_is_game_over: (a: number) => number;
+    readonly wasmboard_king_square: (a: number) => number;
+    readonly wasmboard_legal_moves: (a: number) => [number, number];
+    readonly wasmboard_new: () => number;
+    readonly wasmboard_result: (a: number) => number;
+    readonly wasmboard_result_adjudicated: (a: number, b: number) => number;
+    readonly wasmboard_set_hfen_history: (a: number, b: number, c: number) => void;
+    readonly wasmboard_termination: (a: number) => [number, number];
+    readonly wasmboard_turn: (a: number) => [number, number];
+    readonly wasmboard_set_search_history: (a: number, b: number, c: number) => void;
+    readonly __wbg_scene3d_free: (a: number, b: number) => void;
+    readonly init: () => void;
+    readonly scene3d_animate_move: (a: number, b: number, c: number) => void;
+    readonly scene3d_create: (a: any) => any;
+    readonly scene3d_is_animating: (a: number) => number;
+    readonly scene3d_orbit: (a: number, b: number, c: number) => void;
+    readonly scene3d_pick: (a: number, b: number, c: number) => number;
+    readonly scene3d_render: (a: number) => void;
+    readonly scene3d_resize: (a: number, b: number, c: number) => void;
+    readonly scene3d_set_board: (a: number, b: number, c: number, d: number) => void;
+    readonly scene3d_set_selection: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly scene3d_zoom: (a: number, b: number) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__hb0b40ee7dfd77fc5: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h050ffcb604d90a8a: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h050ffcb604d90a8a_2: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h050ffcb604d90a8a_3: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h73e935f3b365ecab: (a: number, b: number, c: any, d: any) => void;
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_exn_store: (a: number) => void;
+    readonly __externref_table_alloc: () => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_destroy_closure: (a: number, b: number) => void;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;