hyperchess-board-ui 0.1.0

package/README.md

@@ -0,0 +1,40 @@
+# hyperchess-board-ui
+
+2D board UI for [HyperChess](https://github.com/KyrpyDev/hyperchess-core) — the 12×12 chess
+variant with Eagle and Hawk pieces. One package, three framework targets:
+
+```js
+import Board, { useBoardState } from 'hyperchess-board-ui/react';   // React ≥ 18
+import { Board } from 'hyperchess-board-ui/vue';                     // Vue ≥ 3
+import 'hyperchess-board-ui/web-component';                          // <hyperchess-board-ui> element
+```
+
+React and Vue are **optional peer dependencies** — install only the one you use. The web
+component target has no framework dependency at all:
+
+```html
+<script type="module">
+  import 'hyperchess-board-ui/web-component';
+</script>
+<hyperchess-board-ui></hyperchess-board-ui>
+```
+
+## Quick start (React)
+
+```jsx
+import Board, { useBoardState } from 'hyperchess-board-ui/react';
+
+function App() {
+  const { board, applyMove } = useBoardState();   // standard 12×12 start
+  return <Board board={board} onMove={applyMove} />;
+}
+```
+
+Theming comes from [`hyperchess-theme`](https://www.npmjs.com/package/hyperchess-theme); game
+logic from [`hyperchess-core`](https://www.npmjs.com/package/hyperchess-core). To add the full
+Rust engine (best-move search) use
+[`hyperchess-wasm`](https://www.npmjs.com/package/hyperchess-wasm).
+
+Part of the [HyperChess Core](https://github.com/KyrpyDev/hyperchess-core) monorepo —
+see the repository README for the full stack, contributing guide, and license
+(GPL-3.0-or-later).

package/dist/React/Board.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+import { BoardProps } from '../types/props';
+/**
+ * React board component
+ * Renders interactive 2D HyperChess board
+ */
+export declare const Board: React.FC<BoardProps>;
+export default Board;
+//# sourceMappingURL=Board.d.ts.map

package/dist/React/Board.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Board.d.ts","sourceRoot":"","sources":["../../src/React/Board.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAgC,MAAM,OAAO,CAAC;AAErD,OAAO,EAAE,UAAU,EAAkB,MAAM,gBAAgB,CAAC;AAG5D;;;GAGG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC,UAAU,CA+EtC,CAAC;AAEF,eAAe,KAAK,CAAC"}

package/dist/React/Board.js

@@ -0,0 +1,50 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useState, useCallback } from 'react';
+import { useBoardState } from './useBoardState';
+/**
+ * React board component
+ * Renders interactive 2D HyperChess board
+ */
+export const Board = ({ hfen, theme = 'modern', onMove, onSquareClick, enableDragDrop = true, showCoordinates = true, flipBoard = false, highlightLastMove = true, highlightLegalMoves = true, mode = 'play', disabled = false, className, pieceStyle = 'unicode', animationSpeed = 300, size = 'responsive', }) => {
+    const { board, selection, makeMove, selectSquare } = useBoardState(hfen);
+    const [isDragging, setIsDragging] = useState(false);
+    const [dragFrom, setDragFrom] = useState(null);
+    const handleSquareClick = useCallback((square) => {
+        if (disabled || mode === 'view')
+            return;
+        selectSquare(square);
+        onSquareClick?.(square);
+    }, [disabled, mode, selectSquare, onSquareClick]);
+    const handleDragStart = useCallback((square) => {
+        if (disabled || !enableDragDrop)
+            return;
+        setIsDragging(true);
+        setDragFrom(square);
+    }, [disabled, enableDragDrop]);
+    const handleDragEnd = useCallback(() => {
+        setIsDragging(false);
+    }, []);
+    const handleDrop = useCallback((to) => {
+        if (!dragFrom || !board)
+            return;
+        const move = { from: dragFrom, to };
+        const success = makeMove(move);
+        if (success) {
+            onMove?.(move);
+        }
+        setDragFrom(null);
+        handleDragEnd();
+    }, [dragFrom, board, makeMove, onMove, handleDragEnd]);
+    if (!board) {
+        return _jsx("div", { className: `hyperchess-board-ui ${className || ''}`, children: "Loading..." });
+    }
+    return (_jsx("div", { className: `hyperchess-board-ui hyperchess-board-ui-${theme} ${className || ''}`, style: {
+            display: 'grid',
+            gridTemplateColumns: 'repeat(12, 1fr)',
+            gap: '0',
+            aspectRatio: '1',
+            width: size === 'responsive' ? '100%' : `${size}px`,
+        }, children: _jsx("div", { style: { gridColumn: '1 / -1', padding: '20px', textAlign: 'center' }, children: "Board rendering coming in Phase 3.0.4" }) }));
+};
+export default Board;
+//# sourceMappingURL=Board.js.map

package/dist/React/Board.js.map

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

package/dist/React/useBoardState.d.ts

@@ -0,0 +1,26 @@
+import { Board as BoardType, Move, HfenString } from 'hyperchess-core';
+import { SelectionState } from '../types/props';
+/**
+ * React hook owning the board position and the user's click-to-move selection.
+ *
+ * `initialHfen` seeds the first render only; later changes to it are ignored,
+ * so remount the component (or key it) to load a different position. Note that
+ * `reset()` returns to the standard starting position rather than back to
+ * `initialHfen`.
+ *
+ * @param initialHfen - Starting position as an HFEN string or a prebuilt
+ *   `Board`. A `Board` is adopted by reference, not copied. Omitted means the
+ *   standard opening position.
+ * @returns The current `board`, the transient `selection` state, the memoised
+ *   `legalMoves` for the side to move, and the `selectSquare` / `makeMove` /
+ *   `reset` actions.
+ */
+export declare function useBoardState(initialHfen?: HfenString | BoardType): {
+    board: BoardType | null;
+    selection: SelectionState;
+    selectSquare: (square: number) => void;
+    makeMove: (move: Move) => boolean;
+    reset: () => void;
+    legalMoves: Move[];
+};
+//# sourceMappingURL=useBoardState.d.ts.map

package/dist/React/useBoardState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBoardState.d.ts","sourceRoot":"","sources":["../../src/React/useBoardState.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,IAAI,EAAE,UAAU,EAA8C,MAAM,iBAAiB,CAAC;AACnH,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,WAAW,CAAC,EAAE,UAAU,GAAG,SAAS;;;2BAiCrD,MAAM;qBA8CR,IAAI;;;EAyCd"}

package/dist/React/useBoardState.js

@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// HyperChess Core — hyperchess-board-ui
+// File: packages/board/src/React/useBoardState.ts
+// Version: 1.0.0
+// Copyright (c) 2026 HyperChess Developer Team
+import { useState, useCallback, useMemo } from 'react';
+import { createBoard, applyMove, generateLegalMoves } from 'hyperchess-core';
+/**
+ * React hook owning the board position and the user's click-to-move selection.
+ *
+ * `initialHfen` seeds the first render only; later changes to it are ignored,
+ * so remount the component (or key it) to load a different position. Note that
+ * `reset()` returns to the standard starting position rather than back to
+ * `initialHfen`.
+ *
+ * @param initialHfen - Starting position as an HFEN string or a prebuilt
+ *   `Board`. A `Board` is adopted by reference, not copied. Omitted means the
+ *   standard opening position.
+ * @returns The current `board`, the transient `selection` state, the memoised
+ *   `legalMoves` for the side to move, and the `selectSquare` / `makeMove` /
+ *   `reset` actions.
+ */
+export function useBoardState(initialHfen) {
+    const [board, setBoard] = useState(() => {
+        if (!initialHfen) {
+            return createBoard();
+        }
+        if (typeof initialHfen === 'string') {
+            return createBoard(initialHfen);
+        }
+        return initialHfen;
+    });
+    const [selection, setSelection] = useState({
+        selectedSquare: null,
+        legalMoves: [],
+        lastMove: null,
+    });
+    const legalMoves = useMemo(() => {
+        if (!board)
+            return [];
+        return generateLegalMoves(board);
+    }, [board]);
+    /**
+     * Handle a click on a square, driving the three-state selection cycle.
+     *
+     * Clicking one's own piece selects it (and re-selects when another own piece
+     * is clicked), clicking a highlighted destination plays the move, and any
+     * other click clears the selection. `lastMove` is deliberately preserved
+     * across a deselect so the last-move highlight does not flicker.
+     *
+     * @param square - Flat board index that was clicked.
+     */
+    const selectSquare = useCallback((square) => {
+        if (!board)
+            return;
+        const piece = board.pieces[square];
+        // Click on own piece: select it
+        if (piece && piece.color === board.toMove) {
+            const moves = legalMoves
+                .filter((m) => m.from === square)
+                .map((m) => m.to);
+            setSelection({
+                ...selection,
+                selectedSquare: square,
+                legalMoves: moves,
+            });
+        }
+        // Click on destination: try move
+        else if (selection.selectedSquare !== null && selection.legalMoves.includes(square)) {
+            makeMove({ from: selection.selectedSquare, to: square });
+        }
+        // Click elsewhere: deselect
+        else {
+            setSelection({
+                ...selection,
+                selectedSquare: null,
+                legalMoves: [],
+            });
+        }
+    }, [board, selection, legalMoves]);
+    /**
+     * Validate a move against the generated legal moves and apply it.
+     *
+     * Rejection is reported by return value rather than an exception, so a UI can
+     * treat an illegal drop as a no-op. `applyMove` produces a new board rather
+     * than mutating, which is what makes the position safe to hold in state.
+     *
+     * @param move - Move to attempt; only `from` and `to` are matched against the
+     *   legal move list.
+     * @returns `true` if the move was applied, `false` if it was illegal or no
+     *   board is loaded.
+     */
+    const makeMove = useCallback((move) => {
+        if (!board)
+            return false;
+        const isLegal = legalMoves.some((m) => m.from === move.from && m.to === move.to);
+        if (!isLegal)
+            return false;
+        const newBoard = applyMove(board, move);
+        setBoard(newBoard);
+        setSelection({
+            selectedSquare: null,
+            legalMoves: [],
+            lastMove: { from: move.from, to: move.to },
+        });
+        return true;
+    }, [board, legalMoves]);
+    /**
+     * Return to the standard starting position and clear all selection state,
+     * including `lastMove`. Does not restore the hook's `initialHfen`.
+     */
+    const reset = useCallback(() => {
+        setBoard(createBoard());
+        setSelection({
+            selectedSquare: null,
+            legalMoves: [],
+            lastMove: null,
+        });
+    }, []);
+    return {
+        board,
+        selection,
+        selectSquare,
+        makeMove,
+        reset,
+        legalMoves,
+    };
+}
+//# sourceMappingURL=useBoardState.js.map

package/dist/React/useBoardState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBoardState.js","sourceRoot":"","sources":["../../src/React/useBoardState.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,wCAAwC;AACxC,kDAAkD;AAClD,iBAAiB;AACjB,+CAA+C;AAE/C,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AACvD,OAAO,EAAwC,WAAW,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAGnH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa,CAAC,WAAoC;IAChE,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAmB,GAAG,EAAE;QACxD,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,OAAO,WAAW,EAAE,CAAC;QACvB,CAAC;QACD,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE,CAAC;YACpC,OAAO,WAAW,CAAC,WAAW,CAAC,CAAC;QAClC,CAAC;QACD,OAAO,WAAW,CAAC;IACrB,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAiB;QACzD,cAAc,EAAE,IAAI;QACpB,UAAU,EAAE,EAAE;QACd,QAAQ,EAAE,IAAI;KACf,CAAC,CAAC;IAEH,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,EAAE;QAC9B,IAAI,CAAC,KAAK;YAAE,OAAO,EAAE,CAAC;QACtB,OAAO,kBAAkB,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IAEZ;;;;;;;;;OASG;IACH,MAAM,YAAY,GAAG,WAAW,CAC9B,CAAC,MAAc,EAAE,EAAE;QACjB,IAAI,CAAC,KAAK;YAAE,OAAO;QAEnB,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAEnC,gCAAgC;QAChC,IAAI,KAAK,IAAI,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,MAAM,EAAE,CAAC;YAC1C,MAAM,KAAK,GAAG,UAAU;iBACrB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;iBAChC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAEpB,YAAY,CAAC;gBACX,GAAG,SAAS;gBACZ,cAAc,EAAE,MAAM;gBACtB,UAAU,EAAE,KAAK;aAClB,CAAC,CAAC;QACL,CAAC;QACD,iCAAiC;aAC5B,IAAI,SAAS,CAAC,cAAc,KAAK,IAAI,IAAI,SAAS,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YACpF,QAAQ,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,cAAc,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;QAC3D,CAAC;QACD,4BAA4B;aACvB,CAAC;YACJ,YAAY,CAAC;gBACX,GAAG,SAAS;gBACZ,cAAc,EAAE,IAAI;gBACpB,UAAU,EAAE,EAAE;aACf,CAAC,CAAC;QACL,CAAC;IACH,CAAC,EACD,CAAC,KAAK,EAAE,SAAS,EAAE,UAAU,CAAC,CAC/B,CAAC;IAEF;;;;;;;;;;;OAWG;IACH,MAAM,QAAQ,GAAG,WAAW,CAC1B,CAAC,IAAU,EAAE,EAAE;QACb,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QAEzB,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC;QACjF,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QAE3B,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACxC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAEnB,YAAY,CAAC;YACX,cAAc,EAAE,IAAI;YACpB,UAAU,EAAE,EAAE;YACd,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE;SAC3C,CAAC,CAAC;QAEH,OAAO,IAAI,CAAC;IACd,CAAC,EACD,CAAC,KAAK,EAAE,UAAU,CAAC,CACpB,CAAC;IAEF;;;OAGG;IACH,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;QAC7B,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;QACxB,YAAY,CAAC;YACX,cAAc,EAAE,IAAI;YACpB,UAAU,EAAE,EAAE;YACd,QAAQ,EAAE,IAAI;SACf,CAAC,CAAC;IACL,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO;QACL,KAAK;QACL,SAAS;QACT,YAAY;QACZ,QAAQ;QACR,KAAK;QACL,UAAU;KACX,CAAC;AACJ,CAAC"}

package/dist/Vue/useBoardState.d.ts

@@ -0,0 +1,105 @@
+import { Board as BoardType, Move, HfenString } from 'hyperchess-core';
+import type { SelectionState } from '../types/props';
+/**
+ * Vue 3 composable owning the board position and click-to-move selection.
+ *
+ * Behaviourally identical to the React hook of the same name — the split exists
+ * only because the two frameworks' reactivity primitives differ. `initialHfen`
+ * seeds the composable once; later changes are ignored, and `reset()` returns to
+ * the standard starting position rather than to `initialHfen`.
+ *
+ * @param initialHfen - Starting position as an HFEN string or a prebuilt
+ *   `Board`. A `Board` is adopted by reference, not copied. Omitted means the
+ *   standard opening position.
+ * @returns Reactive `board` and `selection` refs, a computed `legalMoves` for
+ *   the side to move, and the `selectSquare` / `makeMove` / `reset` actions.
+ */
+export declare function useBoardState(initialHfen?: HfenString | BoardType): {
+    board: import("vue").Ref<{
+        pieces: ({
+            type: import("hyperchess-core").PieceType;
+            color: import("hyperchess-core").Color;
+            identity?: string | undefined;
+        } | undefined)[];
+        toMove: import("hyperchess-core").Color;
+        enPassantSquare: number;
+        castlingRights: {
+            whiteKingSide: boolean;
+            whiteQueenSide: boolean;
+            blackKingSide: boolean;
+            blackQueenSide: boolean;
+        };
+        halfmoveClock: number;
+        fullmoveNumber: number;
+        history: {
+            pieces: ({
+                type: import("hyperchess-core").PieceType;
+                color: import("hyperchess-core").Color;
+                identity?: string | undefined;
+            } | undefined)[];
+            toMove: import("hyperchess-core").Color;
+            enPassantSquare: number;
+            castlingRights: {
+                whiteKingSide: boolean;
+                whiteQueenSide: boolean;
+                blackKingSide: boolean;
+                blackQueenSide: boolean;
+            };
+            halfmoveClock: number;
+            fullmoveNumber: number;
+        }[];
+    } | null, BoardType | {
+        pieces: ({
+            type: import("hyperchess-core").PieceType;
+            color: import("hyperchess-core").Color;
+            identity?: string | undefined;
+        } | undefined)[];
+        toMove: import("hyperchess-core").Color;
+        enPassantSquare: number;
+        castlingRights: {
+            whiteKingSide: boolean;
+            whiteQueenSide: boolean;
+            blackKingSide: boolean;
+            blackQueenSide: boolean;
+        };
+        halfmoveClock: number;
+        fullmoveNumber: number;
+        history: {
+            pieces: ({
+                type: import("hyperchess-core").PieceType;
+                color: import("hyperchess-core").Color;
+                identity?: string | undefined;
+            } | undefined)[];
+            toMove: import("hyperchess-core").Color;
+            enPassantSquare: number;
+            castlingRights: {
+                whiteKingSide: boolean;
+                whiteQueenSide: boolean;
+                blackKingSide: boolean;
+                blackQueenSide: boolean;
+            };
+            halfmoveClock: number;
+            fullmoveNumber: number;
+        }[];
+    } | null>;
+    selection: import("vue").Ref<{
+        selectedSquare: number | null;
+        legalMoves: number[];
+        lastMove: {
+            from: number;
+            to: number;
+        } | null;
+    }, SelectionState | {
+        selectedSquare: number | null;
+        legalMoves: number[];
+        lastMove: {
+            from: number;
+            to: number;
+        } | null;
+    }>;
+    selectSquare: (square: number) => void;
+    makeMove: (move: Move) => boolean;
+    reset: () => void;
+    legalMoves: import("vue").ComputedRef<Move[]>;
+};
+//# sourceMappingURL=useBoardState.d.ts.map

package/dist/Vue/useBoardState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBoardState.d.ts","sourceRoot":"","sources":["../../src/Vue/useBoardState.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,KAAK,IAAI,SAAS,EAClB,IAAI,EACJ,UAAU,EAIX,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,WAAW,CAAC,EAAE,UAAU,GAAG,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BA2BlC,MAAM;qBAsCZ,IAAI;;;EAsC7B"}

package/dist/Vue/useBoardState.js

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// HyperChess Core — hyperchess-board-ui
+// File: packages/board/src/Vue/useBoardState.ts
+// Version: 1.0.0
+// Copyright (c) 2026 HyperChess Developer Team
+import { ref, computed } from 'vue';
+import { createBoard, applyMove, generateLegalMoves, } from 'hyperchess-core';
+/**
+ * Vue 3 composable owning the board position and click-to-move selection.
+ *
+ * Behaviourally identical to the React hook of the same name — the split exists
+ * only because the two frameworks' reactivity primitives differ. `initialHfen`
+ * seeds the composable once; later changes are ignored, and `reset()` returns to
+ * the standard starting position rather than to `initialHfen`.
+ *
+ * @param initialHfen - Starting position as an HFEN string or a prebuilt
+ *   `Board`. A `Board` is adopted by reference, not copied. Omitted means the
+ *   standard opening position.
+ * @returns Reactive `board` and `selection` refs, a computed `legalMoves` for
+ *   the side to move, and the `selectSquare` / `makeMove` / `reset` actions.
+ */
+export function useBoardState(initialHfen) {
+    // `ref()` takes a value, not a lazy-initializer function like React's
+    // `useState` — compute the initial board up front instead.
+    const initialBoard = !initialHfen ? createBoard() : typeof initialHfen === 'string' ? createBoard(initialHfen) : initialHfen;
+    const board = ref(initialBoard);
+    const selection = ref({
+        selectedSquare: null,
+        legalMoves: [],
+        lastMove: null,
+    });
+    const legalMoves = computed(() => {
+        if (!board.value)
+            return [];
+        return generateLegalMoves(board.value);
+    });
+    /**
+     * Handle a click on a square, driving the three-state selection cycle.
+     *
+     * Clicking one's own piece selects it, clicking a highlighted destination
+     * plays the move, and any other click clears the selection while preserving
+     * `lastMove` so the last-move highlight does not flicker.
+     *
+     * @param square - Flat board index that was clicked.
+     */
+    const selectSquare = (square) => {
+        if (!board.value)
+            return;
+        const piece = board.value.pieces[square];
+        if (piece && piece.color === board.value.toMove) {
+            const moves = legalMoves.value.filter((m) => m.from === square).map((m) => m.to);
+            selection.value = {
+                ...selection.value,
+                selectedSquare: square,
+                legalMoves: moves,
+            };
+        }
+        else if (selection.value.selectedSquare !== null &&
+            selection.value.legalMoves.includes(square)) {
+            makeMove({ from: selection.value.selectedSquare, to: square });
+        }
+        else {
+            selection.value = {
+                ...selection.value,
+                selectedSquare: null,
+                legalMoves: [],
+            };
+        }
+    };
+    /**
+     * Validate a move against the computed legal moves and apply it.
+     *
+     * Assigning the new board to `board.value` rather than mutating in place is
+     * what lets `legalMoves` recompute.
+     *
+     * @param move - Move to attempt; only `from` and `to` are matched against the
+     *   legal move list.
+     * @returns `true` if the move was applied, `false` if it was illegal or no
+     *   board is loaded.
+     */
+    const makeMove = (move) => {
+        if (!board.value)
+            return false;
+        const isLegal = legalMoves.value.some((m) => m.from === move.from && m.to === move.to);
+        if (!isLegal)
+            return false;
+        board.value = applyMove(board.value, move);
+        selection.value = {
+            selectedSquare: null,
+            legalMoves: [],
+            lastMove: { from: move.from, to: move.to },
+        };
+        return true;
+    };
+    /**
+     * Return to the standard starting position and clear all selection state,
+     * including `lastMove`. Does not restore the composable's `initialHfen`.
+     */
+    const reset = () => {
+        board.value = createBoard();
+        selection.value = {
+            selectedSquare: null,
+            legalMoves: [],
+            lastMove: null,
+        };
+    };
+    return {
+        board,
+        selection,
+        selectSquare,
+        makeMove,
+        reset,
+        legalMoves,
+    };
+}
+//# sourceMappingURL=useBoardState.js.map

package/dist/Vue/useBoardState.js.map

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

package/dist/types/props.d.ts

@@ -0,0 +1,92 @@
+import { Board, HfenString } from 'hyperchess-core';
+import { Move } from 'hyperchess-core';
+/**
+ * Name of a theme to resolve from `hyperchess-theme`.
+ *
+ * The known names are listed for editor autocompletion only — the trailing
+ * `string` widens the union, so any registered custom theme name is accepted and
+ * an unknown name is a runtime rather than a compile-time error.
+ */
+export type Theme = 'classic' | 'modern' | 'dark' | 'highcontrast' | string;
+/**
+ * What the user is allowed to do with the board: `view` is read-only, `play`
+ * accepts only legal moves for the side to move, and `analyze` allows moving
+ * either side freely for exploring variations.
+ */
+export type InteractionMode = 'view' | 'play' | 'analyze';
+/**
+ * Props accepted by the board component across all framework bindings.
+ *
+ * Every field is optional; the component is fully usable with no props and falls
+ * back to the standard 12x12 HyperChess starting position. Square indices used
+ * by the callbacks are flat 0-based offsets into the board, not file/rank pairs.
+ */
+export interface BoardProps {
+    /** Initial board state (HFEN or Board object) */
+    hfen?: HfenString | Board;
+    /** Theme name or custom theme */
+    theme?: Theme;
+    /** Called after a move has been validated and applied, never for a rejected one. */
+    onMove?: (move: Move) => void;
+    /** Called for every square click, including clicks that select nothing. */
+    onSquareClick?: (square: number) => void;
+    /** Enable drag-and-drop moves */
+    enableDragDrop?: boolean;
+    /** Show rank/file coordinates */
+    showCoordinates?: boolean;
+    /** Render from black's perspective. Affects display only — square indices
+     * passed to callbacks stay in the engine's orientation. */
+    flipBoard?: boolean;
+    /** Highlight last move */
+    highlightLastMove?: boolean;
+    /** Highlight legal moves for selected piece */
+    highlightLegalMoves?: boolean;
+    /** Interaction mode */
+    mode?: InteractionMode;
+    /** Disable user interaction */
+    disabled?: boolean;
+    /** Custom CSS class */
+    className?: string;
+    /** Piece style (unicode, svg, or font) */
+    pieceStyle?: 'unicode' | 'svg' | 'font';
+    /** Animation speed (ms for move animation) */
+    animationSpeed?: number;
+    /** Edge length in pixels, or `'responsive'` to fill the container while
+     * holding a square aspect ratio. */
+    size?: number | 'responsive';
+}
+/**
+ * Transient UI state tracked while the user interacts with the board.
+ *
+ * Kept separate from the game state so that selecting and deselecting never
+ * touches the position — only a completed move does.
+ */
+export interface SelectionState {
+    /** Square the user has picked up, or `null` when nothing is selected. */
+    selectedSquare: number | null;
+    /** Destination squares reachable from `selectedSquare`, for highlighting.
+     * Empty whenever nothing is selected. */
+    legalMoves: number[];
+    /** Most recent move played on this board, for the last-move highlight. It
+     * survives selection changes and is cleared only by a reset. */
+    lastMove: {
+        from: number;
+        to: number;
+    } | null;
+}
+/**
+ * The full set of interaction callbacks a board renderer must wire up.
+ *
+ * Unlike the optional handlers on {@link BoardProps} these are all required —
+ * this is the internal contract between a renderer and its state hook, not the
+ * public component surface.
+ */
+export interface BoardHandlers {
+    onMove: (move: Move) => void;
+    onSquareClick: (square: number) => void;
+    onDragStart: (square: number) => void;
+    onDragEnd: (square: number) => void;
+    /** Fired on a completed drag; the move still has to pass legality checks. */
+    onDrop: (from: number, to: number) => void;
+}
+//# sourceMappingURL=props.d.ts.map

package/dist/types/props.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"props.d.ts","sourceRoot":"","sources":["../../src/types/props.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAEvC;;;;;;GAMG;AACH,MAAM,MAAM,KAAK,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,cAAc,GAAG,MAAM,CAAC;AAE5E;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,iDAAiD;IACjD,IAAI,CAAC,EAAE,UAAU,GAAG,KAAK,CAAC;IAE1B,iCAAiC;IACjC,KAAK,CAAC,EAAE,KAAK,CAAC;IAEd,oFAAoF;IACpF,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;IAE9B,2EAA2E;IAC3E,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAEzC,iCAAiC;IACjC,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB,iCAAiC;IACjC,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;+DAC2D;IAC3D,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB,0BAA0B;IAC1B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B,+CAA+C;IAC/C,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B,uBAAuB;IACvB,IAAI,CAAC,EAAE,eAAe,CAAC;IAEvB,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,uBAAuB;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,SAAS,GAAG,KAAK,GAAG,MAAM,CAAC;IAExC,8CAA8C;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;wCACoC;IACpC,IAAI,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9B;6CACyC;IACzC,UAAU,EAAE,MAAM,EAAE,CAAC;IAErB;oEACgE;IAChE,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC/C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;IAC7B,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,6EAA6E;IAC7E,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C"}

package/dist/types/props.js

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// HyperChess Core — hyperchess-board-ui
+// File: packages/board/src/types/props.ts
+// Version: 1.0.0
+// Copyright (c) 2026 HyperChess Developer Team
+export {};
+//# sourceMappingURL=props.js.map

package/dist/types/props.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"props.js","sourceRoot":"","sources":["../../src/types/props.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,wCAAwC;AACxC,0CAA0C;AAC1C,iBAAiB;AACjB,+CAA+C"}