hyperchess-wasm 0.1.0

package/README.md

@@ -0,0 +1,35 @@
+# hyperchess-wasm
+
+A thin JS/TS wrapper around `crates/hyperchess-wasm` compiled to WebAssembly — **not** a
+separate implementation of the game rules or the 3D renderer. This package has no Rust source
+of its own; `npm run build` (or `../../scripts/build-wasm-sdk.sh` directly) compiles that
+crate for three targets:
+
+| Export | wasm-pack target | Use case |
+| --- | --- | --- |
+| `hyperchess-wasm` | `bundler` | apps importing this through webpack/vite/etc. |
+| `hyperchess-wasm/nodejs` | `nodejs` | server-side consumers (e.g. an HTMX backend) |
+| `hyperchess-wasm/web` | `web` | plain `<script type="module">`, no bundler |
+
+All three expose:
+- **`WasmBoard`** — rules + search bindings (`from_hfen`, `legal_moves`, `apply_move`, `hfen`,
+  `termination`, `encode`, every searcher entry point). Consumed today by `hyperchess-core`.
+- **`Scene3D`** — WebGPU/WebGL board/piece renderer, taking `WasmBoard::encode()`'s 144-byte
+  board format directly. Not yet consumed by any package here — `hyperchess-board-3d`
+  (extraction plan §12 Phase 8) will wrap it.
+
+**GPLv3, not MIT** (unlike `hyperchess-core`/`board`/`store`/`theme`) — this package's `.wasm`
+binary directly contains the compiled rules+search engine, so it's a GPL derivative by
+construction. Bundling it directly into an app's own bundle makes that app a GPL derivative
+too; consuming it via a Web Worker (`postMessage`) or over the network (the API driver) does
+not — see the extraction plan §4/§5 for the full reasoning and the recommended integration
+patterns.
+
+See `docs/sdk-plan/WASM-MIGRATION-PLAN.md` (carried over from the source repo, historical
+context only) for why this package exists and what still used the hand-written TypeScript
+rules engine in `hyperchess-core` before it was replaced by a wrapper around this package.
+
+**Known trade-off:** the compiled `.wasm` is ~4.5MB because `Scene3D`'s `wgpu` dependency
+compiles into the same binary as `WasmBoard`, even for consumers who only need 2D rules
+validation — see `crates/hyperchess-wasm/docs/README.md` for the full discussion and the
+proposed Phase 8 fix (a Cargo feature split).

package/dist/bundler/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/bundler/hyperchess_wasm.d.ts

@@ -0,0 +1,229 @@
+/* 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;

package/dist/bundler/hyperchess_wasm.js

@@ -0,0 +1,9 @@
+/* @ts-self-types="./hyperchess_wasm.d.ts" */
+import * as wasm from "./hyperchess_wasm_bg.wasm";
+import { __wbg_set_wasm } from "./hyperchess_wasm_bg.js";
+
+__wbg_set_wasm(wasm);
+wasm.__wbindgen_start();
+export {
+    Scene3D, WasmBoard, calibrate_piece, init
+} from "./hyperchess_wasm_bg.js";