@fieldnotes/core 0.64.0 → 0.66.0

package/dist/index.d.cts

@@ -267,7 +267,7 @@ interface Tool {
     setOptions?(options: object): void;
     onOptionsChange?(listener: () => void): () => void;
 }
-type ToolName = 'hand' | 'select' | 'pencil' | 'eraser' | 'arrow' | 'note' | 'image' | 'text' | 'shape' | 'measure' | 'path' | 'template' | 'laser' | 'ping';
+type ToolName = 'hand' | 'select' | 'pencil' | 'eraser' | 'arrow' | 'note' | 'image' | 'text' | 'shape' | 'measure' | 'path' | 'template' | 'laser' | 'ping' | 'fog';
 
 declare function snapPoint(point: Point, gridSize: number): Point;
 declare function snapToHexCenter(point: Point, cellSize: number, orientation: HexOrientation): Point;
@@ -341,6 +341,61 @@ interface Layer {
     opacity: number;
 }
 
+declare const FOG_STATE_VERSION = 1;
+declare const FOG_TILE_CELLS = 128;
+declare const FOG_MAX_TILES = 256;
+type FogBase = 'covered' | 'revealed';
+interface FogDefinitionV1 {
+    readonly version: 1;
+    readonly generation: string;
+    readonly bounds: Bounds;
+    readonly cellSize: number;
+    readonly tileCells: 128;
+    readonly base: FogBase;
+}
+interface FogTileV1 {
+    readonly x: number;
+    readonly y: number;
+    readonly data: string;
+}
+interface FogStateV1 {
+    readonly definition: FogDefinitionV1;
+    readonly tiles: readonly FogTileV1[];
+}
+type FogViewMode = 'off' | 'editor' | 'player';
+type FogOperation = 'reveal' | 'conceal';
+type FogRegion = {
+    kind: 'brush';
+    points: readonly Point[];
+    radius: number;
+} | {
+    kind: 'rectangle';
+    from: Point;
+    to: Point;
+} | {
+    kind: 'polygon';
+    points: readonly Point[];
+};
+interface FogToolOptions {
+    operation?: FogOperation;
+    shape?: 'brush' | 'rectangle' | 'polygon';
+    radius?: number;
+}
+interface FogPatch {
+    readonly tiles: readonly FogTileV1[];
+}
+interface FogChangeEvent {
+    readonly kind: 'tiles' | 'definition' | 'reset' | 'disable';
+    readonly tiles?: readonly {
+        readonly x: number;
+        readonly y: number;
+    }[];
+    readonly origin?: string;
+}
+interface FogViewEvent {
+    readonly mode: FogViewMode;
+}
+
 interface CanvasState {
     version: number;
     camera: {
@@ -350,6 +405,7 @@ interface CanvasState {
     elements: CanvasElement[];
     layers?: Layer[];
     activeLayerId?: string;
+    fog?: FogStateV1;
 }
 
 interface LayerManagerEvents {
@@ -392,6 +448,55 @@ declare class LayerManager {
     private findFallbackLayer;
 }
 
+interface Command {
+    execute(store: ElementStore): void;
+    undo(store: ElementStore): void;
+}
+
+type FogIdFactory = () => string;
+interface FogManagerOptions {
+    idFactory?: FogIdFactory;
+    onCommand?: (command: Command) => void;
+}
+type ChangeListener = (event: FogChangeEvent) => void;
+type ViewListener = (event: FogViewEvent) => void;
+declare class FogManager {
+    private state;
+    private viewMode;
+    private readonly idFactory;
+    private readonly onCommand;
+    private readonly changeListeners;
+    private readonly viewListeners;
+    constructor(options?: FogManagerOptions);
+    getState(): FogStateV1 | null;
+    getViewMode(): FogViewMode;
+    initialize(options: {
+        bounds: Bounds;
+        base?: FogBase;
+        cellSize?: number;
+    }): FogStateV1;
+    loadState(state: FogStateV1 | null, meta?: {
+        origin?: string;
+    }): void;
+    /** Restores a historical visual state without reusing its causal generation id. */
+    restoreHistoryState(state: FogStateV1 | null): void;
+    setBounds(bounds: Bounds): void;
+    reset(base: FogBase): void;
+    disable(): void;
+    setViewMode(mode: FogViewMode): void;
+    applyRegion(region: FogRegion, operation: FogOperation): void;
+    applyPatchDirect(patch: FogPatch, meta?: {
+        origin?: string;
+    }): void;
+    applyTilesDirect(tiles: readonly FogTileV1[]): void;
+    on(event: 'change', listener: ChangeListener): () => void;
+    on(event: 'view', listener: ViewListener): () => void;
+    dispose(): void;
+    private collectTiles;
+    private notifyChange;
+    private notifyView;
+}
+
 interface StorageAdapter {
     load(key: string): Promise<string | null>;
     save(key: string, value: string): Promise<void>;
@@ -402,6 +507,7 @@ interface AutoSaveOptions {
     key?: string;
     debounceMs?: number;
     layerManager?: LayerManager;
+    fogManager?: FogManager;
     adapter?: StorageAdapter;
     onError?: (error: Error) => void;
 }
@@ -411,6 +517,7 @@ declare class AutoSave {
     private readonly key;
     private readonly debounceMs;
     private readonly layerManager?;
+    private readonly fogManager?;
     private readonly adapter;
     private timerId;
     private unsubscribers;
@@ -502,11 +609,6 @@ declare class ToolManager {
     onRegister(listener: (tool: Tool) => void): () => void;
 }
 
-interface Command {
-    execute(store: ElementStore): void;
-    undo(store: ElementStore): void;
-}
-
 interface HistoryStackOptions {
     maxSize?: number;
 }
@@ -635,6 +737,11 @@ interface ExportImageOptions extends ExportResourceOptions, HtmlExportOptions {
      * a non-fatal `'unsupported'` diagnostic regardless of this flag.
      */
     strictMissingCanvasHtml?: boolean;
+    fog?: {
+        state: FogStateV1;
+        mode: 'editor' | 'player';
+        color?: string;
+    } | false;
 }
 type ExportAssetErrorReason = 'load' | 'timeout' | 'encode';
 interface ExportAssetError {
@@ -660,20 +767,14 @@ 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;
+    fog?: {
+        state: FogStateV1;
+        mode: 'editor' | 'player';
+        color?: string;
+    } | false;
 }
 declare function exportSvg(store: ElementStore, options?: ExportSvgOptions, layerManager?: LayerManager): Promise<string>;
 
@@ -699,6 +800,33 @@ interface RenderStatsSnapshot {
     frameCount: number;
 }
 
+interface FogRendererOptions {
+    editorColor?: string;
+    playerColor?: string;
+}
+declare class FogRenderer {
+    private tileCache;
+    private state;
+    private viewMode;
+    private dirty;
+    private editorColor;
+    private playerColor;
+    constructor(options?: FogRendererOptions);
+    setState(state: FogStateV1 | null): void;
+    setViewMode(mode: FogViewMode): void;
+    getState(): FogStateV1 | null;
+    getViewMode(): FogViewMode;
+    markDirty(): void;
+    isDirty(): boolean;
+    isVisible(): boolean;
+    render(ctx: CanvasRenderingContext2D, camera: Camera, viewportWidth: number, viewportHeight: number, _dpr: number): void;
+    renderForExport(ctx: CanvasRenderingContext2D, state: FogStateV1, mode: 'editor' | 'player', color?: string): void;
+    dispose(): void;
+    private tileRaster;
+    private renderTile;
+    private renderTileForExport;
+}
+
 /**
  * A world-space draw callback rendered above elements on every frame,
  * regardless of which tool is active. The context arrives with the camera
@@ -789,6 +917,11 @@ interface ViewportOptions {
     panInertia?: boolean;
     /** Show an overview minimap (bottom-right) with tap/drag-to-navigate. Default `false`. */
     minimap?: boolean;
+    /** Fog-of-war presentation options. Enables fog rendering and the `fog` accessor. */
+    fog?: {
+        editorColor?: string;
+        playerColor?: string;
+    };
 }
 interface HitTestOptions {
     /** Skip elements on locked layers. Default `true` (selection semantics). */
@@ -825,6 +958,8 @@ declare class Viewport {
     private _smartGuides;
     private readonly _gridSize;
     private readonly renderLoop;
+    private readonly fogManager;
+    private readonly fogRenderer;
     private readonly domNodeManager;
     private readonly interactMode;
     private readonly onHtmlElementMount?;
@@ -850,6 +985,7 @@ declare class Viewport {
     private unsubRecorderEnd;
     constructor(container: HTMLElement, options?: ViewportOptions);
     get ctx(): CanvasRenderingContext2D | null;
+    get fog(): FogManager;
     get snapToGrid(): boolean;
     setSnapToGrid(enabled: boolean): void;
     get smartGuides(): boolean;
@@ -2087,6 +2223,8 @@ declare class MinimapController {
     private readonly renderer;
     private readonly htmlPainters;
     private scene;
+    private fogRenderer;
+    private fogUnsub;
     private frameId;
     private debounceTimer;
     private dragging;
@@ -2094,6 +2232,7 @@ declare class MinimapController {
     private readonly unsubs;
     constructor(viewport: Viewport, canvas: HTMLCanvasElement, options?: MinimapControllerOptions);
     setSize(width: number, height: number): void;
+    setFogRenderer(renderer: FogRenderer | null): void;
     requestDraw(): void;
     /**
      * Invalidates the cached scene bitmap in response to html-painter registry
@@ -2205,6 +2344,434 @@ declare class RemoteFocusReceiver {
     dispose(): void;
 }
 
+/**
+ * Sender identity carried on every awareness frame. `id` is the app's stable
+ * peer id (a character id, a user id); `name`, `color`, and `role` are
+ * self-asserted display data. Receivers MUST treat `name` as untrusted text
+ * (render through canvas text or `textContent`, never as HTML) and MUST NOT
+ * gate anything security-relevant on any of these fields — the relay does not
+ * authenticate presence payloads.
+ */
+interface AwarenessIdentity {
+    readonly id: string;
+    readonly name?: string;
+    readonly color?: string;
+    readonly role?: string;
+}
+/**
+ * The wire shape of one awareness frame. Every frame is the sender's COMPLETE
+ * state (identity + whatever it publishes), so any coalescer that keeps only
+ * the newest frame — the relay's per-kind throttle lane, a slow consumer — is
+ * correct by construction: latest wins. Absent fields mean "none / not
+ * published"; there is no delta encoding. A `cleared` frame says the sender is
+ * going away (receivers drop it now instead of waiting for stale expiry).
+ * Presence only: never elements, undo history, persisted canvas state, or
+ * durable operations.
+ */
+interface AwarenessPresence extends AwarenessIdentity {
+    readonly kind: 'awareness';
+    /** World-space pointer position; absent = no cursor to show. */
+    readonly cursor?: Point;
+    /** Selected element ids the sender chose to publish; absent = none. */
+    readonly selection?: readonly string[];
+    /** Active tool name; absent = not published. */
+    readonly tool?: string;
+    readonly cleared?: true;
+}
+declare const AWARENESS_PRESENCE_KIND = "awareness";
+/** Cap on `selection` entries; longer payloads are rejected outright. */
+declare const AWARENESS_MAX_SELECTION = 256;
+/**
+ * Wire-boundary guard, fail closed: any violated cap rejects the whole frame
+ * (nothing is clamped or sanitised). Unknown extra fields are tolerated so a
+ * newer sender can add fields without breaking older receivers. `cleared`,
+ * when present, must be exactly `true`; `cleared: false` rejects the whole
+ * frame.
+ */
+declare function isAwarenessPresence(data: unknown): data is AwarenessPresence;
+
+/** One remote peer as last seen. Liveness timestamps are deliberately not exposed. */
+interface Peer extends AwarenessIdentity {
+    /** The relay's server-owned per-socket sender key (the envelope `from`). */
+    readonly from: string;
+    readonly cursor: Point | null;
+    readonly selection: readonly string[];
+    readonly tool: string | null;
+}
+type PeerLeaveReason = 'left' | 'cleared' | 'stale';
+interface PeerRosterOptions {
+    /**
+     * A sender with no valid frame for this long is dropped (row and discovery
+     * entry) with reason `'stale'`. Default `45000` (3× the publisher heartbeat);
+     * `0` disables expiry.
+     */
+    staleMs?: number;
+    /** Clock seam for tests; default `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Last-known awareness state per remote sender, keyed by the relay's
+ * server-owned `from`. Two books are kept deliberately separate:
+ *
+ * - **Rows** are visible membership: created by any valid non-cleared frame,
+ *   removed by a `cleared` frame, by `remove()` (the server-authored
+ *   presence-leave), or by stale expiry.
+ * - **Discovery entries** are the re-announce budget: touched by EVERY valid
+ *   frame (cleared included) and dropped ONLY by `remove()` or by `staleMs`
+ *   without any valid frame. `onDiscover` fires when a valid frame arrives from
+ *   a sender with no entry — at most once per socket lifetime, so a client
+ *   cycling full → cleared → full cannot make every peer re-announce.
+ *
+ * `getPeers()` returns the same array until a visible field or membership
+ * changes (a heartbeat carrying identical state is silent), which makes it a
+ * valid `useSyncExternalStore` snapshot. Remote clocks are never trusted; all
+ * timing is local.
+ */
+declare class PeerRoster {
+    private readonly staleMs;
+    private readonly now;
+    private readonly rows;
+    private readonly discovered;
+    private readonly changeListeners;
+    private readonly discoverListeners;
+    private readonly leaveListeners;
+    private snapshot;
+    private snapshotDirty;
+    private staleTimer;
+    private isDisposed;
+    constructor(options?: PeerRosterOptions);
+    get disposed(): boolean;
+    /**
+     * Applies a presence payload from `from`. Non-awareness or malformed payloads
+     * return `false` untouched, so hosts can feed every presence frame through.
+     */
+    apply(from: string, data: unknown): boolean;
+    /** Server-authored presence-leave: drops the row AND the discovery entry. */
+    remove(from: string): void;
+    getPeers(): readonly Peer[];
+    getPeer(from: string): Peer | undefined;
+    /** Fires only when `getPeers()` would return a new reference. */
+    onChange(listener: () => void): () => void;
+    /** First valid frame from a sender since its discovery entry was last dropped. */
+    onDiscover(listener: (from: string) => void): () => void;
+    onLeave(listener: (peer: Peer, reason: PeerLeaveReason) => void): () => void;
+    dispose(): void;
+    private dropRow;
+    private changed;
+    private emit;
+    private armStaleTimer;
+    private expireStale;
+}
+
+/** The viewport capabilities the publisher reads; `Viewport` satisfies it. */
+interface LocalAwarenessHost {
+    readonly camera: {
+        screenToWorld(screen: Point): Point;
+    };
+    /** The pointer listener attaches to `domLayer.parentElement` (the wrapper). */
+    readonly domLayer: HTMLElement;
+    onSelectionChange(listener: () => void): () => void;
+    getSelectedIds(): string[];
+    readonly toolManager: {
+        onChange(listener: (name: string) => void): () => void;
+        readonly activeTool: {
+            readonly name: string;
+        } | null;
+    };
+}
+interface AwarenessFields {
+    cursor?: boolean;
+    /** Off by default: selection ids are a disclosure the moment they are sent. */
+    selection?: boolean;
+    tool?: boolean;
+}
+interface LocalAwarenessOptions {
+    identity: AwarenessIdentity;
+    /** Default `{ cursor: true, selection: false, tool: true }`. */
+    fields?: AwarenessFields;
+    /**
+     * Host projection applied to selected ids before they leave the client.
+     * Fails closed: if it throws or returns anything but an array of strings,
+     * frames carry NO selection (never the unfiltered ids) until it next
+     * succeeds, and the error goes to `onError`.
+     */
+    selectionFilter?: (ids: readonly string[]) => readonly string[];
+    onError?: (error: unknown) => void;
+    /** Minimum spacing between frames. Default `50` (the relay lane throttle). */
+    intervalMs?: number;
+    /** Full-state re-send while idle, measured from the last send. Default `15000`; `0` disables. */
+    heartbeatMs?: number;
+    /** Pointer listener target override; default `host.domLayer.parentElement`. */
+    element?: HTMLElement;
+    send: (data: AwarenessPresence) => void;
+}
+/**
+ * Publishes this client's awareness state (identity, pointer in world space,
+ * selection, active tool) as full-snapshot frames through `send`. Sources are
+ * a passive primary-pointer listener on the viewport wrapper, the viewport's
+ * selection-change event, and the tool manager's change event. Any change
+ * marks the state dirty; a leading-edge frame goes out at once when idle,
+ * otherwise one trailing frame per `intervalMs` carries every change made in
+ * the window. A heartbeat re-sends the state while idle. `dispose` sends one
+ * `cleared` frame. Nothing here touches elements, history, or the camera.
+ *
+ * Frames are valid by construction: identity is truncated to the wire caps
+ * (`name`/`color` to 64 characters, `role` to 32) so a sender can never
+ * publish a frame the wire guard would reject outright; truncation is
+ * reported through `onError` (a `RangeError`) rather than silent. An
+ * invalid `id` (empty or over 128 characters) throws instead of truncating.
+ * `tool` is never truncated: a tool name over 64 characters is omitted from
+ * the frame rather than corrupted. An over-long or empty selection id fails
+ * the selection closed (like a non-string filter entry) rather than being
+ * sent. `intervalMs` and `heartbeatMs` are normalised so a non-finite or
+ * out-of-range value (e.g. `Infinity`) can never arm a near-zero busy-loop
+ * timer. The selection filter is re-applied before every frame that carries
+ * a selection, so a policy change takes effect on the next frame without a
+ * selection event.
+ */
+declare class LocalAwareness {
+    private readonly host;
+    private readonly element;
+    private readonly send;
+    private readonly selectionFilter;
+    private readonly onError;
+    private readonly intervalMs;
+    private readonly heartbeatMs;
+    private identity;
+    private fields;
+    private lastPointer;
+    private selection;
+    private selectionFailed;
+    private tool;
+    private dirty;
+    private lastSentAt;
+    private throttleTimer;
+    private heartbeatTimer;
+    private readonly unsubscribers;
+    private isDisposed;
+    private readonly handlePointerMove;
+    private readonly handlePointerEnd;
+    constructor(host: LocalAwarenessHost, options: LocalAwarenessOptions);
+    get disposed(): boolean;
+    getFields(): Readonly<Required<AwarenessFields>>;
+    setIdentity(identity: AwarenessIdentity): void;
+    /** Merges the given flags into the current policy; `undefined` keys are ignored. */
+    setFields(fields: AwarenessFields): void;
+    /**
+     * Requests a full frame: immediate when idle, otherwise folded into the
+     * pending trailing frame (so N simultaneous requests cost one frame). Hosts
+     * call it when the connection becomes live or reconnects.
+     */
+    announce(): void;
+    /**
+     * The complete state a frame carries right now. Side-effecting when
+     * selection publishing is on: re-reads `getSelectedIds()`, re-runs
+     * `selectionFilter`, updates the fail-closed selection state, and may call
+     * `onError`. A no-op with respect to selection while publishing is off.
+     */
+    getState(): AwarenessPresence;
+    dispose(): void;
+    private now;
+    private onPointerMove;
+    private onPointerEnd;
+    private refreshSelection;
+    private schedule;
+    private flush;
+    private armHeartbeat;
+    private safeSend;
+    private report;
+    /**
+     * Truncates identity strings to the wire caps and rejects an invalid id, so a
+     * sender can never publish a frame that the wire guard would drop outright.
+     * A truncated field is reported through `onError` (a `RangeError`) rather
+     * than silently shortened, so a caller passing an over-long name finds out.
+     */
+    private normalizeIdentity;
+}
+
+/** The viewport capabilities the overlay needs; `Viewport` satisfies it. */
+interface RemoteCursorOverlayHost {
+    registerOverlay(draw: OverlayRenderer): () => void;
+    requestRender(): void;
+    /** Read at draw time so glyph and label keep a constant screen size. */
+    readonly camera: {
+        readonly zoom: number;
+    };
+}
+interface RemoteCursorOverlayOptions {
+    /**
+     * Host colour resolver consulted first (e.g. a campaign's per-player colour
+     * table keyed by `peer.id`). Return `undefined` to fall through to the wire
+     * `color`, then to `defaultPeerColor(peer.id)`.
+     */
+    colorFor?: (peer: Peer) => string | undefined;
+    /** Draw the name chip next to the arrow. Default `true`. */
+    showLabels?: boolean;
+    /** Default `'12px sans-serif'`. */
+    labelFont?: string;
+}
+/** Twelve well-separated hues so peers stay distinguishable without a colour on the wire. */
+declare const PEER_COLORS: readonly string[];
+/**
+ * Deterministic palette colour for a stable peer id (FNV-1a over UTF-16 code
+ * units), so every client shows the same peer in the same colour without any
+ * colour travelling on the wire.
+ */
+declare function defaultPeerColor(seed: string): string;
+/**
+ * Renders every roster peer that has a cursor as an arrow glyph plus a name
+ * chip, in world space but at constant screen size (scaled by `1 / zoom`).
+ * Names are drawn as canvas text, so untrusted display text is inert. Reads
+ * the roster only; never re-parses payloads, never moves the camera, never
+ * touches the store.
+ */
+declare class RemoteCursorOverlay {
+    private readonly host;
+    private readonly roster;
+    private readonly colorFor;
+    private readonly showLabels;
+    private readonly labelFont;
+    private readonly labelWidths;
+    private unregister;
+    private unsubscribe;
+    private isDisposed;
+    constructor(host: RemoteCursorOverlayHost, roster: PeerRoster, options?: RemoteCursorOverlayOptions);
+    get disposed(): boolean;
+    resolveColor(peer: Peer): string;
+    dispose(): void;
+    private render;
+    private drawLabel;
+}
+
+/** The viewport capabilities the overlay needs; `Viewport` satisfies it. */
+interface RemoteSelectionOverlayHost {
+    registerOverlay(draw: OverlayRenderer): () => void;
+    requestRender(): void;
+    readonly camera: {
+        readonly zoom: number;
+    };
+    readonly store: ElementStore;
+    readonly layerManager: LayerManager;
+}
+interface RemoteSelectionOverlayOptions {
+    /** Same precedence as `RemoteCursorOverlay`: resolver → wire colour → `defaultPeerColor`. */
+    colorFor?: (peer: Peer) => string | undefined;
+    /** Outline opacity. Default `0.6`. */
+    alpha?: number;
+    /** Outline width in screen pixels. Default `2`. */
+    lineWidthPx?: number;
+}
+/**
+ * Outlines the elements other peers have selected. Only ids that exist in the
+ * LOCAL store AND sit on a locally visible layer are drawn; this is a
+ * rendering courtesy on top of the sender-side opt-in (`fields.selection`) and
+ * `selectionFilter` — privacy is decided at publish time, not here. The store
+ * is rescanned only when some peer's selection reference or resolved colour
+ * changed, or when the store or layer visibility changed; cursor-only roster
+ * updates never scan. When two peers select the same element, the peer
+ * earlier in `roster.getPeers()` order (insertion order: whoever the roster
+ * saw first) supplies the outline colour for it.
+ */
+declare class RemoteSelectionOverlay {
+    private readonly host;
+    private readonly roster;
+    private readonly colorFor;
+    private readonly alpha;
+    private readonly lineWidthPx;
+    private signatures;
+    private outlines;
+    private storeDirty;
+    private unregister;
+    private readonly unsubscribers;
+    private isDisposed;
+    constructor(host: RemoteSelectionOverlayHost, roster: PeerRoster, options?: RemoteSelectionOverlayOptions);
+    get disposed(): boolean;
+    dispose(): void;
+    private resolveColor;
+    /** Recomputes outlines only when the selection signature or the store/layers changed. */
+    private rebuild;
+    private render;
+}
+
+/**
+ * The three presence primitives every Field Notes transport exposes. The raw
+ * `SyncClient`, `ManagedSyncConnection`, and host wrappers all satisfy it
+ * structurally, so core never depends on `@fieldnotes/sync`. `from` is the
+ * relay's opaque per-sender key.
+ */
+interface PresenceChannel {
+    sendPresence(data: unknown): void;
+    onPresence(handler: (from: string, data: unknown) => void): () => void;
+    onPresenceLeave(handler: (from: string) => void): () => void;
+}
+/**
+ * What `attachAwareness` needs from a viewport; `Viewport` satisfies it.
+ *
+ * This does not `extends LocalAwarenessHost, RemoteCursorOverlayHost,
+ * RemoteSelectionOverlayHost`: those three declare `camera` with different
+ * member sets (`screenToWorld` vs `zoom`), and TypeScript rejects an
+ * interface that extends multiple parents whose same-named property types
+ * are not identical or mutually assignable. Listing the members directly
+ * (with `camera` widened to carry both) keeps `AwarenessViewport`
+ * structurally assignable to all three host types.
+ */
+interface AwarenessViewport {
+    readonly camera: {
+        readonly zoom: number;
+        screenToWorld(screen: Point): Point;
+    };
+    /** The pointer listener attaches to `domLayer.parentElement` (the wrapper). */
+    readonly domLayer: HTMLElement;
+    readonly store: ElementStore;
+    readonly layerManager: LayerManager;
+    onSelectionChange(listener: () => void): () => void;
+    getSelectedIds(): string[];
+    readonly toolManager: {
+        onChange(listener: (name: string) => void): () => void;
+        readonly activeTool: {
+            readonly name: string;
+        } | null;
+    };
+    registerOverlay(draw: OverlayRenderer): () => void;
+    requestRender(): void;
+}
+interface AttachAwarenessOptions extends Omit<LocalAwarenessOptions, 'send'> {
+    roster?: PeerRosterOptions;
+    /** Named cursor overlay options, or `false` to render no cursors. Default on. */
+    cursors?: RemoteCursorOverlayOptions | false;
+    /** Selection outline overlay: options or `true` to enable. Default off. */
+    selections?: RemoteSelectionOverlayOptions | boolean;
+    /**
+     * `false` builds a receive-only attachment (no `LocalAwareness`). Default
+     * `true`. When `false`, `identity` is ignored: there is no publisher to
+     * carry it.
+     */
+    publish?: boolean;
+}
+interface AwarenessHandle {
+    readonly roster: PeerRoster;
+    /** `null` when `publish: false`. */
+    readonly local: LocalAwareness | null;
+    readonly cursors: RemoteCursorOverlay | null;
+    readonly selections: RemoteSelectionOverlay | null;
+    /** Call when the connection becomes live or reconnects. No-op when receive-only. */
+    announce(): void;
+    /** Forwards to `LocalAwareness.setFields` (merge). No-op when receive-only. */
+    setFields(fields: AwarenessFields): void;
+    dispose(): void;
+}
+/**
+ * Binds the awareness lifecycle to a presence channel: incoming frames feed
+ * the roster, presence-leave drops rows and discovery budget, and each newly
+ * discovered sender makes this client re-announce once, coalesced by the
+ * publisher's interval: from a cold start the first discovery goes out on
+ * the leading edge and later ones fold into a single trailing frame, so N
+ * simultaneous joiners cost at most two frames; while already active, one.
+ * Dispose order: publisher (sends `cleared`) → overlays → roster → channel
+ * unsubscribes.
+ */
+declare function attachAwareness(viewport: AwarenessViewport, channel: PresenceChannel, options: AttachAwarenessOptions): AwarenessHandle;
+
 interface ActiveFormats {
     bold: boolean;
     italic: boolean;
@@ -2611,6 +3178,43 @@ declare class TemplateTool implements Tool {
     private notifyOptionsChange;
 }
 
-declare const VERSION = "0.64.0";
+declare function encodeBase64(bytes: Uint8Array): string;
+declare function decodeBase64(str: string): Uint8Array;
+declare function canonicalizeFogTile(tile: FogTileV1, def: FogDefinitionV1): FogTileV1 | null;
+declare function validateFogDefinition(def: unknown): asserts def is FogDefinitionV1;
+declare function validateFogTile(tile: unknown, def: FogDefinitionV1): asserts tile is FogTileV1;
+declare function validateFogState(state: unknown): asserts state is FogStateV1;
+declare function recommendedFogCellSize(bounds: Bounds): number;
+
+declare class FogTool implements Tool {
+    readonly name = "fog";
+    private drawing;
+    private points;
+    private startPoint;
+    private operation;
+    private shape;
+    private radius;
+    private readonly manager;
+    private optionListeners;
+    constructor(manager: FogManager, options?: FogToolOptions);
+    onActivate(ctx: ToolContext): void;
+    onDeactivate(ctx: ToolContext): void;
+    getOptions(): FogToolOptions;
+    setOptions(options: FogToolOptions): void;
+    onOptionsChange(listener: () => void): () => void;
+    onPointerDown(state: PointerState, ctx: ToolContext): void;
+    onPointerMove(state: PointerState, ctx: ToolContext): void;
+    onPointerUp(_state: PointerState, ctx: ToolContext): void;
+    onPointerCancel(_state: PointerState, ctx: ToolContext): void;
+    onKeyDown(event: KeyboardEvent, ctx: ToolContext): boolean;
+    renderOverlay(ctx: CanvasRenderingContext2D): void;
+    private buildRegion;
+    private cancelGesture;
+    private renderBrushPreview;
+    private renderRectanglePreview;
+    private renderPolygonPreview;
+}
+
+declare const VERSION = "0.66.0";
 
-export { type ActivationOptions, type ActiveFormats, type AlignEdge, type ArrowElement, type ArrowStrokeStyle, ArrowTool, type ArrowToolOptions, AutoSave, type AutoSaveOptions, type BackgroundOptions, type BackgroundPattern, type Binding, type Bounds, Camera, type CameraAnimationEndReason, CameraAnimator, type CameraAnimatorOptions, type CameraChangeInfo, type CameraOptions, type CameraView, type CanvasElement, type CanvasState, type Command, DEFAULT_NOTE_FONT_SIZE, type DiagonalRule, 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 Footprint, type FrameScheduler, type GridElement, type GridInfo, type GridMetric, 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, PATH_PRESENCE_KIND, PATH_PRESENCE_MAX_POINTS, PING_PRESENCE_KIND, type PathAnchor, type PathDistance, type PathEmission, type PathPresence, type PathRangeBand, type PathSegment, PathTool, type PathToolOptions, 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, RemotePathOverlay, type RemotePathOverlayHost, type RemotePathOverlayOptions, 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, footprintFromSize, getActiveFormats, getArrowBounds, getArrowControlPoint, getArrowMidpoint, getArrowTangentAngle, getBendFromPoint, getElementBounds, getElementStyle, getElementsBoundingBox, getHexCellsInCone, getHexCellsInLine, getHexCellsInRadius, getHexCellsInRectangle, getHexCellsInSquare, getHexDistance, gridDistanceCells, isFocusPresence, isLaserTrailPresence, isMeasurePresence, isNearBezier, isPathPresence, isPingPresence, pathDistanceCells, resolveHtmlRouting, setFontSize, smartSnap, snapFootprintCenter, snapPoint, snapToCellCenter, snapToHexCenter, styleToPatch, toFocusPresence, toLaserTrailPresence, toMeasurePresence, toPathPresence, toPingPresence, toggleBold, toggleItalic, toggleStrikethrough, toggleUnderline };
+export { AWARENESS_MAX_SELECTION, AWARENESS_PRESENCE_KIND, type ActivationOptions, type ActiveFormats, type AlignEdge, type ArrowElement, type ArrowStrokeStyle, ArrowTool, type ArrowToolOptions, type AttachAwarenessOptions, AutoSave, type AutoSaveOptions, type AwarenessFields, type AwarenessHandle, type AwarenessIdentity, type AwarenessPresence, type AwarenessViewport, 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 DiagonalRule, 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, FOG_MAX_TILES, FOG_STATE_VERSION, FOG_TILE_CELLS, type FocusAudience, type FocusPresence, type FocusRole, type FogBase, type FogChangeEvent, type FogDefinitionV1, type FogIdFactory, FogManager, type FogManagerOptions, type FogOperation, type FogPatch, type FogRegion, FogRenderer, type FogRendererOptions, type FogStateV1, type FogTileV1, FogTool, type FogToolOptions, type FogViewEvent, type FogViewMode, type FontSizePreset, type Footprint, type FrameScheduler, type GridElement, type GridInfo, type GridMetric, 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, LocalAwareness, type LocalAwarenessHost, type LocalAwarenessOptions, LocalStorageAdapter, MEASURE_PRESENCE_KIND, type MeasureEmission, type MeasurePresence, MeasureTool, type MeasureToolOptions, type Measurement, MemoryAdapter, MinimapController, type MinimapControllerOptions, type NoteElement, NoteTool, type NoteToolOptions, type OverlayRenderer, PATH_PRESENCE_KIND, PATH_PRESENCE_MAX_POINTS, PEER_COLORS, PING_PRESENCE_KIND, type PathAnchor, type PathDistance, type PathEmission, type PathPresence, type PathRangeBand, type PathSegment, PathTool, type PathToolOptions, type Peer, type PeerLeaveReason, PeerRoster, type PeerRosterOptions, PencilTool, type PencilToolOptions, type PingEmission, PingInput, type PingInputHost, type PingInputOptions, type PingPresence, PingTool, type PingToolOptions, type Point, type PointerState, type PresenceChannel, type RectTrackerHost, RemoteCursorOverlay, type RemoteCursorOverlayHost, type RemoteCursorOverlayOptions, RemoteFocusReceiver, type RemoteFocusReceiverHost, type RemoteFocusReceiverOptions, RemoteLaserOverlay, type RemoteLaserOverlayHost, type RemoteLaserOverlayOptions, RemoteMeasureOverlay, type RemoteMeasureOverlayHost, type RemoteMeasureOverlayOptions, RemotePathOverlay, type RemotePathOverlayHost, type RemotePathOverlayOptions, RemotePingOverlay, type RemotePingOverlayHost, type RemotePingOverlayOptions, RemoteSelectionOverlay, type RemoteSelectionOverlayHost, type RemoteSelectionOverlayOptions, 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, attachAwareness, boundsIntersect, cameraOriginForView, canonicalizeFogTile, captureCameraView, computeElementRects, createArrow, createGrid, createHtmlElement, createImage, createNote, createShape, createStroke, createTemplate, createText, defaultPeerColor, drawHexPath, elementRectsEqual, exportImage, exportSvg, fitZoomForView, decodeBase64 as fogDecodeBase64, encodeBase64 as fogEncodeBase64, footprintFromSize, getActiveFormats, getArrowBounds, getArrowControlPoint, getArrowMidpoint, getArrowTangentAngle, getBendFromPoint, getElementBounds, getElementStyle, getElementsBoundingBox, getHexCellsInCone, getHexCellsInLine, getHexCellsInRadius, getHexCellsInRectangle, getHexCellsInSquare, getHexDistance, gridDistanceCells, isAwarenessPresence, isFocusPresence, isLaserTrailPresence, isMeasurePresence, isNearBezier, isPathPresence, isPingPresence, pathDistanceCells, recommendedFogCellSize, resolveHtmlRouting, setFontSize, smartSnap, snapFootprintCenter, snapPoint, snapToCellCenter, snapToHexCenter, styleToPatch, toFocusPresence, toLaserTrailPresence, toMeasurePresence, toPathPresence, toPingPresence, toggleBold, toggleItalic, toggleStrikethrough, toggleUnderline, validateFogDefinition, validateFogState, validateFogTile };