@mirasen/chessboard 1.2.4 → 1.3.1

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @mirasen/chessboard
 
+## 1.3.1
+
+### Patch Changes
+
+- be0386f: Calibrate the default mobile drag piece scale and add board-level desktop/mobile config presets.
+
+  The mobile main-renderer drag preset now uses a larger lifted piece scale while preserving the existing bottom anchor and offset.
+
+  The root package now also exports `DefaultChessboardDesktopConfig` and `DefaultChessboardMobileConfig`, which combine the matching interaction defaults with the matching main-renderer defaults for easier desktop/mobile preset usage.
+
+- be0386f: Calibrate the default mobile drag piece scale.
+
+  The mobile main-renderer drag preset now uses a larger lifted piece scale, making touch dragging feel closer to common mobile chessboard behavior while keeping the existing bottom anchor and offset.
+
+## 1.3.0
+
+### Minor Changes
+
+- eaed694: Add configurable desktop and mobile drag behavior.
+
+  The board now exposes interaction config APIs through `setInteractionConfig()` and `getInteractionConfig()`, including `drag.liftedActivation.thresholdPx`. This enables desktop-style immediate drag activation and mobile-style delayed drag activation from the same interaction model.
+
+  The first-party main renderer now exposes runtime config APIs through `renderer.setConfig()` and `renderer.getConfig()`. Renderer config now includes dragged-piece visual settings and animation duration:
+  - `drag.pieceScale`
+  - `drag.pieceAnchor`
+  - `drag.pieceAnchorOffsetY`
+  - `animation.durationMs`
+
+  The package also exports public desktop/mobile main-renderer defaults from `@mirasen/chessboard/extensions` as `DefaultMainRendererDesktopConfig` and `DefaultMainRendererMobileConfig`.
+
+  Set `animation.durationMs` to `0` to disable piece movement animation by skipping animation creation.
+
+  Custom extension authors may need to update runtime interaction action names and payload fields to the new drag-session naming.
+
+### Patch Changes
+
+- dde200f: dependabot: directory '/', update eslint
+- dfe6882: dependabot: directory '/', update typescript from 5.9.3 to 6.0.3
+- eb1fcb5: dependabot: directory '/', update @types/node
+- eb1fcb5: dependabot: directory '/', update @vitest/browser-playwright
+- eb1fcb5: dependabot: directory '/', update @vitest/coverage-istanbul
+- eb1fcb5: dependabot: directory '/', update svelte
+- eb1fcb5: dependabot: directory '/', update typescript-eslint
+- eb1fcb5: dependabot: directory '/', update vitest
+- d1da3c1: Prevent fast mouse dragging from triggering native browser drag-and-drop on SVG piece images.
+
+  Browsers can treat SVG images inside pieces as draggable content during quick mouse movement. When that native drag fallback starts, it can interrupt the board's pointer-driven drag flow by causing `pointercancel` / `lostpointercapture` and, in some cases, preventing the board from receiving the expected `pointerup`.
+
+  The board now suppresses native `dragstart` by default when no extension consumes the event, reducing one common source of interrupted fast mouse drags while keeping the existing `lostpointercapture` recovery path for other platform edge cases. `dragstart` remains observable by extensions and does not produce a core interaction action.
+
 ## 1.2.4
 
 ### Patch Changes

package/README.md

@@ -11,6 +11,7 @@ A framework-agnostic TypeScript chessboard platform with real chess interaction
 ## Try it live (including annotations)
 
 - [Play a chess.js game](https://mirasen.io/chessboard/examples/chessjs.html)
+- [Watch 12 live boards](https://mirasen.io/chessboard/examples/live-games-grid.html)
 - [Try the promotion flow](https://mirasen.io/chessboard/examples/promotion.html)
 - [Try the minimal example](https://mirasen.io/chessboard/examples/minimal.html)
 
@@ -18,6 +19,14 @@ A framework-agnostic TypeScript chessboard platform with real chess interaction
 
 Use [`@mirasen/react-chessboard`](https://www.npmjs.com/package/@mirasen/react-chessboard) for a React component with the same built-in interaction, annotations, promotion, animation, and chess.js integration.
 
+## Native mobile apps
+
+`@mirasen/chessboard` is not tied to React or any other web framework. It is plain TypeScript/JavaScript on top of DOM and SVG, so it should fit WebView-based native iOS or Android integrations.
+
+A common integration pattern is to bundle a WebView host page, mount the board there, and communicate with the native app through the platform bridge.
+
+This keeps the integration model lightweight while avoiding a separate native chessboard UI implementation.
+
 ## Why this exists
 
 Most chessboards fall into one of two buckets:
@@ -65,7 +74,7 @@ Rules and legality still belong to your game layer. Use the built-in `chess.js`
 - Real built-in chess interaction
 - Built-in circles and arrows with live add/remove previews
 - **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
+- Works on desktop and mobile out of the box, with pointer-based mouse/touch interaction and tunable drag behavior
 - State-diff animation beyond simple move events
 - Extension-driven architecture
 - First-party baseline extensions
@@ -257,6 +266,68 @@ Movability controls how the board accepts user-initiated moves.
 - `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
 
+### Desktop and mobile drag tuning
+
+The board exposes interaction-level and renderer-level drag configuration so you can tune mouse-first and touch-first surfaces without replacing the built-in interaction model.
+
+Interaction config controls when lifted-piece drag becomes active:
+
+```ts
+const board = createBoard({
+	element
+});
+
+board.setInteractionConfig({
+	drag: {
+		liftedActivation: {
+			thresholdPx: 5
+		}
+	}
+});
+```
+
+Use `thresholdPx: 0` for immediate desktop-style drag activation, or a small threshold for mobile/touch UIs where the piece should not jump on the first tiny pointer movement.
+
+The first-party renderer controls how the lifted piece looks while dragging:
+
+```ts
+board.extensions.renderer.setConfig({
+	drag: {
+		pieceScale: 2,
+		pieceAnchor: 'bottom',
+		pieceAnchorOffsetY: 0.14
+	}
+});
+```
+
+For convenience, the root package ships board-level presets that combine the interaction feel and renderer visuals for a desktop- or mobile-style board. Apply both parts together:
+
+```ts
+import { DefaultChessboardMobileConfig } from '@mirasen/chessboard';
+
+board.setInteractionConfig(DefaultChessboardMobileConfig.interaction);
+
+board.extensions.renderer.setConfig({
+	drag: DefaultChessboardMobileConfig.renderer.drag
+});
+```
+
+`DefaultChessboardDesktopConfig` is the matching desktop preset. If you only want the renderer half, the lower-level `DefaultMainRendererDesktopConfig` and `DefaultMainRendererMobileConfig` building blocks are still exported from `@mirasen/chessboard/extensions`.
+
+### Animation tuning
+
+The first-party renderer exposes animation duration config:
+
+```ts
+board.extensions.renderer.setConfig({
+	animation: {
+		durationMs: 0
+	}
+});
+```
+
+Set `animation.durationMs` to `0` when you want position updates to render instantly without creating movement animations.
+
 ### 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.

package/dist/animation/planner.js

@@ -3,6 +3,7 @@ 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 { baseMovesEqual } from '../state/change/helpers.js';
+import { isDragSessionActiveLiftedPiece } from '../state/interaction/helpers.js';
 // ---------------------------------------------------------------------------
 // Precomputed squared distance: (dFile² + dRank²) for all square pairs.
 // Max value = 7² + 7² = 98, fits in Uint8.  Index: a * 64 + b.
@@ -31,7 +32,7 @@ const EMPTY_EXCLUDE = {
  */
 function detectLiftedPieceDrop(previous, current) {
     const prevDrag = previous.interaction.dragSession;
-    if (!prevDrag || prevDrag.type !== 'lifted-piece-drag')
+    if (!prevDrag || !isDragSessionActiveLiftedPiece(prevDrag))
         return null;
     if (current.interaction.dragSession !== null)
         return null;

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

@@ -10,8 +10,8 @@ export type { ColorCode, EmptyPieceCode, NonEmptyPieceCode, PieceCode, RoleCode,
 export type { MovabilityModeCode } from '../../state/interaction/types/internal.js';
 export { extensionCreateInternalBase, extensionDestroyBase, extensionIsDestroyedBase, extensionIsMountedBase, extensionMountBase, extensionUnmountBase } from '../first-party/common/helpers.js';
 export type { ExtensionInternalBase, OpaqueColor } from '../first-party/common/types.js';
-export type { PieceUrlsInput } from '../first-party/main-renderer/types/input.js';
 export type { PieceUrls } from '../first-party/main-renderer/types/internal.js';
+export type { PieceUrlsPublic } from '../first-party/main-renderer/types/public.js';
 export type { PromotionPieceCode } from '../first-party/promotion/types/internal.js';
 export type { ExtensionSlotName, ExtensionSlotSvgRoots } from '../types/basic/mount.js';
 export { isFrameMounted, isFrameRenderable } from '../types/basic/update.js';

package/dist/extensions/first-party/annotations/update.js

@@ -5,7 +5,7 @@ export function annotationsOnUpdate(state, context) {
     if (state.config.clearOnCoreInteraction &&
         hasCommittedAnnotations(state) &&
         context.mutation.hasMutation({
-            causes: ['runtime.interaction.completeCoreDragTo']
+            causes: ['runtime.interaction.completeCoreDragSessionTo']
         })) {
         clearCommittedAnnotations(state);
         context.invalidation.markDirty(1 /* DirtyLayer.COMMITTED */);

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

@@ -45,8 +45,8 @@ function createBoardEventsInstance(options) {
             });
             const interactionCompleted = context.mutation.hasMutation({
                 causes: [
-                    'runtime.interaction.completeCoreDragTo',
-                    'runtime.interaction.completeExtensionDragTo',
+                    'runtime.interaction.completeCoreDragSessionTo',
+                    'runtime.interaction.completeExtensionDragSession',
                     'runtime.interaction.resolveDeferredUIMoveRequest'
                 ]
             });

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

@@ -1,4 +1,5 @@
 import type { ExtensionRuntimeSurface } from '../../../types/surface/main.js';
 import type { PieceSymbolResolver } from '../piece-symbols.js';
+import type { MainRendererConfigAnimation } from '../types/template.js';
 import type { MainRendererAnimation } from './types.js';
-export declare function createMainRendererAnimation(runtimeSurface: ExtensionRuntimeSurface, resolver: PieceSymbolResolver): MainRendererAnimation;
+export declare function createMainRendererAnimation(runtimeSurface: ExtensionRuntimeSurface, resolver: PieceSymbolResolver, getAnimationConfig: () => MainRendererConfigAnimation): MainRendererAnimation;

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

@@ -1,11 +1,12 @@
 import { cleanAnimationPlan } from '../../../../animation/render/plan.js';
 import { getAnimationSuppressedSquares, rendererAnimationClean, rendererAnimationPrepare, rendererAnimationRender } from './render.js';
 import { rendererAnimationOnUpdate } from './update.js';
-export function createMainRendererAnimation(runtimeSurface, resolver) {
+export function createMainRendererAnimation(runtimeSurface, resolver, getAnimationConfig) {
     const state = {
         runtimeSurface,
         resolver,
-        entries: new Map()
+        entries: new Map(),
+        getAnimationConfig
     };
     return {
         onUpdate(context) {

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

@@ -5,6 +5,7 @@ import { ExtensionCleanAnimationContext, ExtensionPrepareAnimationContext, Exten
 import { ExtensionUpdateContext } from '../../../types/context/update.js';
 import { ExtensionRuntimeSurface } from '../../../types/surface/main.js';
 import type { PieceSymbolResolver } from '../piece-symbols.js';
+import type { MainRendererConfigAnimation } from '../types/template.js';
 export interface MainRendererAnimationEntry {
     plan: AnimationPlan;
     nodes: PreparedNodeMap | null;
@@ -13,6 +14,7 @@ export interface MainRendererAnimationInternal {
     readonly runtimeSurface: ExtensionRuntimeSurface;
     readonly resolver: PieceSymbolResolver;
     readonly entries: Map<number, MainRendererAnimationEntry>;
+    readonly getAnimationConfig: () => MainRendererConfigAnimation;
 }
 export interface MainRendererAnimation {
     onUpdate(context: ExtensionUpdateContext): void;

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

@@ -2,7 +2,6 @@ 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.', 'state.change.'] }) ||
@@ -12,6 +11,9 @@ export function rendererAnimationOnUpdate(state, context) {
     if (piecePositionsEqual(context.previousFrame.state.board, context.currentFrame.state.board) &&
         changeStatesEqual(context.previousFrame.state.change, context.currentFrame.state.change))
         return;
+    const durationMs = state.getAnimationConfig().durationMs;
+    if (durationMs === 0)
+        return;
     // Pass raw snapshots to the planner — it normalizes internally
     const plan = calculateAnimationPlan({
         previous: context.previousFrame.state,
@@ -20,7 +22,7 @@ export function rendererAnimationOnUpdate(state, context) {
     if (plan.tracks.length === 0)
         return;
     const session = state.runtimeSurface.animation.submit({
-        duration: DEFAULT_ANIMATION_DURATION_MS
+        duration: durationMs
     });
     state.entries.set(session.id, { plan, nodes: null });
 }

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

@@ -1,3 +1,3 @@
 import { ConfigColorPair } from '../types/internal.js';
 import { MainRendererBoard } from './types.js';
-export declare function createMainRendererBoard(config: ConfigColorPair): MainRendererBoard;
+export declare function createMainRendererBoard(getColorConfig: () => ConfigColorPair): MainRendererBoard;

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

@@ -1,10 +1,10 @@
 import { rendererBoardRender } from './render.js';
 import { rendererBoardOnUpdate } from './update.js';
-function createMainRendererBoardInternal(config) {
-    return { config };
+function createMainRendererBoardInternal(getColorConfig) {
+    return { getColorConfig };
 }
-export function createMainRendererBoard(config) {
-    const internalState = createMainRendererBoardInternal(config);
+export function createMainRendererBoard(getColorConfig) {
+    const internalState = createMainRendererBoardInternal(getColorConfig);
     return {
         onUpdate(context) {
             rendererBoardOnUpdate(internalState, context);

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

@@ -8,7 +8,7 @@ export function rendererBoardRender(state, context, slot) {
     }
     const geometry = context.currentFrame.layout.geometry;
     clearSvgElementChildren(slot);
-    const { light, dark } = state.config;
+    const { light, dark } = state.getColorConfig();
     for (let sq = 0; sq < SQUARE_COUNT; sq++) {
         const r = geometry.getSquareRect(sq);
         createSvgElement(slot, 'rect', {

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

@@ -2,7 +2,7 @@ import { ExtensionRenderContext } from '../../../types/context/render.js';
 import { ExtensionUpdateContext } from '../../../types/context/update.js';
 import { ConfigColorPair } from '../types/internal.js';
 export interface MainRendererBoardInternal {
-    readonly config: ConfigColorPair;
+    readonly getColorConfig: () => ConfigColorPair;
 }
 export interface MainRendererBoard {
     onUpdate(context: ExtensionUpdateContext): void;

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

@@ -1,3 +1,3 @@
 import { ConfigColorPair } from '../types/internal.js';
 import { MainRendererCoordinates } from './types.js';
-export declare function createMainRendererCoordinates(config: ConfigColorPair): MainRendererCoordinates;
+export declare function createMainRendererCoordinates(getColorConfig: () => ConfigColorPair): MainRendererCoordinates;

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

@@ -1,6 +1,6 @@
 import { rendererCoordinatesRender } from './render.js';
-export function createMainRendererCoordinates(config) {
-    const internalState = { config };
+export function createMainRendererCoordinates(getColorConfig) {
+    const internalState = { getColorConfig };
     return {
         render(context, slot) {
             rendererCoordinatesRender(internalState, context, slot);

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

@@ -10,7 +10,7 @@ export function rendererCoordinatesRender(state, context, slot) {
     }
     const geometry = context.currentFrame.layout.geometry;
     clearSvgElementChildren(slot);
-    const coords = state.config;
+    const coords = state.getColorConfig();
     const fontSize = geometry.squareSize * 0.12;
     const offset = 3;
     // Rank labels on the visual left edge

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

@@ -1,7 +1,7 @@
 import { ExtensionRenderContext } from '../../../types/context/render.js';
 import { ConfigColorPair } from '../types/internal.js';
 export interface MainRendererCoordinatesInternal {
-    readonly config: ConfigColorPair;
+    readonly getColorConfig: () => ConfigColorPair;
 }
 export interface MainRendererCoordinates {
     render(context: ExtensionRenderContext, slot: SVGGElement): void;

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

@@ -0,0 +1,3 @@
+import type { MainRendererConfig } from './types/internal.js';
+import type { MainRendererConfigPublic } from './types/public.js';
+export declare function denormalizeMainRendererConfig(config: MainRendererConfig): MainRendererConfigPublic;

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

@@ -0,0 +1,18 @@
+import { cloneDeep } from 'es-toolkit';
+import { denormalizePieceString } from '../../../state/board/denormalize.js';
+function denormalizePieceUrls(pieceUrls) {
+    const result = {};
+    for (const [codeKey, url] of Object.entries(pieceUrls)) {
+        const code = Number(codeKey);
+        result[denormalizePieceString(code)] = url;
+    }
+    return result;
+}
+export function denormalizeMainRendererConfig(config) {
+    return {
+        colors: cloneDeep(config.colors),
+        drag: cloneDeep(config.drag),
+        animation: cloneDeep(config.animation),
+        pieceUrls: denormalizePieceUrls(config.pieceUrls)
+    };
+}

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

@@ -1,4 +1,5 @@
 import { ExtensionRuntimeSurface } from '../../../types/surface/main.js';
 import type { PieceSymbolResolver } from '../piece-symbols.js';
+import type { MainRendererConfigDrag } from '../types/template.js';
 import { MainRendererDrag } from './types.js';
-export declare function createMainRendererDrag(runtimeSurface: ExtensionRuntimeSurface, resolver: PieceSymbolResolver): MainRendererDrag;
+export declare function createMainRendererDrag(runtimeSurface: ExtensionRuntimeSurface, resolver: PieceSymbolResolver, getDragConfig: () => MainRendererConfigDrag): MainRendererDrag;

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

@@ -1,9 +1,10 @@
 import { rendererDragRenderTransientVisuals } from './render.js';
 import { rendererDragOnUpdate } from './update.js';
-export function createMainRendererDrag(runtimeSurface, resolver) {
+export function createMainRendererDrag(runtimeSurface, resolver, getDragConfig) {
     const internalState = {
         runtimeSurface,
         resolver,
+        getDragConfig,
         isDragActive: false,
         pieceCode: null,
         pieceNode: null

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

@@ -1,28 +1,35 @@
 import { createSvgElement, updateSvgElementAttributes } from '../../../../render/svg/helpers.js';
 export function rendererDragRenderTransientVisuals(state, context, slot) {
+    const config = state.getDragConfig();
     const geometry = context.currentFrame.layout.geometry;
     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();
+    const renderedSize = geometry.squareSize * config.pieceScale;
+    const anchorOffsetY = geometry.squareSize * config.pieceAnchorOffsetY;
+    const x = point.x - renderedSize / 2;
+    const y = config.pieceAnchor === 'bottom'
+        ? point.y - renderedSize + anchorOffsetY
+        : point.y - renderedSize / 2 + anchorOffsetY;
+    const renderedSizeStr = renderedSize.toString();
+    const xStr = x.toString();
+    const yStr = y.toString();
     if (state.isDragActive && state.pieceCode && !state.pieceNode) {
         // Ok this is first render pass, let's create the piece node
         const href = state.resolver.getHref(state.pieceCode);
         state.pieceNode = createSvgElement(slot, 'use', {
             'data-chessboard-id': 'dragged-piece',
-            width: squareSize,
-            height: squareSize,
-            x,
-            y,
+            width: renderedSizeStr,
+            height: renderedSizeStr,
+            x: xStr,
+            y: yStr,
             href
         });
     }
     else if (state.isDragActive && state.pieceNode) {
         updateSvgElementAttributes(state.pieceNode, {
-            width: squareSize,
-            height: squareSize,
-            x,
-            y
+            width: renderedSizeStr,
+            height: renderedSizeStr,
+            x: xStr,
+            y: yStr
         });
     }
 }

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

@@ -3,9 +3,11 @@ import { ExtensionRenderTransientVisualsContext } from '../../../types/context/t
 import { ExtensionUpdateContext } from '../../../types/context/update.js';
 import { ExtensionRuntimeSurface } from '../../../types/surface/main.js';
 import type { PieceSymbolResolver } from '../piece-symbols.js';
+import type { MainRendererConfigDrag } from '../types/template.js';
 export interface MainRendererDragInternal {
     readonly runtimeSurface: ExtensionRuntimeSurface;
     readonly resolver: PieceSymbolResolver;
+    readonly getDragConfig: () => MainRendererConfigDrag;
     isDragActive: boolean;
     pieceCode: NonEmptyPieceCode | null;
     pieceNode: SVGUseElement | null;

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

@@ -1,10 +1,12 @@
 import assert from '@ktarmyshov/assert';
 import { isNonEmptyPieceCode } from '../../../../state/board/check.js';
+import { isDragSessionActiveLiftedPiece } from '../../../../state/interaction/helpers.js';
 export function rendererDragOnUpdate(state, context) {
-    const isLiftedDragActive = context.currentFrame.state.interaction.dragSession?.type === 'lifted-piece-drag';
+    const dragSession = context.currentFrame.state.interaction.dragSession;
+    const isLiftedDragActive = dragSession !== null && isDragSessionActiveLiftedPiece(dragSession);
     if (isLiftedDragActive) {
         if (!state.isDragActive) {
-            const pieceCode = context.currentFrame.state.interaction.dragSession.sourcePieceCode;
+            const pieceCode = dragSession.sourcePieceCode;
             assert(isNonEmptyPieceCode(pieceCode), 'Invalid piece code in drag session');
             state.pieceCode = pieceCode;
             state.runtimeSurface.transientVisuals.subscribe();

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

@@ -1,2 +1,3 @@
-import { MainRendererDefinition, MainRendererInitOptions } from './types/extension.js';
+import { MainRendererDefinition } from './types/extension.js';
+import type { MainRendererInitOptions } from './types/public.js';
 export declare function createMainRenderer(options?: MainRendererInitOptions): MainRendererDefinition;

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

@@ -1,16 +1,16 @@
-import { toMerged } from 'es-toolkit';
 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';
+import { denormalizeMainRendererConfig } from './denormalize.js';
 import { createMainRendererDrag } from './drag/factory.js';
 import { normalizeMainRendererConfig } from './normalize.js';
 import { createPieceSymbolResolver, ensurePieceSymbolsDefined } from './piece-symbols.js';
 import { createMainRendererPieces } from './pieces/factory.js';
-import { EXTENSION_ID, EXTENSION_SLOTS } from './types/extension.js';
-import { DEFAULT_MAIN_RENDERER_CONFIG } from './types/internal.js';
-export function createMainRenderer(options = {}) {
-    const config = toMerged(DEFAULT_MAIN_RENDERER_CONFIG, normalizeMainRendererConfig(options));
+import { DirtyLayer, EXTENSION_ID, EXTENSION_SLOTS } from './types/extension.js';
+import { DefaultMainRendererDesktopConfig } from './types/internal.js';
+export function createMainRenderer(options) {
+    const config = normalizeMainRendererConfig(options, DefaultMainRendererDesktopConfig);
     return {
         id: EXTENSION_ID,
         slots: EXTENSION_SLOTS,
@@ -21,12 +21,15 @@ export function createMainRenderer(options = {}) {
 }
 function createMainRendererInternal(options, config) {
     const pieceSymbolResolver = createPieceSymbolResolver(options.svgIds);
-    const board = createMainRendererBoard(config.colors.board);
-    const coordinates = createMainRendererCoordinates(config.colors.coordinates);
+    // Forward reference: subsystems read color config through getters that close over the
+    // internal state, so a runtime setConfig({ colors }) update is observed on the next render
+    // without re-creating the subsystems.
+    const board = createMainRendererBoard(() => internalState.config.colors.board);
+    const coordinates = createMainRendererCoordinates(() => internalState.config.colors.coordinates);
     const pieces = createMainRendererPieces(pieceSymbolResolver);
-    const drag = createMainRendererDrag(options.runtimeSurface, pieceSymbolResolver);
-    const animation = createMainRendererAnimation(options.runtimeSurface, pieceSymbolResolver);
-    return {
+    const drag = createMainRendererDrag(options.runtimeSurface, pieceSymbolResolver, () => internalState.config.drag);
+    const animation = createMainRendererAnimation(options.runtimeSurface, pieceSymbolResolver, () => internalState.config.animation);
+    const internalState = {
         ...extensionCreateInternalBase(options),
         board,
         coordinates,
@@ -34,7 +37,34 @@ function createMainRendererInternal(options, config) {
         drag,
         animation,
         runtimeSurface: options.runtimeSurface,
-        pieceSymbolResolver
+        pieceSymbolResolver,
+        config
+    };
+    return internalState;
+}
+function createMainRendererInstancePublic(state) {
+    return {
+        getConfig() {
+            return denormalizeMainRendererConfig(state.config);
+        },
+        setConfig(options) {
+            // Defensively strip pieceUrls so a non-TS caller cannot bypass the lifecycle.
+            const { pieceUrls: _ignored, ...safeInput } = (options ?? {});
+            void _ignored;
+            const previous = state.config;
+            state.config = normalizeMainRendererConfig(safeInput, state.config);
+            let dirty = 0;
+            if (state.config.colors.board !== previous.colors.board) {
+                dirty |= DirtyLayer.Board;
+            }
+            if (state.config.colors.coordinates !== previous.colors.coordinates) {
+                dirty |= DirtyLayer.Coordinates;
+            }
+            if (dirty !== 0) {
+                state.runtimeSurface.invalidation.markDirty(dirty);
+                state.runtimeSurface.commands.requestRender({ state: true });
+            }
+        }
     };
 }
 function extensionUnmountLocal(state) {
@@ -51,11 +81,12 @@ function validateIsMounted(state) {
 }
 function createMainRendererInstance(options, config) {
     const internalState = createMainRendererInternal(options, config);
+    const publicInterface = createMainRendererInstancePublic(internalState);
     return {
         id: EXTENSION_ID,
         mount(env) {
             extensionMountBase(internalState, env.slotRoots);
-            ensurePieceSymbolsDefined(env.slotRoots.defs, config.pieceUrls, internalState.pieceSymbolResolver);
+            ensurePieceSymbolsDefined(env.slotRoots.defs, internalState.config.pieceUrls, internalState.pieceSymbolResolver);
         },
         onUpdate(context) {
             internalState.board.onUpdate(context);
@@ -94,6 +125,9 @@ function createMainRendererInstance(options, config) {
         destroy() {
             extensionUnmountLocal(internalState);
             extensionDestroyBase(internalState);
+        },
+        getPublic() {
+            return publicInterface;
         }
     };
 }

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

@@ -1,3 +1,3 @@
-import { MainRendererConfigInput } from './types/input.js';
-import { MainRendererConfig } from './types/internal.js';
-export declare function normalizeMainRendererConfig(input: Partial<MainRendererConfigInput>): MainRendererConfig;
+import type { MainRendererConfig } from './types/internal.js';
+import type { MainRendererInitOptions } from './types/public.js';
+export declare function normalizeMainRendererConfig(input: MainRendererInitOptions | undefined, base: MainRendererConfig): MainRendererConfig;

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

@@ -1,7 +1,7 @@
 import assert from '@ktarmyshov/assert';
+import { toMerged } from 'es-toolkit/object';
 import { normalizePiece } from '../../../state/board/normalize.js';
 import { ALL_NON_EMPTY_PIECE_CODES } from '../../../state/board/types/internal.js';
-import { DEFAULT_MAIN_RENDERER_CONFIG } from './types/internal.js';
 function assertPieceUrlsComplete(pieceUrls) {
     for (const pieceCode of ALL_NON_EMPTY_PIECE_CODES) {
         assert(pieceCode in pieceUrls, `Missing URL for piece code: ${pieceCode}`);
@@ -17,11 +17,23 @@ function normalizePieceUrls(input) {
     assertPieceUrlsComplete(normalized);
     return normalized;
 }
-export function normalizeMainRendererConfig(input) {
-    return {
-        colors: input.colors ?? DEFAULT_MAIN_RENDERER_CONFIG.colors,
-        pieceUrls: input.pieceUrls
-            ? normalizePieceUrls(input.pieceUrls)
-            : DEFAULT_MAIN_RENDERER_CONFIG.pieceUrls
+function validateMainRendererConfig(config) {
+    const { pieceScale, pieceAnchor, pieceAnchorOffsetY } = config.drag;
+    assert(Number.isFinite(pieceScale), 'drag.pieceScale must be a finite number');
+    assert(pieceScale > 0, 'drag.pieceScale must be > 0');
+    assert(pieceAnchor === 'center' || pieceAnchor === 'bottom', `drag.pieceAnchor must be 'center' or 'bottom', received: ${String(pieceAnchor)}`);
+    assert(Number.isFinite(pieceAnchorOffsetY), 'drag.pieceAnchorOffsetY must be a finite number');
+    const { durationMs } = config.animation;
+    assert(Number.isFinite(durationMs), 'animation.durationMs must be a finite number');
+    assert(durationMs >= 0, 'animation.durationMs must be >= 0');
+}
+export function normalizeMainRendererConfig(input, base) {
+    const { pieceUrls: inputPieceUrls, ...rest } = input ?? {};
+    const merged = toMerged(base, rest);
+    const result = {
+        ...merged,
+        pieceUrls: inputPieceUrls !== undefined ? normalizePieceUrls(inputPieceUrls) : merged.pieceUrls
     };
+    validateMainRendererConfig(result);
+    return result;
 }