@scrawl-board/board 0.1.0-beta.7 → 0.1.0-beta.8

package/dist/react.d.ts

@@ -155,6 +155,21 @@ interface CustomObjectDefinition<Props extends JsonValue = JsonValue> {
     /** One pure, synchronous step per consecutive schema version. */
     migrate?: Readonly<Record<number, (oldProps: JsonValue) => JsonValue>>;
     describe(object: ReadonlyCustomObject<Props>, context: ObjectDescribeContext): BoardScene;
+    /**
+     * Optional point-level hit-test precision (Phase 8). Every custom object
+     * hit-tests against its bounding box (`fallback.bounds`) by default — this
+     * lets a non-rectangular shape (e.g. a circular card, an L-shaped region)
+     * reject a point that's inside that box but outside its actual visible
+     * silhouette, tightening a click/marquee/raycast hit to the shape's real
+     * outline. `point` is in this object's own local space — the same
+     * untransformed space `describe`'s returned geometry already lives in
+     * (the caller inverse-transforms the pointer's board point through
+     * `object.transform` before calling this). Absent means every point
+     * inside the bounding box hits, matching pre-Phase-8 behavior exactly.
+     * Rejecting a point here does not fall through to whatever's underneath —
+     * the gesture simply misses this object, same as clicking empty space.
+     */
+    hitTest?(object: ReadonlyCustomObject<Props>, point: BoardPoint): boolean;
 }
 interface SceneNodeBase {
     key: string;
@@ -188,6 +203,15 @@ interface SceneGroup extends SceneNodeBase {
     kind: "group";
     children: readonly BoardScene[];
 }
+/**
+ * **No renderer or SVG-export interpreter exists for this node kind yet**
+ * (tracked as deferred work — see `renderer/shapes/customObjects.ts`'s
+ * `"path"` case). Returning a `ScenePath` from `describe()` renders nothing,
+ * exports nothing, and contributes no hit-test bounds — it neither errors
+ * nor emits a diagnostic. Until an interpreter ships, build custom shapes
+ * from `SceneRect`/`SceneEllipse`/`SceneGroup`/`SceneText`/`SceneImage`
+ * instead.
+ */
 interface ScenePath extends SceneNodeBase {
     kind: "path";
     /** SVG-style path data, board-local coordinates. */
@@ -343,8 +367,23 @@ interface Lockable {
     lockedByName?: string;
 }
 
+/**
+ * Per-object visibility (Phase 8) — mirrors `itemLock.ts`'s `Lockable`
+ * pattern exactly, but simpler: unlike a lock, hidden state carries no
+ * holder/ownership concept, so there's no analogue to `LockHolder`/
+ * `canUnlockItem`. A hidden object stays fully present in the Document
+ * (still serializes, persists, syncs, undoes/redoes) — it just skips
+ * rendering and hit-testing/selection candidacy. `hidden` absent or
+ * `false` means visible; this keeps every pre-Phase-8 document (which has
+ * no `hidden` field on any object at all) implicitly fully visible with
+ * zero migration needed.
+ */
+interface Hideable {
+    hidden?: boolean;
+}
+
 /** A kitchen timer sitting on the board. Remaining time is derived, not ticked. */
-interface KitchenTimer extends Lockable {
+interface KitchenTimer extends Lockable, Hideable {
     id: string;
     x: number;
     y: number;
@@ -358,7 +397,7 @@ interface KitchenTimer extends Lockable {
     runningSince?: number;
 }
 
-interface RectangleObject extends Lockable {
+interface RectangleObject extends Lockable, Hideable {
     id: string;
     x: number;
     y: number;
@@ -380,7 +419,7 @@ interface RectangleObject extends Lockable {
      */
     rotation?: number;
 }
-interface EllipseObject extends Lockable {
+interface EllipseObject extends Lockable, Hideable {
     id: string;
     x: number;
     y: number;
@@ -396,7 +435,7 @@ interface EllipseObject extends Lockable {
 }
 /** `"none"` is a plain line with no arrowhead; today's only real head shape is `"triangle"`. New head shapes extend this union without touching `ArrowObject`'s own fields. */
 type ArrowHeadStyle = "triangle" | "none";
-interface LineObject extends Lockable {
+interface LineObject extends Lockable, Hideable {
     id: string;
     start: BoardPoint;
     end: BoardPoint;
@@ -404,7 +443,7 @@ interface LineObject extends Lockable {
     strokeWidth?: number;
     opacity?: number;
 }
-interface ArrowObject extends Lockable {
+interface ArrowObject extends Lockable, Hideable {
     id: string;
     start: BoardPoint;
     end: BoardPoint;
@@ -423,7 +462,7 @@ interface ArrowObject extends Lockable {
  * `polygonStartAngle`, which encodes each side count's own vertex
  * orientation so the outline always matches the legacy drag-preview shape.
  */
-interface PolygonObject extends Lockable {
+interface PolygonObject extends Lockable, Hideable {
     id: string;
     x: number;
     y: number;
@@ -438,7 +477,7 @@ interface PolygonObject extends Lockable {
     rotation?: number;
 }
 /** Same bounding-box/rotation convention as Rectangle; a 5-pointed star with a tuned inner-radius ratio, matching the legacy tool's own default (see `polygonGeometry.ts`'s `starPoints`). */
-interface StarObject extends Lockable {
+interface StarObject extends Lockable, Hideable {
     id: string;
     x: number;
     y: number;
@@ -455,7 +494,7 @@ interface StarObject extends Lockable {
     rotation?: number;
 }
 /** Same bounding-box/rotation convention as Rectangle; the standard parametric heart curve (see `polygonGeometry.ts`'s `heartPoints`), no extra parameters beyond the shared shape fields. */
-interface HeartObject extends Lockable {
+interface HeartObject extends Lockable, Hideable {
     id: string;
     x: number;
     y: number;
@@ -480,7 +519,7 @@ interface HeartObject extends Lockable {
  * a group into its leaf members is always done by the caller (recursively,
  * with cycle protection), never assumed here.
  */
-interface GroupObject extends Lockable {
+interface GroupObject extends Lockable, Hideable {
     id: string;
     children: string[];
 }
@@ -505,7 +544,7 @@ interface StrokePoint extends BoardPoint {
  * geometric outline, not an expressive ink mark.
  */
 type StrokeTool = "marker" | "highlighter" | "shape";
-interface Stroke extends Lockable {
+interface Stroke extends Lockable, Hideable {
     id: string;
     color: string;
     baseWidth: number;
@@ -521,7 +560,7 @@ interface Stroke extends Lockable {
     clusterId?: string;
 }
 type SerializedPoint = [number, number, number, number];
-interface SerializedStroke extends Lockable {
+interface SerializedStroke extends Lockable, Hideable {
     id: string;
     color: string;
     baseWidth: number;
@@ -585,7 +624,7 @@ interface NoteVote {
  * A sticky note: content floating above the board at a z-offset (pillar 3 —
  * depth as an organizational axis). Center position in board space.
  */
-interface StickyNote extends Lockable {
+interface StickyNote extends Lockable, Hideable {
     id: string;
     x: number;
     y: number;
@@ -603,7 +642,7 @@ interface StickyNote extends Lockable {
  * top-left corner; lines flow downward (-y). Text joins the clustering
  * system like handwriting (build prompt §6.4).
  */
-interface TextBlock extends Lockable {
+interface TextBlock extends Lockable, Hideable {
     id: string;
     x: number;
     y: number;
@@ -617,7 +656,7 @@ interface TextBlock extends Lockable {
  * Interactive structured table on the board. Position (x, y) is top-left in board units.
  * Cells are indexed as `${row},${col}` keys mapping to cell text content.
  */
-interface TableBlock extends Lockable {
+interface TableBlock extends Lockable, Hideable {
     id: string;
     x: number;
     y: number;
@@ -634,7 +673,7 @@ interface TableBlock extends Lockable {
  * An imported image block on the board plane.
  * Coordinates (x, y) represent the center of the image in board space.
  */
-interface ImageBlock extends Lockable {
+interface ImageBlock extends Lockable, Hideable {
     id: string;
     /**
      * A legacy, read-only data URL (or, historically, an arbitrary string) —
@@ -845,6 +884,8 @@ interface BoardEventMap {
     "asset-diagnostic": AssetDiagnostic;
     /** A batch of Ops was reconciled (not applied as-sent) by the persistence adapter (ticket #24). */
     "persistence-diagnostic": PersistenceDiagnostic;
+    /** The collaboration server has confirmed receipt of these op ids (Phase 7) — observability only; the Document was already correct via optimistic local apply before this ever fires. */
+    "collaboration-ops-acknowledged": CollaborationAckDiagnostic;
     audit: unknown;
     error: BoardControllerError;
     disposed: undefined;
@@ -908,9 +949,12 @@ interface PresenceView {
     readonly height: number;
 }
 /**
- * A Host-owned collaborator, synced in for cursor/roster rendering only.
- * Presence is ephemeral — it never touches the Document, Ops, undo/redo,
- * or persistence — so this is a read/query capability, not an adapter.
+ * A collaborator, synced in for cursor/roster rendering only. Presence is
+ * ephemeral — it never touches the Document, Ops, undo/redo, or persistence
+ * (ADR 0006/0007). Two ways a roster gets populated (`presence.sync`
+ * directly, or a `CollaborationAdapter`'s optional presence channel —
+ * Phase 6, ADR 0015) both feed the exact same read/query capability below;
+ * a Host picks one, not both, for a given controller.
  */
 interface PresenceUser {
     readonly id: string;
@@ -919,6 +963,14 @@ interface PresenceUser {
     readonly tool?: string;
     readonly cursor?: PresenceCursor;
     readonly view?: PresenceView;
+    /** Host-supplied extras (avatar URL, role, etc.) — opaque to Scrawl, never interpreted. */
+    readonly metadata?: Record<string, unknown>;
+}
+/** This client's own local presence, published via `presence.broadcast()` (Phase 6). */
+interface LocalPresence {
+    readonly cursor?: PresenceCursor | null;
+    readonly view?: PresenceView | null;
+    readonly tool?: string;
 }
 /**
  * The Custom arm wraps `CustomBoardObject` under the same `type` discriminant
@@ -1044,10 +1096,34 @@ type LoadResult = {
 } | {
     state: "missing";
 };
+/**
+ * Result of a whole-document `PersistenceAdapter.replace()` call (ADR 0006:
+ * "Whole-document writes survive only for create, clear-board and import,
+ * where replacing everything is the actual intent"). Revision-gated, unlike
+ * `applyOps` — `conflict` means `baseRevision` was stale (someone else's
+ * write landed first); the caller must reload and never overwrites blind.
+ */
+type ReplaceResult = {
+    state: "applied";
+    revision: string;
+} | {
+    state: "conflict";
+    currentRevision: string;
+};
+/**
+ * The one sanctioned seam for persisting a Board's Document to a Host's own
+ * storage — implement this against a database, an HTTP API, IndexedDB
+ * (see `@scrawl-board/board/local`'s `createIndexedDBPersistence`), or
+ * anything else. `load()` fetches the current state on connect; `applyOps()`
+ * streams incremental Ops as edits happen; `replace()` is only for
+ * whole-document writes (create, clear-board, import — see ADR 0006) and is
+ * revision-gated so a stale write never silently clobbers a newer one.
+ * Passed via `createBoardController({ adapters: { persistence } })`.
+ */
 interface PersistenceAdapter {
     load(context: DocumentContext): Promise<LoadResult>;
     applyOps(context: DocumentContext, ops: readonly ControllerOp[]): Promise<ApplyOpsResult>;
-    replace(context: DocumentContext, document: CurrentSerializedDocument, baseRevision: string): Promise<unknown>;
+    replace(context: DocumentContext, document: CurrentSerializedDocument, baseRevision: string): Promise<ReplaceResult>;
 }
 /**
  * `"reconcile"` (ticket #24) means the server authoritatively resolved the
@@ -1071,6 +1147,10 @@ interface PersistenceDiagnostic {
     rejectedOpIds: readonly string[];
     revision: string;
 }
+/** Emitted as `"collaboration-ops-acknowledged"` (Phase 7) — the server has confirmed receipt of these op ids on the live pipe. */
+interface CollaborationAckDiagnostic {
+    opIds: readonly string[];
+}
 interface ControllerOp {
     id: string;
     schemaVersion: 1;
@@ -1087,7 +1167,39 @@ interface ControllerOp {
      | "order";
     objectId: string;
     payload?: unknown;
+    /**
+     * This op's position in its own originating client's local sequence
+     * (Phase 7) — 1, 2, 3, ... per controller instance, distinct from `id`
+     * (an opaque, globally-unique identifier used for dedup/ack, not
+     * ordering) and from a server's own authoritative ordering (e.g.
+     * `referenceCollaborationServer.ts`'s per-room `version` counter).
+     * Present on every op this SDK originates locally; a remote peer's op
+     * carries whatever its own origin set, unchanged — never renumbered in
+     * transit. Absent on an op minted by decoding the legacy wire envelope
+     * (`scrawlOpEnvelope.ts`), which predates this field and has no
+     * per-client sequence concept of its own.
+     */
+    clientSequence?: number;
+    /**
+     * The `CollaboratorIdentity.id` of this op's originating client (Phase
+     * 7) — set for every op this SDK originates locally when `identity` is
+     * configured, omitted entirely otherwise (never sent as `undefined`).
+     * The explicit foundation for a future per-author undo filter (a local
+     * user's own undo should only ever touch their own ops) — no undo-stack
+     * behavior itself changes this phase.
+     */
+    clientId?: string;
 }
+/**
+ * The one sanctioned seam for real-time multiplayer — implement this against
+ * a Host's own collaboration backend (WebSocket relay, CRDT server, etc.).
+ * `connect()` is called once per controller with the local user's
+ * `identity` and a `receive` callback the adapter invokes with incoming
+ * Ops, presence updates, acks, and connection status; it resolves with a
+ * `CollaborationSession` the controller uses to send local Ops and presence
+ * back out. Passed via `createBoardController({ adapters: { collaboration } })`;
+ * omit it entirely to run single-player.
+ */
 interface CollaborationAdapter {
     connect(options: DocumentContext & {
         identity: CollaboratorIdentity;
@@ -1098,14 +1210,72 @@ interface CollaboratorIdentity {
     id: string;
     name: string;
     color?: string;
+    /** Host-supplied extras (avatar URL, role, etc.) — opaque to Scrawl, forwarded into any resulting `PresenceUser` unread and never interpreted. */
+    metadata?: Record<string, unknown>;
 }
 interface CollaborationReceiver {
     ops(ops: readonly ControllerOp[]): void;
+    /**
+     * The current presence roster (Phase 6, ADR 0015) — always a full
+     * replacement, never a delta, matching `presence.sync`'s existing
+     * semantics exactly (an adapter that aggregates wire deltas into a full
+     * roster before calling this is the adapter's own job, not the
+     * controller's). Required on this interface (not optional) because a
+     * Host only ever *consumes* `CollaborationReceiver` — never implements
+     * it — so adding a required method here cannot break an existing custom
+     * `CollaborationAdapter`. An adapter with no presence support simply
+     * never calls it.
+     */
+    presence(users: readonly PresenceUser[]): void;
+    /**
+     * The server has confirmed receipt of these op ids (Phase 7) —
+     * distinguishes "sent" from "server accepted," which `sendOps` alone
+     * (fire-and-forget) cannot. Required for the same reason `presence` is:
+     * Hosts only ever consume this interface, never implement it, so this
+     * cannot break an existing custom `CollaborationAdapter`. An adapter with
+     * no ack support simply never calls it — the collaboration pipe still
+     * works exactly as it did before this existed, just without the
+     * bookkeeping/observability this enables.
+     */
+    acknowledged(opIds: readonly string[]): void;
     status(state: "online" | "reconnecting" | "offline"): void;
     error(cause: unknown): void;
 }
+/**
+ * Result of `CollaborationSession.requestSync()` (Phase 7). `"ops"` means
+ * the adapter's own live-pipe cache fully covered the gap since the
+ * caller's last known revision — apply `ops` and the client is caught up,
+ * no persistence reload needed. `"unavailable"` means it couldn't (gap too
+ * large, server restarted, or the adapter has no retained history at all)
+ * — the caller must fall back to a persistence-backed reload. This is a
+ * best-effort *liveness* cache, deliberately never a durable source of
+ * truth (ADR 0006's "collaboration is never a second source of document
+ * truth" — see ADR 0015's own extension of that principle to presence,
+ * now extended once more, the same way, to this).
+ */
+type CollaborationSyncResult = {
+    state: "ops";
+    ops: readonly ControllerOp[];
+    serverRevision: string;
+} | {
+    state: "unavailable";
+};
 interface CollaborationSession {
     sendOps(ops: readonly ControllerOp[]): void;
+    /**
+     * Publishes this client's own local presence (Phase 6, ADR 0015) —
+     * best-effort, unordered, never persisted, never an Op. Optional: an
+     * adapter that doesn't support presence simply omits this method, and
+     * `presence.broadcast()` becomes a silent no-op.
+     */
+    updatePresence?(presence: LocalPresence): void;
+    /**
+     * Requests an incremental catch-up after a reconnect (Phase 7) — optional;
+     * an adapter that doesn't support this simply omits the method, and the
+     * caller (`resyncAfterReconnect`) goes straight to its existing
+     * persistence-backed full reload, unchanged from Phase 6.
+     */
+    requestSync?(): Promise<CollaborationSyncResult>;
     close(): Promise<void>;
 }
 interface CreateBoardControllerOptions {
@@ -1145,6 +1315,87 @@ interface CreateBoardControllerOptions {
      * doesn't use the React theme system can set this directly instead.
      */
     boardTheme?: BoardThemeOptions;
+    /**
+     * Debounced auto-flush of pending persistence Ops after document changes
+     * settle (Phase 5). Enabled by default (1000ms debounce) whenever
+     * `adapters.persistence` is configured — today, without this, a Host must
+     * call `flush()` manually after every edit for anything to persist. Pass
+     * `false` to opt out entirely and drive `flush()` yourself, preserving
+     * prior behavior exactly. Never fires on a per-change basis — rapid edits
+     * coalesce into one flush of their final state (ADR 0006).
+     */
+    autosave?: boolean | {
+        debounceMs?: number;
+    };
+    /**
+     * Throttle for `presence.broadcast()` (Phase 6, ADR 0015) — the minimum
+     * interval between outgoing presence updates sent via the configured
+     * `CollaborationAdapter`. Defaults to 50ms. A trailing throttle: the
+     * latest value passed to `broadcast()` always eventually sends, even if
+     * calls arrive faster than this interval.
+     */
+    presenceThrottleMs?: number;
+    /**
+     * Caps how many `ControllerOp`s can sit queued, unsent, for the
+     * persistence pipe (`pendingOps`) or the collaboration pipe
+     * (`pendingCollaborationOps`) at once (Phase 7) — each pipe is capped
+     * independently. Prevents unbounded memory growth from a long-lived
+     * offline session or a stuck adapter. Exceeding it never fails or drops
+     * the local edit itself (the Document already applied it optimistically)
+     * — only queueing for that one pipe is skipped, and a
+     * `{code:"queue-overflow", retryable:false}` error is emitted so a Host
+     * can react. Defaults to 1000 — the Phase 9 collaboration coalescing
+     * above (`collaborationCoalesceMs`) already keeps a busy drag from
+     * approaching this on its own, so hitting it in practice means a pipe
+     * has been offline/stuck for a genuinely long editing session.
+     *
+     * **Recovery** (Phase 9): the dropped op itself is gone from that one
+     * pipe's queue — there is no automatic backfill, and the live
+     * controller keeps running with that pipe now silently missing one
+     * edit. Two things stay true regardless: (1) the in-memory Document is
+     * never affected — a queue-overflow can never corrupt or roll back a
+     * local edit, only skip sending it; (2) staleness is per-object, not
+     * permanent — any *later* edit to that same object produces a brand
+     * new, undropped Op carrying its full current state, which naturally
+     * supersedes the gap (the Op model is already last-write-wins/
+     * idempotent, so a superseding Op doesn't need the earlier one to have
+     * arrived). The real risk is an object that's dropped and never edited
+     * again before the controller is disposed or the page reloads — a Host
+     * that needs strict durability should treat `queue-overflow` as a
+     * signal to check `persistence.state`/`pendingOps` pressure (via
+     * `usePersistenceStatus`/`getSnapshot().connection.persistence`)
+     * before disposing, not assume disposing and reconnecting alone
+     * repairs the gap (a fresh `load()` only returns what the backend
+     * already has, which is exactly what's missing the dropped edit).
+     */
+    maxPendingOps?: number;
+    /**
+     * Coalescing window (ms) for outgoing collaboration Ops (Phase 9) — same
+     * trailing-throttle shape as `presenceThrottleMs`: the first Op after an
+     * idle period sends immediately, and subsequent Ops for the *same*
+     * object within this window replace each other (latest value wins,
+     * matching the already-idempotent Op model) rather than each triggering
+     * its own send. A multi-second drag that previously sent one full Op per
+     * pointer-move now sends at most one per window per touched object.
+     * Persistence (`pendingOps`) is unaffected — it already debounces via
+     * `autosave`, so this option only changes live collaboration traffic.
+     * Defaults to 50ms.
+     */
+    collaborationCoalesceMs?: number;
+    /**
+     * Caps how many resolved objects a single `content.copy`/`content.cut`
+     * (or their Cmd/Ctrl+C/X keyboard equivalents) will hold in the
+     * in-memory clipboard at once (Phase 9) — `expandSelection` recursively
+     * expands groups, so an unbounded selection (a huge group, or thousands
+     * of individually selected strokes) could otherwise clone and retain an
+     * arbitrarily large snapshot indefinitely, until the next copy/cut
+     * replaces it. Exceeding it rejects the whole copy/cut (nothing is
+     * cloned, and — for cut — nothing is removed from the Document either,
+     * never a partial copy of an arbitrary subset) and emits a
+     * `{code:"clipboard-overflow", retryable:false}` error. Defaults to
+     * 5000.
+     */
+    maxClipboardItems?: number;
 }
 interface BoardController {
     readonly document: ReadonlyBoardDocument;
@@ -1176,6 +1427,15 @@ interface BoardController {
     };
     readonly view: {
         fit(): void;
+        /**
+         * Frame the current selection (Phase 8), the same way `fit()` frames the
+         * whole board. A no-op with nothing selected — deliberately doesn't fall
+         * back to `fit()`'s "frame everything," which would be a surprising
+         * result for an empty selection. On a headless board this can only
+         * re-center the view (no viewport to compute a real zoom-to-fit from),
+         * matching `fit()`'s own headless limitation exactly.
+         */
+        zoomToSelection(): void;
         zoomTo(value: number): void;
         centerOn(point: BoardPoint): void;
         get(): BoardView;
@@ -1247,6 +1507,14 @@ interface BoardController {
          * aren't listed separately. `[]` when the clipboard is empty.
          */
         paste(): readonly string[];
+        /**
+         * Select every top-level object (Phase 8) — a group's own id stands for
+         * its children, which aren't selected separately, matching `paste`'s own
+         * "what the user sees" id list. Hidden objects are excluded, consistent
+         * with them already being excluded from marquee selection. Works with
+         * no canvas/engine, same as {@link toggleSelectionVisibility}.
+         */
+        selectAll(): void;
         table: {
             addRow(tableId: string): void;
             addCol(tableId: string): void;
@@ -1265,6 +1533,21 @@ interface BoardController {
          * another collaborator who isn't the current lock holder.
          */
         toggleSelectionLock(): void;
+        /**
+         * Toggle hidden state for the current selection, as one undo entry
+         * (Phase 8). If any selected object is hidden, shows every selected
+         * object; otherwise hides them all — same "any wins" semantics as
+         * {@link toggleSelectionLock}. Hidden objects stay fully present in the
+         * document (they still serialize, persist, sync, undo/redo) — they just
+         * stop rendering and stop being hit-testable/selectable via pointer
+         * interaction. Unlike `toggleSelectionLock`, this works on a headless
+         * board too: it only touches `selection`/the document, no canvas or
+         * engine involved. Custom objects have no visibility concept (no
+         * `Hideable` field) and are silently skipped, matching how
+         * `toggleSelectionLock` already excludes them. A no-op with nothing
+         * selected or when the selection is only custom objects.
+         */
+        toggleSelectionVisibility(): void;
     };
     readonly query: {
         get(id: string): DeepReadonly<BoardObject> | undefined;
@@ -1293,6 +1576,15 @@ interface BoardController {
         follow(view: PresenceView): void;
         /** Ease the camera to a peer's view; returns false (no-op) while mid-stroke. */
         gather(view: PresenceView): boolean;
+        /**
+         * Publishes this client's own cursor/tool/view for other collaborators
+         * (Phase 6, ADR 0015), via the configured `CollaborationAdapter` —
+         * throttled internally (`presenceThrottleMs` option, default 50ms) so
+         * a raw pointermove stream never becomes a message-per-event flood. A
+         * no-op if no collaboration adapter is configured, or if the
+         * configured one doesn't implement `updatePresence`.
+         */
+        broadcast(local: LocalPresence): void;
     };
     readonly export: {
         svg(): string;
@@ -1318,6 +1610,7 @@ interface BoardController {
     }>;
     dispose(): Promise<void>;
 }
+/** @deprecated Use `BoardController.getSnapshot()`'s return type instead. */
 type LocalBoardSnapshot = {
     documentId: string;
     selectedStrokeId: string | null;
@@ -1326,6 +1619,7 @@ type LocalBoardSnapshot = {
     canRedo: boolean;
     disposed: boolean;
 };
+/** @deprecated Use `BoardController` (from `createBoardController`) instead — this stroke-only, single-tool surface predates the full capability-grouped controller. */
 type LocalBoard = {
     drawStroke(stroke: Stroke): void;
     selectAt(point: BoardPoint): string | null;
@@ -1579,6 +1873,16 @@ interface ScrawlProviderProps {
     className?: string;
     style?: ThemeStyle;
 }
+/**
+ * Wraps a Board `controller` you created yourself (via `createBoardController`)
+ * so its descendants can use `useScrawlController`/`useScrawlSnapshot`/etc.
+ * and render its default UI pieces (`DefaultBoardChrome`, `StyleShelf`, ...).
+ * Prefer `Scrawl` unless you need to construct or own the controller's
+ * lifecycle yourself (e.g. you create it outside React, or need it before
+ * first render). Set `disposeOnUnmount` to have this provider call
+ * `controller.dispose()` on unmount; otherwise disposal remains your own
+ * responsibility.
+ */
 declare function ScrawlProvider({ controller, children, preset, theme, portalContainer: customPortal, disposeOnUnmount, onThemeDiagnostic, className, style }: ScrawlProviderProps): react.JSX.Element;
 interface ScrawlProps extends Omit<CreateBoardControllerOptions, "canvas"> {
     children?: ReactNode;
@@ -1599,6 +1903,17 @@ interface ScrawlProps extends Omit<CreateBoardControllerOptions, "canvas"> {
      */
     icons?: Partial<Record<BuiltInTool, ReactNode>>;
 }
+/**
+ * The fastest path to an embedded Board: creates and owns a
+ * `BoardController` for you (constructed once, disposed on unmount) and
+ * renders it into a canvas. Render with no `children` to get the SDK's
+ * default toolbar/UI chrome, or supply your own `children` (using the
+ * `useScrawlController`/`useScrawlSnapshot` hooks, or the exported
+ * `DefaultBoardChrome`/`StyleShelf`/etc. pieces) to build a custom UI on
+ * top of the same controller. Accepts every `CreateBoardControllerOptions`
+ * field except `canvas` (pass `canvas={null}` for a headless board, or an
+ * existing `<canvas>` element to control its identity yourself).
+ */
 declare function Scrawl({ children, preset, theme, portalContainer, className, style, onReady, onError, onThemeDiagnostic, canvas: suppliedCanvas, icons, ...options }: ScrawlProps): react.JSX.Element;
 interface ScrawlCanvasProps {
     element?: HTMLCanvasElement;
@@ -1624,6 +1939,38 @@ declare function ScrawlPortal({ children }: {
 declare function useScrawlController(): BoardController;
 declare function useScrawlTheme(): ScrawlResolvedTheme;
 declare function useScrawlSnapshot(): BoardSnapshot;
+/**
+ * A thin, purely-derived convenience over
+ * `useScrawlSnapshot().connection.persistence` (Phase 5) — for a Host
+ * component that only cares about save status (e.g. a
+ * "Saving…"/"Saved"/"Offline" indicator) and would otherwise re-derive
+ * this same field access itself. Adds no state and no behavior of its
+ * own: React still owns none of persistence, exactly as before — this
+ * hook only re-reads what the controller already tracks.
+ *
+ * Deliberately does *not* go through `useScrawlSnapshot()` (Phase 9):
+ * `changed()` rebuilds the whole `BoardSnapshot` — including a fresh
+ * `connection.persistence` object — on every document mutation, even ones
+ * that never touch persistence at all, so a component using only this
+ * hook would otherwise re-render on every stroke draw. `useSyncStatus`
+ * below memoizes on the value (`state`/`error`), not just the object
+ * reference, and returns the same cached value across renders where
+ * nothing relevant changed — the same shape `usePresence` already uses
+ * for its own independently-scoped store.
+ */
+declare function usePersistenceStatus(): PersistenceSnapshot;
+/** The `CollaborationSnapshot` equivalent of `usePersistenceStatus` (Phase 6) — same value-memoized convenience over `useScrawlSnapshot().connection.collaboration` (Phase 9: see `usePersistenceStatus`'s doc comment for why it doesn't derive from the full snapshot). */
+declare function useCollaborationStatus(): CollaborationSnapshot;
+/**
+ * The current presence roster (Phase 6), live-updating — wraps
+ * `controller.presence.list()`/`subscribe` the same way `useScrawlSnapshot`
+ * wraps the controller's main snapshot, via `useSyncExternalStore`. Does
+ * not re-render on every remote pointer move by itself; it re-renders
+ * whenever the roster the controller already tracks changes, at whatever
+ * rate that arrives at (throttled adapter-side, per `presenceThrottleMs`).
+ */
+declare function usePresence(): readonly PresenceUser[];
+/** @deprecated Use `Scrawl` instead — this predates the full capability-grouped `BoardController` and only exposes the stroke-only `LocalBoard` surface. */
 type ScrawlBoardProps = {
     documentId: string;
     initialDocument?: SerializedBoardDocument;
@@ -1631,7 +1978,8 @@ type ScrawlBoardProps = {
     className?: string;
     style?: CSSProperties;
 };
+/** @deprecated Use `Scrawl` instead — this predates the full capability-grouped `BoardController` and only exposes the stroke-only `LocalBoard` surface. */
 declare function ScrawlBoard({ documentId, initialDocument, onReady, className, style }: ScrawlBoardProps): react.JSX.Element;
 
-export { AssetResolutionError, DefaultBoardChrome, FocusedItemToolbar, InlineEditors, MultiplayerCursors, SUPPORTED_ASSET_MEDIA_TYPES, Scrawl, ScrawlBoard, ScrawlCanvas, ScrawlDefaultUI, ScrawlPortal, ScrawlProvider, StyleShelf, assetRef, clampAssetCacheBytes, cloneCustomObject, isAssetRef, resolveScrawlTheme, scrawlThemePresets, useScrawlController, useScrawlSnapshot, useScrawlTheme, validateScrawlTheme };
-export type { AssetDiagnostic, AssetIngestRequest, AssetIngestResult, AssetIngestor, AssetKind, AssetPurpose, AssetRef, AssetResolutionErrorCode, AssetResolveRequest, AssetResolveResult, AssetResolver, BoardController, BoardKeyInput, BoardPointerInput, BoardScene, BoardSlotProps, BoardSnapshot, BoardStyle, BoardThemeOptions, CommentMarker, CreateBoardControllerOptions, CustomBoardObject, CustomObjectAddInput, CustomObjectDefinition, CustomTool, CustomToolDefinition, DefaultBoardChromeProps, DefaultUIRegion, DefaultUISlot, DefaultUISlots, DialogSlotProps, ExtensionCommand, ExtensionDiagnostic, ExtensionHitResult, ExtensionId, ExtensionRequirement, FocusedItem, FocusedItemToolbarProps, InlineEditorsProps, InputModifiers, JsonObject, JsonValue, LocalBoard, LocalBoardSnapshot, Mat2x3, MultiplayerCursorsProps, ObjectDescribeContext, ObjectIntent, ObjectType, PresenceCursor, PresenceUser, PresenceView, QueryableBoardObject, ReadonlyCustomObject, SceneEllipse, SceneGroup, SceneImage, ScenePath, SceneRect, SceneText, ScrawlBoardProps, ScrawlCanvasProps, ScrawlDefaultUIProps, ScrawlDensity, ScrawlExtension, ScrawlGridMode, ScrawlProps, ScrawlProviderProps, ScrawlResolvedTheme, ScrawlSurfaceTexture, ScrawlTheme, ScrawlThemeDiagnostic, ScrawlThemePreset, StyleShelfProps, SupportedAssetMediaType, ToolCancelReason, ToolCapabilities, ToolCursor, ToolId };
+export { AssetResolutionError, DefaultBoardChrome, FocusedItemToolbar, InlineEditors, MultiplayerCursors, SUPPORTED_ASSET_MEDIA_TYPES, Scrawl, ScrawlBoard, ScrawlCanvas, ScrawlDefaultUI, ScrawlPortal, ScrawlProvider, StyleShelf, assetRef, clampAssetCacheBytes, cloneCustomObject, isAssetRef, resolveScrawlTheme, scrawlThemePresets, useCollaborationStatus, usePersistenceStatus, usePresence, useScrawlController, useScrawlSnapshot, useScrawlTheme, validateScrawlTheme };
+export type { AssetDiagnostic, AssetExportFailure, AssetIngestRequest, AssetIngestResult, AssetIngestor, AssetKind, AssetPurpose, AssetRef, AssetResolutionErrorCode, AssetResolveRequest, AssetResolveResult, AssetResolver, BoardController, BoardKeyInput, BoardPointerInput, BoardScene, BoardSlotProps, BoardSnapshot, BoardStyle, BoardThemeOptions, CollaborationSnapshot, CommentMarker, CreateBoardControllerOptions, CustomBoardObject, CustomObjectAddInput, CustomObjectDefinition, CustomTool, CustomToolDefinition, DefaultBoardChromeProps, DefaultUIRegion, DefaultUISlot, DefaultUISlots, DialogSlotProps, ExportDocumentSVGOptions, ExportDocumentSVGResult, ExtensionCommand, ExtensionDiagnostic, ExtensionHitResult, ExtensionId, ExtensionRequirement, FocusedItem, FocusedItemToolbarProps, InlineEditorsProps, InputModifiers, JsonObject, JsonValue, LocalBoard, LocalBoardSnapshot, LocalPresence, Mat2x3, MultiplayerCursorsProps, ObjectDescribeContext, ObjectIntent, ObjectType, PresenceCursor, PresenceUser, PresenceView, QueryableBoardObject, ReadonlyCustomObject, SceneEllipse, SceneGroup, SceneImage, ScenePath, SceneRect, SceneText, ScrawlBoardProps, ScrawlCanvasProps, ScrawlDefaultUIProps, ScrawlDensity, ScrawlExtension, ScrawlGridMode, ScrawlProps, ScrawlProviderProps, ScrawlResolvedTheme, ScrawlSurfaceTexture, ScrawlTheme, ScrawlThemeDiagnostic, ScrawlThemePreset, SearchHit, SearchHitKind, SearchableComment, StyleShelfProps, SupportedAssetMediaType, ToolCancelReason, ToolCapabilities, ToolCursor, ToolId };