@fieldnotes/core 0.59.0 → 0.61.0

package/dist/index.d.cts

@@ -410,6 +410,7 @@ declare class ToolManager {
     private tools;
     private current;
     private changeListeners;
+    private registerListeners;
     get activeTool(): Tool | null;
     get toolNames(): string[];
     register(tool: Tool): void;
@@ -419,6 +420,7 @@ declare class ToolManager {
     handlePointerMove(state: PointerState, ctx: ToolContext): void;
     handlePointerUp(state: PointerState, ctx: ToolContext): void;
     onChange(listener: (name: string) => void): () => void;
+    onRegister(listener: (tool: Tool) => void): () => void;
 }
 
 interface Command {
@@ -558,6 +560,11 @@ declare function getElementStyle(element: CanvasElement): ElementStyle;
 
 type RotateDirection = 'cw' | 'ccw';
 
+interface SelectionStyleDetails {
+    common: ElementStyle;
+    applicable: readonly (keyof ElementStyle)[];
+    mixed: readonly (keyof ElementStyle)[];
+}
 type AlignEdge = 'left' | 'center-x' | 'right' | 'top' | 'middle' | 'bottom';
 type DistributeAxis = 'horizontal' | 'vertical';
 
@@ -637,6 +644,11 @@ declare class Viewport {
     private minimap;
     private readonly htmlRenderers;
     private readonly resizeListeners;
+    private readonly selectionListeners;
+    private detachSelectionSource;
+    private unsubToolRegister;
+    private pendingSelectionPrune;
+    private unsubRecorderEnd;
     constructor(container: HTMLElement, options?: ViewportOptions);
     get ctx(): CanvasRenderingContext2D | null;
     get snapToGrid(): boolean;
@@ -646,6 +658,18 @@ declare class Viewport {
     fitToContent(padding?: number): void;
     /** World-space rectangle currently visible through the canvas. */
     getVisibleRect(): Bounds;
+    /**
+     * Size in CSS pixels of the canvas that `getVisibleRect()` measures.
+     * Exposed because `canvasEl` is private: consumers can only reach the
+     * wrapper (via `domLayer.parentElement`), so without this accessor the
+     * canonical size behind `getVisibleRect()` is unreachable and callers
+     * resort to `getVisibleRect().w * camera.zoom`. Capture and restore must
+     * measure the same element or saved views do not round-trip.
+     */
+    getCanvasSize(): {
+        w: number;
+        h: number;
+    };
     /** Centers the camera on a world point without changing zoom. */
     centerCameraAt(world: Point): void;
     /**
@@ -730,12 +754,34 @@ declare class Viewport {
     getGridInfo(): GridInfo | null;
     onGridChange(listener: (info: GridInfo | null) => void): () => void;
     private getSelectTool;
+    private pruneSelection;
+    private handleRemovedElement;
+    private static isSelectionSource;
+    private emitSelectionChange;
+    private attachSelectionSource;
+    /**
+     * getSelectedIds() and the onSelectionChange emitter never surface stale ids:
+     * once the enclosing history transaction completes, both reflect
+     * the current selection.
+     */
     getSelectedIds(): string[];
     runAction(action: string): void;
     canPaste(): boolean;
     openContextMenu(screenPos: Point): void;
+    /**
+     * Persistent, viewport-owned selection-change emitter. Subscribing works
+     * regardless of whether a select tool is registered yet; it forwards
+     * events from whichever select tool is currently attached via
+     * `toolManager.onRegister`. Never delivers stale ids once the enclosing
+     * history transaction completes.
+     */
     onSelectionChange(listener: () => void): () => void;
     getSelectionStyle(): ElementStyle | null;
+    /**
+     * Unlike `getSelectionStyle()` — which returns `{}` for a style-less
+     * selection — this returns `null` when no style field is applicable.
+     */
+    getSelectionStyleDetails(): SelectionStyleDetails | null;
     applyStyleToSelection(style: ElementStyle): void;
     groupSelection(): void;
     ungroupSelection(): void;
@@ -1350,6 +1396,201 @@ 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
+ * canvas state, or durable operations. A frame that arrives while a client is
+ * offline is dropped, never queued, and late joiners are never retro-focused.
+ *
+ * `audience` is a delivery hint, NOT a security boundary: the relay broadcasts
+ * presence room-wide and receivers filter by their own role. The payload is a
+ * map rectangle, not secret data; hidden elements stay behind relay `canRead`.
+ */
+interface FocusPresence {
+    readonly kind: 'focus';
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+    readonly audience: FocusAudience;
+    readonly color?: string;
+}
+type FocusAudience = 'all' | 'players' | 'display';
+declare const FOCUS_PRESENCE_KIND = "focus";
+/**
+ * The only trust boundary between untyped wire data and the canvas. Mirrors
+ * `isPingPresence`: every field is validated, and `color` is rejected when
+ * defined but not a string, because it flows into canvas styling.
+ *
+ * These rules deliberately match `CameraView` validation, so a payload that
+ * passes here can never make the animator's synchronous target validation
+ * throw on the receive path.
+ */
+declare function isFocusPresence(data: unknown): data is FocusPresence;
+/** Builds the presence payload for one local focus request. */
+declare function toFocusPresence(view: CameraView, audience: FocusAudience, color?: string): FocusPresence;
+
+type FocusRole = 'dm' | 'player' | 'display';
+/** The two viewport capabilities the receiver needs; `Viewport` satisfies it. */
+type RemoteFocusReceiverHost = RemotePingOverlayHost;
+interface RemoteFocusReceiverOptions {
+    role: FocusRole;
+    animator: CameraAnimator;
+    /** Draw an arrival pulse at the focus target. Default `true`. */
+    pulse?: boolean;
+    pulseColor?: string;
+    pulseDurationMs?: number;
+    pulseRadius?: number;
+    /** Animate the camera (default) or jump instantly. */
+    animate?: boolean;
+}
+/**
+ * Applies remote focus requests addressed to this client's role: moves the
+ * camera and marks the target with one pulse.
+ *
+ * The pulse is DELEGATED to a private `RemotePingOverlay` rather than
+ * reimplemented. `renderPingPulse` draws a single frame from an elapsed time,
+ * so an animated pulse needs a rAF loop that re-requests renders, expires the
+ * pulse, and cancels on disposal — machinery that already exists and is tested
+ * there. `maxPingsPerSender: 1` makes a rapid second focus REPLACE the older
+ * pulse instead of leaving two competing markers; different senders keep
+ * separate keys and coexist, which is correct when two DMs share a table.
+ */
+declare class RemoteFocusReceiver {
+    private readonly role;
+    private readonly animator;
+    private readonly animate;
+    private readonly pulseColor;
+    private readonly overlay;
+    private disposed;
+    constructor(host: RemoteFocusReceiverHost, options: RemoteFocusReceiverOptions);
+    /**
+     * Applies a presence payload from `sender`. Returns `false` for payloads
+     * that are not focus frames, or are addressed to a different role, so hosts
+     * can feed every presence frame through without disturbing other handlers.
+     */
+    apply(from: string, data: unknown): boolean;
+    /** Idempotent. Does NOT dispose the animator — the host owns that. */
+    dispose(): void;
+}
+
 interface ActiveFormats {
     bold: boolean;
     italic: boolean;
@@ -1755,6 +1996,6 @@ declare class TemplateTool implements Tool {
     private notifyOptionsChange;
 }
 
-declare const VERSION = "0.59.0";
+declare const VERSION = "0.61.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 CameraChangeInfo, type CameraOptions, 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, type FontSizePreset, 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, RemoteLaserOverlay, type RemoteLaserOverlayHost, type RemoteLaserOverlayOptions, RemoteMeasureOverlay, type RemoteMeasureOverlayHost, type RemoteMeasureOverlayOptions, RemotePingOverlay, type RemotePingOverlayHost, type RemotePingOverlayOptions, type RenderStatsSnapshot, type RotateDirection, SelectTool, 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, boundsIntersect, createArrow, createGrid, createHtmlElement, createImage, createNote, createShape, createStroke, createTemplate, createText, drawHexPath, exportImage, exportSvg, getActiveFormats, getArrowBounds, getArrowControlPoint, getArrowMidpoint, getArrowTangentAngle, getBendFromPoint, getElementBounds, getElementStyle, getElementsBoundingBox, getHexCellsInCone, getHexCellsInLine, getHexCellsInRadius, getHexCellsInRectangle, getHexCellsInSquare, getHexDistance, isLaserTrailPresence, isMeasurePresence, isNearBezier, isPingPresence, setFontSize, smartSnap, snapPoint, snapToHexCenter, styleToPatch, toLaserTrailPresence, toMeasurePresence, toPingPresence, toggleBold, toggleItalic, toggleStrikethrough, toggleUnderline };
+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 };

package/dist/index.d.ts

@@ -410,6 +410,7 @@ declare class ToolManager {
     private tools;
     private current;
     private changeListeners;
+    private registerListeners;
     get activeTool(): Tool | null;
     get toolNames(): string[];
     register(tool: Tool): void;
@@ -419,6 +420,7 @@ declare class ToolManager {
     handlePointerMove(state: PointerState, ctx: ToolContext): void;
     handlePointerUp(state: PointerState, ctx: ToolContext): void;
     onChange(listener: (name: string) => void): () => void;
+    onRegister(listener: (tool: Tool) => void): () => void;
 }
 
 interface Command {
@@ -558,6 +560,11 @@ declare function getElementStyle(element: CanvasElement): ElementStyle;
 
 type RotateDirection = 'cw' | 'ccw';
 
+interface SelectionStyleDetails {
+    common: ElementStyle;
+    applicable: readonly (keyof ElementStyle)[];
+    mixed: readonly (keyof ElementStyle)[];
+}
 type AlignEdge = 'left' | 'center-x' | 'right' | 'top' | 'middle' | 'bottom';
 type DistributeAxis = 'horizontal' | 'vertical';
 
@@ -637,6 +644,11 @@ declare class Viewport {
     private minimap;
     private readonly htmlRenderers;
     private readonly resizeListeners;
+    private readonly selectionListeners;
+    private detachSelectionSource;
+    private unsubToolRegister;
+    private pendingSelectionPrune;
+    private unsubRecorderEnd;
     constructor(container: HTMLElement, options?: ViewportOptions);
     get ctx(): CanvasRenderingContext2D | null;
     get snapToGrid(): boolean;
@@ -646,6 +658,18 @@ declare class Viewport {
     fitToContent(padding?: number): void;
     /** World-space rectangle currently visible through the canvas. */
     getVisibleRect(): Bounds;
+    /**
+     * Size in CSS pixels of the canvas that `getVisibleRect()` measures.
+     * Exposed because `canvasEl` is private: consumers can only reach the
+     * wrapper (via `domLayer.parentElement`), so without this accessor the
+     * canonical size behind `getVisibleRect()` is unreachable and callers
+     * resort to `getVisibleRect().w * camera.zoom`. Capture and restore must
+     * measure the same element or saved views do not round-trip.
+     */
+    getCanvasSize(): {
+        w: number;
+        h: number;
+    };
     /** Centers the camera on a world point without changing zoom. */
     centerCameraAt(world: Point): void;
     /**
@@ -730,12 +754,34 @@ declare class Viewport {
     getGridInfo(): GridInfo | null;
     onGridChange(listener: (info: GridInfo | null) => void): () => void;
     private getSelectTool;
+    private pruneSelection;
+    private handleRemovedElement;
+    private static isSelectionSource;
+    private emitSelectionChange;
+    private attachSelectionSource;
+    /**
+     * getSelectedIds() and the onSelectionChange emitter never surface stale ids:
+     * once the enclosing history transaction completes, both reflect
+     * the current selection.
+     */
     getSelectedIds(): string[];
     runAction(action: string): void;
     canPaste(): boolean;
     openContextMenu(screenPos: Point): void;
+    /**
+     * Persistent, viewport-owned selection-change emitter. Subscribing works
+     * regardless of whether a select tool is registered yet; it forwards
+     * events from whichever select tool is currently attached via
+     * `toolManager.onRegister`. Never delivers stale ids once the enclosing
+     * history transaction completes.
+     */
     onSelectionChange(listener: () => void): () => void;
     getSelectionStyle(): ElementStyle | null;
+    /**
+     * Unlike `getSelectionStyle()` — which returns `{}` for a style-less
+     * selection — this returns `null` when no style field is applicable.
+     */
+    getSelectionStyleDetails(): SelectionStyleDetails | null;
     applyStyleToSelection(style: ElementStyle): void;
     groupSelection(): void;
     ungroupSelection(): void;
@@ -1350,6 +1396,201 @@ 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
+ * canvas state, or durable operations. A frame that arrives while a client is
+ * offline is dropped, never queued, and late joiners are never retro-focused.
+ *
+ * `audience` is a delivery hint, NOT a security boundary: the relay broadcasts
+ * presence room-wide and receivers filter by their own role. The payload is a
+ * map rectangle, not secret data; hidden elements stay behind relay `canRead`.
+ */
+interface FocusPresence {
+    readonly kind: 'focus';
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+    readonly audience: FocusAudience;
+    readonly color?: string;
+}
+type FocusAudience = 'all' | 'players' | 'display';
+declare const FOCUS_PRESENCE_KIND = "focus";
+/**
+ * The only trust boundary between untyped wire data and the canvas. Mirrors
+ * `isPingPresence`: every field is validated, and `color` is rejected when
+ * defined but not a string, because it flows into canvas styling.
+ *
+ * These rules deliberately match `CameraView` validation, so a payload that
+ * passes here can never make the animator's synchronous target validation
+ * throw on the receive path.
+ */
+declare function isFocusPresence(data: unknown): data is FocusPresence;
+/** Builds the presence payload for one local focus request. */
+declare function toFocusPresence(view: CameraView, audience: FocusAudience, color?: string): FocusPresence;
+
+type FocusRole = 'dm' | 'player' | 'display';
+/** The two viewport capabilities the receiver needs; `Viewport` satisfies it. */
+type RemoteFocusReceiverHost = RemotePingOverlayHost;
+interface RemoteFocusReceiverOptions {
+    role: FocusRole;
+    animator: CameraAnimator;
+    /** Draw an arrival pulse at the focus target. Default `true`. */
+    pulse?: boolean;
+    pulseColor?: string;
+    pulseDurationMs?: number;
+    pulseRadius?: number;
+    /** Animate the camera (default) or jump instantly. */
+    animate?: boolean;
+}
+/**
+ * Applies remote focus requests addressed to this client's role: moves the
+ * camera and marks the target with one pulse.
+ *
+ * The pulse is DELEGATED to a private `RemotePingOverlay` rather than
+ * reimplemented. `renderPingPulse` draws a single frame from an elapsed time,
+ * so an animated pulse needs a rAF loop that re-requests renders, expires the
+ * pulse, and cancels on disposal — machinery that already exists and is tested
+ * there. `maxPingsPerSender: 1` makes a rapid second focus REPLACE the older
+ * pulse instead of leaving two competing markers; different senders keep
+ * separate keys and coexist, which is correct when two DMs share a table.
+ */
+declare class RemoteFocusReceiver {
+    private readonly role;
+    private readonly animator;
+    private readonly animate;
+    private readonly pulseColor;
+    private readonly overlay;
+    private disposed;
+    constructor(host: RemoteFocusReceiverHost, options: RemoteFocusReceiverOptions);
+    /**
+     * Applies a presence payload from `sender`. Returns `false` for payloads
+     * that are not focus frames, or are addressed to a different role, so hosts
+     * can feed every presence frame through without disturbing other handlers.
+     */
+    apply(from: string, data: unknown): boolean;
+    /** Idempotent. Does NOT dispose the animator — the host owns that. */
+    dispose(): void;
+}
+
 interface ActiveFormats {
     bold: boolean;
     italic: boolean;
@@ -1755,6 +1996,6 @@ declare class TemplateTool implements Tool {
     private notifyOptionsChange;
 }
 
-declare const VERSION = "0.59.0";
+declare const VERSION = "0.61.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 CameraChangeInfo, type CameraOptions, 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, type FontSizePreset, 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, RemoteLaserOverlay, type RemoteLaserOverlayHost, type RemoteLaserOverlayOptions, RemoteMeasureOverlay, type RemoteMeasureOverlayHost, type RemoteMeasureOverlayOptions, RemotePingOverlay, type RemotePingOverlayHost, type RemotePingOverlayOptions, type RenderStatsSnapshot, type RotateDirection, SelectTool, 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, boundsIntersect, createArrow, createGrid, createHtmlElement, createImage, createNote, createShape, createStroke, createTemplate, createText, drawHexPath, exportImage, exportSvg, getActiveFormats, getArrowBounds, getArrowControlPoint, getArrowMidpoint, getArrowTangentAngle, getBendFromPoint, getElementBounds, getElementStyle, getElementsBoundingBox, getHexCellsInCone, getHexCellsInLine, getHexCellsInRadius, getHexCellsInRectangle, getHexCellsInSquare, getHexDistance, isLaserTrailPresence, isMeasurePresence, isNearBezier, isPingPresence, setFontSize, smartSnap, snapPoint, snapToHexCenter, styleToPatch, toLaserTrailPresence, toMeasurePresence, toPingPresence, toggleBold, toggleItalic, toggleStrikethrough, toggleUnderline };
+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 };