@mirasen/chessboard 1.0.7 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @mirasen/chessboard
 
+## 1.1.0
+
+### Minor Changes
+
+- 3956358: Add a stable chess.js adapter with pure move conversion helpers.
+
+### Patch Changes
+
+- 3956358: Fix lifted-drag animation suppression for compound moves.
+- 3956358: Fix `onUIMove` so it only fires for committed UI moves.
+
 ## 1.0.7
 
 ### Patch Changes

package/README.md

@@ -37,16 +37,22 @@ The default first-party extension baseline includes rendering, events, selection
 - `promotion`
 - `autoPromote`
 
+The package also includes `chess.js` adapter helpers for connecting legal destinations, UI moves, external moves, promotion, castling, and en passant without writing special-move glue code by hand.
+
 That means the board already covers a meaningful baseline chess UX instead of stopping at “draw squares and pieces”.
 
 ### Built-in chessboard behavior
 
-Mirasen Chessboard provides a complete modern interaction and visual baseline out of the box: selection, deselection, reselection, drag-to-move, release targeting, legal destinations, promotion, auto-promotion, and state-diff animation. Moves are resolved on release rather than committed immediately on press, giving users a more forgiving interaction flow. Because animation is driven by board-state transitions, pieces can move, appear, disappear, promote, or return smoothly without app-level glue code.
+Mirasen Chessboard provides a complete modern interaction and visual baseline out of the box: selection, deselection, reselection, drag-to-move, release targeting, legal destinations, promotion, auto-promotion, and state-diff animation.
+
+Moves are resolved on release rather than committed immediately on press, giving users a more forgiving interaction flow. Because animation is driven by board-state transitions, pieces can move, appear, disappear, promote, castle, or return smoothly without app-level rendering glue code.
+
+Rules and legality still belong to your game layer. Use the built-in `chess.js` adapter when you want a ready-made bridge from `chess.js` legal moves and move results into the board.
 
 ## Highlights
 
 - Real built-in chess interaction
-- Easy game/rules layer integration
+- **Easy game/rules integration** — connect your own game model, or use the built-in `chess.js` adapter
 - Works on desktop and mobile out of the box, with pointer-based mouse and touch interaction
 - State-diff animation beyond simple move events
 - Extension-driven architecture
@@ -68,8 +74,8 @@ Interactive examples are available on the Mirasen website:
 
 - [Examples overview](https://mirasen.io/chessboard/examples/)
 - [Minimal interactive example](https://mirasen.io/chessboard/examples/minimal.html)
-- [Legal moves example](https://mirasen.io/chessboard/examples/legal-moves.html)
 - [Promotion example](https://mirasen.io/chessboard/examples/promotion.html)
+- [chess.js game example](https://mirasen.io/chessboard/examples/chessjs.html)
 
 ## Usage
 
@@ -95,40 +101,25 @@ board.setMovability({
 });
 ```
 
-### Connect to a game/rules layer
+### Connect to chess.js
 
-`@mirasen/chessboard` handles board interaction and move intent. Your application can keep chess rules and game state in its own game/rules layer.
+`@mirasen/chessboard` owns board interaction, rendering, promotion UI, and animation.  
+Your game/rules layer owns legality and game state.
 
-A typical integration uses a small adapter between your game move format and the board move format. The `game` object below represents your own chess rules layer, such as chess.js, a server-backed game model, or a custom engine.
+For `chess.js`, use the built-in adapter:
+
+```bash
+npm install chess.js
+```
 
 ```ts
+import { createBoard } from '@mirasen/chessboard';
 import {
-	createBoard,
-	type MoveDestinationInput,
-	type MoveOutput,
-	type MoveRequestInput
-} from '@mirasen/chessboard';
-
-type GameMove = {
-	from: string;
-	to: string;
-	capturedSquare?: string;
-	secondary?: {
-		from: string;
-		to: string;
-	};
-	promotedTo?: 'queen' | 'rook' | 'bishop' | 'knight';
-};
-
-type GameDestination = {
-	to: string;
-	capturedSquare?: string;
-	secondary?: {
-		from: string;
-		to: string;
-	};
-	promotedTo?: ('queen' | 'rook' | 'bishop' | 'knight')[];
-};
+	toBoardMove,
+	toBoardMoveDestinations,
+	toGameMove
+} from '@mirasen/chessboard/adapters/chessjs';
+import { Chess } from 'chess.js';
 
 const element = document.getElementById('board');
 
@@ -136,70 +127,76 @@ if (!element) {
 	throw new Error('Missing board element');
 }
 
-const game = createYourGameEngine(); // Your app/game layer.
+const chess = new Chess();
 const board = createBoard({
 	element
 });
 
-board.setPosition(game.getPosition());
+// Let the user play white in this example.
+const playerColor = 'w';
 
-function toBoardDestination(gameDestination: GameDestination): MoveDestinationInput {
-	return {
-		to: gameDestination.to,
-		capturedSquare: gameDestination.capturedSquare,
-		secondary: gameDestination.secondary, // e.g. castling.
-		promotedTo: gameDestination.promotedTo
-	};
-}
-
-function toBoardMoveRequest(gameMove: GameMove): MoveRequestInput {
-	return {
-		from: gameMove.from,
-		to: gameMove.to,
-		capturedSquare: gameMove.capturedSquare,
-		secondary: gameMove.secondary,
-		promotedTo: gameMove.promotedTo
-	};
-}
-
-function toGameMove(move: MoveOutput): GameMove {
-	return {
-		from: move.from,
-		to: move.to,
-		capturedSquare: move.capturedSquare,
-		secondary: move.secondary,
-		promotedTo: move.promotedTo
-	};
-}
+board.setPosition(chess.fen());
 
 board.setMovability({
 	mode: 'strict',
-	destinations: (source): MoveDestinationInput[] | undefined => {
-		const gameDestinations = game.getDestinationsFor(source);
+	destinations: (source) => {
+		// During the computer's turn, do not allow user moves.
+		if (chess.turn() !== playerColor) {
+			return undefined;
+		}
+
+		const moves = chess.moves({ square: source, verbose: true });
+		const destinations = toBoardMoveDestinations(moves);
 
-		return gameDestinations.length > 0 ? gameDestinations.map(toBoardDestination) : undefined;
+		return destinations.length > 0 ? destinations : undefined;
 	}
 });
 
 board.extensions.events.setOnUIMove((move) => {
-	// The board accepted and applied this UI move.
-	// Keep your game/rules layer in sync.
-	game.move(toGameMove(move));
+	// The board has already accepted and applied this UI move.
+	// Keep chess.js in sync.
+	chess.move(toGameMove(move));
+
+	if (!chess.isGameOver()) {
+		makeRandomComputerMove();
+	}
 });
 
-function applyExternalMove(gameMove: GameMove) {
-	// Apply moves that come from outside the board UI:
-	// server, engine, opponent, imported game, replay, etc.
-	game.move(gameMove);
+function makeRandomComputerMove() {
+	const moves = chess.moves({ verbose: true });
+	const randomMove = moves[Math.floor(Math.random() * moves.length)];
+
+	if (!randomMove) {
+		return;
+	}
+
+	// Apply the move to chess.js first.
+	const appliedMove = chess.move(randomMove);
 
-	// Then animate/apply the same move on the board.
-	board.move(toBoardMoveRequest(gameMove));
+	// Then apply and animate the same move on the board.
+	board.move(toBoardMove(appliedMove));
+}
+
+function resetGame() {
+	chess.reset();
+	board.setPosition(chess.fen());
 }
 ```
 
-`MoveDestinationInput` can describe more than a target square. For example, `secondary` can represent paired piece movement (e.g. castling), `capturedSquare` can represent captures away from the destination square (e.g. en passant), and `promotedTo` can represent promotion choices.
+The adapter exposes three small conversion helpers:
+
+- `toGameMove` converts a board UI move into a move accepted by `chess.move(...)`.
+- `toBoardMove` converts a `chess.js` move result into a board move request for external or computer moves.
+- `toBoardMoveDestinations` converts verbose legal `chess.js` moves into strict board destinations.
 
-This lets your game/rules layer own chess legality and game state while the board owns interaction, selection, targeting, visual feedback, promotion UI, animation, and its own displayed position.
+This keeps the boundary explicit:
+
+- `chess.js` decides which moves are legal.
+- The board handles interaction, legal targets, promotion UI, castling/en-passant board updates, and animation.
+- User moves flow from the board into `chess.js`.
+- External moves flow from `chess.js` back into the board.
+
+`toBoardMoveDestinations` preserves special move information such as promotion choices, en passant capture squares, and castling secondary rook movement, so those flows work through the normal board pipeline.
 
 ### Promotion and auto-promotion
 
@@ -326,3 +323,7 @@ For details, see:
 
 - [./assets/pieces/chessnut/ATTRIBUTION.md](./assets/pieces/chessnut/ATTRIBUTION.md)
 - [./assets/pieces/chessnut/LICENSE.txt](./assets/pieces/chessnut/LICENSE.txt)
+
+```
+
+```

package/dist/adapters/chessjs/index.d.ts

@@ -0,0 +1 @@
+export { toBoardMove, toBoardMoveDestinations, toGameMove } from './main.js';

package/dist/adapters/chessjs/index.js

@@ -0,0 +1 @@
+export { toBoardMove, toBoardMoveDestinations, toGameMove } from './main.js';

package/dist/adapters/chessjs/main.d.ts

@@ -0,0 +1,19 @@
+import type { Chess, Move } from 'chess.js';
+import type { MoveRequestInput } from '../../state/board/types/input.js';
+import type { MoveOutput } from '../../state/board/types/output.js';
+import type { MoveDestinationInput } from '../../state/interaction/types/input.js';
+type ChessJsMoveInput = Exclude<Parameters<Chess['move']>[0], string | null>;
+/**
+ * Convert a board MoveOutput into the object notation accepted by chess.move().
+ */
+export declare function toGameMove(move: MoveOutput): ChessJsMoveInput;
+/**
+ * Convert a chess.js Move object into MoveRequestInput.
+ */
+export declare function toBoardMove(move: Move): MoveRequestInput;
+/**
+ * Convert readonly chess.js verbose moves into readonly MoveDestinationInput[].
+ * Merges promotion variants for the same from/to/special-move identity into one destination.
+ */
+export declare function toBoardMoveDestinations(moves: readonly Move[]): MoveDestinationInput[];
+export {};

package/dist/adapters/chessjs/main.js

@@ -0,0 +1,134 @@
+const BOARD_TO_CHESSJS = {
+    Q: 'q',
+    R: 'r',
+    B: 'b',
+    N: 'n'
+};
+const CHESSJS_TO_BOARD = {
+    q: 'Q',
+    r: 'R',
+    b: 'B',
+    n: 'N'
+};
+function toBoardPromotion(p) {
+    const result = CHESSJS_TO_BOARD[p];
+    if (!result) {
+        throw new Error(`Unsupported chess.js promotion symbol: "${p}"`);
+    }
+    return result;
+}
+function toChessJsPromotion(p) {
+    const result = BOARD_TO_CHESSJS[p];
+    if (!result) {
+        throw new Error(`Unsupported board promotion symbol: "${p}"`);
+    }
+    return result;
+}
+/**
+ * Convert a board MoveOutput into the object notation accepted by chess.move().
+ */
+export function toGameMove(move) {
+    const result = {
+        from: move.from,
+        to: move.to
+    };
+    if (move.promotedTo) {
+        result.promotion = toChessJsPromotion(move.promotedTo);
+    }
+    return result;
+}
+/**
+ * Convert a chess.js Move object into MoveRequestInput.
+ */
+export function toBoardMove(move) {
+    const result = {
+        from: move.from,
+        to: move.to
+    };
+    if (move.isPromotion()) {
+        if (!move.promotion) {
+            throw new Error('Promotion move missing promotion piece');
+        }
+        result.promotedTo = toBoardPromotion(move.promotion);
+    }
+    if (move.isEnPassant()) {
+        const file = move.to[0];
+        const toRank = parseInt(move.to[1], 10);
+        const capturedRank = move.color === 'w' ? toRank - 1 : toRank + 1;
+        result.capturedSquare = `${file}${capturedRank}`;
+    }
+    if (move.isKingsideCastle()) {
+        if (move.from === 'e1' && move.to === 'g1') {
+            result.secondary = { from: 'h1', to: 'f1' };
+        }
+        else if (move.from === 'e8' && move.to === 'g8') {
+            result.secondary = { from: 'h8', to: 'f8' };
+        }
+        else {
+            throw new Error(`Unsupported chess.js kingside castling move: ${move.from}-${move.to}`);
+        }
+    }
+    else if (move.isQueensideCastle()) {
+        if (move.from === 'e1' && move.to === 'c1') {
+            result.secondary = { from: 'a1', to: 'd1' };
+        }
+        else if (move.from === 'e8' && move.to === 'c8') {
+            result.secondary = { from: 'a8', to: 'd8' };
+        }
+        else {
+            throw new Error(`Unsupported chess.js queenside castling move: ${move.from}-${move.to}`);
+        }
+    }
+    return result;
+}
+/**
+ * Convert readonly chess.js verbose moves into readonly MoveDestinationInput[].
+ * Merges promotion variants for the same from/to/special-move identity into one destination.
+ */
+export function toBoardMoveDestinations(moves) {
+    if (moves.length === 0)
+        return [];
+    const destinations = [];
+    const keyToIndex = new Map();
+    for (const move of moves) {
+        const boardMove = toBoardMove(move);
+        // Build identity key: from + to + capturedSquare + secondary
+        const key = [
+            boardMove.from,
+            boardMove.to,
+            boardMove.capturedSquare ?? '',
+            boardMove.secondary ? `${boardMove.secondary.from}-${boardMove.secondary.to}` : ''
+        ].join('|');
+        const existingIdx = keyToIndex.get(key);
+        if (existingIdx !== undefined) {
+            // Merge promotion into existing destination
+            const existing = destinations[existingIdx];
+            if (boardMove.promotedTo) {
+                if (!existing.promotedTo) {
+                    existing.promotedTo = [];
+                }
+                if (!existing.promotedTo.includes(boardMove.promotedTo)) {
+                    existing.promotedTo.push(boardMove.promotedTo);
+                }
+            }
+        }
+        else {
+            // Create new destination
+            const dest = {
+                to: boardMove.to
+            };
+            if (boardMove.capturedSquare) {
+                dest.capturedSquare = boardMove.capturedSquare;
+            }
+            if (boardMove.secondary) {
+                dest.secondary = boardMove.secondary;
+            }
+            if (boardMove.promotedTo) {
+                dest.promotedTo = [boardMove.promotedTo];
+            }
+            keyToIndex.set(key, destinations.length);
+            destinations.push(dest);
+        }
+    }
+    return destinations;
+}

package/dist/animation/planner.js

@@ -239,11 +239,9 @@ export function calculateAnimationPlan(input) {
     const tracks = calculateTracks(effectivePrevious.board, planningCurrent.board, exclude);
     // 5) Build suppressedSquares: track-derived + excluded drop endpoints
     const suppressed = collectSuppressedSquaresFromTracks(tracks);
-    if (droppedMove !== null) {
-        // The dropped move was intentionally suppressed (no move track emitted),
-        // but the base render must still hide both endpoints.
-        suppressed.add(droppedMove.from);
-        suppressed.add(droppedMove.to);
-    }
-    return { tracks, suppressedSquares: suppressed };
+    const result = {
+        tracks,
+        suppressedSquares: suppressed
+    };
+    return result;
 }

package/dist/extensions/first-party/board-events/factory.js

@@ -40,8 +40,17 @@ function createBoardEventsInstance() {
                     currentFrame: context.currentFrame
                 });
             }
-            if (context.mutation.hasMutation({ causes: ['state.change.setLastMove'] }) &&
-                context.currentFrame.state.change.lastMove) {
+            const lastMoveChanged = context.mutation.hasMutation({
+                causes: ['state.change.setLastMove']
+            });
+            const interactionCompleted = context.mutation.hasMutation({
+                causes: [
+                    'runtime.interaction.completeCoreDragTo',
+                    'runtime.interaction.completeExtensionDragTo',
+                    'runtime.interaction.resolveDeferredUIMoveRequest'
+                ]
+            });
+            if (interactionCompleted && lastMoveChanged && context.currentFrame.state.change.lastMove) {
                 internalState.onUIMove?.(denormalizeMove(context.currentFrame.state.change.lastMove));
             }
         },

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@mirasen/chessboard",
 	"description": "Framework-agnostic TypeScript chessboard platform with real chess interaction built in.",
-	"version": "1.0.7",
+	"version": "1.1.0",
 	"license": "MIT",
 	"author": {
 		"name": "Mirasen",
@@ -42,6 +42,10 @@
 			"types": "./dist/extensions/build/index.d.ts",
 			"import": "./dist/extensions/build/index.js"
 		},
+		"./adapters/chessjs": {
+			"types": "./dist/adapters/chessjs/index.d.ts",
+			"import": "./dist/adapters/chessjs/index.js"
+		},
 		"./unstable/*": {
 			"types": "./dist/*.d.ts",
 			"import": "./dist/*.js"
@@ -100,5 +104,13 @@
 		"@ktarmyshov/assert": "^0.1.9",
 		"es-toolkit": "^1.45.1",
 		"type-fest": "^5.5.0"
+	},
+	"peerDependencies": {
+		"chess.js": "^1.4.0"
+	},
+	"peerDependenciesMeta": {
+		"chess.js": {
+			"optional": true
+		}
 	}
 }