@mirasen/chessboard 1.1.5 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @mirasen/chessboard
 
+## 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

@@ -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, promotion, animation, and chess.js integration.
 
 ## Why this exists
 

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;

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

@@ -0,0 +1,79 @@
+import { normalizeSquare } from '../../../state/board/normalize.js';
+import { denormalizeArrows, denormalizeCircles } from './denormalize.js';
+import { markCommittedDirtyAndRequestRender } from './invalidation.js';
+import { arrowAnnotationKey, normalizeArrowAnnotation, normalizeCircleAnnotation } from './normalize.js';
+export function annotationsGetCircles(state) {
+    return denormalizeCircles(state.annotations.circles);
+}
+export function annotationsGetArrows(state) {
+    return denormalizeArrows(state.annotations.arrows);
+}
+export function annotationsSetCircles(state, circles) {
+    state.annotations.circles.clear();
+    for (const pub of circles) {
+        const circle = normalizeCircleAnnotation(pub);
+        state.annotations.circles.set(circle.key, circle);
+    }
+    markCommittedDirtyAndRequestRender(state);
+}
+export function annotationsSetArrows(state, arrows) {
+    // Validate all entries before mutating state (atomic behavior)
+    const normalized = arrows.map((pub) => normalizeArrowAnnotation(pub));
+    state.annotations.arrows.clear();
+    for (const arrow of normalized) {
+        state.annotations.arrows.set(arrow.key, arrow);
+    }
+    markCommittedDirtyAndRequestRender(state);
+}
+export function annotationsSetCircle(state, square, annotation) {
+    const key = normalizeSquare(square);
+    if (annotation === null) {
+        state.annotations.circles.delete(key);
+    }
+    else {
+        const normalizedAnnotation = normalizeCircleAnnotation({
+            square,
+            color: annotation.color
+        });
+        state.annotations.circles.set(key, normalizedAnnotation);
+    }
+    markCommittedDirtyAndRequestRender(state);
+}
+export function annotationsSetArrow(state, from, to, annotation) {
+    const key = arrowAnnotationKey(from, to);
+    if (annotation === null) {
+        state.annotations.arrows.delete(key);
+    }
+    else {
+        const normalizedArrow = normalizeArrowAnnotation({
+            from,
+            to,
+            color: annotation.color
+        });
+        state.annotations.arrows.set(key, normalizedArrow);
+    }
+    markCommittedDirtyAndRequestRender(state);
+}
+export function annotationsClear(state) {
+    state.annotations.circles.clear();
+    state.annotations.arrows.clear();
+    markCommittedDirtyAndRequestRender(state);
+}
+export function annotationsSetClearOnCoreInteraction(state, value) {
+    state.config.clearOnCoreInteraction = value;
+}
+export function annotationsGetClearOnCoreInteraction(state) {
+    return state.config.clearOnCoreInteraction;
+}
+export function annotationsSetDrawButton(state, value) {
+    state.config.drawButton = value;
+}
+export function annotationsGetDrawButton(state) {
+    return state.config.drawButton;
+}
+export function annotationsSetDrawModifier(state, value) {
+    state.config.drawModifier = value;
+}
+export function annotationsGetDrawModifier(state) {
+    return state.config.drawModifier;
+}

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

@@ -0,0 +1,3 @@
+import type { AnnotationsStateInternal } from './types/main.js';
+export declare function hasCommittedAnnotations(state: AnnotationsStateInternal): boolean;
+export declare function clearCommittedAnnotations(state: AnnotationsStateInternal): boolean;

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

@@ -0,0 +1,11 @@
+export function hasCommittedAnnotations(state) {
+    return state.annotations.circles.size > 0 || state.annotations.arrows.size > 0;
+}
+export function clearCommittedAnnotations(state) {
+    if (state.annotations.circles.size === 0 && state.annotations.arrows.size === 0) {
+        return false;
+    }
+    state.annotations.circles.clear();
+    state.annotations.arrows.clear();
+    return true;
+}

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

@@ -0,0 +1,3 @@
+import type { AnnotationsConfig, VisualConfig } from './types/internal.js';
+export declare const DEFAULT_CONFIG: AnnotationsConfig;
+export declare const VISUAL_CONFIG: VisualConfig;

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

@@ -0,0 +1,54 @@
+export const DEFAULT_CONFIG = {
+    clearOnCoreInteraction: true,
+    colors: {
+        none: '#15781B',
+        ctrl: '#882020',
+        shift: '#e68f00',
+        alt: '#003088',
+        meta: '#6f2da8'
+    },
+    drawButton: 2,
+    drawModifier: null
+};
+export const VISUAL_CONFIG = {
+    circle: {
+        committed: {
+            strokeWidth: 0.0625,
+            radius: 0.46875,
+            opacity: 1
+        },
+        previewAdd: {
+            strokeWidth: 0.05,
+            radius: 0.46875,
+            opacity: 0.8
+        },
+        previewRemoveOpacity: 0.25
+    },
+    arrow: {
+        committed: {
+            strokeWidth: 0.15625,
+            startOffset: 0,
+            endOffset: 0.15625,
+            opacity: 0.75,
+            markerWidth: 4,
+            markerHeight: 4,
+            markerRefX: 2.05,
+            markerRefY: 2,
+            markerViewBox: '0 0 4 4',
+            markerPathD: 'M0,0 V4 L3,2 Z'
+        },
+        previewAdd: {
+            strokeWidth: 0.11,
+            startOffset: 0,
+            endOffset: 0.15625,
+            opacity: 0.55,
+            markerWidth: 4,
+            markerHeight: 4,
+            markerRefX: 2.05,
+            markerRefY: 2,
+            markerViewBox: '0 0 4 4',
+            markerPathD: 'M0,0 V4 L3,2 Z'
+        },
+        previewRemoveOpacity: 0.25
+    }
+};

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

@@ -0,0 +1,4 @@
+import type { ArrowAnnotation, ArrowAnnotationKey, CircleAnnotation, CircleAnnotationKey } from './types/internal.js';
+import type { ArrowAnnotationPublic, CircleAnnotationPublic } from './types/public.js';
+export declare function denormalizeCircles(circles: Map<CircleAnnotationKey, CircleAnnotation>): CircleAnnotationPublic[];
+export declare function denormalizeArrows(arrows: Map<ArrowAnnotationKey, ArrowAnnotation>): ArrowAnnotationPublic[];

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

@@ -0,0 +1,22 @@
+import { denormalizeSquare } from '../../../state/board/denormalize.js';
+export function denormalizeCircles(circles) {
+    const result = [];
+    for (const circle of circles.values()) {
+        result.push({
+            square: denormalizeSquare(circle.square),
+            color: circle.color
+        });
+    }
+    return result;
+}
+export function denormalizeArrows(arrows) {
+    const result = [];
+    for (const arrow of arrows.values()) {
+        result.push({
+            from: denormalizeSquare(arrow.from),
+            to: denormalizeSquare(arrow.to),
+            color: arrow.color
+        });
+    }
+    return result;
+}

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

@@ -0,0 +1,3 @@
+import type { AnnotationsDefinition } from './types/main.js';
+import type { AnnotationsInitOptions } from './types/public.js';
+export declare function createAnnotations(options?: AnnotationsInitOptions): AnnotationsDefinition;