@fieldnotes/core 0.63.0 → 0.65.0

package/dist/index.d.cts

@@ -241,7 +241,25 @@ interface Tool {
     onPointerDown(state: PointerState, ctx: ToolContext): void;
     onPointerMove(state: PointerState, ctx: ToolContext): void;
     onPointerUp(state: PointerState, ctx: ToolContext): void;
+    /**
+     * The gesture was taken over (a second pointer started navigation) or the
+     * platform cancelled the pointer. Optional: tools without it receive
+     * `onPointerUp` instead, exactly as before. Implement it when "up" and
+     * "abandon" must differ (a multi-step tool must not treat a pinch as input).
+     * The gesture's history transaction is still committed afterwards (an
+     * in-progress store mutation must never be left open); a tool that wants
+     * abandon semantics must revert its own store mutations before returning.
+     */
+    onPointerCancel?(state: PointerState, ctx: ToolContext): void;
     onHover?(state: PointerState, ctx: ToolContext): void;
+    /**
+     * Offered every keydown that reaches the canvas (never from editable
+     * targets, and only within the viewport's keyboard scope) BEFORE the
+     * shortcut map. Return `true` to consume it (default prevented, no shortcut
+     * runs). Listeners are owned by the viewport, so a tool holds no DOM
+     * subscriptions and deactivation cannot leak.
+     */
+    onKeyDown?(event: KeyboardEvent, ctx: ToolContext): boolean;
     onActivate?(ctx: ToolContext): void;
     onDeactivate?(ctx: ToolContext): void;
     renderOverlay?(ctx: CanvasRenderingContext2D): void;
@@ -249,11 +267,70 @@ interface Tool {
     setOptions?(options: object): void;
     onOptionsChange?(listener: () => void): () => void;
 }
-type ToolName = 'hand' | 'select' | 'pencil' | 'eraser' | 'arrow' | 'note' | 'image' | 'text' | 'shape' | 'measure' | 'template' | 'laser' | 'ping';
+type ToolName = 'hand' | 'select' | 'pencil' | 'eraser' | 'arrow' | 'note' | 'image' | 'text' | 'shape' | 'measure' | 'path' | 'template' | 'laser' | 'ping';
 
 declare function snapPoint(point: Point, gridSize: number): Point;
 declare function snapToHexCenter(point: Point, cellSize: number, orientation: HexOrientation): Point;
 declare function smartSnap(point: Point, ctx: ToolContext): Point;
+/** Cell footprint of a snapped thing: a scalar N means N×N cells. */
+type Footprint = number | {
+    w: number;
+    h: number;
+};
+/**
+ * The cell footprint an element of `size` occupies on a square grid: each axis
+ * rounds to the NEAREST whole cell (a 1.25-cell token is one cell wide), never
+ * below one. Without a usable grid size the footprint is a single cell. Pair it
+ * with `snapFootprintCenter` so an odd-cell element lands on a cell centre and
+ * an even-cell one on an intersection.
+ */
+declare function footprintFromSize(size: {
+    w: number;
+    h: number;
+}, gridSize: number): Footprint;
+/**
+ * Snaps a CENTRE point so a footprint of `w`×`h` cells fills whole cells on a
+ * square grid: an odd axis lands on a cell centre, an even axis on an
+ * intersection. Each axis is independent (a 1×2 footprint centres on X and
+ * sits on an intersection on Y). Compare `snapPoint`, which snaps to
+ * intersections only.
+ */
+declare function snapToCellCenter(point: Point, gridSize: number, footprint?: Footprint): Point;
+/**
+ * `smartSnap` for centres: identity when snapping is off, hex centres on hex
+ * grids, footprint-aware cell centres otherwise.
+ */
+declare function snapFootprintCenter(point: Point, footprint: Footprint, ctx: ToolContext): Point;
+
+/**
+ * How diagonal steps are costed on a SQUARE grid, in cells.
+ * - `euclidean` — straight-line distance over the cell size (the ruler's behaviour; default).
+ * - `chebyshev` — a diagonal step costs one cell.
+ * - `alternate` — diagonals alternate 1, 2, 1, 2 … cells ("5-10-5"), counted over the WHOLE path.
+ * - `manhattan` — a diagonal step costs two cells.
+ * Ignored on hex grids (hex distance is the cube metric).
+ */
+type DiagonalRule = 'euclidean' | 'chebyshev' | 'alternate' | 'manhattan';
+interface GridMetric {
+    gridSize: number;
+    gridType?: 'square' | 'hex';
+    hexOrientation?: HexOrientation;
+    diagonalRule?: DiagonalRule;
+}
+interface PathDistance {
+    /** Cost of the whole path in cells. */
+    total: number;
+    /** Cost after each waypoint; `cumulative[0] === 0`, one entry per point. */
+    cumulative: number[];
+}
+/**
+ * Distance of a polyline in grid cells. Stateful rules (`alternate`) accumulate
+ * over the whole path, so the unit of computation is the path, not a segment;
+ * a segment's own cost is `cumulative[i] - cumulative[i - 1]`.
+ */
+declare function pathDistanceCells(points: readonly Point[], grid: GridMetric): PathDistance;
+/** Two-point convenience over `pathDistanceCells`. */
+declare function gridDistanceCells(a: Point, b: Point, grid: GridMetric): number;
 
 interface Layer {
     id: string;
@@ -419,6 +496,8 @@ declare class ToolManager {
     handlePointerDown(state: PointerState, ctx: ToolContext): void;
     handlePointerMove(state: PointerState, ctx: ToolContext): void;
     handlePointerUp(state: PointerState, ctx: ToolContext): void;
+    /** Cancels the active gesture; falls back to `onPointerUp` for tools without `onPointerCancel`. */
+    handlePointerCancel(state: PointerState, ctx: ToolContext): void;
     onChange(listener: (name: string) => void): () => void;
     onRegister(listener: (tool: Tool) => void): () => void;
 }
@@ -1568,17 +1647,13 @@ interface RemoteMeasureOverlayOptions {
  * updated for `maxAgeMs` is expired by a timer — an idle map never renders,
  * so expiry cannot ride on the draw path. The overlay never touches elements,
  * history, or persisted state, and never moves the viewer's camera.
+ *
+ * The per-sender lifetime is `LingerOverlay`; this class only validates
+ * payloads and draws one measurement.
  */
 declare class RemoteMeasureOverlay {
-    private readonly host;
     private readonly color;
-    private readonly holdMs;
-    private readonly fadeMs;
-    private readonly maxAgeMs;
-    private readonly measurements;
-    private unregister;
-    private rafId;
-    private disposed;
+    private readonly overlay;
     constructor(host: RemoteMeasureOverlayHost, options?: RemoteMeasureOverlayOptions);
     private now;
     /**
@@ -1595,10 +1670,265 @@ declare class RemoteMeasureOverlay {
     get activeSenderCount(): number;
     /** Unregisters the overlay, cancels timers, stops animating. Idempotent. */
     dispose(): void;
-    private beginLinger;
-    private ensureAnimating;
-    private tick;
-    private renderMeasurements;
+}
+
+/** A running-total threshold: segments up to `feet` are drawn in `color`. */
+interface PathRangeBand {
+    readonly feet: number;
+    readonly color: string;
+}
+/**
+ * Where a path starts. A host resolves the pointer to the thing being moved
+ * (a token, a marker) so the path anchors on it instead of the raw cursor;
+ * `anchorKey` is opaque to the tool and echoed back on every emission so the
+ * host can apply the move it asked for.
+ */
+interface PathAnchor {
+    origin: Point;
+    footprint?: Footprint;
+    anchorKey?: string;
+}
+interface PathToolOptions {
+    feetPerCell?: number;
+    color?: string;
+    diagonalRule?: DiagonalRule;
+    footprint?: Footprint;
+    rangeBands?: readonly PathRangeBand[];
+    /**
+     * Screen-space radius, in CSS pixels, around the last waypoint inside which a
+     * tap finishes the path instead of adding a corner. Default `12`. Screen
+     * space so the target keeps its physical size at any zoom; `0` restores
+     * exact-match-only commits (a fingertip can never hit an exact world point on
+     * a gridless canvas, so a touch commit needs the tolerance). Ignored while
+     * this path has an active snapping grid (square, or hex with an
+     * orientation) — there the snapped tap already lands exactly on the last
+     * waypoint, and a screen-space radius could otherwise reach a neighbouring
+     * cell centre at a zoomed-out camera.
+     */
+    commitTapRadiusPx?: number;
+    /** Returning `null` vetoes the gesture — no path opens and nothing is emitted. */
+    resolveStart?: (world: Point, ctx: ToolContext) => PathAnchor | null;
+}
+interface PathSegment {
+    readonly cells: number;
+    readonly feet: number;
+}
+/**
+ * A raf-coalesced snapshot of the in-progress path. `waypoints` are the
+ * committed corners; `cursor` is the rubber-banding end (null once the path
+ * closes) and is counted in the totals without being a waypoint. Ephemeral by
+ * contract: presence only — never elements, history, or persisted state.
+ */
+interface PathEmission {
+    readonly anchorKey?: string;
+    readonly waypoints: readonly Point[];
+    readonly cursor: Point | null;
+    readonly segments: readonly PathSegment[];
+    readonly totalCells: number;
+    readonly totalFeet: number;
+    readonly color: string;
+    readonly rangeBands: readonly PathRangeBand[];
+}
+/**
+ * Multi-waypoint movement measuring: tap to anchor, drag or click to add
+ * corners, tap on or near the last waypoint (or press Enter) to finish, Escape
+ * or a pointer takeover to abandon.
+ *
+ * Store-free by contract: the tool never creates, moves, or deletes elements
+ * and never opens a history transaction — it only measures. A completed path
+ * is handed to `onCommit` listeners and the HOST applies the move (inside its
+ * own transaction) if it wants one. Path snapshots are ephemeral in the same
+ * sense as `MeasureTool`'s: presence only — never elements, history, or
+ * persisted state.
+ */
+declare class PathTool implements Tool {
+    readonly name = "path";
+    private feetPerCell;
+    private color;
+    private diagonalRule;
+    private footprintOption;
+    private rangeBands;
+    private commitTapRadiusPx;
+    private resolveStart;
+    private waypoints;
+    private cursor;
+    private anchorKey;
+    private footprint;
+    private pointerDown;
+    private commitOnUp;
+    private gridSize;
+    private gridType;
+    private hexOrientation;
+    private snapEnabled;
+    private optionListeners;
+    private pathListeners;
+    private commitListeners;
+    private emissionRafId;
+    constructor(options?: PathToolOptions);
+    getOptions(): PathToolOptions;
+    setOptions(options: PathToolOptions): void;
+    onOptionsChange(listener: () => void): () => void;
+    /**
+     * Subscribes to raf-coalesced path snapshots. While a path is open,
+     * listeners receive at most one snapshot per animation frame carrying the
+     * latest state; `null` is delivered synchronously when the path closes
+     * (commit, cancel, or deactivate).
+     */
+    onPath(listener: (emission: PathEmission | null) => void): () => void;
+    /**
+     * Subscribes to finished paths. The emission carries `cursor: null` and the
+     * final waypoints; applying the move (and recording history for it) is the
+     * host's job — the tool has already forgotten the path by then.
+     */
+    onCommit(listener: (emission: PathEmission) => void): () => void;
+    get isOpen(): boolean;
+    /** Synchronous snapshot of the open path; `null` when no path is open. */
+    getEmission(): PathEmission | null;
+    onPointerDown(state: PointerState, ctx: ToolContext): void;
+    onPointerMove(state: PointerState, ctx: ToolContext): void;
+    onPointerUp(_state: PointerState, ctx: ToolContext): void;
+    onHover(state: PointerState, ctx: ToolContext): void;
+    /** A takeover (second pointer, platform cancel) abandons the path outright. */
+    onPointerCancel(_state: PointerState, ctx: ToolContext): void;
+    onDeactivate(ctx: ToolContext): void;
+    onKeyDown(event: KeyboardEvent, ctx: ToolContext): boolean;
+    renderOverlay(ctx: CanvasRenderingContext2D): void;
+    private lastWaypoint;
+    /**
+     * Is `point` close enough to `last` to mean "finish here"? EXACT match always
+     * qualifies. The screen-space tolerance is added ONLY when this path has no
+     * active snapping grid: on a snapping grid (`gridType === 'square'`, or
+     * `'hex'` with a captured orientation, and `gridSize > 0`) the adjacent
+     * cell/hex centre can be as little as one grid cell away, and a radius
+     * computed from CSS pixels has no relationship to that distance — at a
+     * sufficiently zoomed-out camera the radius would swallow a whole neighbour
+     * cell and turn a deliberate next-waypoint tap into an unwanted commit.
+     * Snapping already makes a fingertip tap land exactly on the last waypoint,
+     * so the tolerance is unnecessary there; it exists for the gridless and
+     * `snapPoint`/identity paths, where a fingertip can never land on an exact
+     * world point.
+     */
+    private withinCommitRadius;
+    /**
+     * True when this path's captured grid state snaps every waypoint onto a
+     * cell/hex centre: a `square` grid, or a `hex` grid with a captured
+     * orientation, both with a usable `gridSize`. Mirrors the unconditional
+     * branches of `snap` below — NOT the `snapToGrid`-gated fallback, which
+     * leaves waypoints unsnapped when the user turns snapping off.
+     */
+    private hasSnappingGrid;
+    /**
+     * Snapping to cell or hex centres is UNCONDITIONAL for a `square` grid, or a
+     * `hex` grid WITH a captured orientation: a movement path measures in cells,
+     * so an unsnapped waypoint would report a distance the grid does not agree
+     * with. A `hex` grid WITHOUT an orientation falls through to the
+     * `snapToGrid`-gated `snapPoint` (intersection) branch below, same as the
+     * gridType-less case — unlike `smartSnap`, which is off entirely when the
+     * user turns snapping off.
+     */
+    private snap;
+    /** The measured polyline: waypoints, plus the cursor when it adds a leg. */
+    private measure;
+    private buildEmission;
+    private commit;
+    private cancel;
+    private reset;
+    private notifyOptionsChange;
+    private scheduleEmission;
+    private emitClear;
+    private emitPath;
+    private emitCommit;
+}
+
+/**
+ * The wire shape of a movement-path presence payload. Presence data is untyped
+ * on the wire, so hosts discriminate on `kind`; `isPathPresence` validates a
+ * received payload before it reaches the overlay. Distance is
+ * sender-authoritative: receivers render the payload's `feet` and pre-resolved
+ * `segmentColors` and never recompute from their own grid or range bands.
+ * Paths are ephemeral by contract: presence only — never elements, undo
+ * history, persisted canvas state, or durable operations. The emission's
+ * `anchorKey` is host-private and never travels on the wire.
+ */
+type PathPresence = {
+    readonly kind: 'path';
+    readonly points: readonly Point[];
+    /** One entry per segment: `points.length - 1` colours. */
+    readonly segmentColors: readonly string[];
+    readonly feet: number;
+    readonly color?: string;
+} | {
+    readonly kind: 'path';
+    readonly cleared: true;
+};
+declare const PATH_PRESENCE_KIND = "path";
+/** Point cap for a received path; longer payloads are rejected outright. */
+declare const PATH_PRESENCE_MAX_POINTS = 256;
+declare function isPathPresence(data: unknown): data is PathPresence;
+/**
+ * Builds the presence payload for one local `PathTool` emission. Range bands
+ * are resolved to per-segment colours here, so a receiver renders the sender's
+ * bands without knowing them. `anchorKey` is deliberately dropped: it names a
+ * local element the receiver cannot resolve.
+ *
+ * The sender imposes NO waypoint cap: a path longer than
+ * `PATH_PRESENCE_MAX_POINTS` produces a payload that every receiver rejects, so
+ * a host that allows very long paths should cap waypoints itself or expect
+ * non-delivery beyond the limit.
+ */
+declare function toPathPresence(emission: PathEmission | null): PathPresence;
+/**
+ * The two viewport capabilities the overlay needs; `Viewport` satisfies it.
+ * Structurally identical to the internal `LingerOverlayHost` and to
+ * `RemoteMeasureOverlayHost`; the members are spelled out rather than inherited
+ * so the public shape never depends on an unexported internal interface.
+ */
+interface RemotePathOverlayHost {
+    registerOverlay(draw: OverlayRenderer): () => void;
+    requestRender(): void;
+}
+interface RemotePathOverlayOptions {
+    /** Style fallback when a payload omits `color`. Default `'#FF5722'`. */
+    color?: string;
+    /** Full-opacity hold after a cleared payload. Default `1500`. */
+    holdMs?: number;
+    /** Linear fade to 0 after the hold. Default `400`. */
+    fadeMs?: number;
+    /** Stale active entries are treated as cleared after this. Default `30000`. */
+    maxAgeMs?: number;
+}
+/**
+ * Renders remote movement paths through the viewport overlay registration,
+ * independent of the viewer's active tool. Entries are stamped with local
+ * receive time (remote clocks are never trusted). A cleared payload holds the
+ * final path for `holdMs`, fades over `fadeMs`, and deletes; presence-leave
+ * (`remove`) deletes immediately. An active entry not updated for `maxAgeMs`
+ * is expired by a timer — an idle map never renders, so expiry cannot ride on
+ * the draw path. The overlay never touches elements, history, or persisted
+ * state, and never moves the viewer's camera.
+ *
+ * The per-sender lifetime is `LingerOverlay`; this class only validates
+ * payloads and draws one path.
+ */
+declare class RemotePathOverlay {
+    private readonly color;
+    private readonly overlay;
+    constructor(host: RemotePathOverlayHost, options?: RemotePathOverlayOptions);
+    private now;
+    /**
+     * Applies a presence payload from `sender` (any opaque per-sender key, e.g.
+     * the envelope `from`). Non-path or malformed payloads are ignored and
+     * reported as `false`, so hosts can feed every presence frame through.
+     */
+    apply(sender: string, data: unknown): boolean;
+    /** Removes a sender's path immediately (presence-leave/disconnect). */
+    remove(sender: string): void;
+    /** Removes every path immediately. */
+    clear(): void;
+    /** Number of senders with a visible (active or lingering) path. */
+    get activeSenderCount(): number;
+    /** Unregisters the overlay, cancels timers, stops animating. Idempotent. */
+    dispose(): void;
 }
 
 /**
@@ -1875,6 +2205,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;
@@ -2232,8 +2990,8 @@ declare class ShapeTool implements Tool {
     private computeRect;
     private notifyOptionsChange;
     private snap;
-    private onKeyDown;
-    private onKeyUp;
+    private trackShiftKeyDown;
+    private trackShiftKeyUp;
 }
 
 interface TemplateToolOptions {
@@ -2281,6 +3039,6 @@ declare class TemplateTool implements Tool {
     private notifyOptionsChange;
 }
 
-declare const VERSION = "0.63.0";
+declare const VERSION = "0.65.0";
 
-export { type ActivationOptions, type ActiveFormats, type AlignEdge, type ArrowElement, type ArrowStrokeStyle, ArrowTool, type ArrowToolOptions, AutoSave, type AutoSaveOptions, type BackgroundOptions, type BackgroundPattern, type Binding, type Bounds, Camera, type CameraAnimationEndReason, CameraAnimator, type CameraAnimatorOptions, type CameraChangeInfo, type CameraOptions, type CameraView, type CanvasElement, type CanvasState, type Command, DEFAULT_NOTE_FONT_SIZE, type DistributeAxis, type ElementActivationEvent, type ElementChangeMeta, type ElementRect, type ElementRectMatch, type ElementRectMatchError, ElementRectTracker, type ElementRectTrackerOptions, ElementStore, type ElementStyle, type ElementType, type ElementUpdateEvent, EraserTool, type EraserToolOptions, type ExportAssetError, type ExportAssetErrorReason, type ExportImageOptions, type ExportResourceOptions, type ExportSvgOptions, FOCUS_PRESENCE_KIND, type FocusAudience, type FocusPresence, type FocusRole, type FontSizePreset, type FrameScheduler, type GridElement, type GridInfo, HandTool, type HexOrientation, HistoryStack, type HistoryStackOptions, type HitTestOptions, type HtmlElement, type HtmlExportError, type HtmlExportErrorReason, type HtmlExportOptions, type HtmlExportRenderer, type HtmlPaintContext, type HtmlPaintDiagnostic, type HtmlPainter, HtmlPainterMissingError, HtmlPainterRegistry, type HtmlRenderTarget, type HtmlRouting, type ImageElement, ImageTool, type ImageToolOptions, IndexedDBAdapter, type IndexedDBAdapterOptions, LASER_TRAIL_PRESENCE_KIND, LaserTool, type LaserToolOptions, type LaserTrailEmission, type LaserTrailPresence, type Layer, LayerManager, LocalStorageAdapter, MEASURE_PRESENCE_KIND, type MeasureEmission, type MeasurePresence, MeasureTool, type MeasureToolOptions, type Measurement, MemoryAdapter, MinimapController, type MinimapControllerOptions, type NoteElement, NoteTool, type NoteToolOptions, type OverlayRenderer, PING_PRESENCE_KIND, PencilTool, type PencilToolOptions, type PingEmission, PingInput, type PingInputHost, type PingInputOptions, type PingPresence, PingTool, type PingToolOptions, type Point, type PointerState, type RectTrackerHost, RemoteFocusReceiver, type RemoteFocusReceiverHost, type RemoteFocusReceiverOptions, RemoteLaserOverlay, type RemoteLaserOverlayHost, type RemoteLaserOverlayOptions, RemoteMeasureOverlay, type RemoteMeasureOverlayHost, type RemoteMeasureOverlayOptions, RemotePingOverlay, type RemotePingOverlayHost, type RemotePingOverlayOptions, type RenderStatsSnapshot, type RotateDirection, SelectTool, type SelectionStyleDetails, type ShapeElement, type ShapeKind, ShapeTool, type ShapeToolOptions, type ShortcutBindings, type ShortcutOptions, type ShortcutsApi, type Size, type StorageAdapter, type StrokeElement, type StrokePoint, type TemplateElement, type TemplateRenderStyle, type TemplateShape, TemplateTool, type TemplateToolOptions, type TextElement, TextTool, type TextToolOptions, type Tool, type ToolContext, ToolManager, type ToolName, VERSION, Viewport, type ViewportOptions, applyCameraView, boundsIntersect, cameraOriginForView, captureCameraView, computeElementRects, createArrow, createGrid, createHtmlElement, createImage, createNote, createShape, createStroke, createTemplate, createText, drawHexPath, elementRectsEqual, exportImage, exportSvg, fitZoomForView, getActiveFormats, getArrowBounds, getArrowControlPoint, getArrowMidpoint, getArrowTangentAngle, getBendFromPoint, getElementBounds, getElementStyle, getElementsBoundingBox, getHexCellsInCone, getHexCellsInLine, getHexCellsInRadius, getHexCellsInRectangle, getHexCellsInSquare, getHexDistance, isFocusPresence, isLaserTrailPresence, isMeasurePresence, isNearBezier, isPingPresence, resolveHtmlRouting, setFontSize, smartSnap, snapPoint, snapToHexCenter, styleToPatch, toFocusPresence, toLaserTrailPresence, toMeasurePresence, toPingPresence, toggleBold, toggleItalic, toggleStrikethrough, toggleUnderline };
+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, 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, 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, captureCameraView, computeElementRects, createArrow, createGrid, createHtmlElement, createImage, createNote, createShape, createStroke, createTemplate, createText, defaultPeerColor, drawHexPath, elementRectsEqual, exportImage, exportSvg, fitZoomForView, 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, resolveHtmlRouting, setFontSize, smartSnap, snapFootprintCenter, snapPoint, snapToCellCenter, snapToHexCenter, styleToPatch, toFocusPresence, toLaserTrailPresence, toMeasurePresence, toPathPresence, toPingPresence, toggleBold, toggleItalic, toggleStrikethrough, toggleUnderline };