@mirasen/chessboard 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @mirasen/chessboard
 
+## 1.0.5
+
+### Patch Changes
+
+- 0422020: Fix fast drag-and-drop sometimes leaving a stale drag visual due to an unsynced target square.
+- 0422020: Update dependencies
+- 0422020: Fix promotion extension to accept renderer-compatible piece URL maps without throwing on extra entries.
+- 0422020: Allow createBoard options to configure built-in extensions without direct factory calls.
+
+## 1.0.4
+
+### Patch Changes
+
+- f586eea: Update README integration examples and export move-related public types.
+
 ## 1.0.3
 
 ### Patch Changes

package/README.md

@@ -24,7 +24,7 @@ This is not just a board renderer. It is a chessboard platform designed for real
 
 ## What you get out of the box
 
-The built-in first-party extension baseline currently includes both foundational runtime-facing extensions and user-facing board features.
+The default first-party extension baseline includes rendering, events, selection, active target feedback, legal move hints, last move feedback, promotion UI, and optional auto-promotion.
 
 - `renderer` — the first-party rendering extension that validates the same extension architecture used for board features
 - `events`
@@ -78,44 +78,48 @@ if (!element) {
 const board = createBoard({
 	element
 });
-// Set free movability, default - disabled
+
+// User moves are disabled by default.
+// Enable free movement when you want unconstrained UI moves.
 board.setMovability({
 	mode: 'free'
 });
 ```
 
-### Explicit extensions
-
-```ts
-import { createBoard, type Chessboard, type ChessboardExtensionInput } from '@mirasen/chessboard';
-
-const extensionList = [
-	// Always add renderer first, otherwise nothing will be rendered
-	'renderer',
-	'lastMove',
-	// Keep autoPromote before promotion, otherwise promotion may defer the move first
-	'autoPromote',
-	'promotion'
-	// customExtensionDefinition
-] as const satisfies readonly ChessboardExtensionInput[];
-let board: Chessboard<typeof extensionList> | null = null;
-
-const element = document.getElementById('board');
-
-if (!element) {
-	throw new Error('Missing board element');
-}
+### Connect to a game/rules layer
 
-board = createBoard({
-	element,
-	extensions: extensionList
-});
-```
+`@mirasen/chessboard` handles board interaction and move intent. Your application can keep chess rules and game state in its own game/rules layer.
 
-### setOnUIMove
+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.
 
 ```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')[];
+};
 
 const element = document.getElementById('board');
 
@@ -123,95 +127,72 @@ if (!element) {
 	throw new Error('Missing board element');
 }
 
+const game = createYourGameEngine(); // Your app/game layer.
 const board = createBoard({
-	element,
-	state: {
-		board: 'start',
-		interaction: {
-			movability: {
-				mode: 'free'
-			}
-		}
-	}
-});
-
-board.extensions.events.setOnUIMove((move) => {
-	console.log('UI move:', move);
+	element
 });
-```
-
-### setMovability - strict with explicit destinations
 
-```ts
-import { createBoard } from '@mirasen/chessboard';
+board.setPosition(game.getPosition());
 
-const element = document.getElementById('board');
+function toBoardDestination(gameDestination: GameDestination): MoveDestinationInput {
+	return {
+		to: gameDestination.to,
+		capturedSquare: gameDestination.capturedSquare,
+		secondary: gameDestination.secondary, // e.g. castling.
+		promotedTo: gameDestination.promotedTo
+	};
+}
 
-if (!element) {
-	throw new Error('Missing board element');
+function toBoardMoveRequest(gameMove: GameMove): MoveRequestInput {
+	return {
+		from: gameMove.from,
+		to: gameMove.to,
+		capturedSquare: gameMove.capturedSquare,
+		secondary: gameMove.secondary,
+		promotedTo: gameMove.promotedTo
+	};
 }
 
-const board = createBoard({
-	element
-});
+function toGameMove(move: MoveOutput): GameMove {
+	return {
+		from: move.from,
+		to: move.to,
+		capturedSquare: move.capturedSquare,
+		secondary: move.secondary,
+		promotedTo: move.promotedTo
+	};
+}
 
 board.setMovability({
 	mode: 'strict',
-	destinations: {
-		e2: [{ to: 'e3' }, { to: 'e4' }],
-		d7: [
-			{ to: 'c8', promotedTo: ['queen', 'rook', 'bishop', 'knight'] },
-			{ to: 'd8', promotedTo: ['queen', 'rook', 'bishop', 'knight'] }
-		],
-		g1: [{ to: 'f3' }, { to: 'h3' }]
+	destinations: (source): MoveDestinationInput[] | undefined => {
+		const gameDestinations = game.getDestinationsFor(source);
+
+		return gameDestinations.length > 0 ? gameDestinations.map(toBoardDestination) : undefined;
 	}
 });
-```
-
-### setMovability - strict with a resolver
 
-```ts
-import { createBoard } from '@mirasen/chessboard';
+board.extensions.events.setOnUIMove((move) => {
+	// The board accepted and applied this UI move.
+	// Keep your game/rules layer in sync.
+	game.move(toGameMove(move));
+});
 
-const element = document.getElementById('board');
+function applyExternalMove(gameMove: GameMove) {
+	// Apply moves that come from outside the board UI:
+	// server, engine, opponent, imported game, replay, etc.
+	game.move(gameMove);
 
-if (!element) {
-	throw new Error('Missing board element');
+	// Then animate/apply the same move on the board.
+	board.move(toBoardMoveRequest(gameMove));
 }
+```
 
-const board = createBoard({
-	element
-});
+`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.
 
-board.setMovability({
-	mode: 'strict',
-	destinations: (source) => {
-		if (source === 'e2')
-			return [
-				{ to: 'e8', promotedTo: ['bishop', 'queen'] },
-				{ to: 'd8', promotedTo: ['rook', 'knight', 'queen'] }
-			];
-		if (source === 'f7')
-			return [
-				{ to: 'f8', promotedTo: ['bishop', 'rook', 'knight', 'queen'] },
-				{ to: 'g8', promotedTo: ['bishop', 'rook', 'knight', 'queen'] }
-			];
-		if (source === 'd7')
-			return [
-				{ to: 'd1', promotedTo: ['bishop', 'knight'] },
-				{ to: 'e1', promotedTo: ['rook', 'knight', 'queen'] }
-			];
-		if (source === 'c2')
-			return [
-				{ to: 'c1', promotedTo: ['bishop', 'rook', 'knight', 'queen'] },
-				{ to: 'b1', promotedTo: ['bishop', 'rook', 'knight', 'queen'] }
-			];
-		return undefined;
-	}
-});
-```
+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.
 
-## Promotion and auto-promotion
+### Promotion and auto-promotion
 
 Promotion is handled inside the board interaction pipeline through a natural deferred move flow.
 
@@ -249,6 +230,44 @@ const board = createBoard({
 board.extensions.autoPromote.toQueen = true;
 ```
 
+### Movability modes
+
+Movability controls how the board accepts user-initiated moves.
+
+- `disabled` — user moves are ignored
+- `free` — user moves are accepted without legal destination filtering
+- `strict` — user moves are accepted only when the target is allowed by the destinations provided by your app/rules layer
+
+### Advanced: explicit extension lists
+
+Most users can rely on the default first-party extension baseline. Use an explicit extension list only when you want to control which built-in or custom extensions are installed.
+
+```ts
+import { createBoard, type Chessboard, type ChessboardExtensionInput } from '@mirasen/chessboard';
+
+const extensionList = [
+	// Always add renderer first, otherwise nothing will be rendered
+	'renderer',
+	'lastMove',
+	// Keep autoPromote before promotion, otherwise promotion may defer the move first
+	'autoPromote',
+	'promotion'
+	// customExtensionDefinition
+] as const satisfies readonly ChessboardExtensionInput[];
+let board: Chessboard<typeof extensionList> | null = null;
+
+const element = document.getElementById('board');
+
+if (!element) {
+	throw new Error('Missing board element');
+}
+
+board = createBoard({
+	element,
+	extensions: extensionList
+});
+```
+
 ## Architecture
 
 `@mirasen/chessboard` is built around explicit boundaries:

package/dist/extensions/build/index.d.ts

@@ -1,3 +1,4 @@
+export { cleanAnimationPlan, prepareAnimationPlan, renderAnimationPlan } from '../../animation/render/plan.js';
 export { clearElementChildren, createSvgElement, updateElementAttributes } from '../../render/svg/helpers.js';
 export type { RuntimeReadonlyMutationSession } from '../../runtime/mutation/types.js';
 export { isNonEmptyPieceCode } from '../../state/board/check.js';

package/dist/extensions/build/index.js

@@ -1,3 +1,4 @@
+export { cleanAnimationPlan, prepareAnimationPlan, renderAnimationPlan } from '../../animation/render/plan.js';
 export { clearElementChildren, createSvgElement, updateElementAttributes } from '../../render/svg/helpers.js';
 export { isNonEmptyPieceCode } from '../../state/board/check.js';
 export { fileOf, rankOf, squareOf } from '../../state/board/coords.js';

package/dist/extensions/first-party/promotion/normalize.js

@@ -6,21 +6,23 @@ function assertPieceUrlsComplete(pieceUrls) {
         assert(pieceCode in pieceUrls, `Missing URL for piece code: ${pieceCode}`);
     }
 }
-function assertPieceCodeIsPromotionPieceCode(pieceCode) {
-    assert(pieceCode === 5 /* PieceCode.WhiteQueen */ ||
+function isPromotionPieceCode(pieceCode) {
+    return (pieceCode === 5 /* PieceCode.WhiteQueen */ ||
         pieceCode === 4 /* PieceCode.WhiteRook */ ||
         pieceCode === 3 /* PieceCode.WhiteBishop */ ||
         pieceCode === 2 /* PieceCode.WhiteKnight */ ||
         pieceCode === 13 /* PieceCode.BlackQueen */ ||
         pieceCode === 12 /* PieceCode.BlackRook */ ||
         pieceCode === 11 /* PieceCode.BlackBishop */ ||
-        pieceCode === 10 /* PieceCode.BlackKnight */, `Invalid promotion piece code: ${pieceCode}`);
+        pieceCode === 10 /* PieceCode.BlackKnight */);
 }
 function normalizePromotionPieceUrls(input) {
     const normalized = {};
     for (const [key, url] of Object.entries(input)) {
         const pieceCode = normalizePiece(key);
-        assertPieceCodeIsPromotionPieceCode(pieceCode);
+        if (!isPromotionPieceCode(pieceCode)) {
+            continue;
+        }
         normalized[pieceCode] = url;
     }
     assertPieceUrlsComplete(normalized);

package/dist/extensions/types/wrapper.d.ts

@@ -1,6 +1,3 @@
-/**
- * Public built-in extension ids accepted by createBoard({ extensions })
- */
 import { createActiveTarget } from '../first-party/active-target/factory.js';
 import { createAutoPromote } from '../first-party/auto-promote/factory.js';
 import { createBoardEvents } from '../first-party/board-events/factory.js';

package/dist/extensions/types/wrapper.js

@@ -1,6 +1,3 @@
-/**
- * Public built-in extension ids accepted by createBoard({ extensions })
- */
 import { createActiveTarget } from '../first-party/active-target/factory.js';
 import { EXTENSION_ID as EXTENSION_ID_ACTIVE_TARGET } from '../first-party/active-target/types.js';
 import { createAutoPromote } from '../first-party/auto-promote/factory.js';

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export type { MoveOutput } from './extensions/build/index.js';
+export type { MoveRequestInput, PiecePositionRecordString } from './state/board/types/input.js';
+export type { MoveDestinationInput } from './state/interaction/types/input.js';
 export { createBoard } from './wrapper/factory.js';
 export type { Chessboard, ChessboardExtensionInput, ChessboardInitOptions } from './wrapper/types.js';
-export type { MoveRequestInput, PiecePositionRecordString } from './state/board/types/input.js';

package/dist/runtime/factory/input.js

@@ -42,23 +42,24 @@ export function createRuntimeInteractionSurface(state) {
             const internalState = state();
             const mutationSession = internalState.mutation.getSession();
             const interaction = internalState.state.interaction;
+            interaction.updateDragSessionCurrentTarget(target, mutationSession);
             const dragSession = interaction.dragSession;
-            assert(dragSession !== null, 'completeDragTo requires an active drag session');
             assert(isDragSessionCoreOwned(dragSession), 'completeDragTo can only be called for core-owned drag sessions');
             uiMoveCompleteTo(internalState, target);
-            mutationSession.addMutation('runtime.interaction.completeDragTo', true, dragSession);
+            mutationSession.addMutation('runtime.interaction.completeCoreDragTo', true, dragSession);
             runtimeRunMutationPipeline(internalState);
         },
         completeExtensionDrag(target) {
             const internalState = state();
             const mutationSession = internalState.mutation.getSession();
             const interaction = internalState.state.interaction;
+            interaction.updateDragSessionCurrentTarget(target, mutationSession);
             const dragSession = interaction.dragSession;
-            assert(dragSession !== null, 'completeExtensionDrag requires an active drag session');
             assert(!isDragSessionCoreOwned(dragSession), 'completeExtensionDrag can only be called for extension-owned drag sessions');
-            assert(dragSession.targetSquare === target, 'The target square in completeExtensionDrag must match the current target square of the drag session');
             internalState.extensionSystem.completeDrag(dragSession);
             internalState.state.interaction.setDragSession(null, mutationSession);
+            mutationSession.addMutation('runtime.interaction.completeExtensionDragTo', true, dragSession);
+            runtimeRunMutationPipeline(internalState);
         },
         startReleaseTargetingDrag(source, target) {
             const internalState = state();
@@ -92,9 +93,7 @@ export function createRuntimeInteractionSurface(state) {
             const internalState = state();
             const interactionMutationSession = internalState.mutation.getSession();
             const interaction = internalState.state.interaction;
-            const currentDragSession = interaction.dragSession;
-            assert(currentDragSession !== null, 'No active drag session to update');
-            internalState.state.interaction.updateDragSessionCurrentTarget(target, interactionMutationSession);
+            interaction.updateDragSessionCurrentTarget(target, interactionMutationSession);
             runtimeRunMutationPipeline(internalState);
         },
         onEvent(context) {

package/dist/runtime/mutation/interaction.js

@@ -4,7 +4,7 @@ export const reconcileInteractionSelectionAfterBoardStateChange = (context, muta
     const { current } = context;
     if (!mutationSession.hasMutation({ prefixes: ['state.board.'] }) ||
         mutationSession.hasMutation({
-            causes: ['state.interaction.clear', 'runtime.interaction.completeDragTo']
+            causes: ['state.interaction.clear', 'runtime.interaction.completeCoreDragTo']
         })) {
         return;
     }

package/dist/runtime/mutation/types.d.ts

@@ -3,10 +3,11 @@ import type { MutationSession, ReadonlyMutationSession } from '../../mutation/ty
 import type { BoardStateMutationPayloadByCause } from '../../state/board/mutation.js';
 import type { ChangeStateMutationPayloadByCause } from '../../state/change/mutation.js';
 import type { InteractionStateMutationPayloadByCause } from '../../state/interaction/mutation.js';
-import type { DragSessionCoreOwnedSnapshot } from '../../state/interaction/types/internal.js';
+import type { DragSessionCoreOwnedSnapshot, DragSessionExtensionOwnedSnapshot } from '../../state/interaction/types/internal.js';
 import type { ViewStateMutationPayloadByCause } from '../../state/view/mutation.js';
 type RuntimeOwnMutationPayloadByCause = {
-    'runtime.interaction.completeDragTo': DragSessionCoreOwnedSnapshot;
+    'runtime.interaction.completeCoreDragTo': DragSessionCoreOwnedSnapshot;
+    'runtime.interaction.completeExtensionDragTo': DragSessionExtensionOwnedSnapshot;
     'runtime.interaction.resolveDeferredUIMoveRequest': undefined;
     'runtime.interaction.cancelDeferredUIMoveRequest': undefined;
 };

package/dist/wrapper/factory.d.ts

@@ -1,3 +1,3 @@
 import { DefaultBuiltinChessboardExtensions } from '../extensions/types/wrapper.js';
-import { Chessboard, ChessboardExtensionInput, ChessboardInitOptions } from './types.js';
+import { type Chessboard, type ChessboardExtensionInput, type ChessboardInitOptions } from './types.js';
 export declare function createBoard<TExtensions extends readonly ChessboardExtensionInput[] = DefaultBuiltinChessboardExtensions>(options: ChessboardInitOptions<TExtensions>): Chessboard<TExtensions>;

package/dist/wrapper/factory.js

@@ -1,5 +1,9 @@
 import { builtInExtensionFactoryMap, DefaultBuiltinChessboardExtensions } from '../extensions/types/wrapper.js';
 import { createRuntime } from '../runtime/factory/main.js';
+function resolveBuiltInExtensionWithOptions(input) {
+    const factory = builtInExtensionFactoryMap[input.builtin];
+    return factory(input.options);
+}
 export function createBoard(options) {
     // prepare init options for runtime
     const extensionsInput = options.extensions ?? DefaultBuiltinChessboardExtensions;
@@ -8,6 +12,10 @@ export function createBoard(options) {
             // built-in extension, convert to definition
             return builtInExtensionFactoryMap[ext]();
         }
+        if ('builtin' in ext) {
+            // built-in extension with options, convert to definition
+            return resolveBuiltInExtensionWithOptions(ext);
+        }
         // assume it's already a definition
         return ext;
     });

package/dist/wrapper/types.d.ts

@@ -1,15 +1,25 @@
 import type { AnyExtensionDefinition, ExtensionDefinitionId, ExtensionDefinitionPublicApi } from '../extensions/types/extension.js';
-import { BuiltInExtensionDefinitionMap, BuiltInExtensionId, DefaultBuiltinChessboardExtensions } from '../extensions/types/wrapper.js';
-import { Runtime } from '../runtime/types/main.js';
-import { RuntimeStateInitOptions } from '../state/types.js';
+import { type BuiltInExtensionDefinitionMap, type BuiltInExtensionId, type DefaultBuiltinChessboardExtensions, builtInExtensionFactoryMap } from '../extensions/types/wrapper.js';
+import type { Runtime } from '../runtime/types/main.js';
+import type { RuntimeStateInitOptions } from '../state/types.js';
 /**
  * What createBoard accepts in options.extensions
  */
-export type ChessboardExtensionInput = BuiltInExtensionId | AnyExtensionDefinition;
+export type BuiltInExtensionFactoryInitOptions<TId extends BuiltInExtensionId> = Parameters<(typeof builtInExtensionFactoryMap)[TId]> extends [] ? never : NonNullable<Parameters<(typeof builtInExtensionFactoryMap)[TId]>[0]>;
+type BuiltInExtensionIdsWithOptions = {
+    [TId in BuiltInExtensionId]: [BuiltInExtensionFactoryInitOptions<TId>] extends [never] ? never : TId;
+}[BuiltInExtensionId];
+export type BuiltInExtensionInitOptions = {
+    [TId in BuiltInExtensionIdsWithOptions]: {
+        builtin: TId;
+        options: BuiltInExtensionFactoryInitOptions<TId>;
+    };
+}[BuiltInExtensionIdsWithOptions];
+export type ChessboardExtensionInput = BuiltInExtensionId | BuiltInExtensionInitOptions | AnyExtensionDefinition;
 /**
  * Resolve one public input item into a concrete extension definition type
  */
-export type ResolveChessboardExtensionInput<T> = T extends keyof BuiltInExtensionDefinitionMap ? BuiltInExtensionDefinitionMap[T] : T extends AnyExtensionDefinition ? T : never;
+export type ResolveChessboardExtensionInput<T> = T extends keyof BuiltInExtensionDefinitionMap ? BuiltInExtensionDefinitionMap[T] : T extends BuiltInExtensionInitOptions ? T['builtin'] extends keyof BuiltInExtensionDefinitionMap ? BuiltInExtensionDefinitionMap[T['builtin']] : never : T extends AnyExtensionDefinition ? T : never;
 /**
  * Resolve an input tuple into a tuple of concrete extension definitions
  */

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.3",
+	"version": "1.0.5",
 	"license": "MIT",
 	"author": {
 		"name": "Mirasen",