hyperchess-core 0.1.0

package/dist/wasm/engine.js

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// HyperChess Core — hyperchess-core
+// File: packages/core/src/wasm/engine.ts
+// Version: 1.0.0
+// Copyright (c) 2026 HyperChess Developer Team
+import { WasmBoard } from 'hyperchess-wasm';
+export { snapshotFromWasmBoard, moveToUci, uciToMove } from './snapshot';
+/**
+ * Loads a `WasmBoard` from the Rust engine — starting position if `hfen` is
+ * omitted, or parses `hfen` (throws via wasm-pack's `Option::None` → JS
+ * `undefined` if it's invalid; callers should check).
+ *
+ * Imports from the package root, not a specific wasm-pack target subpath:
+ * `hyperchess-wasm`'s package.json resolves this to the `nodejs` target
+ * under Node (loads synchronously via `fs`) and the `bundler` target
+ * everywhere else (a real bundler's module graph resolution is already
+ * async, so no explicit init call is needed here either — see
+ * docs/sdk-plan/WASM-MIGRATION-PLAN.md Phase 5).
+ *
+ * NOT usable for a bundler-free browser deployment (a bare
+ * `<script type="module">` import with no build step) — the `bundler`
+ * target this resolves to there fails to even load (it does a raw
+ * `import ... from "./x.wasm"`, which needs a bundler to handle). See
+ * `../standalone.ts` for that case instead, which uses the `web` target
+ * with an explicit async init and deliberately does NOT import this module.
+ */
+export function loadWasmBoard(hfen) {
+    if (!hfen) {
+        return new WasmBoard();
+    }
+    const board = WasmBoard.from_hfen(hfen);
+    if (!board) {
+        throw new Error(`Invalid HFEN: ${hfen}`);
+    }
+    return board;
+}
+//# sourceMappingURL=engine.js.map

package/dist/wasm/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/wasm/engine.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,oCAAoC;AACpC,yCAAyC;AACzC,iBAAiB;AACjB,+CAA+C;AAE/C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EAAE,qBAAqB,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEzE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAAC,IAAa;IACzC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,IAAI,SAAS,EAAE,CAAC;IACzB,CAAC;IACD,MAAM,KAAK,GAAG,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/wasm/snapshot.d.ts

@@ -0,0 +1,47 @@
+import { Board } from '../types/board';
+import { Move } from '../types/move';
+/**
+ * The subset of `WasmBoard`'s instance API these helpers need, expressed as
+ * a minimal structural interface rather than importing `hyperchess-wasm`'s
+ * own type. That keeps this module free of any dependency on a specific
+ * wasm-pack target, so both `wasm/engine.ts` (the main, Node/bundler-backed
+ * synchronous API) and `standalone.ts` (the no-bundler-browser async API)
+ * can share it without either pulling in the other's WASM loading strategy.
+ */
+export interface WasmBoardLike {
+    /** Pack the piece placement into one byte per square, where 0 means empty
+     * and the remaining values encode colour and piece type. */
+    encode(): Uint8Array;
+    /** Render the position as a HFEN string, the source of the fields
+     * (side to move, castling, en passant, clocks) that `encode()` omits. */
+    hfen(): string;
+}
+/**
+ * Build a plain-JS `Board` snapshot from a `WasmBoard`-like instance.
+ *
+ * `Board` stays a plain data object (not the opaque WASM handle) so existing
+ * direct property access across the SDK (`board.pieces[i]`, `board.toMove`,
+ * etc. — used throughout `hyperchess-board`'s hooks and elsewhere) keeps
+ * working unchanged. The HFEN's own metadata fields (side to move, castling,
+ * en passant, clocks) are re-derived from `wasmBoard.hfen()` — the engine's
+ * own canonical output — rather than trusting whatever HFEN the caller passed
+ * in, so the snapshot always reflects what Rust actually parsed.
+ */
+export declare function snapshotFromWasmBoard(wasmBoard: WasmBoardLike, history?: Board['history']): Board;
+/**
+ * Convert a structured `Move` to the UCI string `WasmBoard.apply_move`
+ * expects (source + destination algebraic squares, plus a lowercase
+ * promotion letter — matching `HyperMove::stringify()` in the Rust engine;
+ * no `=` separator, unlike this SDK's own algebraic/HSAN notation).
+ */
+export declare function moveToUci(move: Move): string;
+/**
+ * Parse a UCI move string (as returned by `WasmBoard.legal_moves()`) into a
+ * structured `Move`, inferring `isCastling`/`isEnPassant` from board context
+ * — the UCI string alone doesn't flag these (it's just src+dst+promo), so
+ * they're derived the same way the old hand-written move generator did: a
+ * king moving 2 files is always castling (its only 2-file move), and a pawn
+ * capturing onto the recorded en passant square is always en passant.
+ */
+export declare function uciToMove(uci: string, board: Board): Move;
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/wasm/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/wasm/snapshot.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,EAAkB,MAAM,gBAAgB,CAAC;AAEvD,OAAO,EAAE,IAAI,EAAkB,MAAM,eAAe,CAAC;AAKrD;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B;gEAC4D;IAC5D,MAAM,IAAI,UAAU,CAAC;IAErB;6EACyE;IACzE,IAAI,IAAI,MAAM,CAAC;CAChB;AA6BD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,aAAa,EAAE,OAAO,GAAE,KAAK,CAAC,SAAS,CAAM,GAAG,KAAK,CA4CrG;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAG5C;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAqBzD"}

package/dist/wasm/snapshot.js

@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// HyperChess Core — hyperchess-core
+// File: packages/core/src/wasm/snapshot.ts
+// Version: 1.0.0
+// Copyright (c) 2026 HyperChess Developer Team
+import { algebraicToSquare, squareToAlgebraic } from '../utils/square-notation';
+import { parseHfenPosition } from '../board/hfen';
+/** Piece type in `WasmBoard.encode()`'s byte order (index 0 unused — 0 means empty). */
+const ENCODE_PIECE_ORDER = ['P', 'N', 'B', 'R', 'Q', 'K', 'E', 'H'];
+function decodePieceByte(byte) {
+    if (byte === 0)
+        return undefined;
+    const color = byte <= 8 ? 'white' : 'black';
+    const type = ENCODE_PIECE_ORDER[(byte <= 8 ? byte : byte - 8) - 1];
+    return { type, color };
+}
+function parseCastlingRights(castlingStr) {
+    return {
+        whiteKingSide: castlingStr.includes('K'),
+        whiteQueenSide: castlingStr.includes('Q'),
+        blackKingSide: castlingStr.includes('k'),
+        blackQueenSide: castlingStr.includes('q'),
+    };
+}
+/** Parse an en passant square (e.g. "e3", "-" for none) from a HFEN field. */
+function parseEnPassant(enPassantStr) {
+    if (enPassantStr === '-')
+        return -1;
+    const match = enPassantStr.match(/^([a-l])(1[0-2]|[1-9])$/);
+    if (!match)
+        return -1;
+    return algebraicToSquare(match[1] + match[2]);
+}
+/**
+ * Build a plain-JS `Board` snapshot from a `WasmBoard`-like instance.
+ *
+ * `Board` stays a plain data object (not the opaque WASM handle) so existing
+ * direct property access across the SDK (`board.pieces[i]`, `board.toMove`,
+ * etc. — used throughout `hyperchess-board`'s hooks and elsewhere) keeps
+ * working unchanged. The HFEN's own metadata fields (side to move, castling,
+ * en passant, clocks) are re-derived from `wasmBoard.hfen()` — the engine's
+ * own canonical output — rather than trusting whatever HFEN the caller passed
+ * in, so the snapshot always reflects what Rust actually parsed.
+ */
+export function snapshotFromWasmBoard(wasmBoard, history = []) {
+    const hfen = wasmBoard.hfen();
+    const hfenParts = hfen.split(' ');
+    const [positionStr, toMoveStr, castlingStr, enPassantStr, halfmoveStr, fullmoveStr] = hfenParts;
+    // Piece placement comes from `encode()` (one byte per square: colour +
+    // current type), which is authoritative for *what* each piece is but knows
+    // nothing about *which* piece it is. Identity is recovered from the
+    // engine's own HFEN-I position field and merged in, so the snapshot — and
+    // therefore everything `getBoardHfen` later re-serializes — keeps it.
+    //
+    // `encode()` stays the source of truth for type and colour; the parsed
+    // position only contributes the identity character. That way a disagreement
+    // between the two cannot change the position, and a legacy type-only HFEN
+    // simply contributes no identity at all.
+    const pieces = Array.from(wasmBoard.encode()).map(decodePieceByte);
+    let identities;
+    try {
+        identities = parseHfenPosition(positionStr);
+    }
+    catch {
+        // A position field the engine emitted but this parser cannot read is not
+        // worth failing the snapshot over — the board is still correct, it just
+        // carries no identity. (The Rust side is the canonical parser.)
+        identities = undefined;
+    }
+    if (identities) {
+        for (let sq = 0; sq < pieces.length; sq++) {
+            const identity = identities[sq]?.identity;
+            const piece = pieces[sq];
+            if (piece && identity) {
+                pieces[sq] = { ...piece, identity };
+            }
+        }
+    }
+    return {
+        pieces,
+        toMove: toMoveStr === 'w' ? 'white' : 'black',
+        enPassantSquare: parseEnPassant(enPassantStr),
+        castlingRights: parseCastlingRights(castlingStr),
+        halfmoveClock: parseInt(halfmoveStr, 10),
+        fullmoveNumber: parseInt(fullmoveStr || '1', 10),
+        history,
+    };
+}
+/**
+ * Convert a structured `Move` to the UCI string `WasmBoard.apply_move`
+ * expects (source + destination algebraic squares, plus a lowercase
+ * promotion letter — matching `HyperMove::stringify()` in the Rust engine;
+ * no `=` separator, unlike this SDK's own algebraic/HSAN notation).
+ */
+export function moveToUci(move) {
+    const promo = move.promotion ? move.promotion.toLowerCase() : '';
+    return `${squareToAlgebraic(move.from)}${squareToAlgebraic(move.to)}${promo}`;
+}
+/**
+ * Parse a UCI move string (as returned by `WasmBoard.legal_moves()`) into a
+ * structured `Move`, inferring `isCastling`/`isEnPassant` from board context
+ * — the UCI string alone doesn't flag these (it's just src+dst+promo), so
+ * they're derived the same way the old hand-written move generator did: a
+ * king moving 2 files is always castling (its only 2-file move), and a pawn
+ * capturing onto the recorded en passant square is always en passant.
+ */
+export function uciToMove(uci, board) {
+    const match = uci.match(/^([a-l](?:1[0-2]|[1-9]))([a-l](?:1[0-2]|[1-9]))([qrbneh])?$/);
+    if (!match) {
+        throw new Error(`Invalid UCI move string: ${uci}`);
+    }
+    const from = algebraicToSquare(match[1]);
+    const to = algebraicToSquare(match[2]);
+    const promotion = match[3] ? match[3].toUpperCase() : undefined;
+    const piece = board.pieces[from];
+    const move = { from, to, promotion };
+    if (piece?.type === 'K' && Math.abs((from % 12) - (to % 12)) === 2) {
+        move.isCastling = true;
+    }
+    if (piece?.type === 'P' && to === board.enPassantSquare && board.pieces[to] === undefined) {
+        move.isEnPassant = true;
+    }
+    return move;
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/wasm/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/wasm/snapshot.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "hyperchess-core",
+  "version": "0.1.0",
+  "description": "HyperChess core game logic - framework agnostic",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./board": {
+      "import": "./dist/board/index.js",
+      "types": "./dist/board/index.d.ts"
+    },
+    "./moves": {
+      "import": "./dist/moves/index.js",
+      "types": "./dist/moves/index.d.ts"
+    },
+    "./game": {
+      "import": "./dist/game/index.js",
+      "types": "./dist/game/index.d.ts"
+    },
+    "./standalone": {
+      "import": "./dist/standalone.js",
+      "types": "./dist/standalone.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "hyperchess",
+    "chess",
+    "chess-variant",
+    "board",
+    "game",
+    "logic",
+    "engine"
+  ],
+  "author": "HyperChess Contributors",
+  "license": "GPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KyrpyDev/hyperchess-core.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/KyrpyDev/hyperchess-core#readme",
+  "bugs": {
+    "url": "https://github.com/KyrpyDev/hyperchess-core/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "hyperchess-wasm": "0.1.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.0",
+    "typescript": "^5.2.0",
+    "vitest": "^0.34.0"
+  },
+  "scripts": {
+    "build": "tsc && npm run build:standalone-bundle",
+    "build:standalone-bundle": "esbuild src/standalone.ts --bundle --format=esm --platform=browser --target=es2022 --external:hyperchess-wasm/web --outfile=dist/standalone.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}