@fieldnotes/core 0.61.0 → 0.63.0

package/dist/index.d.cts

@@ -450,7 +450,7 @@ declare class HistoryStack {
 }
 
 type HtmlExportRenderer = (element: HtmlElement) => CanvasImageSource | null | Promise<CanvasImageSource | null>;
-type HtmlExportErrorReason = 'unsupported' | 'timeout' | 'render' | 'encode';
+type HtmlExportErrorReason = 'unsupported' | 'timeout' | 'render' | 'encode' | 'missing-painter' | 'painter-threw' | 'degenerate-size';
 interface HtmlExportError {
     elementId: string;
     htmlType?: string;
@@ -466,6 +466,51 @@ interface HtmlExportOptions {
     onHtmlError?: (error: HtmlExportError) => void;
 }
 
+interface HtmlPaintContext {
+    /** Translated to the element origin, rotated about its centre, clipped, save()d.
+     *  Layer opacity is NOT applied here — each surface owns that boundary. */
+    ctx: CanvasRenderingContext2D;
+    element: Readonly<HtmlElement>;
+    size: Readonly<Size>;
+    /** CSS pixels per world unit for THIS surface (screen | minimap | export). */
+    zoom: number;
+}
+type HtmlPainter = (paint: HtmlPaintContext) => void;
+type HtmlRouting = 'dom' | 'canvas' | 'missing';
+declare class HtmlPainterMissingError extends Error {
+    readonly elementId: string;
+    readonly htmlType: string | undefined;
+    constructor(elementId: string, htmlType: string | undefined);
+}
+declare class HtmlPainterRegistry {
+    private readonly painters;
+    private readonly declared;
+    private readonly listeners;
+    private _version;
+    private canvasTypesCache;
+    get version(): number;
+    /**
+     * Memoized: this is the hottest read in the feature — `isDomElement` consults it several
+     * times per element per frame, and every html-element store update re-reconciles every
+     * html element. The cache is dropped in `bump()`, which is called on exactly the
+     * transitions that can change the membership of this set (first `expect` of a type, last
+     * release of a type, any `register`, and any unregister that empties a type's stack).
+     *
+     * The returned `Set` is the LIVE memoized instance, not a copy: callers must not mutate
+     * it, and a caller that holds it across a `bump()` holds a stale snapshot. Nothing in the
+     * codebase does either — `withHtmlDefaults` passes it straight through to the exporters
+     * unless the caller supplied `expectedCanvasTypes`, in which case it builds a fresh union
+     * — and holding it across a change was already a stale snapshot before memoization.
+     */
+    get canvasTypes(): ReadonlySet<string>;
+    expect(htmlTypes: Iterable<string>): () => void;
+    register(htmlType: string, painter: HtmlPainter): () => void;
+    getActivePainter(htmlType: string): HtmlPainter | undefined;
+    onChange(listener: () => void): () => void;
+    private bump;
+}
+declare function resolveHtmlRouting(el: Readonly<HtmlElement>, registry: HtmlPainterRegistry | null, expectedCanvasTypes?: ReadonlySet<string>): HtmlRouting;
+
 interface ExportImageOptions extends ExportResourceOptions, HtmlExportOptions {
     scale?: number;
     padding?: number;
@@ -497,6 +542,20 @@ interface ExportImageOptions extends ExportResourceOptions, HtmlExportOptions {
      * caps (never above the requested scale).
      */
     scaleMode?: 'exact' | 'fit';
+    /** Registry of canvas-backed html painters, keyed by `htmlType`. When absent (or when
+     *  an element's `htmlType` isn't claimed), html elements fall back to the legacy
+     *  DOM-raster path (`renderHtml`). */
+    htmlPainters?: HtmlPainterRegistry;
+    /** `htmlType`s that must route to canvas even before a painter for them is
+     *  registered — lets a host declare intent up front (mirrors `HtmlPainterRegistry.expect`). */
+    expectedCanvasTypes?: ReadonlySet<string>;
+    /**
+     * When true, a canvas-routed html element with no active painter throws
+     * `HtmlPainterMissingError` instead of reporting `onHtmlError` and continuing.
+     * DOM-routed html elements are never affected — a missing `renderHtml` stays
+     * a non-fatal `'unsupported'` diagnostic regardless of this flag.
+     */
+    strictMissingCanvasHtml?: boolean;
 }
 type ExportAssetErrorReason = 'load' | 'timeout' | 'encode';
 interface ExportAssetError {
@@ -522,9 +581,32 @@ interface ExportSvgOptions extends ExportResourceOptions, HtmlExportOptions {
     background?: string;
     filter?: (el: CanvasElement) => boolean;
     rasterScale?: number;
+    /** Registry of canvas-backed html painters, keyed by `htmlType`. When absent (or when
+     *  an element's `htmlType` isn't claimed), html elements fall back to the legacy
+     *  DOM-raster path (`renderHtml`). */
+    htmlPainters?: HtmlPainterRegistry;
+    /** `htmlType`s that must route to canvas even before a painter for them is
+     *  registered — lets a host declare intent up front (mirrors `HtmlPainterRegistry.expect`). */
+    expectedCanvasTypes?: ReadonlySet<string>;
+    /**
+     * When true, a canvas-routed html element with no active painter throws
+     * `HtmlPainterMissingError` instead of reporting `onHtmlError` and continuing.
+     * DOM-routed html elements are never affected — a missing `renderHtml` stays
+     * a non-fatal `'unsupported'` diagnostic regardless of this flag.
+     */
+    strictMissingCanvasHtml?: boolean;
 }
 declare function exportSvg(store: ElementStore, options?: ExportSvgOptions, layerManager?: LayerManager): Promise<string>;
 
+type HtmlRenderTarget = 'screen' | 'minimap' | 'export';
+interface HtmlPaintDiagnostic {
+    kind: 'missing-painter' | 'painter-threw' | 'degenerate-size';
+    elementId: string;
+    htmlType?: string;
+    target: HtmlRenderTarget;
+    error?: unknown;
+}
+
 interface RenderStatsSnapshot {
     fps: number;
     avgFrameMs: number;
@@ -575,6 +657,30 @@ interface GridInfo {
     cellRadius: number;
 }
 
+interface ElementActivationEvent {
+    element: Readonly<CanvasElement>;
+    /** Pointerup location converted through the pointerup camera snapshot. */
+    world: Point;
+    /**
+     * Raw `PointerEvent.pointerType`. Usually `'mouse' | 'touch' | 'pen'`, but the
+     * spec permits vendor-defined and empty strings, so this is NOT narrowed and
+     * NOT normalised.
+     */
+    pointerType: string;
+    gesture: 'single' | 'double';
+}
+interface ActivationOptions {
+    gesture: 'single' | 'double';
+    /** Additional host filter, applied on top of the core canvas-routing gate. */
+    isActivatable?: (el: Readonly<CanvasElement>) => boolean;
+    /** Host-owned camera animators the viewport cannot see. */
+    isCameraBusy?: () => boolean;
+    /** Maximum pointer travel between down and up. Default `8` (PingInput parity). */
+    slopPx?: number;
+    /** Maximum gap between the halves of a double tap. Default `300`. */
+    doubleDelayMs?: number;
+}
+
 interface ViewportOptions {
     camera?: CameraOptions;
     background?: BackgroundOptions;
@@ -605,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;
@@ -643,6 +755,14 @@ declare class Viewport {
     private contextMenu;
     private minimap;
     private readonly htmlRenderers;
+    private readonly htmlPainters;
+    private readonly htmlDiagnosticListeners;
+    private readonly htmlDiagnostics;
+    private readonly resolveRouting;
+    private readonly unsubHtmlPainters;
+    private activation;
+    private activationGeneration;
+    private readonly activationListeners;
     private readonly resizeListeners;
     private readonly selectionListeners;
     private detachSelectionSource;
@@ -658,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
@@ -690,6 +819,15 @@ declare class Viewport {
     registerOverlay(draw: OverlayRenderer): () => void;
     exportState(): CanvasState;
     exportJSON(): string;
+    /**
+     * Injects this viewport's own html painter registry into export options so a host
+     * that registered painters via `registerHtmlPainter`/`expectCanvasHtmlTypes` gets
+     * markers in exports without passing anything. An explicitly passed `htmlPainters`
+     * REPLACES the viewport's registry rather than merging with it. `expectedCanvasTypes`
+     * is always UNIONED with the resolved registry's own declarations — a caller's set
+     * can only add expectations, never shrink the registry's own.
+     */
+    private withHtmlDefaults;
     exportImage(options?: ExportImageOptions): Promise<Blob | null>;
     exportSVG(options?: ExportSvgOptions): Promise<string>;
     loadState(state: CanvasState): void;
@@ -741,6 +879,74 @@ declare class Viewport {
     removeLayer(id: string): void;
     registerHtmlRenderer(htmlType: string, factory: (el: HtmlElement) => HTMLElement): void;
     updateHtmlElement(id: string, newContent: HTMLElement): void;
+    /**
+     * Declares htmlTypes that route to canvas painters even before a painter for
+     * them registers, so the element renderer never treats them as DOM-backed
+     * (avoiding a DOM-mount flash while a host is still loading its painter).
+     * Returns an idempotent release; each `expect` call is independently reference
+     * counted by the registry.
+     */
+    expectCanvasHtmlTypes(htmlTypes: Iterable<string>): () => void;
+    /**
+     * Direct access to the viewport's live html-painter registry — the same
+     * instance the viewport itself uses to route canvas-backed html elements.
+     * Beyond `register`/`expectCanvasHtmlTypes` (already exposed above), this
+     * hands out `getActivePainter`, `canvasTypes`, `onChange`, and `version`,
+     * so a surface such as the minimap that needs to read routing state or
+     * react to registry changes can do so without the viewport re-deriving or
+     * proxying each capability individually.
+     */
+    getHtmlPainters(): HtmlPainterRegistry;
+    /**
+     * Registers the canvas painter for `htmlType`. Later registrations for the
+     * same type shadow earlier ones (LIFO); unregistering restores the previous
+     * entry. Existing elements of this type reconcile synchronously — DOM nodes
+     * detach and the render loop repaints on the next frame.
+     */
+    registerHtmlPainter(htmlType: string, painter: HtmlPainter): () => void;
+    /**
+     * Subscribes to diagnostics emitted while painting canvas-routed html
+     * elements (missing painter, painter threw, degenerate size). Deduped per
+     * element/target/kind against the current registry and element versions, so
+     * a fail -> repair -> fail-again sequence reports twice rather than being
+     * suppressed forever. Returns an idempotent unsubscribe.
+     */
+    onHtmlPaintDiagnostic(listener: (d: HtmlPaintDiagnostic) => void): () => void;
+    /**
+     * Enables (or replaces, or with `null` disables) pointer activation of
+     * canvas-painted elements — the bridge for elements that are drawn rather than
+     * mounted and so cannot receive DOM events. **Default off**, so every existing
+     * consumer behaves identically.
+     *
+     * The controller is a passive observer: listeners are `{ passive: true }` and
+     * it never calls `preventDefault`, `stopPropagation`, or takes pointer capture.
+     * Changing or disabling activation resets all active and pending gestures.
+     * Throws `RangeError` for a non-finite/negative `slopPx` or a non-positive
+     * `doubleDelayMs`, leaving any existing activation untouched.
+     *
+     * The returned disposer clears **only its own generation**, so a stale
+     * Strict-Mode cleanup cannot tear down a newer registration.
+     */
+    setActivation(options: ActivationOptions | null): () => void;
+    /**
+     * Subscribes to element activations. Persistent and independent of
+     * `setActivation`: subscribing before activation is enabled, or across a
+     * replacement, keeps working. Emission iterates a snapshot with per-listener
+     * try/catch. Returns an idempotent unsubscribe.
+     */
+    onElementActivate(listener: (e: ElementActivationEvent) => void): () => void;
+    private emitActivation;
+    /**
+     * Fires whenever the html painter registry's active-painter set changes
+     * (declare, register, or their release). Reconciliation is synchronous —
+     * routing flips (and any DOM detach/remount) happen before this returns —
+     * while the actual repaint of newly canvas-routed elements is deferred to
+     * the next render frame via markAllLayersDirty + requestRender. Does NOT
+     * touch a minimap: Viewport does not own a MinimapController, and the
+     * built-in wrapper / React <Minimap /> each subscribe to the registry
+     * directly.
+     */
+    private onHtmlRegistryChanged;
     addGrid(input: {
         gridType?: 'square' | 'hex';
         hexOrientation?: 'pointy' | 'flat';
@@ -799,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;
@@ -1368,6 +1755,7 @@ declare class MinimapController {
     private readonly requestFrame;
     private readonly cancelFrame;
     private readonly renderer;
+    private readonly htmlPainters;
     private scene;
     private frameId;
     private debounceTimer;
@@ -1377,6 +1765,19 @@ declare class MinimapController {
     constructor(viewport: Viewport, canvas: HTMLCanvasElement, options?: MinimapControllerOptions);
     setSize(width: number, height: number): void;
     requestDraw(): void;
+    /**
+     * Invalidates the cached scene bitmap in response to html-painter registry
+     * changes (a painter registering/unregistering, or an `expect` declaration
+     * changing) and schedules the same debounced rebuild `markSceneDirty` uses
+     * for every other invalidation source. Unlike those other sources — which
+     * deliberately keep compositing the OLD bitmap until the rebuild lands, so
+     * camera motion and content edits never stall on a render — painter
+     * availability has no "old bitmap is still valid" reading: an element that
+     * was falling back to a neutral fillRect (no painter yet) or a stale
+     * painter's output is not a safe thing to keep showing, so the cached
+     * bitmap is dropped immediately instead of composited a further time.
+     */
+    invalidateScene(): void;
     dispose(): void;
     private clearDebounce;
     private dpr;
@@ -1396,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
@@ -1649,6 +1933,7 @@ interface HtmlInput extends BaseDefaults {
     interactive?: boolean;
     htmlType?: string;
     data?: Record<string, unknown>;
+    rotation?: number;
 }
 interface TextInput extends BaseDefaults {
     position: Point;
@@ -1996,6 +2281,6 @@ declare class TemplateTool implements Tool {
     private notifyOptionsChange;
 }
 
-declare const VERSION = "0.61.0";
+declare const VERSION = "0.63.0";
 
-export { 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 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 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, 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 };