@fieldnotes/core 0.62.0 → 0.63.0

package/dist/index.d.ts

@@ -711,6 +711,12 @@ interface ViewportOptions {
     /** Show an overview minimap (bottom-right) with tap/drag-to-navigate. Default `false`. */
     minimap?: boolean;
 }
+interface HitTestOptions {
+    /** Skip elements on locked layers. Default `true` (selection semantics). */
+    respectLayerLock?: boolean;
+    /** Applied inside the candidate walk; the topmost passing element wins. */
+    match?: (element: CanvasElement) => boolean;
+}
 declare class Viewport {
     private readonly container;
     readonly camera: Camera;
@@ -772,6 +778,15 @@ declare class Viewport {
     fitToContent(padding?: number): void;
     /** World-space rectangle currently visible through the canvas. */
     getVisibleRect(): Bounds;
+    /**
+     * Topmost element at a world point, using the same geometry selection uses
+     * (rotation-aware, grid excluded, real stroke/line hit paths).
+     *
+     * `match` participates in the topmost-first walk rather than filtering the
+     * result, so a non-matching element on top does not swallow the hit.
+     * Invisible layers are never returned, in any mode.
+     */
+    getElementAt(world: Point, options?: HitTestOptions): CanvasElement | null;
     /**
      * Size in CSS pixels of the canvas that `getVisibleRect()` measures.
      * Exposed because `canvasEl` is private: consumers can only reach the
@@ -990,6 +1005,187 @@ declare class Viewport {
     private observeResize;
 }
 
+/**
+ * A viewport-size-independent camera view: the world rectangle to frame.
+ * Restored by contain-fit, so the same view frames the same world content on
+ * any screen size or aspect — a DM's saved zone looks right on a phone and a
+ * TV. Center+zoom would NOT have this property.
+ */
+interface CameraView {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** Captures the currently visible world rect. */
+declare function captureCameraView(viewport: {
+    getVisibleRect(): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}): CameraView;
+/**
+ * Unclamped contain-fit zoom: the largest zoom at which the whole rect fits.
+ * Contain, never crop — a view whose aspect differs from the canvas shows
+ * extra world content on the short axis.
+ */
+declare function fitZoomForView(view: CameraView, canvasW: number, canvasH: number): number;
+/** Camera origin that centers `view` on the canvas at an already-decided zoom. */
+declare function cameraOriginForView(view: CameraView, zoom: number, canvasW: number, canvasH: number): Point;
+/**
+ * Writes `view` to `camera`. No-ops on a zero canvas dimension (mount and
+ * visibility races are legitimate); throws on an invalid view or on negative
+ * or non-finite dimensions.
+ */
+declare function applyCameraView(camera: Camera, view: CameraView, canvasW: number, canvasH: number): void;
+
+/** A scheduler and its matching canceller. Inseparable by construction. */
+interface FrameScheduler {
+    requestFrame: (cb: () => void) => number;
+    cancelFrame: (id: number) => void;
+}
+interface CameraAnimatorOptions {
+    /** REQUIRED. `element` is used for input listeners only, never measurement. */
+    getCanvasSize: () => {
+        w: number;
+        h: number;
+    };
+    durationMs?: number;
+    easing?: (t: number) => number;
+    interactive?: boolean;
+    frames?: FrameScheduler;
+    now?: () => number;
+}
+type CameraAnimationEndReason = 'complete' | 'cancelled' | 'superseded';
+/**
+ * Animates a camera to a `CameraView`. Standalone controller in the
+ * `PingInput`/`MinimapController` shape: the host owns construction and
+ * disposal, and every timing dependency is injectable for deterministic tests.
+ */
+declare class CameraAnimator {
+    private readonly camera;
+    private readonly getCanvasSize;
+    private readonly frames;
+    private readonly now;
+    private readonly durationMs;
+    private readonly easing;
+    private rafId;
+    private from;
+    private to;
+    private startedAt;
+    private endListeners;
+    /**
+     * Monotonic operation counter. `animateTo`/`jumpTo` claim a generation
+     * before emitting 'superseded'; if an onEnd listener starts a newer
+     * operation during that emit, the outer call sees a bumped counter and
+     * bails instead of overwriting the nested animation's state. Without this,
+     * the nested animation would run to completion having never reported an end
+     * reason, breaking the exactly-one guarantee the spec makes.
+     */
+    private generation;
+    private lastWrite;
+    private disposed;
+    private detachListeners;
+    constructor(element: HTMLElement, camera: Camera, options: CameraAnimatorOptions);
+    get animating(): boolean;
+    onEnd(listener: (reason: CameraAnimationEndReason) => void): () => void;
+    animateTo(view: CameraView): void;
+    jumpTo(view: CameraView): void;
+    cancel(): void;
+    /**
+     * Terminal. Order is load-bearing: the flag is set BEFORE any listener runs,
+     * because an onEnd listener can call animateTo during the disposal callback.
+     * With the flag set last, that call would start a real animation which the
+     * listener clear then silently discards — a second animation with no end
+     * reason, breaking the exactly-one guarantee.
+     */
+    dispose(): void;
+    /**
+     * Steps 1-3 of the public-call contract. Returns null when the caller must
+     * stop, having already handled termination.
+     *
+     * The disposed check precedes validation deliberately: ordering it after
+     * would make `disposed.animateTo(invalidView)` both required to throw and
+     * required to stay silent. Disposal wins — a terminal animator is inert for
+     * every input, and post-disposal calls are exactly the racy teardown paths
+     * where a throw is least useful.
+     */
+    private validateAndMeasure;
+    private step;
+    private recordWrite;
+    private foreignWrite;
+    /** Terminates an in-flight animation with `reason`. No-op when idle. */
+    private end;
+    private clearFrame;
+    private emit;
+}
+
+/** World-space rect of a tracked element, plus the host key it matched under. */
+interface ElementRect {
+    id: string;
+    /** Opaque host key echoed back from `match`. Core never interprets it. */
+    key: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    /** Radians, clockwise, about the rect centre. 0 when the element has none. */
+    rotation: number;
+}
+/** Returns an opaque key to track the element, or `null` to skip it. */
+type ElementRectMatch = (element: CanvasElement) => string | null;
+type ElementRectMatchError = (error: unknown, element: CanvasElement) => void;
+/**
+ * The tracker's per-frame computation, exported so consumers that need a
+ * snapshot without a live tracker (e.g. a React `getSnapshot` before
+ * subscription) cannot drift from these rules.
+ */
+declare function computeElementRects(store: ElementStore, match: ElementRectMatch, onError?: ElementRectMatchError): ElementRect[];
+/** Field-for-field comparison; `key` participates so identity changes emit. */
+declare function elementRectsEqual(a: readonly ElementRect[], b: readonly ElementRect[]): boolean;
+/** Narrow structural host: the tracker needs the element store and nothing else. */
+interface RectTrackerHost {
+    store: ElementStore;
+}
+interface ElementRectTrackerOptions {
+    match: ElementRectMatch;
+    /** Inseparable request/cancel pair. Defaults to global rAF. */
+    frames?: FrameScheduler;
+    onError?: ElementRectMatchError;
+}
+/**
+ * Tracks the world rects of a host-matched subset of elements.
+ *
+ * Deliberately store-only: it never subscribes to the camera, so pan and zoom
+ * emit nothing and hosts that position content under a single camera transform
+ * (the SDK's own domLayer technique) do no per-frame work.
+ */
+declare class ElementRectTracker {
+    private readonly store;
+    private readonly frames;
+    private readonly onError?;
+    private readonly listeners;
+    private readonly unsubscribe;
+    private match;
+    private rects;
+    private frameId;
+    private disposed;
+    constructor(host: RectTrackerHost, options: ElementRectTrackerOptions);
+    onChange(listener: (rects: readonly ElementRect[]) => void): () => void;
+    getRects(): readonly ElementRect[];
+    /**
+     * Replaces the matcher and forces a rescan — including when handed the same
+     * reference, because callers legitimately pass one stable wrapper whose
+     * behavior changes (see the React hook).
+     */
+    setMatch(match: ElementRectMatch): void;
+    dispose(): void;
+    private schedule;
+    private flush;
+}
+
 interface LaserToolOptions {
     name?: string;
     color?: string;
@@ -1601,123 +1797,6 @@ declare class MinimapController {
     private onPointerEnd;
 }
 
-/**
- * A viewport-size-independent camera view: the world rectangle to frame.
- * Restored by contain-fit, so the same view frames the same world content on
- * any screen size or aspect — a DM's saved zone looks right on a phone and a
- * TV. Center+zoom would NOT have this property.
- */
-interface CameraView {
-    x: number;
-    y: number;
-    w: number;
-    h: number;
-}
-/** Captures the currently visible world rect. */
-declare function captureCameraView(viewport: {
-    getVisibleRect(): {
-        x: number;
-        y: number;
-        w: number;
-        h: number;
-    };
-}): CameraView;
-/**
- * Unclamped contain-fit zoom: the largest zoom at which the whole rect fits.
- * Contain, never crop — a view whose aspect differs from the canvas shows
- * extra world content on the short axis.
- */
-declare function fitZoomForView(view: CameraView, canvasW: number, canvasH: number): number;
-/** Camera origin that centers `view` on the canvas at an already-decided zoom. */
-declare function cameraOriginForView(view: CameraView, zoom: number, canvasW: number, canvasH: number): Point;
-/**
- * Writes `view` to `camera`. No-ops on a zero canvas dimension (mount and
- * visibility races are legitimate); throws on an invalid view or on negative
- * or non-finite dimensions.
- */
-declare function applyCameraView(camera: Camera, view: CameraView, canvasW: number, canvasH: number): void;
-
-/** A scheduler and its matching canceller. Inseparable by construction. */
-interface FrameScheduler {
-    requestFrame: (cb: () => void) => number;
-    cancelFrame: (id: number) => void;
-}
-interface CameraAnimatorOptions {
-    /** REQUIRED. `element` is used for input listeners only, never measurement. */
-    getCanvasSize: () => {
-        w: number;
-        h: number;
-    };
-    durationMs?: number;
-    easing?: (t: number) => number;
-    interactive?: boolean;
-    frames?: FrameScheduler;
-    now?: () => number;
-}
-type CameraAnimationEndReason = 'complete' | 'cancelled' | 'superseded';
-/**
- * Animates a camera to a `CameraView`. Standalone controller in the
- * `PingInput`/`MinimapController` shape: the host owns construction and
- * disposal, and every timing dependency is injectable for deterministic tests.
- */
-declare class CameraAnimator {
-    private readonly camera;
-    private readonly getCanvasSize;
-    private readonly frames;
-    private readonly now;
-    private readonly durationMs;
-    private readonly easing;
-    private rafId;
-    private from;
-    private to;
-    private startedAt;
-    private endListeners;
-    /**
-     * Monotonic operation counter. `animateTo`/`jumpTo` claim a generation
-     * before emitting 'superseded'; if an onEnd listener starts a newer
-     * operation during that emit, the outer call sees a bumped counter and
-     * bails instead of overwriting the nested animation's state. Without this,
-     * the nested animation would run to completion having never reported an end
-     * reason, breaking the exactly-one guarantee the spec makes.
-     */
-    private generation;
-    private lastWrite;
-    private disposed;
-    private detachListeners;
-    constructor(element: HTMLElement, camera: Camera, options: CameraAnimatorOptions);
-    get animating(): boolean;
-    onEnd(listener: (reason: CameraAnimationEndReason) => void): () => void;
-    animateTo(view: CameraView): void;
-    jumpTo(view: CameraView): void;
-    cancel(): void;
-    /**
-     * Terminal. Order is load-bearing: the flag is set BEFORE any listener runs,
-     * because an onEnd listener can call animateTo during the disposal callback.
-     * With the flag set last, that call would start a real animation which the
-     * listener clear then silently discards — a second animation with no end
-     * reason, breaking the exactly-one guarantee.
-     */
-    dispose(): void;
-    /**
-     * Steps 1-3 of the public-call contract. Returns null when the caller must
-     * stop, having already handled termination.
-     *
-     * The disposed check precedes validation deliberately: ordering it after
-     * would make `disposed.animateTo(invalidView)` both required to throw and
-     * required to stay silent. Disposal wins — a terminal animator is inert for
-     * every input, and post-disposal calls are exactly the racy teardown paths
-     * where a throw is least useful.
-     */
-    private validateAndMeasure;
-    private step;
-    private recordWrite;
-    private foreignWrite;
-    /** Terminates an in-flight animation with `reason`. No-op when idle. */
-    private end;
-    private clearFrame;
-    private emit;
-}
-
 /**
  * The wire shape of a focus-request presence payload. Focus is ephemeral by
  * contract: presence frames only — never elements, undo history, persisted
@@ -2202,6 +2281,6 @@ declare class TemplateTool implements Tool {
     private notifyOptionsChange;
 }
 
-declare const VERSION = "0.62.0";
+declare const VERSION = "0.63.0";
 
-export { type ActivationOptions, type ActiveFormats, type AlignEdge, type ArrowElement, type ArrowStrokeStyle, ArrowTool, type ArrowToolOptions, AutoSave, type AutoSaveOptions, type BackgroundOptions, type BackgroundPattern, type Binding, type Bounds, Camera, type CameraAnimationEndReason, CameraAnimator, type CameraAnimatorOptions, type CameraChangeInfo, type CameraOptions, type CameraView, type CanvasElement, type CanvasState, type Command, DEFAULT_NOTE_FONT_SIZE, type DistributeAxis, type ElementActivationEvent, type ElementChangeMeta, ElementStore, type ElementStyle, type ElementType, type ElementUpdateEvent, EraserTool, type EraserToolOptions, type ExportAssetError, type ExportAssetErrorReason, type ExportImageOptions, type ExportResourceOptions, type ExportSvgOptions, FOCUS_PRESENCE_KIND, type FocusAudience, type FocusPresence, type FocusRole, type FontSizePreset, type FrameScheduler, type GridElement, type GridInfo, HandTool, type HexOrientation, HistoryStack, type HistoryStackOptions, type HtmlElement, type HtmlExportError, type HtmlExportErrorReason, type HtmlExportOptions, type HtmlExportRenderer, type HtmlPaintContext, type HtmlPaintDiagnostic, type HtmlPainter, HtmlPainterMissingError, HtmlPainterRegistry, type HtmlRenderTarget, type HtmlRouting, type ImageElement, ImageTool, type ImageToolOptions, IndexedDBAdapter, type IndexedDBAdapterOptions, LASER_TRAIL_PRESENCE_KIND, LaserTool, type LaserToolOptions, type LaserTrailEmission, type LaserTrailPresence, type Layer, LayerManager, LocalStorageAdapter, MEASURE_PRESENCE_KIND, type MeasureEmission, type MeasurePresence, MeasureTool, type MeasureToolOptions, type Measurement, MemoryAdapter, MinimapController, type MinimapControllerOptions, type NoteElement, NoteTool, type NoteToolOptions, type OverlayRenderer, PING_PRESENCE_KIND, PencilTool, type PencilToolOptions, type PingEmission, PingInput, type PingInputHost, type PingInputOptions, type PingPresence, PingTool, type PingToolOptions, type Point, type PointerState, RemoteFocusReceiver, type RemoteFocusReceiverHost, type RemoteFocusReceiverOptions, RemoteLaserOverlay, type RemoteLaserOverlayHost, type RemoteLaserOverlayOptions, RemoteMeasureOverlay, type RemoteMeasureOverlayHost, type RemoteMeasureOverlayOptions, RemotePingOverlay, type RemotePingOverlayHost, type RemotePingOverlayOptions, type RenderStatsSnapshot, type RotateDirection, SelectTool, type SelectionStyleDetails, type ShapeElement, type ShapeKind, ShapeTool, type ShapeToolOptions, type ShortcutBindings, type ShortcutOptions, type ShortcutsApi, type Size, type StorageAdapter, type StrokeElement, type StrokePoint, type TemplateElement, type TemplateRenderStyle, type TemplateShape, TemplateTool, type TemplateToolOptions, type TextElement, TextTool, type TextToolOptions, type Tool, type ToolContext, ToolManager, type ToolName, VERSION, Viewport, type ViewportOptions, applyCameraView, boundsIntersect, cameraOriginForView, captureCameraView, createArrow, createGrid, createHtmlElement, createImage, createNote, createShape, createStroke, createTemplate, createText, drawHexPath, exportImage, exportSvg, fitZoomForView, getActiveFormats, getArrowBounds, getArrowControlPoint, getArrowMidpoint, getArrowTangentAngle, getBendFromPoint, getElementBounds, getElementStyle, getElementsBoundingBox, getHexCellsInCone, getHexCellsInLine, getHexCellsInRadius, getHexCellsInRectangle, getHexCellsInSquare, getHexDistance, isFocusPresence, isLaserTrailPresence, isMeasurePresence, isNearBezier, isPingPresence, resolveHtmlRouting, setFontSize, smartSnap, snapPoint, snapToHexCenter, styleToPatch, toFocusPresence, toLaserTrailPresence, toMeasurePresence, toPingPresence, toggleBold, toggleItalic, toggleStrikethrough, toggleUnderline };
+export { type ActivationOptions, type ActiveFormats, type AlignEdge, type ArrowElement, type ArrowStrokeStyle, ArrowTool, type ArrowToolOptions, AutoSave, type AutoSaveOptions, type BackgroundOptions, type BackgroundPattern, type Binding, type Bounds, Camera, type CameraAnimationEndReason, CameraAnimator, type CameraAnimatorOptions, type CameraChangeInfo, type CameraOptions, type CameraView, type CanvasElement, type CanvasState, type Command, DEFAULT_NOTE_FONT_SIZE, type DistributeAxis, type ElementActivationEvent, type ElementChangeMeta, type ElementRect, type ElementRectMatch, type ElementRectMatchError, ElementRectTracker, type ElementRectTrackerOptions, ElementStore, type ElementStyle, type ElementType, type ElementUpdateEvent, EraserTool, type EraserToolOptions, type ExportAssetError, type ExportAssetErrorReason, type ExportImageOptions, type ExportResourceOptions, type ExportSvgOptions, FOCUS_PRESENCE_KIND, type FocusAudience, type FocusPresence, type FocusRole, type FontSizePreset, type FrameScheduler, type GridElement, type GridInfo, HandTool, type HexOrientation, HistoryStack, type HistoryStackOptions, type HitTestOptions, type HtmlElement, type HtmlExportError, type HtmlExportErrorReason, type HtmlExportOptions, type HtmlExportRenderer, type HtmlPaintContext, type HtmlPaintDiagnostic, type HtmlPainter, HtmlPainterMissingError, HtmlPainterRegistry, type HtmlRenderTarget, type HtmlRouting, type ImageElement, ImageTool, type ImageToolOptions, IndexedDBAdapter, type IndexedDBAdapterOptions, LASER_TRAIL_PRESENCE_KIND, LaserTool, type LaserToolOptions, type LaserTrailEmission, type LaserTrailPresence, type Layer, LayerManager, LocalStorageAdapter, MEASURE_PRESENCE_KIND, type MeasureEmission, type MeasurePresence, MeasureTool, type MeasureToolOptions, type Measurement, MemoryAdapter, MinimapController, type MinimapControllerOptions, type NoteElement, NoteTool, type NoteToolOptions, type OverlayRenderer, PING_PRESENCE_KIND, PencilTool, type PencilToolOptions, type PingEmission, PingInput, type PingInputHost, type PingInputOptions, type PingPresence, PingTool, type PingToolOptions, type Point, type PointerState, type RectTrackerHost, RemoteFocusReceiver, type RemoteFocusReceiverHost, type RemoteFocusReceiverOptions, RemoteLaserOverlay, type RemoteLaserOverlayHost, type RemoteLaserOverlayOptions, RemoteMeasureOverlay, type RemoteMeasureOverlayHost, type RemoteMeasureOverlayOptions, RemotePingOverlay, type RemotePingOverlayHost, type RemotePingOverlayOptions, type RenderStatsSnapshot, type RotateDirection, SelectTool, type SelectionStyleDetails, type ShapeElement, type ShapeKind, ShapeTool, type ShapeToolOptions, type ShortcutBindings, type ShortcutOptions, type ShortcutsApi, type Size, type StorageAdapter, type StrokeElement, type StrokePoint, type TemplateElement, type TemplateRenderStyle, type TemplateShape, TemplateTool, type TemplateToolOptions, type TextElement, TextTool, type TextToolOptions, type Tool, type ToolContext, ToolManager, type ToolName, VERSION, Viewport, type ViewportOptions, applyCameraView, boundsIntersect, cameraOriginForView, captureCameraView, computeElementRects, createArrow, createGrid, createHtmlElement, createImage, createNote, createShape, createStroke, createTemplate, createText, drawHexPath, elementRectsEqual, exportImage, exportSvg, fitZoomForView, getActiveFormats, getArrowBounds, getArrowControlPoint, getArrowMidpoint, getArrowTangentAngle, getBendFromPoint, getElementBounds, getElementStyle, getElementsBoundingBox, getHexCellsInCone, getHexCellsInLine, getHexCellsInRadius, getHexCellsInRectangle, getHexCellsInSquare, getHexDistance, isFocusPresence, isLaserTrailPresence, isMeasurePresence, isNearBezier, isPingPresence, resolveHtmlRouting, setFontSize, smartSnap, snapPoint, snapToHexCenter, styleToPatch, toFocusPresence, toLaserTrailPresence, toMeasurePresence, toPingPresence, toggleBold, toggleItalic, toggleStrikethrough, toggleUnderline };