@mirasen/chessboard 0.1.1 → 1.0.0

package/dist/extensions/first-party/last-move/factory.js

@@ -2,7 +2,7 @@ import assert from '@ktarmyshov/assert';
 import { toMerged } from 'es-toolkit';
 import { createSvgElement, updateElementAttributes } from '../../../render/svg/helpers.js';
 import { isUpdateContextRenderable } from '../../types/context/update.js';
-import { extensionCreateInternalBase, extensionDestroy, extensionMount, extensionUnmount } from '../common/helpers.js';
+import { extensionCreateInternalBase, extensionDestroyBase, extensionMountBase, extensionUnmountBase } from '../common/helpers.js';
 import { DEFAULT_CONFIG, EXTENSION_ID, EXTENSION_SLOTS } from './types.js';
 export function createLastMove(config = {}) {
     const mergedConfig = toMerged(DEFAULT_CONFIG, config);
@@ -31,7 +31,7 @@ function createLastMoveInstance(config) {
     return {
         id: EXTENSION_ID,
         mount(env) {
-            extensionMount(internalState, env.slotRoots);
+            extensionMountBase(internalState, env.slotRoots);
         },
         onUpdate(context) {
             const needsRender = context.mutation.hasMutation({
@@ -57,13 +57,13 @@ function createLastMoveInstance(config) {
                 return;
             }
             const geometry = context.currentFrame.layout.geometry;
-            const rFrom = geometry.squareRect(fromSq);
-            const rTo = geometry.squareRect(toSq);
+            const rFrom = geometry.getSquareRect(fromSq);
+            const rTo = geometry.getSquareRect(toSq);
             const rectFromAttributes = {
                 x: rFrom.x.toString(),
                 y: rFrom.y.toString(),
-                width: rFrom.size.toString(),
-                height: rFrom.size.toString(),
+                width: rFrom.width.toString(),
+                height: rFrom.height.toString(),
                 fill: internalState.config.color,
                 'fill-opacity': internalState.config.opacity.toString(),
                 'shape-rendering': 'crispEdges'
@@ -71,8 +71,8 @@ function createLastMoveInstance(config) {
             const rectToAttributes = {
                 x: rTo.x.toString(),
                 y: rTo.y.toString(),
-                width: rTo.size.toString(),
-                height: rTo.size.toString(),
+                width: rTo.width.toString(),
+                height: rTo.height.toString(),
                 fill: internalState.config.color,
                 'fill-opacity': internalState.config.opacity.toString(),
                 'shape-rendering': 'crispEdges'
@@ -95,11 +95,11 @@ function createLastMoveInstance(config) {
             }
         },
         unmount() {
-            extensionUnmount(internalState);
+            extensionUnmountBase(internalState);
             extensionClean(internalState);
         },
         destroy() {
-            extensionDestroy(internalState);
+            extensionDestroyBase(internalState);
             extensionClean(internalState);
         }
     };

package/dist/extensions/first-party/last-move/types.d.ts

@@ -1,6 +1,6 @@
 import { PartialDeep } from 'type-fest';
 import { ExtensionDefinition, ExtensionInstance } from '../../types/extension.js';
-import { ExtensionInternal, OpaqueColor } from '../common/types.js';
+import { ExtensionInternalBase, OpaqueColor } from '../common/types.js';
 export declare const EXTENSION_SLOTS: readonly ["underPieces"];
 export type ExtensionSlotsType = typeof EXTENSION_SLOTS;
 export declare const EXTENSION_ID: "lastMove";
@@ -9,7 +9,7 @@ export declare const DEFAULT_CONFIG: LastMoveConfig;
 export type LastMoveInitConfig = PartialDeep<LastMoveConfig>;
 export type LastMoveDefinition = ExtensionDefinition<typeof EXTENSION_ID, typeof EXTENSION_SLOTS, never>;
 export type LastMoveInstance = ExtensionInstance<typeof EXTENSION_ID, typeof EXTENSION_SLOTS, never>;
-export interface LastMoveInstanceInternal extends ExtensionInternal<ExtensionSlotsType> {
+export interface LastMoveInstanceInternal extends ExtensionInternalBase<ExtensionSlotsType> {
     svgRectFrom: SVGRectElement | null;
     svgRectTo: SVGRectElement | null;
     readonly config: LastMoveConfig;

package/dist/extensions/first-party/legal-moves/factory.js

@@ -4,7 +4,7 @@ import { clearElementChildren, createSvgElement } from '../../../render/svg/help
 import { isNonEmptyPieceCode } from '../../../state/board/check.js';
 import { fromPieceCode } from '../../../state/board/piece.js';
 import { isUpdateContextRenderable } from '../../types/context/update.js';
-import { extensionCreateInternalBase, extensionDestroy, extensionMount, extensionUnmount } from '../common/helpers.js';
+import { extensionCreateInternalBase, extensionDestroyBase, extensionMountBase, extensionUnmountBase } from '../common/helpers.js';
 import { DEFAULT_CONFIG, EXTENSION_ID, EXTENSION_SLOTS } from './types.js';
 export function createLegalMoves(config = {}) {
     const mergedConfig = toMerged(DEFAULT_CONFIG, config);
@@ -31,7 +31,7 @@ function createLegalMovesInstance(config) {
     return {
         id: EXTENSION_ID,
         mount(env) {
-            extensionMount(internalState, env.slotRoots);
+            extensionMountBase(internalState, env.slotRoots);
         },
         onUpdate(context) {
             const needsRender = context.mutation.hasMutation({
@@ -70,7 +70,7 @@ function createLegalMovesInstance(config) {
                 fill: 'none'
             }; // TODO: Remove, this is just for visual test
             for (const [square, destination] of interaction.activeDestinations) {
-                const rect = geometry.squareRect(square);
+                const rect = geometry.getSquareRect(square);
                 const circleX = rect.x + geometry.squareSize / 2;
                 const circleY = rect.y + geometry.squareSize / 2;
                 const selectedPieceCode = context.currentFrame.state.board.pieces[interaction.selected.square];
@@ -90,11 +90,11 @@ function createLegalMovesInstance(config) {
             }
         },
         unmount() {
-            extensionUnmount(internalState);
+            extensionUnmountBase(internalState);
             extensionClean(internalState);
         },
         destroy() {
-            extensionDestroy(internalState);
+            extensionDestroyBase(internalState);
             extensionClean(internalState);
         }
     };

package/dist/extensions/first-party/legal-moves/types.d.ts

@@ -1,6 +1,6 @@
 import { PartialDeep } from 'type-fest';
 import { ExtensionDefinition, ExtensionInstance } from '../../types/extension.js';
-import { ExtensionInternal, OpaqueColor } from '../common/types.js';
+import { ExtensionInternalBase, OpaqueColor } from '../common/types.js';
 export declare const EXTENSION_SLOTS: readonly ["overPieces"];
 export type ExtensionSlotsType = typeof EXTENSION_SLOTS;
 export declare const EXTENSION_ID: "legalMoves";
@@ -19,7 +19,7 @@ export declare const DEFAULT_CONFIG: LegalMovesConfig;
 export type LegalMovesInitConfig = PartialDeep<LegalMovesConfig>;
 export type LegalMovesDefinition = ExtensionDefinition<typeof EXTENSION_ID, typeof EXTENSION_SLOTS, never>;
 export type LegalMovesInstance = ExtensionInstance<typeof EXTENSION_ID, typeof EXTENSION_SLOTS, never>;
-export interface LegalMovesInstanceInternal extends ExtensionInternal<ExtensionSlotsType> {
+export interface LegalMovesInstanceInternal extends ExtensionInternalBase<ExtensionSlotsType> {
     destroyed: boolean;
     svgCircles: SVGCircleElement[];
     readonly config: LegalMovesConfig;

package/dist/extensions/first-party/main-renderer/animation/render.js

@@ -1,4 +1,3 @@
-import { collectSuppressedSquares } from '../../../../animation/planner.js';
 import { cleanAnimationPlan, prepareAnimationPlan, renderAnimationPlan } from '../../../../animation/render/plan.js';
 const EMPTY_SQUARES = new Set();
 export function rendererAnimationPrepare(state, context, layer) {
@@ -38,7 +37,7 @@ export function getAnimationSuppressedSquares(state) {
         const entry = state.entries.get(session.id);
         if (!entry)
             continue;
-        for (const sq of collectSuppressedSquares(entry.plan.tracks)) {
+        for (const sq of entry.plan.suppressedSquares) {
             result.add(sq);
         }
     }

package/dist/extensions/first-party/main-renderer/animation/update.js

@@ -1,40 +1,26 @@
 import { calculateAnimationPlan } from '../../../../animation/planner.js';
 import { piecePositionsEqual } from '../../../../state/board/check.js';
+import { changeStatesEqual } from '../../../../state/change/helpers.js';
 import { isUpdateContextRenderable } from '../../../types/context/update.js';
 const DEFAULT_ANIMATION_DURATION_MS = 180;
 export function rendererAnimationOnUpdate(state, context) {
     if (!isUpdateContextRenderable(context) ||
-        !context.mutation.hasMutation({ prefixes: ['state.board.'] }) ||
+        !context.mutation.hasMutation({ prefixes: ['state.board.', 'state.change.'] }) ||
         !context.previousFrame) {
         return;
     }
-    const previousBoard = context.previousFrame.state.board;
-    const currentBoard = context.currentFrame.state.board;
-    if (piecePositionsEqual(previousBoard, currentBoard))
+    if (piecePositionsEqual(context.previousFrame.state.board, context.currentFrame.state.board) &&
+        changeStatesEqual(context.previousFrame.state.change, context.currentFrame.state.change))
         return;
-    // On DropTo exclude the move that user did from the animation plan
-    const exclude = [];
-    if (context.mutation.hasMutation({ causes: ['runtime.interaction.dropTo'] }) &&
-        context.currentFrame.state.change.lastMove) {
-        exclude.push({
-            fromSq: context.currentFrame.state.change.lastMove.from,
-            toSq: context.currentFrame.state.change.lastMove.to
-        });
-        exclude.push({
-            sq: context.currentFrame.state.change.lastMove.from
-        });
-        exclude.push({
-            sq: context.currentFrame.state.change.lastMove.to
-        });
-    }
-    const plan = calculateAnimationPlan(previousBoard, currentBoard, 0 /* placeholder session id for draft plan */, {
-        exclude
+    // Pass raw snapshots to the planner — it normalizes internally
+    const plan = calculateAnimationPlan({
+        previous: context.previousFrame.state,
+        current: context.currentFrame.state
     });
     if (plan.tracks.length === 0)
         return;
     const session = state.runtimeSurface.animation.submit({
         duration: DEFAULT_ANIMATION_DURATION_MS
     });
-    plan.sessionId = session.id;
-    state.entries.set(plan.sessionId, { plan, nodes: null });
+    state.entries.set(session.id, { plan, nodes: null });
 }

package/dist/extensions/first-party/main-renderer/board/render.js

@@ -10,13 +10,13 @@ export function rendererBoardRender(state, context, layer) {
     clearElementChildren(layer);
     const { light, dark } = state.config;
     for (let sq = 0; sq < SQUARE_COUNT; sq++) {
-        const r = geometry.squareRect(sq);
+        const r = geometry.getSquareRect(sq);
         createSvgElement(layer, 'rect', {
             'data-chessboard-id': `square-${sq}`,
             x: r.x.toString(),
             y: r.y.toString(),
-            width: r.size.toString(),
-            height: r.size.toString(),
+            width: r.width.toString(),
+            height: r.height.toString(),
             fill: isLightSquare(sq) ? light : dark,
             'shape-rendering': 'crispEdges'
         });

package/dist/extensions/first-party/main-renderer/board/update.js

@@ -1,3 +1,4 @@
+import { sceneRectsEqual } from '../../../../layout/geometry/helpers.js';
 import { isFrameRenderable } from '../../../types/basic/update.js';
 import { isUpdateContextRenderable } from '../../../types/context/update.js';
 import { DirtyLayer } from '../types/extension.js';
@@ -12,14 +13,15 @@ export function rendererBoardOnUpdate(_state, context) {
     }
     // Ok geometry changed, let's check the board size
     const currentGeometry = context.currentFrame.layout.geometry;
-    const currentBoardSize = currentGeometry.boardSize;
+    const currentBoardRect = currentGeometry.boardRect;
     const currentOrientation = currentGeometry.orientation;
     const previousGeometry = context.previousFrame && isFrameRenderable(context.previousFrame)
         ? context.previousFrame.layout.geometry
         : null;
-    const previousBoardSize = previousGeometry?.boardSize;
+    const previousBoardRect = previousGeometry?.boardRect ?? null;
     const previousOrientation = previousGeometry?.orientation;
-    const needsRender = currentBoardSize !== previousBoardSize || currentOrientation !== previousOrientation;
+    const needsRender = sceneRectsEqual(currentBoardRect, previousBoardRect) === false ||
+        currentOrientation !== previousOrientation;
     if (!needsRender) {
         return; // no-op
     }

package/dist/extensions/first-party/main-renderer/coordinates/render.js

@@ -19,7 +19,7 @@ export function rendererCoordinatesRender(state, context, layer) {
         const logicalRank = (geometry.orientation === 0 /* ColorCode.White */ ? 7 - visualRank : visualRank);
         const sq = squareOf(rankFile, logicalRank);
         const label = geometry.orientation === 0 /* ColorCode.White */ ? String(8 - visualRank) : String(1 + visualRank);
-        const r = geometry.squareRect(sq);
+        const r = geometry.getSquareRect(sq);
         const color = labelColorForSquare(sq, coords);
         const text = createSvgElement(layer, 'text', {
             'data-chessboard-id': `coord-rank-${label}`,
@@ -42,12 +42,12 @@ export function rendererCoordinatesRender(state, context, layer) {
         const label = geometry.orientation === 0 /* ColorCode.White */
             ? String.fromCharCode('a'.charCodeAt(0) + visualFile)
             : String.fromCharCode('h'.charCodeAt(0) - visualFile);
-        const r = geometry.squareRect(sq);
+        const r = geometry.getSquareRect(sq);
         const color = labelColorForSquare(sq, coords);
         const text = createSvgElement(layer, 'text', {
             'data-chessboard-id': `coord-file-${label}`,
-            x: (r.x + r.size - offset).toString(),
-            y: (r.y + r.size - offset).toString(),
+            x: (r.x + r.width - offset).toString(),
+            y: (r.y + r.height - offset).toString(),
             'font-size': fontSize.toString(),
             'font-family': 'sans-serif',
             'font-weight': 'bold',

package/dist/extensions/first-party/main-renderer/drag/render.js

@@ -1,7 +1,7 @@
 import { createSvgElement, updateElementAttributes } from '../../../../render/svg/helpers.js';
 export function rendererDragRenderTransientVisuals(state, context, layer) {
     const geometry = context.currentFrame.layout.geometry;
-    const point = context.transientInput.clampedPoint;
+    const point = context.transientInput.boardClampedPoint;
     const squareSize = geometry.squareSize.toString();
     const x = (point.x - geometry.squareSize / 2).toString();
     const y = (point.y - geometry.squareSize / 2).toString();

package/dist/extensions/first-party/main-renderer/factory.js

@@ -1,5 +1,5 @@
 import { toMerged } from 'es-toolkit';
-import { extensionCreateInternalBase, extensionDestroy, extensionMount, extensionUnmount } from '../common/helpers.js';
+import { extensionCreateInternalBase, extensionDestroyBase, extensionMountBase, extensionUnmountBase } from '../common/helpers.js';
 import { createMainRendererAnimation } from './animation/factory.js';
 import { createMainRendererBoard } from './board/factory.js';
 import { createMainRendererCoordinates } from './coordinates/factory.js';
@@ -51,7 +51,7 @@ function createMainRendererInstance(options, config) {
     return {
         id: EXTENSION_ID,
         mount(env) {
-            extensionMount(internalState, env.slotRoots);
+            extensionMountBase(internalState, env.slotRoots);
         },
         onUpdate(context) {
             internalState.board.onUpdate(context);
@@ -85,11 +85,11 @@ function createMainRendererInstance(options, config) {
         },
         unmount() {
             extensionUnmountLocal(internalState);
-            extensionUnmount(internalState);
+            extensionUnmountBase(internalState);
         },
         destroy() {
             extensionUnmountLocal(internalState);
-            extensionDestroy(internalState);
+            extensionDestroyBase(internalState);
         }
     };
 }

package/dist/extensions/first-party/main-renderer/normalize.d.ts

@@ -1,4 +1,3 @@
-import { MainRendererConfigInput, PieceUrlsInput } from './types/input.js';
-import { MainRendererConfig, PieceUrls } from './types/internal.js';
-export declare function normalizePieceUrls(input: PieceUrlsInput): PieceUrls;
+import { MainRendererConfigInput } from './types/input.js';
+import { MainRendererConfig } from './types/internal.js';
 export declare function normalizeMainRendererConfig(input: Partial<MainRendererConfigInput>): MainRendererConfig;

package/dist/extensions/first-party/main-renderer/normalize.js

@@ -7,7 +7,7 @@ function assertPieceUrlsComplete(pieceUrls) {
         assert(pieceCode in pieceUrls, `Missing URL for piece code: ${pieceCode}`);
     }
 }
-export function normalizePieceUrls(input) {
+function normalizePieceUrls(input) {
     const normalized = {};
     for (const [key, url] of Object.entries(input)) {
         const pieceCode = normalizePiece(key);

package/dist/extensions/first-party/main-renderer/pieces/render.js

@@ -14,13 +14,13 @@ export function rendererPiecesRender(state, context, layer) {
         const suppressed = state.suppressedSquares.has(sq);
         if (isNonEmptyPieceCode(pieceCode) && !suppressed) {
             const url = state.config[pieceCode];
-            const r = geometry.squareRect(sq);
+            const r = geometry.getSquareRect(sq);
             if (existing !== null) {
                 updateElementAttributes(existing.root, {
                     x: r.x.toString(),
                     y: r.y.toString(),
-                    width: r.size.toString(),
-                    height: r.size.toString(),
+                    width: r.width.toString(),
+                    height: r.height.toString(),
                     href: url
                 });
             }
@@ -31,8 +31,8 @@ export function rendererPiecesRender(state, context, layer) {
                         href: url,
                         x: r.x.toString(),
                         y: r.y.toString(),
-                        width: r.size.toString(),
-                        height: r.size.toString()
+                        width: r.width.toString(),
+                        height: r.height.toString()
                     })
                 });
             }

package/dist/extensions/first-party/main-renderer/pieces/suppress.js

@@ -1,9 +1,14 @@
 export function calculateSuppressedSquares(_state, context, animationSuppressedSquares) {
     const dragSession = context.currentFrame.state.interaction.dragSession;
-    const dragSquare = dragSession?.type === 'lifted-piece-drag' ? dragSession.sourceSquare : undefined;
+    const dragSquare = dragSession?.type === 'lifted-piece-drag' ? dragSession.sourceSquare : null;
     const result = new Set(animationSuppressedSquares);
-    if (dragSquare !== undefined) {
+    if (dragSquare !== null) {
         result.add(dragSquare);
     }
+    const pendingMoveRequest = context.currentFrame.state.change.deferredUIMoveRequest;
+    if (pendingMoveRequest) {
+        result.add(pendingMoveRequest.sourceSquare);
+        result.add(pendingMoveRequest.destination.to);
+    }
     return result;
 }

package/dist/extensions/first-party/main-renderer/types/extension.d.ts

@@ -3,7 +3,7 @@ import { MainRendererConfigInput } from './input.js';
 export type MainRendererInitOptions = Partial<MainRendererConfigInput>;
 export declare const EXTENSION_SLOTS: readonly ["board", "coordinates", "pieces", "animation", "drag"];
 export type ExtensionSlotsType = typeof EXTENSION_SLOTS;
-export declare const EXTENSION_ID: "main-renderer";
+export declare const EXTENSION_ID: "renderer";
 export type MainRendererDefinition = ExtensionDefinition<typeof EXTENSION_ID, typeof EXTENSION_SLOTS, never>;
 export type MainRendererInstance = ExtensionInstance<typeof EXTENSION_ID, typeof EXTENSION_SLOTS, never>;
 export declare enum DirtyLayer {

package/dist/extensions/first-party/main-renderer/types/extension.js

@@ -1,5 +1,5 @@
 export const EXTENSION_SLOTS = ['board', 'coordinates', 'pieces', 'animation', 'drag'];
-export const EXTENSION_ID = 'main-renderer';
+export const EXTENSION_ID = 'renderer';
 export var DirtyLayer;
 (function (DirtyLayer) {
     DirtyLayer[DirtyLayer["Board"] = 1] = "Board";

package/dist/extensions/first-party/main-renderer/types/instance.d.ts

@@ -1,12 +1,12 @@
 import { ExtensionRuntimeSurface } from '../../../types/surface/main.js';
-import { ExtensionInternal } from '../../common/types.js';
+import { ExtensionInternalBase } from '../../common/types.js';
 import { MainRendererAnimation } from '../animation/types.js';
 import { MainRendererBoard } from '../board/types.js';
 import { MainRendererCoordinates } from '../coordinates/types.js';
 import { MainRendererDrag } from '../drag/types.js';
 import { MainRendererPieces } from '../pieces/types.js';
 import { ExtensionSlotsType } from './extension.js';
-export interface MainRendererInstanceInternal extends ExtensionInternal<ExtensionSlotsType> {
+export interface MainRendererInstanceInternal extends ExtensionInternalBase<ExtensionSlotsType> {
     readonly board: MainRendererBoard;
     readonly coordinates: MainRendererCoordinates;
     readonly pieces: MainRendererPieces;

package/dist/extensions/first-party/promotion/factory.d.ts

@@ -0,0 +1,3 @@
+import { PromotionInitConfig } from './types/input.js';
+import { PromotionDefinition } from './types/main.js';
+export declare function createPromotion(config?: PromotionInitConfig): PromotionDefinition;

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

@@ -0,0 +1,219 @@
+import assert from '@ktarmyshov/assert';
+import { createSvgElement, updateElementAttributes } from '../../../render/svg/helpers.js';
+import { fileOf, rankOf, squareOf } from '../../../state/board/coords.js';
+import { toPieceCode } from '../../../state/board/piece.js';
+import { isUpdateContextRenderable } from '../../types/context/update.js';
+import { extensionCreateInternalBase, extensionDestroyBase, extensionMountBase, extensionUnmountBase } from '../common/helpers.js';
+import { normalizePromotionConfig } from './normalize.js';
+import { EXTENSION_ID, EXTENSION_SLOTS } from './types/main.js';
+export function createPromotion(config = {}) {
+    const mergedConfig = normalizePromotionConfig(config);
+    return {
+        id: EXTENSION_ID,
+        slots: EXTENSION_SLOTS,
+        createInstance(options) {
+            return createPromotionInstance(options, mergedConfig);
+        }
+    };
+}
+function createPromotionInternal(options, config) {
+    return {
+        ...extensionCreateInternalBase(),
+        svgPromotionPieces: new Map(),
+        activePromotionSquares: new Map(),
+        svgHoverRect: null,
+        config,
+        runtimeSurface: options.runtimeSurface
+    };
+}
+function extensionCleanPieceNode(state, roleCode) {
+    const pieceNode = state.svgPromotionPieces.get(roleCode);
+    if (pieceNode) {
+        pieceNode.svg.remove();
+        pieceNode.rect.remove();
+        state.svgPromotionPieces.delete(roleCode);
+    }
+}
+function extensionCleanPieceNodes(state) {
+    for (const pieceNode of state.svgPromotionPieces.values()) {
+        pieceNode.svg.remove();
+        pieceNode.rect.remove();
+    }
+    state.svgPromotionPieces.clear();
+}
+function extensionCleanHoverRect(state) {
+    if (state.svgHoverRect) {
+        state.svgHoverRect.remove();
+        state.svgHoverRect = null;
+    }
+}
+function extensionClean(state) {
+    extensionCleanPieceNodes(state);
+    extensionCleanHoverRect(state);
+    state.activePromotionSquares.clear();
+}
+function createPromotionInstance(options, config) {
+    const internalState = createPromotionInternal(options, config);
+    return {
+        id: EXTENSION_ID,
+        mount(env) {
+            extensionMountBase(internalState, env.slotRoots);
+        },
+        onUIMoveRequest(context) {
+            const request = context.request;
+            if (request.status !== 'unresolved')
+                return; // no-op if the request is already resolved or deferred
+            if (request.canBeAutoResolved)
+                return; // no-op, core will auto-resolve
+            // OK! now this one is our request!
+            request.defer(); // defer the request until the user selects a piece to promote to
+        },
+        onUpdate(context) {
+            const needsRender = context.mutation.hasMutation({
+                causes: ['state.change.setDeferredUIMoveRequest', 'layout.refreshGeometry']
+            }) && isUpdateContextRenderable(context);
+            if (!needsRender) {
+                return; // no-op
+            }
+            const request = context.currentFrame.state.change.deferredUIMoveRequest;
+            if (request !== null) {
+                internalState.runtimeSurface.transientVisuals.subscribe();
+                internalState.runtimeSurface.events.subscribeEvent('pointerdown');
+            }
+            else {
+                internalState.runtimeSurface.transientVisuals.unsubscribe();
+                internalState.runtimeSurface.events.unsubscribeEvent('pointerdown');
+            }
+            context.invalidation.markDirty(1 /* DirtyLayer.Promotion */);
+        },
+        render(context) {
+            assert(context.invalidation.dirtyLayers !== 0, 'Render should only be called when there are dirty layers');
+            const deferredRequest = context.currentFrame.state.change.deferredUIMoveRequest;
+            if (deferredRequest === null) {
+                // No deferred request, so we can clean up any existing promotion piece nodes and highlights
+                extensionClean(internalState);
+                return;
+            }
+            const targetSquare = deferredRequest.destination.to;
+            const targetFile = fileOf(targetSquare);
+            const targetRank = rankOf(targetSquare);
+            const promotedTo = deferredRequest.destination.promotedTo;
+            assert(promotedTo && promotedTo.length > 1 && promotedTo.length <= 4, 'PromotedTo should be available in a deferred promotion request and have between 2 and 4 roles');
+            const promotedToSorted = promotedTo.toSorted((a, b) => b - a); // Descending order to render queen on top
+            const geometry = context.currentFrame.layout.geometry;
+            // Determine piece color from target rank
+            const isWhitePromotion = targetRank === 7;
+            const pieceColor = isWhitePromotion ? 0 /* ColorCode.White */ : 8 /* ColorCode.Black */;
+            // Direction: white pieces cascade downward (rank decreases), black upward (rank increases)
+            const rankStep = isWhitePromotion ? -1 : 1;
+            // Rebuild the active promotion squares set
+            internalState.activePromotionSquares.clear();
+            // Remove nodes for roles no longer in the desired set
+            const desiredRoles = new Set(promotedToSorted);
+            for (const [roleCode] of internalState.svgPromotionPieces) {
+                if (!desiredRoles.has(roleCode)) {
+                    extensionCleanPieceNode(internalState, roleCode);
+                }
+            }
+            // Create or update a node for each promotion role
+            assert(internalState.slotRoots, 'Slot roots should be available when render is called');
+            const layer = internalState.slotRoots.animation;
+            for (let i = 0; i < promotedToSorted.length; i++) {
+                const roleCode = promotedToSorted[i];
+                const displayRank = (targetRank + i * rankStep);
+                const displaySquare = squareOf(targetFile, displayRank);
+                const pieceCode = toPieceCode(roleCode, pieceColor);
+                const url = internalState.config.pieceUrls[pieceCode];
+                const r = geometry.getSquareRect(displaySquare);
+                const rectAttrs = {
+                    x: r.x.toString(),
+                    y: r.y.toString(),
+                    width: r.width.toString(),
+                    height: r.height.toString(),
+                    fill: internalState.config.squareColor.color,
+                    'fill-opacity': internalState.config.squareColor.opacity.toString(),
+                    'shape-rendering': 'crispEdges'
+                };
+                const imageAttrs = {
+                    href: url,
+                    x: r.x.toString(),
+                    y: r.y.toString(),
+                    width: r.width.toString(),
+                    height: r.height.toString()
+                };
+                internalState.activePromotionSquares.set(displaySquare, roleCode);
+                const existing = internalState.svgPromotionPieces.get(roleCode) ?? null;
+                if (existing !== null) {
+                    updateElementAttributes(existing.rect, rectAttrs);
+                    updateElementAttributes(existing.svg, imageAttrs);
+                }
+                else {
+                    const rect = createSvgElement(layer, 'rect', {
+                        'data-chessboard-id': `promotion-bg-${roleCode}`,
+                        ...rectAttrs
+                    });
+                    const svg = createSvgElement(layer, 'image', {
+                        'data-chessboard-id': `promotion-piece-${roleCode}`,
+                        ...imageAttrs
+                    });
+                    internalState.svgPromotionPieces.set(roleCode, { svg, rect });
+                }
+            }
+        },
+        renderTransientVisuals(context) {
+            const target = context.transientInput.target;
+            if (target !== null && internalState.activePromotionSquares.has(target)) {
+                // Hover is over one of the promotion squares
+                const geometry = context.currentFrame.layout.geometry;
+                const r = geometry.getSquareRect(target);
+                const attrs = {
+                    x: r.x.toString(),
+                    y: r.y.toString(),
+                    width: r.width.toString(),
+                    height: r.height.toString(),
+                    fill: internalState.config.hoverColor.color,
+                    'fill-opacity': internalState.config.hoverColor.opacity.toString(),
+                    'shape-rendering': 'crispEdges'
+                };
+                if (internalState.svgHoverRect) {
+                    updateElementAttributes(internalState.svgHoverRect, attrs);
+                }
+                else {
+                    assert(internalState.slotRoots, 'Slot roots should be available when renderTransientVisuals is called');
+                    const layer = internalState.slotRoots.animation;
+                    internalState.svgHoverRect = createSvgElement(layer, 'rect', {
+                        'data-chessboard-id': 'promotion-hover',
+                        ...attrs
+                    });
+                }
+            }
+            else {
+                // Not hovering over a promotion square — remove hover rect
+                extensionCleanHoverRect(internalState);
+            }
+        },
+        onEvent(context) {
+            assert(context.rawEvent.type === 'pointerdown', 'Only pointerdown events should be subscribed to');
+            const targetSquare = context.sceneEvent?.targetSquare ?? null;
+            if (targetSquare !== null) {
+                const roleCode = internalState.activePromotionSquares.get(targetSquare);
+                if (roleCode !== undefined) {
+                    context.rawEvent.preventDefault(); // Prevent focus change and other side effects if it is our promotion square
+                    internalState.runtimeSurface.commands.resolveDeferredUIMoveRequest({
+                        promotedTo: roleCode
+                    });
+                    return;
+                }
+            }
+            internalState.runtimeSurface.commands.cancelDeferredUIMoveRequest();
+        },
+        unmount() {
+            extensionUnmountBase(internalState);
+            extensionClean(internalState);
+        },
+        destroy() {
+            extensionDestroyBase(internalState);
+            extensionClean(internalState);
+        }
+    };
+}

package/dist/extensions/first-party/promotion/normalize.d.ts

@@ -0,0 +1,3 @@
+import { PromotionInitConfig } from './types/input.js';
+import { PromotionConfig } from './types/internal.js';
+export declare function normalizePromotionConfig(config: PromotionInitConfig): PromotionConfig;