@mirasen/chessboard 1.1.5 → 1.2.1

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;

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

@@ -0,0 +1,143 @@
+import { cloneDeep } from 'es-toolkit';
+import { extensionCreateInternalBase, extensionDestroyBase, extensionMountBase, extensionUnmountBase } from '../common/helpers.js';
+import { annotationsClear, annotationsGetArrows, annotationsGetCircles, annotationsGetClearOnCoreInteraction, annotationsGetDrawButton, annotationsGetDrawModifier, annotationsSetArrow, annotationsSetArrows, annotationsSetCircle, annotationsSetCircles, annotationsSetClearOnCoreInteraction, annotationsSetDrawButton, annotationsSetDrawModifier } from './api.js';
+import { cancelAnnotationsDrag, completeAnnotationsDrag, handleAnnotationsEvent } from './interaction.js';
+import { normalizeAnnotationsConfig, normalizeInitialAnnotations } from './normalize.js';
+import { renderCommittedAnnotations } from './render/committed.js';
+import { renderPreviewAnnotations } from './render/preview.js';
+import { EXTENSION_ID, EXTENSION_SLOTS } from './types/main.js';
+import { annotationsOnUpdate } from './update.js';
+export function createAnnotations(options = {}) {
+    const normalizedConfig = normalizeAnnotationsConfig(options.config);
+    const normalizedAnnotations = normalizeInitialAnnotations(options.annotations);
+    return {
+        id: EXTENSION_ID,
+        slots: EXTENSION_SLOTS,
+        createInstance(runtimeOptions) {
+            return createAnnotationsInstance(normalizedConfig, normalizedAnnotations, runtimeOptions);
+        }
+    };
+}
+function createAnnotationsInternal(normalizedConfig, normalizedAnnotations, runtimeOptions) {
+    // Clone to ensure each instance has independent mutable state
+    const config = cloneDeep(normalizedConfig);
+    const annotations = {
+        circles: new Map(normalizedAnnotations.circles),
+        arrows: new Map(normalizedAnnotations.arrows)
+    };
+    return {
+        ...extensionCreateInternalBase(runtimeOptions),
+        runtimeSurface: runtimeOptions.runtimeSurface,
+        svg: {
+            svgCircles: new Map(),
+            svgArrows: new Map()
+        },
+        annotations,
+        config,
+        activeDrawGesture: null,
+        activeDrawPreviewTarget: null,
+        previewSvg: { circle: null, arrow: null }
+    };
+}
+function extensionCleanSvg(state) {
+    state.svg.svgCircles.clear();
+    state.svg.svgArrows.clear();
+    if (state.previewSvg.arrow) {
+        state.previewSvg.arrow.marker.remove();
+    }
+    state.previewSvg.circle = null;
+    state.previewSvg.arrow = null;
+}
+function extensionClean(state) {
+    state.runtimeSurface.events.unsubscribeEvent('pointerdown');
+    state.runtimeSurface.events.unsubscribeEvent('contextmenu');
+    state.activeDrawGesture = null;
+    state.activeDrawPreviewTarget = null;
+    extensionCleanSvg(state);
+}
+function createAnnotationsPublicAPI(state) {
+    return {
+        getCircles() {
+            return annotationsGetCircles(state);
+        },
+        getArrows() {
+            return annotationsGetArrows(state);
+        },
+        setCircles(circles) {
+            annotationsSetCircles(state, circles);
+        },
+        setArrows(arrows) {
+            annotationsSetArrows(state, arrows);
+        },
+        circle(square, annotation) {
+            annotationsSetCircle(state, square, annotation);
+        },
+        arrow(from, to, annotation) {
+            annotationsSetArrow(state, from, to, annotation);
+        },
+        clear() {
+            annotationsClear(state);
+        },
+        get clearOnCoreInteraction() {
+            return annotationsGetClearOnCoreInteraction(state);
+        },
+        set clearOnCoreInteraction(value) {
+            annotationsSetClearOnCoreInteraction(state, value);
+        },
+        get drawButton() {
+            return annotationsGetDrawButton(state);
+        },
+        set drawButton(value) {
+            annotationsSetDrawButton(state, value);
+        },
+        get drawModifier() {
+            return annotationsGetDrawModifier(state);
+        },
+        set drawModifier(value) {
+            annotationsSetDrawModifier(state, value);
+        }
+    };
+}
+function createAnnotationsInstance(normalizedConfig, normalizedAnnotations, runtimeOptions) {
+    const internalState = createAnnotationsInternal(normalizedConfig, normalizedAnnotations, runtimeOptions);
+    const publicAPI = createAnnotationsPublicAPI(internalState);
+    return {
+        id: EXTENSION_ID,
+        mount(env) {
+            extensionMountBase(internalState, env.slotRoots);
+            internalState.runtimeSurface.events.subscribeEvent('pointerdown');
+            internalState.runtimeSurface.events.subscribeEvent('contextmenu');
+        },
+        onUpdate(context) {
+            annotationsOnUpdate(internalState, context);
+        },
+        render(context) {
+            if (context.invalidation.dirtyLayers & 1 /* DirtyLayer.COMMITTED */) {
+                renderCommittedAnnotations(internalState, context.currentFrame.layout.geometry);
+            }
+            if (context.invalidation.dirtyLayers & 2 /* DirtyLayer.PREVIEW */) {
+                renderPreviewAnnotations(internalState, context.currentFrame.layout.geometry);
+            }
+        },
+        onEvent(context) {
+            handleAnnotationsEvent(internalState, context);
+        },
+        completeDrag(session) {
+            completeAnnotationsDrag(internalState, session);
+        },
+        cancelDrag(session) {
+            cancelAnnotationsDrag(internalState, session);
+        },
+        unmount() {
+            extensionClean(internalState);
+            extensionUnmountBase(internalState);
+        },
+        destroy() {
+            extensionClean(internalState);
+            extensionDestroyBase(internalState);
+        },
+        getPublic() {
+            return publicAPI;
+        }
+    };
+}

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

@@ -0,0 +1,8 @@
+import type { ExtensionDragSessionSnapshot } from '../../types/basic/interaction.js';
+import type { ExtensionOnEventContext } from '../../types/context/events.js';
+import type { AnnotationColor, AnnotationsConfig } from './types/internal.js';
+import type { AnnotationsStateInternal } from './types/main.js';
+export declare function resolveAnnotationColor(config: AnnotationsConfig, rawEvent: PointerEvent): AnnotationColor;
+export declare function handleAnnotationsEvent(state: AnnotationsStateInternal, context: ExtensionOnEventContext): void;
+export declare function completeAnnotationsDrag(state: AnnotationsStateInternal, session: ExtensionDragSessionSnapshot): void;
+export declare function cancelAnnotationsDrag(state: AnnotationsStateInternal, session: ExtensionDragSessionSnapshot): void;

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

@@ -0,0 +1,129 @@
+import assert from '@ktarmyshov/assert';
+import { clearCommittedAnnotations, hasCommittedAnnotations } from './committed.js';
+import { markCommittedDirtyAndRequestRender } from './invalidation.js';
+import { arrowAnnotationKeyNormalized } from './normalize.js';
+const ANNOTATIONS_IDLE_CLEAR_DRAG_TYPE = 'ext:idle-clear';
+const ANNOTATIONS_DRAW_DRAG_TYPE = 'ext:draw';
+export function resolveAnnotationColor(config, rawEvent) {
+    if (config.drawModifier != null) {
+        return config.colors[config.drawModifier];
+    }
+    if (rawEvent.ctrlKey)
+        return config.colors.ctrl;
+    if (rawEvent.shiftKey)
+        return config.colors.shift;
+    if (rawEvent.altKey)
+        return config.colors.alt;
+    if (rawEvent.metaKey)
+        return config.colors.meta;
+    return config.colors.none;
+}
+export function handleAnnotationsEvent(state, context) {
+    assert(context.rawEvent.type === 'pointerdown' || context.rawEvent.type === 'contextmenu');
+    if (context.rawEvent.type === 'contextmenu') {
+        // Browser context menus are separate from the pointer drag lifecycle.
+        // The board owns secondary-button interaction, so suppress the browser menu.
+        context.rawEvent.preventDefault();
+        return;
+    }
+    const rawEvent = context.rawEvent;
+    // The configured draw button owns annotation drawing gestures.
+    // If configured as primary, drawing intentionally takes precedence over idle-clear.
+    if (rawEvent.button === state.config.drawButton) {
+        const targetSquare = context.sceneEvent?.targetSquare;
+        if (targetSquare === undefined || targetSquare === null)
+            return;
+        state.activeDrawGesture = {
+            sourceSquare: targetSquare,
+            color: resolveAnnotationColor(state.config, rawEvent)
+        };
+        const success = state.runtimeSurface.commands.startDrag({
+            type: ANNOTATIONS_DRAW_DRAG_TYPE,
+            sourceSquare: targetSquare,
+            sourcePieceCode: null,
+            targetSquare: targetSquare
+        });
+        if (success) {
+            rawEvent.preventDefault();
+        }
+        else {
+            state.activeDrawGesture = null;
+        }
+        return;
+    }
+    // Drawing uses the configured draw button above.
+    // The remaining primary-button path is reserved for idle-clear.
+    if (rawEvent.button !== 0)
+        return;
+    const targetSquare = context.sceneEvent?.targetSquare;
+    if (targetSquare === undefined || targetSquare === null)
+        return;
+    if (context.runtimeInteractionActionPreview !== null)
+        return;
+    if (!state.config.clearOnCoreInteraction)
+        return;
+    if (!hasCommittedAnnotations(state))
+        return;
+    const success = state.runtimeSurface.commands.startDrag({
+        type: ANNOTATIONS_IDLE_CLEAR_DRAG_TYPE,
+        sourceSquare: targetSquare,
+        sourcePieceCode: null,
+        targetSquare: targetSquare
+    });
+    if (success) {
+        rawEvent.preventDefault();
+    }
+}
+export function completeAnnotationsDrag(state, session) {
+    if (session.type === ANNOTATIONS_DRAW_DRAG_TYPE) {
+        const gesture = state.activeDrawGesture;
+        state.activeDrawGesture = null;
+        state.activeDrawPreviewTarget = null;
+        if (!gesture)
+            return;
+        if (session.targetSquare === null)
+            return;
+        if (gesture.sourceSquare === session.targetSquare) {
+            commitCircleToggle(state, gesture.sourceSquare, gesture.color);
+        }
+        else {
+            commitArrowToggle(state, gesture.sourceSquare, session.targetSquare, gesture.color);
+        }
+        return;
+    }
+    if (session.type !== ANNOTATIONS_IDLE_CLEAR_DRAG_TYPE)
+        return;
+    if (session.targetSquare === null)
+        return;
+    if (!hasCommittedAnnotations(state))
+        return;
+    clearCommittedAnnotations(state);
+    markCommittedDirtyAndRequestRender(state);
+}
+export function cancelAnnotationsDrag(state, session) {
+    if (session.type === ANNOTATIONS_DRAW_DRAG_TYPE) {
+        state.activeDrawGesture = null;
+        state.activeDrawPreviewTarget = null;
+    }
+}
+function commitCircleToggle(state, square, color) {
+    const existing = state.annotations.circles.get(square);
+    if (existing && existing.color === color) {
+        state.annotations.circles.delete(square);
+    }
+    else {
+        state.annotations.circles.set(square, { key: square, square, color });
+    }
+    markCommittedDirtyAndRequestRender(state);
+}
+function commitArrowToggle(state, from, to, color) {
+    const key = arrowAnnotationKeyNormalized(from, to);
+    const existing = state.annotations.arrows.get(key);
+    if (existing && existing.color === color) {
+        state.annotations.arrows.delete(key);
+    }
+    else {
+        state.annotations.arrows.set(key, { key, from, to, color });
+    }
+    markCommittedDirtyAndRequestRender(state);
+}

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

@@ -0,0 +1,3 @@
+import type { AnnotationsStateInternal } from './types/main.js';
+export declare function markDirtyAndRequestRender(state: AnnotationsStateInternal, layers: number): void;
+export declare function markCommittedDirtyAndRequestRender(state: AnnotationsStateInternal): void;

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

@@ -0,0 +1,7 @@
+export function markDirtyAndRequestRender(state, layers) {
+    state.runtimeSurface.invalidation.markDirty(layers);
+    state.runtimeSurface.commands.requestRender({ state: true });
+}
+export function markCommittedDirtyAndRequestRender(state) {
+    markDirtyAndRequestRender(state, 1 /* DirtyLayer.COMMITTED */);
+}

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

@@ -0,0 +1,12 @@
+import type { SquareString } from '../../../state/board/types/input.js';
+import type { Square } from '../../../state/board/types/internal.js';
+import type { AnnotationsConfig, ArrowAnnotation, ArrowAnnotationKey, CircleAnnotation, CircleAnnotationKey } from './types/internal.js';
+import type { AnnotationsStateInternalAnnotations } from './types/main.js';
+import type { AnnotationsInitOptionsAnnotations, AnnotationsInitOptionsConfig, ArrowAnnotationPublic, CircleAnnotationPublic } from './types/public.js';
+export declare function normalizeAnnotationsConfig(input?: AnnotationsInitOptionsConfig): AnnotationsConfig;
+export declare function circleAnnotationKey(square: SquareString): CircleAnnotationKey;
+export declare function normalizeCircleAnnotation(pub: CircleAnnotationPublic): CircleAnnotation;
+export declare function arrowAnnotationKeyNormalized(from: Square, to: Square): ArrowAnnotationKey;
+export declare function arrowAnnotationKey(from: SquareString, to: SquareString): ArrowAnnotationKey;
+export declare function normalizeArrowAnnotation(pub: ArrowAnnotationPublic): ArrowAnnotation;
+export declare function normalizeInitialAnnotations(input?: AnnotationsInitOptionsAnnotations): AnnotationsStateInternalAnnotations;

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

@@ -0,0 +1,54 @@
+import { cloneDeep, toMerged } from 'es-toolkit';
+import { normalizeSquare } from '../../../state/board/normalize.js';
+import { DEFAULT_CONFIG } from './constants.js';
+export function normalizeAnnotationsConfig(input) {
+    if (!input) {
+        return cloneDeep(DEFAULT_CONFIG);
+    }
+    return toMerged(DEFAULT_CONFIG, input);
+}
+export function circleAnnotationKey(square) {
+    return normalizeSquare(square);
+}
+export function normalizeCircleAnnotation(pub) {
+    const square = normalizeSquare(pub.square);
+    return {
+        key: square,
+        square,
+        color: pub.color
+    };
+}
+export function arrowAnnotationKeyNormalized(from, to) {
+    if (from === to) {
+        throw new Error("Invalid arrow: 'from' and 'to' must be different squares");
+    }
+    return from * 64 + to;
+}
+export function arrowAnnotationKey(from, to) {
+    const fromKey = normalizeSquare(from);
+    const toKey = normalizeSquare(to);
+    return arrowAnnotationKeyNormalized(fromKey, toKey);
+}
+export function normalizeArrowAnnotation(pub) {
+    const from = normalizeSquare(pub.from);
+    const to = normalizeSquare(pub.to);
+    const key = arrowAnnotationKeyNormalized(from, to);
+    return { key, from, to, color: pub.color };
+}
+export function normalizeInitialAnnotations(input) {
+    const circles = new Map();
+    const arrows = new Map();
+    if (input?.circles) {
+        for (const pub of input.circles) {
+            const circle = normalizeCircleAnnotation(pub);
+            circles.set(circle.key, circle);
+        }
+    }
+    if (input?.arrows) {
+        for (const pub of input.arrows) {
+            const arrow = normalizeArrowAnnotation(pub);
+            arrows.set(arrow.key, arrow);
+        }
+    }
+    return { circles, arrows };
+}

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

@@ -0,0 +1,3 @@
+import type { SceneRenderGeometry } from '../../../../layout/geometry/types.js';
+import type { AnnotationsStateInternal } from '../types/main.js';
+export declare function renderCommittedAnnotations(state: AnnotationsStateInternal, geometry: SceneRenderGeometry): void;