@mirasen/chessboard 1.1.5 → 1.2.1

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @mirasen/chessboard
 
+## 1.2.1
+
+### Patch Changes
+
+- 7f5649f: Update README and documentation entry points for the built-in annotations release.
+
+  The README now describes annotations as part of the default first-party extension baseline, adds a short annotations section, updates the explicit extension-list example, and links to the new documentation hub.
+
+## 1.2.0
+
+### Minor Changes
+
+- 101903a: Add board annotations with square markers, free arrows, live previews, and programmatic annotation APIs.
+- 101903a: Refines extension/rendering internals before third-party extension APIs stabilize.
+
+  Breaking for custom extension authors:
+  - SVG helper exports were simplified around generic SVG helpers: `createSvgElement`, `createSvgRootElement`, `createSvgDefsElement`, and `clearSvgElementChildren`.
+  - `defs` is now an extension-owned top-level `<defs>` slot under the root `<svg>`, instead of a shared `defs-root`.
+  - `extensionUnmountBase` now clears the extension-owned slot roots directly and no longer accepts an `extensionId`.
+
+  Board/runtime initialization is now element-first. Most consumers using direct container-based board creation should not need migration changes.
+
+### Patch Changes
+
+- 4ec620b: dependabot: directory '/', update @sveltejs/kit
+- 4ec620b: dependabot: directory '/', update eslint
+- 4ec620b: dependabot: directory '/', update globals
+- 4ec620b: dependabot: directory '/', update svelte-check
+- 49760cc: dependabot: directory '/', update @sveltejs/kit
+- 49760cc: dependabot: directory '/', update @types/node
+- 49760cc: dependabot: directory '/', update publint
+- 49760cc: dependabot: directory '/', update svelte-check
+- 49760cc: dependabot: directory '/', update typescript-eslint
+- 559677e: dependabot: directory '/', update @eslint/compat
+- 559677e: dependabot: directory '/', update publint
+- 72a1480: dependabot: directory '/', update @playwright/test
+- 72a1480: dependabot: directory '/', update @types/node
+- 72a1480: dependabot: directory '/', update @vitest/browser-playwright
+- 72a1480: dependabot: directory '/', update @vitest/coverage-istanbul
+- 72a1480: dependabot: directory '/', update playwright
+- 72a1480: dependabot: directory '/', update prettier-plugin-svelte
+- 72a1480: dependabot: directory '/', update publint
+- 72a1480: dependabot: directory '/', update typescript-eslint
+- 72a1480: dependabot: directory '/', update vitest
+
 ## 1.1.5
 
 ### Patch Changes

package/README.md

@@ -8,7 +8,7 @@
 
 A framework-agnostic TypeScript chessboard platform with real chess interaction built in and an extension-driven architecture.
 
-## Try it live
+## Try it live (including annotations)
 
 - [Play a chess.js game](https://mirasen.io/chessboard/examples/chessjs.html)
 - [Try the promotion flow](https://mirasen.io/chessboard/examples/promotion.html)
@@ -16,7 +16,7 @@ A framework-agnostic TypeScript chessboard platform with real chess interaction
 
 ## Using React?
 
-Use [`@mirasen/react-chessboard`](https://github.com/mirasen-io/react-chessboard) for a React component with the same built-in interaction, promotion, animation, and chess.js integration.
+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.
 
 ## Why this exists
 
@@ -36,7 +36,7 @@ This is not just a board renderer. It is a chessboard platform designed for real
 
 ## What you get out of the box
 
-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.
+The default first-party extension baseline includes rendering, events, selection, active target feedback, legal move hints, last move feedback, annotations, promotion UI, and optional auto-promotion.
 
 - `renderer` — the first-party rendering extension that validates the same extension architecture used for board features
 - `events`
@@ -44,16 +44,17 @@ The default first-party extension baseline includes rendering, events, selection
 - `activeTarget`
 - `legalMoves`
 - `lastMove`
+- `annotations`
 - `promotion`
 - `autoPromote`
 
 The package also includes `chess.js` adapter helpers for connecting legal destinations, UI moves, external moves, promotion, castling, and en passant without writing special-move glue code by hand.
 
-That means the board already covers a meaningful baseline chess UX instead of stopping at “draw squares and pieces”.
+That means the board already covers a meaningful baseline chess UX instead of stopping at “draw squares and pieces”: users can move pieces, see legal targets, promote naturally, animate state changes, and draw circles and arrows without rebuilding common board behavior in app code.
 
 ### Built-in chessboard behavior
 
-Mirasen Chessboard provides a complete modern interaction and visual baseline out of the box: selection, deselection, reselection, drag-to-move, release targeting, legal destinations, promotion, auto-promotion, and state-diff animation.
+Mirasen Chessboard provides a complete modern interaction and visual baseline out of the box: selection, deselection, reselection, drag-to-move, release targeting, legal destinations, circles and arrows, promotion, auto-promotion, and state-diff animation.
 
 Moves are resolved on release rather than committed immediately on press, giving users a more forgiving interaction flow. Because animation is driven by board-state transitions, pieces can move, appear, disappear, promote, castle, or return smoothly without app-level rendering glue code.
 
@@ -62,6 +63,7 @@ Rules and legality still belong to your game layer. Use the built-in `chess.js`
 ## Highlights
 
 - 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
 - State-diff animation beyond simple move events
@@ -104,7 +106,7 @@ board.setMovability({
 
 ### Connect to chess.js
 
-`@mirasen/chessboard` owns board interaction, rendering, promotion UI, and animation.  
+`@mirasen/chessboard` owns board interaction, rendering, annotations, promotion UI, and animation.  
 Your game/rules layer owns legality and game state.
 
 For `chess.js`, use the built-in adapter:
@@ -193,7 +195,7 @@ The adapter exposes three small conversion helpers:
 This keeps the boundary explicit:
 
 - `chess.js` decides which moves are legal.
-- The board handles interaction, legal targets, promotion UI, castling/en-passant board updates, and animation.
+- The board handles interaction, legal targets, annotations, promotion UI, castling/en-passant board updates, and animation.
 - User moves flow from the board into `chess.js`.
 - External moves flow from `chess.js` back into the board.
 
@@ -237,6 +239,16 @@ const board = createBoard({
 board.extensions.autoPromote.toQueen = true;
 ```
 
+### Annotations
+
+The default extension baseline includes built-in board annotations.
+
+Users can draw circles and arrows directly on the board. Desktop users can right-click to annotate by default, while touch or mobile-style UIs can switch annotation drawing to the primary pointer button with `drawButton`.
+
+Annotation gestures show live previews before commit. Repeating the same-color circle or arrow removes it, with a low-opacity remove preview so users can see that release will delete the existing annotation.
+
+Color selection can come from keyboard modifiers, or be forced through `drawModifier` for on-screen controls.
+
 ### Movability modes
 
 Movability controls how the board accepts user-initiated moves.
@@ -251,14 +263,44 @@ Most users can rely on the default first-party extension baseline. Use an explic
 
 ```ts
 import { createBoard, type Chessboard, type ChessboardExtensionInput } from '@mirasen/chessboard';
+import { builtInExtensionFactoryMap } from '@mirasen/chessboard/extensions';
+
+const pieceUrls = {
+	wK: '/pieces/wK.svg',
+	wQ: '/pieces/wQ.svg',
+	wR: '/pieces/wR.svg',
+	wB: '/pieces/wB.svg',
+	wN: '/pieces/wN.svg',
+	wP: '/pieces/wP.svg',
+	bK: '/pieces/bK.svg',
+	bQ: '/pieces/bQ.svg',
+	bR: '/pieces/bR.svg',
+	bB: '/pieces/bB.svg',
+	bN: '/pieces/bN.svg',
+	bP: '/pieces/bP.svg'
+};
 
 const extensionList = [
-	// Always add renderer first, otherwise nothing will be rendered
-	'renderer',
+	// Always add renderer first, otherwise nothing will be rendered.
+	{
+		builtin: 'renderer',
+		options: {
+			pieceUrls,
+			colors: {
+				board: {
+					light: '#d7dde5',
+					dark: '#707a8a'
+				}
+			}
+		}
+	},
 	'lastMove',
-	// Keep autoPromote before promotion, otherwise promotion may defer the move first
+	'annotations',
+	// Keep autoPromote before promotion, otherwise promotion may defer the move first.
 	'autoPromote',
-	'promotion'
+	builtInExtensionFactoryMap.promotion({
+		pieceUrls
+	})
 	// customExtensionDefinition
 ] as const satisfies readonly ChessboardExtensionInput[];
 let board: Chessboard<typeof extensionList> | null = null;
@@ -275,12 +317,18 @@ board = createBoard({
 });
 ```
 
+Configured built-in extensions can be provided either as declarative `{ builtin, options }` objects or through the built-in extension factory map. If you use custom piece assets, pass the same `pieceUrls` map to renderer and promotion when you want the board and promotion UI to use the same piece set.
+
 ### Default visual identity
 
 The default first-party extension baseline includes a subtle Mirasen board watermark.
 
 If you want full control over the visual baseline, use an explicit extension list and omit the `watermark` extension.
 
+## Documentation
+
+See [Documentation](./documentation.md) for the documentation hub.
+
 ## Architecture
 
 `@mirasen/chessboard` is built around explicit boundaries:
@@ -304,7 +352,7 @@ A board that only renders pieces and leaves everything else to app code often fo
 
 A board that handles everything internally without clean boundaries becomes difficult to evolve, customize, or extend.
 
-### Opt out, not build up
+### Opt out, don’t build up, focus on your app
 
 `@mirasen/chessboard` aims for a middle path:
 
@@ -312,7 +360,7 @@ A board that handles everything internally without clean boundaries becomes diff
 - clean internal architecture
 - extension-driven feature growth
 
-Common chessboard behavior is included by default: rendering, interaction, selection, legal target feedback, promotion, and animation. You start from a working interaction baseline and remove or replace extensions only when you want less or need something different.
+Common chessboard behavior is included by default: rendering, interaction, selection, legal target feedback, annotations, promotion, and animation. You start from a working interaction baseline, remove or replace extensions only when you need something different, and keep your own code focused on your application domain.
 
 ## Project direction
 

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

@@ -1,7 +1,6 @@
-import type { PieceUrls } from '../../extensions/first-party/main-renderer/types/internal.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: SceneRenderGeometry, pieceUrls: PieceUrls, layer: SVGElement): PreparedFadeNode;
+import type { PieceHrefResolver, PreparedFadeNode } from './types.js';
+export declare function prepareFadeTrack(track: AnimationTrackFade, geometry: SceneRenderGeometry, resolveHref: PieceHrefResolver, slot: SVGGElement): PreparedFadeNode;
 export declare function renderFadeTrack(node: PreparedFadeNode, progress: number): void;
 export declare function cleanFadeTrack(node: PreparedFadeNode): void;

package/dist/animation/render/fade.js

@@ -1,12 +1,12 @@
-import { createSvgElement, updateElementAttributes } from '../../render/svg/helpers.js';
-export function prepareFadeTrack(track, geometry, pieceUrls, layer) {
+import { createSvgElement, updateSvgElementAttributes } from '../../render/svg/helpers.js';
+export function prepareFadeTrack(track, geometry, resolveHref, slot) {
     const r = geometry.getSquareRect(track.sq);
-    const url = pieceUrls[track.pieceCode];
+    const href = resolveHref(track.pieceCode);
     const initialOpacity = track.effect === 'fade-in' ? '0' : '1';
-    const root = createSvgElement(layer, 'image', {
+    const root = createSvgElement(slot, 'use', {
         'data-chessboard-id': `animation-fade-${track.id}`,
         'data-animation-effect': track.effect,
-        href: url,
+        href,
         x: r.x.toString(),
         y: r.y.toString(),
         width: r.width.toString(),
@@ -17,7 +17,7 @@ export function prepareFadeTrack(track, geometry, pieceUrls, layer) {
 }
 export function renderFadeTrack(node, progress) {
     const opacity = node.effect === 'fade-in' ? progress : 1 - progress;
-    updateElementAttributes(node.root, { opacity: opacity.toString() });
+    updateSvgElementAttributes(node.root, { opacity: opacity.toString() });
 }
 export function cleanFadeTrack(node) {
     node.root.remove();

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

@@ -1,7 +1,6 @@
-import type { PieceUrls } from '../../extensions/first-party/main-renderer/types/internal.js';
 import type { SceneRenderGeometry } from '../../layout/geometry/types.js';
 import type { AnimationTrackMove } from '../types.js';
-import type { PreparedMoveNode } from './types.js';
-export declare function prepareMoveTrack(track: AnimationTrackMove, geometry: SceneRenderGeometry, pieceUrls: PieceUrls, layer: SVGElement): PreparedMoveNode;
+import type { PieceHrefResolver, PreparedMoveNode } from './types.js';
+export declare function prepareMoveTrack(track: AnimationTrackMove, geometry: SceneRenderGeometry, resolveHref: PieceHrefResolver, slot: SVGGElement): PreparedMoveNode;
 export declare function renderMoveTrack(node: PreparedMoveNode, geometry: SceneRenderGeometry, progress: number): void;
 export declare function cleanMoveTrack(node: PreparedMoveNode): void;

package/dist/animation/render/move.js

@@ -1,11 +1,11 @@
-import { createSvgElement, updateElementAttributes } from '../../render/svg/helpers.js';
-export function prepareMoveTrack(track, geometry, pieceUrls, layer) {
+import { createSvgElement, updateSvgElementAttributes } from '../../render/svg/helpers.js';
+export function prepareMoveTrack(track, geometry, resolveHref, slot) {
     const r = geometry.getSquareRect(track.fromSq);
-    const url = pieceUrls[track.pieceCode];
-    const root = createSvgElement(layer, 'image', {
+    const href = resolveHref(track.pieceCode);
+    const root = createSvgElement(slot, 'use', {
         'data-chessboard-id': `animation-move-${track.id}`,
         'data-animation-effect': 'move',
-        href: url,
+        href,
         x: r.x.toString(),
         y: r.y.toString(),
         width: r.width.toString(),
@@ -18,7 +18,7 @@ export function renderMoveTrack(node, geometry, progress) {
     const to = geometry.getSquareRect(node.toSq);
     const x = from.x + (to.x - from.x) * progress;
     const y = from.y + (to.y - from.y) * progress;
-    updateElementAttributes(node.root, {
+    updateSvgElementAttributes(node.root, {
         x: x.toString(),
         y: y.toString()
     });

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

@@ -1,12 +1,11 @@
-import type { PieceUrls } from '../../extensions/first-party/main-renderer/types/internal.js';
 import type { SceneRenderGeometry } from '../../layout/geometry/types.js';
 import type { AnimationPlan } from '../types.js';
-import type { PreparedNodeMap } from './types.js';
+import type { PieceHrefResolver, PreparedNodeMap } from './types.js';
 /**
- * Prepare all tracks in the plan — creates SVG nodes in `layer` for each track.
+ * Prepare all tracks in the plan — creates SVG nodes in `slot` for each track.
  * Returns a map keyed by track id for use in render/clean passes.
  */
-export declare function prepareAnimationPlan(plan: AnimationPlan, geometry: SceneRenderGeometry, pieceUrls: PieceUrls, layer: SVGElement): PreparedNodeMap;
+export declare function prepareAnimationPlan(plan: AnimationPlan, geometry: SceneRenderGeometry, resolveHref: PieceHrefResolver, slot: SVGGElement): PreparedNodeMap;
 export declare function renderAnimationPlan(nodes: PreparedNodeMap, geometry: SceneRenderGeometry, progress: number): void;
 /**
  * Clean up all track nodes — removes SVG elements from the DOM.

package/dist/animation/render/plan.js

@@ -2,23 +2,23 @@ import { cleanFadeTrack, prepareFadeTrack, renderFadeTrack } from './fade.js';
 import { cleanMoveTrack, prepareMoveTrack, renderMoveTrack } from './move.js';
 import { cleanStaticTrack, prepareStaticTrack, renderStaticTrack } from './static.js';
 /**
- * Prepare all tracks in the plan — creates SVG nodes in `layer` for each track.
+ * Prepare all tracks in the plan — creates SVG nodes in `slot` for each track.
  * Returns a map keyed by track id for use in render/clean passes.
  */
-export function prepareAnimationPlan(plan, geometry, pieceUrls, layer) {
+export function prepareAnimationPlan(plan, geometry, resolveHref, slot) {
     const nodes = new Map();
     for (const track of plan.tracks) {
         let node;
         switch (track.effect) {
             case 'move':
-                node = prepareMoveTrack(track, geometry, pieceUrls, layer);
+                node = prepareMoveTrack(track, geometry, resolveHref, slot);
                 break;
             case 'fade-in':
             case 'fade-out':
-                node = prepareFadeTrack(track, geometry, pieceUrls, layer);
+                node = prepareFadeTrack(track, geometry, resolveHref, slot);
                 break;
             case 'static':
-                node = prepareStaticTrack(track, geometry, pieceUrls, layer);
+                node = prepareStaticTrack(track, geometry, resolveHref, slot);
                 break;
             default:
                 throw new RangeError(`Unsupported track effect: ${track}`);

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

@@ -1,7 +1,6 @@
-import type { PieceUrls } from '../../extensions/first-party/main-renderer/types/internal.js';
 import type { SceneRenderGeometry } from '../../layout/geometry/types.js';
 import type { AnimationTrackStatic } from '../types.js';
-import type { PreparedStaticNode } from './types.js';
-export declare function prepareStaticTrack(track: AnimationTrackStatic, geometry: SceneRenderGeometry, pieceUrls: PieceUrls, layer: SVGElement): PreparedStaticNode;
+import type { PieceHrefResolver, PreparedStaticNode } from './types.js';
+export declare function prepareStaticTrack(track: AnimationTrackStatic, geometry: SceneRenderGeometry, resolveHref: PieceHrefResolver, slot: SVGGElement): PreparedStaticNode;
 export declare function renderStaticTrack(_node: PreparedStaticNode): void;
 export declare function cleanStaticTrack(node: PreparedStaticNode): void;

package/dist/animation/render/static.js

@@ -1,11 +1,11 @@
 import { createSvgElement } from '../../render/svg/helpers.js';
-export function prepareStaticTrack(track, geometry, pieceUrls, layer) {
+export function prepareStaticTrack(track, geometry, resolveHref, slot) {
     const r = geometry.getSquareRect(track.sq);
-    const url = pieceUrls[track.pieceCode];
-    const root = createSvgElement(layer, 'image', {
+    const href = resolveHref(track.pieceCode);
+    const root = createSvgElement(slot, 'use', {
         'data-chessboard-id': `animation-static-${track.id}`,
         'data-animation-effect': 'static',
-        href: url,
+        href,
         x: r.x.toString(),
         y: r.y.toString(),
         width: r.width.toString(),

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

@@ -1,15 +1,21 @@
+import type { NonEmptyPieceCode } from '../../state/board/types/internal.js';
 import type { AnimationTrack, AnimationTrackFade, AnimationTrackMove, AnimationTrackStatic } from '../types.js';
-/** Prepared node for a move track — holds the SVG image and its track. */
+/**
+ * A function that resolves a piece code to a href string for <use> elements.
+ * Decoupled from main-renderer internals — any conforming callback works.
+ */
+export type PieceHrefResolver = (pieceCode: NonEmptyPieceCode) => string;
+/** Prepared node for a move track — holds the SVG use element and its track. */
 export interface PreparedMoveNode extends AnimationTrackMove {
-    root: SVGImageElement;
+    root: SVGUseElement;
 }
 /** Prepared node for a fade-in / fade-out track. */
 export interface PreparedFadeNode extends AnimationTrackFade {
-    root: SVGImageElement;
+    root: SVGUseElement;
 }
 /** Prepared node for a static (captured piece) track. */
 export interface PreparedStaticNode extends AnimationTrackStatic {
-    root: SVGImageElement;
+    root: SVGUseElement;
 }
 export type PreparedTrackNode = PreparedMoveNode | PreparedFadeNode | PreparedStaticNode;
 /** Keyed map from track id → prepared node, for fast lookup during render/clean. */

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

@@ -1,5 +1,5 @@
 export { cleanAnimationPlan, prepareAnimationPlan, renderAnimationPlan } from '../../animation/render/plan.js';
-export { clearElementChildren, createSvgElement, updateElementAttributes } from '../../render/svg/helpers.js';
+export { clearSvgElementChildren, createSvgElement, createSvgRootElement, updateSvgElementAttributes } from '../../render/svg/helpers.js';
 export type { RuntimeReadonlyMutationSession } from '../../runtime/mutation/types.js';
 export { isNonEmptyPieceCode } from '../../state/board/check.js';
 export { fileOf, rankOf, squareOf } from '../../state/board/coords.js';
@@ -7,7 +7,6 @@ export { denormalizeMove } from '../../state/board/denormalize.js';
 export { normalizePiece } from '../../state/board/normalize.js';
 export { fromPieceCode, toPieceCode } from '../../state/board/piece.js';
 export type { ColorCode, EmptyPieceCode, NonEmptyPieceCode, PieceCode, RoleCode, RolePromotionCode, Square, SquareFile, SquareRank } from '../../state/board/types/internal.js';
-export type { MoveOutput } from '../../state/board/types/output.js';
 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';

package/dist/extensions/build/index.js

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

package/dist/extensions/factory/main.js

@@ -1,9 +1,11 @@
 import assert from '@ktarmyshov/assert';
+import { createSvgIdResolver } from '../../render/svg/ids.js';
 import { createExtensionAnimationController } from '../animation/factory.js';
 import { createExtensionInvalidationState } from '../invalidation/factory.js';
 import { extensionSystemUpdateState, extensionSystemUpdateUIMoveRequest } from '../update.js';
 import { createExtensionRuntimeSurface } from './runtime.js';
 function createExtensionSystemInternal(getInternalState, options) {
+    const svgIds = createSvgIdResolver();
     const extensions = new Map();
     const extensionsArray = options.extensions ?? [];
     for (const extensionDef of extensionsArray) {
@@ -14,7 +16,8 @@ function createExtensionSystemInternal(getInternalState, options) {
             throw new Error(`Duplicate extension id found: ${extensionDef.id}`);
         }
         const instance = extensionDef.createInstance({
-            runtimeSurface: createExtensionRuntimeSurface(getInternalState, options.extensionRuntimeSurfaceCommands, options.extensionRuntimeSurfaceEvents, extensionDef)
+            runtimeSurface: createExtensionRuntimeSurface(getInternalState, options.extensionRuntimeSurfaceCommands, options.extensionRuntimeSurfaceEvents, extensionDef),
+            svgIds
         });
         const record = {
             id: extensionDef.id,
@@ -93,23 +96,24 @@ export function createExtensionSystem(options) {
             assert(extensionRec.instance.completeDrag, `Extension instance does not have a completeDrag handler for completing drag session with owner ${session.owner}`);
             extensionRec.instance.completeDrag(session);
         },
+        cancelDrag(session) {
+            const extensionRec = internalState.extensions.get(session.owner);
+            assert(extensionRec, `Extension record not found for cancelling drag session with owner ${session.owner}`);
+            extensionRec.instance.cancelDrag?.(session);
+        },
         onUnmount() {
             internalState.transientVisualsSubscribers.clear();
             internalState.eventSubscribers.clear();
             internalState.currentFrame = null;
             for (const extensionRec of internalState.extensions.values()) {
-                extensionRec.invalidation.clear();
                 extensionRec.animation.clear();
             }
         },
         onDestroy() {
-            // We assume that the onUnmout was already called by runtime, but let's still validate
+            // We assume that the onUnmount was already called by runtime, but let's still validate
             for (const extensionRec of internalState.extensions.values()) {
                 extensionRec.instance.destroy?.();
-                const onUnmountCalled = [
-                    extensionRec.invalidation.dirtyLayers === 0,
-                    extensionRec.animation.getAll().length === 0
-                ].every(Boolean);
+                const onUnmountCalled = extensionRec.animation.getAll().length === 0;
                 if (!onUnmountCalled) {
                     throw new Error(`Extension ${extensionRec.id} was not properly unmounted before destroy. Please make sure to call onUnmount before onDestroy to allow the extension to clean up its state and resources.`);
                 }

package/dist/extensions/factory/runtime.js

@@ -80,11 +80,34 @@ function createExtensionRuntimeSurfaceCommands(getInternalState, runtimeSurfaceC
         }
     };
 }
+function createExtensionRuntimeSurfaceInvalidation(getInternalState, extensionDef) {
+    function getInvalidation() {
+        const internalState = getInternalState();
+        const record = internalState.extensions.get(extensionDef.id);
+        assert(record, 'Extension record not found for invalidation');
+        return record.invalidation;
+    }
+    return {
+        get dirtyLayers() {
+            return getInvalidation().dirtyLayers;
+        },
+        markDirty(layers) {
+            getInvalidation().markDirty(layers);
+        },
+        clearDirty(layers) {
+            getInvalidation().clearDirty(layers);
+        },
+        clear() {
+            getInvalidation().clear();
+        }
+    };
+}
 export function createExtensionRuntimeSurface(getInternalState, commands, events, extensionDef) {
     return {
         commands: createExtensionRuntimeSurfaceCommands(getInternalState, commands, extensionDef),
         animation: createExtensionRuntimeSurfaceAnimation(getInternalState, extensionDef),
         transientVisuals: createExtensionRuntimeSurfaceTransientVisuals(getInternalState, extensionDef),
-        events: createExtensionRuntimeSurfaceEvents(getInternalState, events, extensionDef)
+        events: createExtensionRuntimeSurfaceEvents(getInternalState, events, extensionDef),
+        invalidation: createExtensionRuntimeSurfaceInvalidation(getInternalState, extensionDef)
     };
 }

package/dist/extensions/first-party/active-target/factory.js

@@ -1,6 +1,6 @@
 import assert from '@ktarmyshov/assert';
 import { toMerged } from 'es-toolkit';
-import { createSvgElement, updateElementAttributes } from '../../../render/svg/helpers.js';
+import { createSvgElement, updateSvgElementAttributes } from '../../../render/svg/helpers.js';
 import { isUpdateContextRenderable } from '../../types/context/update.js';
 import { extensionCreateInternalBase, extensionDestroyBase, extensionMountBase, extensionUnmountBase } from '../common/helpers.js';
 import { DEFAULT_CONFIG, EXTENSION_ID, EXTENSION_SLOTS } from './types.js';
@@ -9,14 +9,14 @@ export function createActiveTarget(config = {}) {
     return {
         id: EXTENSION_ID,
         slots: EXTENSION_SLOTS,
-        createInstance() {
-            return createActiveTargetInstance(mergedConfig);
+        createInstance(options) {
+            return createActiveTargetInstance(options, mergedConfig);
         }
     };
 }
-function createActiveTargetInternal(config) {
+function createActiveTargetInternal(options, config) {
     return {
-        ...extensionCreateInternalBase(),
+        ...extensionCreateInternalBase(options),
         svgRect: null,
         svgCircle: null,
         config
@@ -26,8 +26,8 @@ function extensionClean(state) {
     state.svgRect = null;
     state.svgCircle = null;
 }
-function createActiveTargetInstance(config) {
-    const internalState = createActiveTargetInternal(config);
+function createActiveTargetInstance(options, config) {
+    const internalState = createActiveTargetInternal(options, config);
     return {
         id: EXTENSION_ID,
         mount(env) {
@@ -38,7 +38,11 @@ function createActiveTargetInstance(config) {
                 causes: ['layout.refreshGeometry'],
                 // we really need almost all: setDrag, updateTarget, clear, clearActive, so just take all interaction mutations
                 prefixes: ['state.interaction.']
-            }) && isUpdateContextRenderable(context);
+            }) &&
+                isUpdateContextRenderable(context) &&
+                (context.currentFrame.state.interaction.dragSession?.type === 'lifted-piece-drag' ||
+                    context.currentFrame.state.interaction.dragSession?.type === 'release-targeting' ||
+                    context.currentFrame.state.interaction.dragSession === null);
             if (!needsRender) {
                 return; // no-op
             }
@@ -48,7 +52,10 @@ function createActiveTargetInstance(config) {
             assert(context.invalidation.dirtyLayers !== 0, 'Render should only be called when there are dirty layers');
             // For AI: `release-targeting` is also represented by `dragSession`.
             // `dragSession` here is the active interaction session, not only lifted-piece drag.
-            const square = context.currentFrame.state.interaction.dragSession?.targetSquare;
+            const square = context.currentFrame.state.interaction.dragSession?.type === 'lifted-piece-drag' ||
+                context.currentFrame.state.interaction.dragSession?.type === 'release-targeting'
+                ? context.currentFrame.state.interaction.dragSession.targetSquare
+                : null;
             if (square === undefined || square === null) {
                 if (internalState.svgRect !== null) {
                     internalState.svgRect.remove();
@@ -92,9 +99,9 @@ function createActiveTargetInstance(config) {
                 });
             }
             else {
-                updateElementAttributes(internalState.svgRect, rectAttributes);
+                updateSvgElementAttributes(internalState.svgRect, rectAttributes);
                 assert(internalState.svgCircle, 'svgCircle should be available if svgRect is available');
-                updateElementAttributes(internalState.svgCircle, haloAttributes);
+                updateSvgElementAttributes(internalState.svgCircle, haloAttributes);
             }
         },
         unmount() {

package/dist/extensions/first-party/annotations/api.d.ts

@@ -0,0 +1,16 @@
+import type { SquareString } from '../../../state/board/types/input.js';
+import type { AnnotationsStateInternal } from './types/main.js';
+import type { AnnotationsDrawModifier, ArrowAnnotationPublic, ArrowAnnotationValuePublic, CircleAnnotationPublic, CircleAnnotationValuePublic } from './types/public.js';
+export declare function annotationsGetCircles(state: AnnotationsStateInternal): CircleAnnotationPublic[];
+export declare function annotationsGetArrows(state: AnnotationsStateInternal): ArrowAnnotationPublic[];
+export declare function annotationsSetCircles(state: AnnotationsStateInternal, circles: CircleAnnotationPublic[]): void;
+export declare function annotationsSetArrows(state: AnnotationsStateInternal, arrows: ArrowAnnotationPublic[]): void;
+export declare function annotationsSetCircle(state: AnnotationsStateInternal, square: SquareString, annotation: CircleAnnotationValuePublic | null): void;
+export declare function annotationsSetArrow(state: AnnotationsStateInternal, from: SquareString, to: SquareString, annotation: ArrowAnnotationValuePublic | null): void;
+export declare function annotationsClear(state: AnnotationsStateInternal): void;
+export declare function annotationsSetClearOnCoreInteraction(state: AnnotationsStateInternal, value: boolean): void;
+export declare function annotationsGetClearOnCoreInteraction(state: AnnotationsStateInternal): boolean;
+export declare function annotationsSetDrawButton(state: AnnotationsStateInternal, value: number): void;
+export declare function annotationsGetDrawButton(state: AnnotationsStateInternal): number;
+export declare function annotationsSetDrawModifier(state: AnnotationsStateInternal, value: AnnotationsDrawModifier | null): void;
+export declare function annotationsGetDrawModifier(state: AnnotationsStateInternal): AnnotationsDrawModifier | null;