@fieldnotes/core 0.61.0 → 0.62.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;
@@ -643,6 +749,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;
@@ -690,6 +804,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 +864,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';
@@ -1368,6 +1559,7 @@ declare class MinimapController {
     private readonly requestFrame;
     private readonly cancelFrame;
     private readonly renderer;
+    private readonly htmlPainters;
     private scene;
     private frameId;
     private debounceTimer;
@@ -1377,6 +1569,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;
@@ -1649,6 +1854,7 @@ interface HtmlInput extends BaseDefaults {
     interactive?: boolean;
     htmlType?: string;
     data?: Record<string, unknown>;
+    rotation?: number;
 }
 interface TextInput extends BaseDefaults {
     position: Point;
@@ -1996,6 +2202,6 @@ declare class TemplateTool implements Tool {
     private notifyOptionsChange;
 }
 
-declare const VERSION = "0.61.0";
+declare const VERSION = "0.62.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, 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 };

package/dist/index.d.ts

@@ -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;
@@ -643,6 +749,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;
@@ -690,6 +804,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 +864,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';
@@ -1368,6 +1559,7 @@ declare class MinimapController {
     private readonly requestFrame;
     private readonly cancelFrame;
     private readonly renderer;
+    private readonly htmlPainters;
     private scene;
     private frameId;
     private debounceTimer;
@@ -1377,6 +1569,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;
@@ -1649,6 +1854,7 @@ interface HtmlInput extends BaseDefaults {
     interactive?: boolean;
     htmlType?: string;
     data?: Record<string, unknown>;
+    rotation?: number;
 }
 interface TextInput extends BaseDefaults {
     position: Point;
@@ -1996,6 +2202,6 @@ declare class TemplateTool implements Tool {
     private notifyOptionsChange;
 }
 
-declare const VERSION = "0.61.0";
+declare const VERSION = "0.62.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, 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 };