@mirasen/chessboard 0.1.1 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @mirasen/chessboard
 
+## 1.0.0
+
+### Major Changes
+
+- 2609920: First v1.0.0 release with the new extension-driven architecture, built-in chess interaction baseline, promotion flow, and auto-promote support.
+
+### Patch Changes
+
+- 31364b7: dependabot: directory '/', update @sveltejs/kit
+- 31364b7: dependabot: directory '/', update @vitest/browser-playwright
+- 31364b7: dependabot: directory '/', update eslint-plugin-svelte
+- 31364b7: dependabot: directory '/', update svelte
+- 2609920: Added promotion and auto-promotion to queen extensions
+
+## 1.0.0-rc.0
+
+### Major Changes
+
+- 2609920: First 1.0 release candidate with the new extension-driven architecture, built-in chess interaction baseline, promotion flow, and auto-promote support.
+
+### Patch Changes
+
+- 2609920: Added promotion and auto-promotion to queen extensions
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -1,50 +1,51 @@
 [![NPM Version](https://img.shields.io/npm/v/%40mirasen%2Fchessboard)](https://www.npmjs.com/package/@mirasen/chessboard)
 [![CI](https://github.com/mirasen-io/chessboard/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mirasen-io/chessboard/actions/workflows/ci.yml)
-[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=mirasen-io_chessboard&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=mirasen-io_chessboard)
-[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=mirasen-io_chessboard&metric=coverage)](https://sonarcloud.io/summary/new_code?id=mirasen-io_chessboard)
 [![License](https://img.shields.io/npm/l/@mirasen/chessboard)](./LICENSE)
 
 # @mirasen/chessboard
 
-Framework-agnostic TypeScript chessboard library focused on clean architecture, explicit rendering ownership, and extension-driven features.
+A framework-agnostic TypeScript chessboard platform with real chess interaction built in and an extension-driven architecture.
 
-## Status
+## Why this exists
 
-**Early public release (`0.1.x`)**
+Most chessboards fall into one of two buckets:
 
-The core architecture is already usable, but the package is still pre-`1.0.0` and the API may evolve.
+- rendering primitives that leave core interaction UX to app code
+- tightly coupled monoliths that are hard to extend cleanly
 
-Current focus:
+`@mirasen/chessboard` aims for a better balance:
 
-- stable core runtime
-- extension-driven rendering and interaction
-- public wrapper / package API
-- early integration ergonomics
+- meaningful built-in chess interaction out of the box
+- first-party extensions for common board UX
+- explicit rendering and ownership boundaries
+- extension-driven growth without turning the board into glue hell
 
-Not finalized yet:
+This is not just a board renderer. It is a chessboard platform designed for real chess interaction.
 
-- promotion flow
-- some higher-level public APIs
-- broader test coverage
-- final `1.0.0` API guarantees
+## What you get out of the box
 
-## Goals
+The built-in first-party extension baseline currently includes both foundational runtime-facing extensions and user-facing board features.
 
-- framework-agnostic board core
-- explicit runtime / render / interaction boundaries
-- extension-first architecture
-- predictable rendering ownership
-- room for advanced features without core hacks
+- `renderer` — the first-party rendering extension that validates the same extension architecture used for board features
+- `events`
+- `selectedSquare`
+- `activeTarget`
+- `legalMoves`
+- `lastMove`
+- `promotion`
+- `autoPromote`
 
-## Current features
+That means the board already covers a meaningful baseline chess UX instead of stopping at “draw squares and pieces”.
 
-- board rendering
-- orientation support
-- selection and drag interaction
-- move targeting
-- move animation foundation
-- built-in visual extensions such as selected square, active target, legal moves, and last move
-- board events extension with `setOnUiMove(...)` and `setOnRawUpdate(...)`
+## Highlights
+
+- Real built-in chess interaction
+- Extension-driven architecture
+- First-party baseline extensions
+- Explicit SVG slot ownership
+- Clean separation between runtime, rendering, interaction, and animation
+- Promotion flow built into the board pipeline
+- Optional auto-promotion as a separate behavior extension
 
 ## Installation
 
@@ -52,20 +53,226 @@ Not finalized yet:
 npm install @mirasen/chessboard
 ```
 
-## Example
+## Usage
+
+### Minimal example
 
 ```ts
 import { createBoard } from '@mirasen/chessboard';
 
+const element = document.getElementById('board');
+
+if (!element) {
+	throw new Error('Missing board element');
+}
+
 const board = createBoard({
-	// API still evolving in 0.1.x
+	element
+});
+// Set free movability, default - disabled
+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');
+}
+
+board = createBoard({
+	element,
+	extensions: extensionList
+});
+```
 
-board.extensions.events.setOnUiMove((move) => {
+### setOnUIMove
+
+```ts
+import { createBoard } from '@mirasen/chessboard';
+
+const element = document.getElementById('board');
+
+if (!element) {
+	throw new Error('Missing board element');
+}
+
+const board = createBoard({
+	element,
+	state: {
+		board: 'start',
+		interaction: {
+			movability: {
+				mode: 'free'
+			}
+		}
+	}
+});
+
+board.extensions.events.setOnUIMove((move) => {
 	console.log('UI move:', move);
 });
 ```
 
+### setMovability - strict with explicit destinations
+
+```ts
+import { createBoard } from '@mirasen/chessboard';
+
+const element = document.getElementById('board');
+
+if (!element) {
+	throw new Error('Missing board element');
+}
+
+const board = createBoard({
+	element
+});
+
+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' }]
+	}
+});
+```
+
+### setMovability - strict with a resolver
+
+```ts
+import { createBoard } from '@mirasen/chessboard';
+
+const element = document.getElementById('board');
+
+if (!element) {
+	throw new Error('Missing board element');
+}
+
+const board = createBoard({
+	element
+});
+
+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;
+	}
+});
+```
+
+## Promotion and auto-promotion
+
+Promotion is handled inside the board interaction pipeline through a natural deferred move flow.
+
+That means the board does not need the awkward pattern of:
+
+- reject move
+- open external dialog
+- replay the move later
+
+Instead:
+
+- `promotion` provides the built-in promotion chooser UI
+- `autoPromote` provides behavior-only auto-promotion logic
+
+These are separate extensions on purpose:
+
+- `promotion` is UI
+- `autoPromote` is behavior
+
+This separation is a good example of the architecture: common chess UX can be built in without collapsing everything into one hardcoded board layer.
+
+```ts
+import { createBoard } from '@mirasen/chessboard';
+
+const element = document.getElementById('board');
+
+if (!element) {
+	throw new Error('Missing board element');
+}
+
+const board = createBoard({
+	element
+});
+
+board.extensions.autoPromote.toQueen = true;
+```
+
+## Architecture
+
+`@mirasen/chessboard` is built around explicit boundaries:
+
+- runtime owns board, interaction, and update semantics
+- renderer owns SVG structure and visual layers
+- animation owns transition planning and temporary visual occupancy
+- extensions render through declared slots instead of ad hoc DOM access
+
+The goal is to make common chess interaction powerful without making the system brittle.
+
+## Not just a primitive, not a monolith
+
+The project is intentionally positioned between two weak extremes:
+
+### Primitive-only board
+
+A board that only renders pieces and leaves everything else to app code often forces consumers to rebuild the same interaction UX repeatedly.
+
+### Hardcoded monolith
+
+A board that handles everything internally without clean boundaries becomes difficult to evolve, customize, or extend.
+
+`@mirasen/chessboard` aims for a middle path:
+
+- strong built-in baseline interaction
+- clean internal architecture
+- extension-driven feature growth
+
+## Project direction
+
+This platform is being built as a foundation for richer chess learning and interaction workflows, but the board itself is designed to stand as a serious open-source UI platform in its own right.
+
 ## Artwork
 
 ### Chessnut piece set
@@ -82,15 +289,3 @@ For details, see:
 
 - [./assets/pieces/chessnut/ATTRIBUTION.md](./assets/pieces/chessnut/ATTRIBUTION.md)
 - [./assets/pieces/chessnut/LICENSE.txt](./assets/pieces/chessnut/LICENSE.txt)
-
-## Versioning note
-
-`0.1.x` is an early public package release.
-
-It exists so the package can be installed, explored, integrated experimentally, and published publicly while the library continues moving toward a more complete `1.0.0`.
-
-Breaking changes are still possible before `1.0.0`.
-
-## License
-
-MIT

package/dist/animation/planner.d.ts

@@ -1,6 +1,11 @@
-import { Square } from '../state/board/types/internal.js';
-import { BoardStateSnapshot } from '../state/board/types/main.js';
-import { AnimationPlan, AnimationTrack, CalculateAnimationTracksOptions } from './types.js';
-export declare function collectSuppressedSquares(tracks: AnimationTrack[]): ReadonlySet<Square>;
-export declare function calculateAnimationTracks(pos1: BoardStateSnapshot, pos2: BoardStateSnapshot, options?: CalculateAnimationTracksOptions): AnimationTrack[];
-export declare function calculateAnimationPlan(pos1: BoardStateSnapshot, pos2: BoardStateSnapshot, sessionId: number, options?: CalculateAnimationTracksOptions): AnimationPlan;
+import type { AnimationPlan, AnimationPlanningInput } from './types.js';
+/**
+ * Plan animation tracks and suppressed squares for a state transition.
+ *
+ * This is the single entry point for animation planning.  It:
+ * 1. Normalizes both snapshots (incorporates deferredUIMoveRequest).
+ * 2. Detects lifted-piece-drag drop completion and builds an internal exclude.
+ * 3. Computes tracks via greedy min-distance matching.
+ * 4. Assembles the full suppressedSquares set (track-derived + excluded drop endpoints).
+ */
+export declare function calculateAnimationPlan(input: AnimationPlanningInput): AnimationPlan;

package/dist/animation/planner.js

@@ -1,9 +1,11 @@
+import assert from '@ktarmyshov/assert';
 import { isNonEmptyPieceCode } from '../state/board/check.js';
 import { fileOf, rankOf } from '../state/board/coords.js';
 import { SQUARE_COUNT } from '../state/board/types/internal.js';
-import { isMoveExclude, isSquareExclude } from './types.js';
+// ---------------------------------------------------------------------------
 // Precomputed squared distance: (dFile² + dRank²) for all square pairs.
-// Max value = 7² + 7² = 98, fits in Uint8. Index: a * 64 + b.
+// Max value = 7² + 7² = 98, fits in Uint8.  Index: a * 64 + b.
+// ---------------------------------------------------------------------------
 const SQUARE_DIST = new Uint8Array(SQUARE_COUNT * SQUARE_COUNT);
 for (let a = 0; a < SQUARE_COUNT; a++) {
     for (let b = 0; b < SQUARE_COUNT; b++) {
@@ -12,7 +14,107 @@ for (let a = 0; a < SQUARE_COUNT; a++) {
         SQUARE_DIST[a * SQUARE_COUNT + b] = df * df + dr * dr;
     }
 }
-export function collectSuppressedSquares(tracks) {
+const EMPTY_EXCLUDE = {
+    move: new Map(),
+    square: new Set()
+};
+/**
+ * Detect whether a lifted-piece-drag was just completed (dropped).
+ *
+ * Condition:
+ * - previous snapshot had an active lifted-piece-drag session
+ * - current snapshot has no drag session
+ * - current snapshot has a lastMove
+ *
+ * Returns the lastMove when the condition holds, otherwise null.
+ */
+function detectLiftedPieceDrop(previous, current) {
+    const prevDrag = previous.interaction.dragSession;
+    if (!prevDrag || prevDrag.type !== 'lifted-piece-drag')
+        return null;
+    if (current.interaction.dragSession !== null)
+        return null;
+    return current.change.lastMove ?? null;
+}
+/**
+ * Build an ExcludeSpec that suppresses the move track and both endpoint
+ * fades for a given lastMove (used when a lifted-piece drop is detected).
+ */
+function buildExcludeForDrop(lastMove) {
+    const moveMap = new Map();
+    moveMap.set(lastMove.from, new Set([lastMove.to]));
+    const squareSet = new Set([lastMove.from, lastMove.to]);
+    return { move: moveMap, square: squareSet };
+}
+/**
+ * Normalize a snapshot by incorporating a pending deferredUIMoveRequest
+ * into the board and lastMove.  Currently limited to pawn moves.
+ *
+ * If there is no deferred request the snapshot is returned as-is.
+ */
+function buildEffectiveAnimationPlanningSnapshot(state) {
+    const request = state.change.deferredUIMoveRequest;
+    if (request === null)
+        return state; // nothing to do
+    const newPieces = new Uint8Array(state.board.pieces);
+    const from = request.sourceSquare;
+    const to = request.destination.to;
+    const pieceCode = state.board.pieces[from];
+    assert(pieceCode === 1 /* PieceCode.WhitePawn */ || pieceCode === 9 /* PieceCode.BlackPawn */, 'Only pawn moves should be deferred UI move requests at this time');
+    newPieces[to] = pieceCode;
+    newPieces[from] = 0 /* PieceCode.Empty */;
+    const newBoard = {
+        ...state.board,
+        pieces: newPieces
+    };
+    const newLastMove = {
+        from,
+        to,
+        piece: pieceCode
+    };
+    const newChange = {
+        deferredUIMoveRequest: null,
+        lastMove: newLastMove
+    };
+    return {
+        ...state,
+        board: newBoard,
+        change: newChange
+    };
+}
+/**
+ * When a promotion was already auto-resolved/auto-promoted (no deferredUIMoveRequest but
+ * lastMove.promotedTo is set), the current board already contains the promoted
+ * piece (e.g. queen) on the target square.  For animation planning we
+ * temporarily replace it with the original piece (pawn) so that the greedy
+ * matching can build a proper move track from→to instead of separate fades.
+ *
+ * After the animation finishes the promoted piece will "snap" into view on
+ * the next render frame.
+ */
+function buildPromotionEffectiveCurrent(state) {
+    const lastMove = state.change.lastMove;
+    if (state.change.deferredUIMoveRequest !== null ||
+        lastMove === null ||
+        lastMove.promotedTo === undefined) {
+        return state; // not an auto-resolved/auto-promoted move — nothing to do
+    }
+    const newPieces = new Uint8Array(state.board.pieces);
+    newPieces[lastMove.to] = lastMove.piece;
+    const newBoard = {
+        ...state.board,
+        pieces: newPieces
+    };
+    return {
+        ...state,
+        board: newBoard
+    };
+}
+/**
+ * Collect suppressed squares purely from the given tracks.
+ * For move tracks both endpoints are included; for fade/static the single square.
+ */
+function collectSuppressedSquaresFromTracks(tracks) {
     const result = new Set();
     for (const track of tracks) {
         if (track.effect === 'move') {
@@ -25,14 +127,20 @@ export function collectSuppressedSquares(tracks) {
     }
     return result;
 }
-export function calculateAnimationTracks(pos1, pos2, options) {
+/**
+ * Low-level track calculation.
+ *
+ * Compares two board snapshots (already derived / effective), applies the
+ * provided exclude spec, and returns the resulting animation tracks.
+ */
+function calculateTracks(prevBoard, currBoard, exclude) {
     const tracks = [];
     let nextId = 0;
     const removed = [];
     const added = [];
     for (let sq = 0; sq < SQUARE_COUNT; sq++) {
-        const c1 = pos1.pieces[sq];
-        const c2 = pos2.pieces[sq];
+        const c1 = prevBoard.pieces[sq];
+        const c2 = currBoard.pieces[sq];
         if (c1 === c2)
             continue;
         if (isNonEmptyPieceCode(c1))
@@ -43,29 +151,29 @@ export function calculateAnimationTracks(pos1, pos2, options) {
     // Step 2: greedy min-distance matching of same-code pairs → move tracks
     const removedMatched = new Uint8Array(removed.length);
     const addedMatched = new Uint8Array(added.length);
-    // toSq → code of the piece that moved there (used for static detection)
-    const movedToSqCode = new Map();
     const candidates = [];
     for (let ri = 0; ri < removed.length; ri++) {
         for (let ai = 0; ai < added.length; ai++) {
             if (removed[ri].pieceCode !== added[ai].pieceCode)
                 continue;
-            candidates.push({ dist: SQUARE_DIST[removed[ri].sq * SQUARE_COUNT + added[ai].sq], ri, ai });
+            candidates.push({
+                dist: SQUARE_DIST[removed[ri].sq * SQUARE_COUNT + added[ai].sq],
+                ri,
+                ai
+            });
         }
     }
     candidates.sort((a, b) => a.dist - b.dist);
-    const excl = options?.exclude;
-    const preparedExcl = prepareExclude(excl);
     for (const { ri, ai } of candidates) {
         if (removedMatched[ri] || addedMatched[ai])
             continue;
         removedMatched[ri] = 1;
         addedMatched[ai] = 1;
-        movedToSqCode.set(added[ai].sq, removed[ri].pieceCode);
-        if (excl &&
-            preparedExcl.move.has(removed[ri].sq) &&
-            preparedExcl.move.get(removed[ri].sq).has(added[ai].sq)) {
-            // Suppress this move track but keep both squares matched so they don't become fades.
+        // Check if this move pair is excluded (e.g. lifted-piece drop)
+        const fromSet = exclude.move.get(removed[ri].sq);
+        if (fromSet && fromSet.has(added[ai].sq)) {
+            // Suppress the move track but keep both entries matched so they
+            // don't turn into fades.
             continue;
         }
         tracks.push({
@@ -80,9 +188,8 @@ export function calculateAnimationTracks(pos1, pos2, options) {
     for (let ai = 0; ai < added.length; ai++) {
         if (addedMatched[ai])
             continue;
-        if (preparedExcl.square.has(added[ai].sq)) {
+        if (exclude.square.has(added[ai].sq))
             continue;
-        }
         tracks.push({
             id: nextId++,
             pieceCode: added[ai].pieceCode,
@@ -90,39 +197,51 @@ export function calculateAnimationTracks(pos1, pos2, options) {
             effect: 'fade-in'
         });
     }
-    // Step 4: unmatched removed → fade-out or static
+    // Step 4: unmatched removed → fade-out
     for (let ri = 0; ri < removed.length; ri++) {
         if (removedMatched[ri])
             continue;
-        if (preparedExcl.square.has(removed[ri].sq)) {
+        if (exclude.square.has(removed[ri].sq))
             continue;
-        }
-        const { pieceCode: code, sq } = removed[ri];
-        /*const movedCode = movedToSqCode.get(sq);
-        const isCapture =
-            movedCode !== undefined && fromPieceCode(code).color !== fromPieceCode(movedCode).color;*/
-        const pieceCode = code;
-        tracks.push({ id: nextId++, pieceCode, sq, effect: 'fade-out' });
+        tracks.push({
+            id: nextId++,
+            pieceCode: removed[ri].pieceCode,
+            sq: removed[ri].sq,
+            effect: 'fade-out'
+        });
     }
     return tracks;
 }
-export function calculateAnimationPlan(pos1, pos2, sessionId, options) {
-    return { sessionId, tracks: calculateAnimationTracks(pos1, pos2, options) };
-}
-function prepareExclude(exclude) {
-    const result = { move: new Map(), square: new Set() };
-    if (!exclude)
-        return result;
-    for (const e of exclude) {
-        if (isMoveExclude(e)) {
-            if (!result.move.has(e.fromSq)) {
-                result.move.set(e.fromSq, new Set());
-            }
-            result.move.get(e.fromSq).add(e.toSq);
-        }
-        else if (isSquareExclude(e)) {
-            result.square.add(e.sq);
-        }
+// ---------------------------------------------------------------------------
+// Public API — single orchestrator
+// ---------------------------------------------------------------------------
+/**
+ * Plan animation tracks and suppressed squares for a state transition.
+ *
+ * This is the single entry point for animation planning.  It:
+ * 1. Normalizes both snapshots (incorporates deferredUIMoveRequest).
+ * 2. Detects lifted-piece-drag drop completion and builds an internal exclude.
+ * 3. Computes tracks via greedy min-distance matching.
+ * 4. Assembles the full suppressedSquares set (track-derived + excluded drop endpoints).
+ */
+export function calculateAnimationPlan(input) {
+    // 1) Normalize snapshots to account for deferredUIMoveRequest
+    const effectivePrevious = buildEffectiveAnimationPlanningSnapshot(input.previous);
+    const effectiveCurrent = buildEffectiveAnimationPlanningSnapshot(input.current);
+    // 2) Detect lifted-piece drop and prepare exclude spec
+    const droppedMove = detectLiftedPieceDrop(effectivePrevious, effectiveCurrent);
+    const exclude = droppedMove !== null ? buildExcludeForDrop(droppedMove) : EMPTY_EXCLUDE;
+    // 3) Normalize current for auto-resolved/auto-promoted move (pawn→queen on target square)
+    const planningCurrent = buildPromotionEffectiveCurrent(effectiveCurrent);
+    // 4) Calculate tracks
+    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 result;
+    return { tracks, suppressedSquares: suppressed };
 }

package/dist/animation/render/fade.d.ts

@@ -1,7 +1,7 @@
 import type { PieceUrls } from '../../extensions/first-party/main-renderer/types/internal.js';
-import type { RenderGeometry } from '../../layout/geometry/types.js';
+import type { SceneRenderGeometry } from '../../layout/geometry/types.js';
 import type { AnimationTrackFade } from '../types.js';
 import type { PreparedFadeNode } from './types.js';
-export declare function prepareFadeTrack(track: AnimationTrackFade, geometry: RenderGeometry, pieceUrls: PieceUrls, layer: SVGElement): PreparedFadeNode;
+export declare function prepareFadeTrack(track: AnimationTrackFade, geometry: SceneRenderGeometry, pieceUrls: PieceUrls, layer: SVGElement): PreparedFadeNode;
 export declare function renderFadeTrack(node: PreparedFadeNode, progress: number): void;
 export declare function cleanFadeTrack(node: PreparedFadeNode): void;