@scrawl-board/board 0.1.0-beta.0 → 0.1.0-beta.10

package/dist/react.d.ts

@@ -1,13 +1,11 @@
 import * as react from 'react';
 import { ReactNode, ComponentType, CSSProperties } from 'react';
 
-declare const strokeIdBrand: unique symbol;
-type StrokeId = string & {
-    readonly [strokeIdBrand]: "StrokeId";
-};
-
 /** Wire grammar: `asset:<namespace>:<opaque-id>`. Interpreted only by the Host. */
 type AssetRef = string;
+declare function isAssetRef(value: unknown): value is AssetRef;
+/** Throws on malformed input; use `isAssetRef` where a boolean is wanted instead. */
+declare function assetRef(value: string): AssetRef;
 type AssetKind = "image";
 type AssetPurpose = "render" | "thumbnail" | "export";
 interface AssetResolveRequest {
@@ -49,6 +47,12 @@ interface AssetIngestor {
     ingest(request: AssetIngestRequest): Promise<AssetIngestResult>;
 }
 type AssetResolutionErrorCode = "resolver-unavailable" | "not-found" | "forbidden" | "offline" | "unsupported-type" | "too-large" | "invalid-content" | "decode-failed" | "budget-exceeded" | "aborted" | "unknown";
+declare class AssetResolutionError extends Error {
+    readonly code: AssetResolutionErrorCode;
+    readonly retryable: boolean;
+    readonly ref?: AssetRef | undefined;
+    constructor(code: AssetResolutionErrorCode, retryable: boolean, message: string, ref?: AssetRef | undefined);
+}
 /** Runtime event for a resolution/ingestion failure — never carries credentials or a fetchable location. */
 interface AssetDiagnostic {
     code: AssetResolutionErrorCode;
@@ -57,6 +61,9 @@ interface AssetDiagnostic {
     objectKind: "image" | "custom";
     retryable: boolean;
 }
+declare const SUPPORTED_ASSET_MEDIA_TYPES: readonly ["image/png", "image/jpeg", "image/webp"];
+type SupportedAssetMediaType = (typeof SUPPORTED_ASSET_MEDIA_TYPES)[number];
+declare function clampAssetCacheBytes(value: number | undefined): number;
 
 type Mat2x3 = [number, number, number, number, number, number];
 
@@ -104,6 +111,7 @@ interface CustomBoardObject {
     };
     props: JsonValue;
 }
+declare function cloneCustomObject(object: CustomBoardObject): CustomBoardObject;
 /**
  * The read-only view handed to `describe`. Deep-readonly by construction
  * (not derived via a shallow `Readonly<>`) because `describe` must treat its
@@ -142,6 +150,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;
@@ -175,6 +198,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. */
@@ -330,8 +362,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;
@@ -345,6 +392,146 @@ interface KitchenTimer extends Lockable {
     runningSince?: number;
 }
 
+interface RectangleObject extends Lockable, Hideable {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    /** Corner radius in board units; clamped to at most half the shorter side at render time. */
+    cornerRadius?: number;
+    /** `[0, 1]`; undefined means fully opaque (Phase 4). */
+    opacity?: number;
+    /**
+     * Radians, about the shape's own center `(x + width/2, y - height/2)`.
+     * Undefined means 0 (Phase 3). `x`/`y`/`width`/`height` stay in the
+     * shape's own unrotated local frame — rotation is a separate, applied-last
+     * transform, not baked into them, matching how Stroke/CustomBoardObject
+     * keep geometry and placement independent via their own `matrix`.
+     */
+    rotation?: number;
+}
+interface EllipseObject extends Lockable, Hideable {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    /** `[0, 1]`; undefined means fully opaque (Phase 4). */
+    opacity?: number;
+    /** Radians, about the shape's own center — see RectangleObject's `rotation` doc. */
+    rotation?: number;
+}
+/** `"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, Hideable {
+    id: string;
+    start: BoardPoint;
+    end: BoardPoint;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+}
+/** An endpoint anchored to a normalized position on another object's bounds. */
+interface ConnectorBinding {
+    objectId: string;
+    /** Horizontal and vertical fractions of the target's axis-aligned bounds. */
+    x: number;
+    y: number;
+}
+interface ArrowObject extends Lockable, Hideable {
+    /** Omitted for legacy arrows. Connectors share Arrow's persistence/history contract. */
+    routing?: "straight" | "curved" | "polyline";
+    /** Intermediate board-space vertices for a multi-point connector. */
+    waypoints?: BoardPoint[];
+    startBinding?: ConnectorBinding;
+    endBinding?: ConnectorBinding;
+    id: string;
+    start: BoardPoint;
+    end: BoardPoint;
+    head?: ArrowHeadStyle;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+}
+/**
+ * Triangle(3)/Diamond(4)/Pentagon(5)/Hexagon(6)/Octagon(8) as one shared
+ * type instead of five near-duplicate interfaces — a regular N-gon
+ * inscribed in the same `x`/`y`/`width`/`height`/`rotation` bounding box
+ * Rectangle already uses, parameterized by `sides`. Diamond is exactly a
+ * 4-sided regular polygon with vertex 0 pointing right (not up, like
+ * Triangle/Pentagon/Hexagon) — see `polygonGeometry.ts`'s
+ * `polygonStartAngle`, which encodes each side count's own vertex
+ * orientation so the outline always matches the legacy drag-preview shape.
+ */
+interface PolygonObject extends Lockable, Hideable {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    sides: 3 | 4 | 5 | 6 | 8;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    /** Radians, about the shape's own center — see RectangleObject's `rotation` doc. */
+    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, Hideable {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Vertex count; today's only shipped preset is 5, matching the legacy tool. */
+    points: number;
+    /** `(0, 1)` — inner vertex radius as a fraction of the outer radius. */
+    innerRadiusRatio: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    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, Hideable {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    rotation?: number;
+}
+/**
+ * A logical grouping of other board objects (Phase 3 — Selection,
+ * Transformation & Grouping). Deliberately has no `x`/`y`/`transform` of its
+ * own — a group's bounds are always derived on demand from its (recursively
+ * resolved) children, and "moving/rotating/scaling the group" is exactly a
+ * multi-object transform applied to those children, nothing more. A group
+ * has no renderer/mesh of its own; its only visual presence is the
+ * selection gizmo's bounding box while it's the current selection.
+ *
+ * `children` may itself contain other group ids (nested groups) — expanding
+ * a group into its leaf members is always done by the caller (recursively,
+ * with cycle protection), never assumed here.
+ */
+interface GroupObject extends Lockable, Hideable {
+    id: string;
+    children: string[];
+}
+
 interface BoardPoint {
     x: number;
     y: number;
@@ -358,9 +545,14 @@ interface StrokePoint extends BoardPoint {
      */
     erase?: number;
 }
-/** Which drawing tool made a stroke; undefined means marker (back-compat). */
-type StrokeTool = "marker" | "highlighter";
-interface Stroke extends Lockable {
+/**
+ * Which drawing tool made a stroke; undefined means marker (back-compat).
+ * `"shape"` (rect/ellipse/line/arrow/polygon/star/heart) renders at its
+ * exact configured width with no pressure variance or end taper — a
+ * geometric outline, not an expressive ink mark.
+ */
+type StrokeTool = "marker" | "highlighter" | "shape";
+interface Stroke extends Lockable, Hideable {
     id: string;
     color: string;
     baseWidth: number;
@@ -376,7 +568,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;
@@ -386,7 +578,36 @@ interface SerializedStroke extends Lockable {
     matrix?: [number, number, number, number, number, number];
     clusterId?: string;
 }
+/** A named notebook containing sections. */
+interface BoardNotebook {
+    readonly id: string;
+    readonly name: string;
+    readonly color: string;
+}
+/** A named section containing pages. */
+interface BoardSection {
+    readonly id: string;
+    readonly notebookId: string;
+    readonly name: string;
+    readonly color: string;
+}
+/** An additional page. The first page remains in the document's top-level collections. */
+interface SerializedBoardPage {
+    id: string;
+    sectionId?: string;
+    name: string;
+    content: SerializedDocument;
+}
 interface SerializedDocument {
+    /** Notebook and section metadata. Older boards use an implicit default of each. */
+    notebooks?: BoardNotebook[];
+    sections?: BoardSection[];
+    /** Section of the original first page; defaults to `default`. */
+    pageSectionId?: string;
+    /** Display name of the first page (id `default`). */
+    pageName?: string;
+    /** Additional pages, in sidebar order. Nested pages are not allowed. */
+    pages?: SerializedBoardPage[];
     /** Absent in every historical document; current saves always write 1. */
     schemaVersion?: 1;
     strokes: SerializedStroke[];
@@ -402,6 +623,31 @@ interface SerializedDocument {
     timers?: KitchenTimer[];
     /** Absent in documents saved before Custom board objects existed (ticket #22). */
     customObjects?: CustomBoardObject[];
+    /** Absent in documents saved before semantic Rectangle objects existed (Phase 2). */
+    rectangles?: RectangleObject[];
+    /** Absent in documents saved before semantic Ellipse objects existed (Phase 2). */
+    ellipses?: EllipseObject[];
+    /** Absent in documents saved before Groups existed (Phase 3). */
+    groups?: GroupObject[];
+    /** Absent in documents saved before semantic Line objects existed (Phase 4). */
+    lines?: LineObject[];
+    /** Absent in documents saved before semantic Arrow objects existed (Phase 4). */
+    arrows?: ArrowObject[];
+    /** Absent in documents saved before semantic Polygon objects existed (Phase 4). */
+    polygons?: PolygonObject[];
+    /** Absent in documents saved before semantic Star objects existed (Phase 4). */
+    stars?: StarObject[];
+    /** Absent in documents saved before semantic Heart objects existed (Phase 4). */
+    hearts?: HeartObject[];
+    /**
+     * Every content-object id (every type above except comments, which are
+     * host-synced and never enter this schema) in paint order, back to front.
+     * Absent in documents saved before per-object z-order existed (Phase 3) —
+     * migration synthesizes a default order preserving the old fixed-Z-band
+     * visual stacking exactly, so an existing document never visibly changes
+     * on load; only an explicit reorder action touches this from then on.
+     */
+    objectOrder?: string[];
 }
 /**
  * One collaborator's vote on a note. One per person; toggling removes it.
@@ -415,7 +661,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;
@@ -433,7 +679,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;
@@ -447,7 +693,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;
@@ -464,7 +710,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) —
@@ -487,13 +733,23 @@ interface ImageBlock extends Lockable {
     stamp?: string;
 }
 
+declare const strokeIdBrand: unique symbol;
+type StrokeId = string & {
+    readonly [strokeIdBrand]: "StrokeId";
+};
+
 declare const CURRENT_DOCUMENT_SCHEMA_VERSION: 1;
 type CurrentSerializedStroke = Omit<SerializedStroke, "id"> & {
     id: StrokeId;
 };
-interface CurrentSerializedDocument extends Required<SerializedDocument> {
+interface CurrentSerializedDocument extends Required<Omit<SerializedDocument, "pages" | "pageName" | "notebooks" | "sections" | "pageSectionId">> {
     schemaVersion: typeof CURRENT_DOCUMENT_SCHEMA_VERSION;
     strokes: CurrentSerializedStroke[];
+    pageName?: string;
+    notebooks?: BoardNotebook[];
+    sections?: BoardSection[];
+    pageSectionId?: string;
+    pages?: SerializedBoardPage[];
 }
 
 interface SearchableComment {
@@ -519,6 +775,490 @@ interface SearchHit {
 /** A stamp is a small sticker dropped on the board — not ink, not a photo. */
 type StampKind = "star" | "check" | "ship" | "heart" | "plus" | "fire";
 
+declare const ICON_LIBRARY: readonly [{
+    readonly name: "lucide:check";
+    readonly label: "Check";
+    readonly category: "Status";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M20 6L9 17l-5-5\"/>";
+}, {
+    readonly name: "lucide:x";
+    readonly label: "Cross";
+    readonly category: "Status";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M18 6L6 18M6 6l12 12\"/>";
+}, {
+    readonly name: "lucide:star";
+    readonly label: "Star";
+    readonly category: "Status";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M11.525 2.295a.53.53 0 0 1 .95 0l2.31 4.679a2.12 2.12 0 0 0 1.595 1.16l5.166.756a.53.53 0 0 1 .294.904l-3.736 3.638a2.12 2.12 0 0 0-.611 1.878l.882 5.14a.53.53 0 0 1-.771.56l-4.618-2.428a2.12 2.12 0 0 0-1.973 0L6.396 21.01a.53.53 0 0 1-.77-.56l.881-5.139a2.12 2.12 0 0 0-.611-1.879L2.16 9.795a.53.53 0 0 1 .294-.906l5.165-.755a2.12 2.12 0 0 0 1.597-1.16z\"/>";
+}, {
+    readonly name: "lucide:heart";
+    readonly label: "Heart";
+    readonly category: "Status";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M2 9.5a5.5 5.5 0 0 1 9.591-3.676a.56.56 0 0 0 .818 0A5.49 5.49 0 0 1 22 9.5c0 2.29-1.5 4-3 5.5l-5.492 5.313a2 2 0 0 1-3 .019L5 15c-1.5-1.5-3-3.2-3-5.5\"/>";
+}, {
+    readonly name: "lucide:flag";
+    readonly label: "Flag";
+    readonly category: "Status";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M4 22V4a1 1 0 0 1 .4-.8A6 6 0 0 1 8 2c3 0 5 2 7.333 2q2 0 3.067-.8A1 1 0 0 1 20 4v10a1 1 0 0 1-.4.8A6 6 0 0 1 16 16c-3 0-5-2-8-2a6 6 0 0 0-4 1.528\"/>";
+}, {
+    readonly name: "lucide:bookmark";
+    readonly label: "Bookmark";
+    readonly category: "Status";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M17 3a2 2 0 0 1 2 2v15a1 1 0 0 1-1.496.868l-4.512-2.578a2 2 0 0 0-1.984 0l-4.512 2.578A1 1 0 0 1 5 20V5a2 2 0 0 1 2-2z\"/>";
+}, {
+    readonly name: "lucide:bell";
+    readonly label: "Bell";
+    readonly category: "Status";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M10.268 21a2 2 0 0 0 3.464 0m-10.47-5.674A1 1 0 0 0 4 17h16a1 1 0 0 0 .74-1.673C19.41 13.956 18 12.499 18 8A6 6 0 0 0 6 8c0 4.499-1.411 5.956-2.738 7.326\"/>";
+}, {
+    readonly name: "lucide:info";
+    readonly label: "Info";
+    readonly category: "Status";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><circle cx=\"12\" cy=\"12\" r=\"10\"/><path d=\"M12 16v-4m0-4h.01\"/></g>";
+}, {
+    readonly name: "lucide:circle-alert";
+    readonly label: "Alert";
+    readonly category: "Status";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><circle cx=\"12\" cy=\"12\" r=\"10\"/><path d=\"M12 8v4m0 4h.01\"/></g>";
+}, {
+    readonly name: "lucide:circle-question-mark";
+    readonly label: "Question";
+    readonly category: "Status";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><circle cx=\"12\" cy=\"12\" r=\"10\"/><path d=\"M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3m.08 4h.01\"/></g>";
+}, {
+    readonly name: "lucide:thumbs-up";
+    readonly label: "Thumbs up";
+    readonly category: "Status";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M15 5.88L14 10h5.83a2 2 0 0 1 1.92 2.56l-2.33 8A2 2 0 0 1 17.5 22H4a2 2 0 0 1-2-2v-8a2 2 0 0 1 2-2h2.76a2 2 0 0 0 1.79-1.11L12 2a3.13 3.13 0 0 1 3 3.88M7 10v12\"/>";
+}, {
+    readonly name: "lucide:thumbs-down";
+    readonly label: "Thumbs down";
+    readonly category: "Status";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M9 18.12L10 14H4.17a2 2 0 0 1-1.92-2.56l2.33-8A2 2 0 0 1 6.5 2H20a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2h-2.76a2 2 0 0 0-1.79 1.11L12 22a3.13 3.13 0 0 1-3-3.88M17 14V2\"/>";
+}, {
+    readonly name: "lucide:arrow-up";
+    readonly label: "Arrow up";
+    readonly category: "Arrows";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"m5 12l7-7l7 7m-7 7V5\"/>";
+}, {
+    readonly name: "lucide:arrow-down";
+    readonly label: "Arrow down";
+    readonly category: "Arrows";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M12 5v14m7-7l-7 7l-7-7\"/>";
+}, {
+    readonly name: "lucide:arrow-left";
+    readonly label: "Arrow left";
+    readonly category: "Arrows";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"m12 19l-7-7l7-7m7 7H5\"/>";
+}, {
+    readonly name: "lucide:arrow-right";
+    readonly label: "Arrow right";
+    readonly category: "Arrows";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M5 12h14m-7-7l7 7l-7 7\"/>";
+}, {
+    readonly name: "lucide:arrow-up-right";
+    readonly label: "Arrow up-right";
+    readonly category: "Arrows";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M7 7h10v10M7 17L17 7\"/>";
+}, {
+    readonly name: "lucide:refresh-cw";
+    readonly label: "Refresh";
+    readonly category: "Arrows";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M3 12a9 9 0 0 1 9-9a9.75 9.75 0 0 1 6.74 2.74L21 8\"/><path d=\"M21 3v5h-5m5 4a9 9 0 0 1-9 9a9.75 9.75 0 0 1-6.74-2.74L3 16\"/><path d=\"M8 16H3v5\"/></g>";
+}, {
+    readonly name: "lucide:move";
+    readonly label: "Move";
+    readonly category: "Arrows";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M12 2v20m3-3l-3 3l-3-3M19 9l3 3l-3 3M2 12h20M5 9l-3 3l3 3M9 5l3-3l3 3\"/>";
+}, {
+    readonly name: "lucide:shuffle";
+    readonly label: "Shuffle";
+    readonly category: "Arrows";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"m18 14l4 4l-4 4m0-20l4 4l-4 4\"/><path d=\"M2 18h1.973a4 4 0 0 0 3.3-1.7l5.454-8.6a4 4 0 0 1 3.3-1.7H22M2 6h1.972a4 4 0 0 1 3.6 2.2M22 18h-6.041a4 4 0 0 1-3.3-1.8l-.359-.45\"/></g>";
+}, {
+    readonly name: "lucide:user";
+    readonly label: "User";
+    readonly category: "People";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2\"/><circle cx=\"12\" cy=\"7\" r=\"4\"/></g>";
+}, {
+    readonly name: "lucide:users";
+    readonly label: "Users";
+    readonly category: "People";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2M16 3.128a4 4 0 0 1 0 7.744M22 21v-2a4 4 0 0 0-3-3.87\"/><circle cx=\"9\" cy=\"7\" r=\"4\"/></g>";
+}, {
+    readonly name: "lucide:briefcase";
+    readonly label: "Briefcase";
+    readonly category: "People";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M16 20V4a2 2 0 0 0-2-2h-4a2 2 0 0 0-2 2v16\"/><rect width=\"20\" height=\"14\" x=\"2\" y=\"6\" rx=\"2\"/></g>";
+}, {
+    readonly name: "lucide:building";
+    readonly label: "Building";
+    readonly category: "People";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M12 10h.01M12 14h.01M12 6h.01M16 10h.01M16 14h.01M16 6h.01M8 10h.01M8 14h.01M8 6h.01M9 22v-3a1 1 0 0 1 1-1h4a1 1 0 0 1 1 1v3\"/><rect width=\"16\" height=\"20\" x=\"4\" y=\"2\" rx=\"2\"/></g>";
+}, {
+    readonly name: "lucide:calendar";
+    readonly label: "Calendar";
+    readonly category: "People";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M8 2v3m8-3v3\"/><rect width=\"18\" height=\"18\" x=\"3\" y=\"3\" rx=\"2\"/><path d=\"M3 9h18\"/></g>";
+}, {
+    readonly name: "lucide:clock";
+    readonly label: "Clock";
+    readonly category: "People";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><circle cx=\"12\" cy=\"12\" r=\"10\"/><path d=\"M12 6v6l4 2\"/></g>";
+}, {
+    readonly name: "lucide:mail";
+    readonly label: "Mail";
+    readonly category: "People";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"m22 7l-8.991 5.727a2 2 0 0 1-2.009 0L2 7\"/><rect width=\"20\" height=\"16\" x=\"2\" y=\"4\" rx=\"2\"/></g>";
+}, {
+    readonly name: "lucide:message-circle";
+    readonly label: "Message";
+    readonly category: "People";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M2.992 16.342a2 2 0 0 1 .094 1.167l-1.065 3.29a1 1 0 0 0 1.236 1.168l3.413-.998a2 2 0 0 1 1.099.092a10 10 0 1 0-4.777-4.719\"/>";
+}, {
+    readonly name: "lucide:file";
+    readonly label: "File";
+    readonly category: "Objects";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M6 22a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h8a2.4 2.4 0 0 1 1.704.706l3.588 3.588A2.4 2.4 0 0 1 20 8v12a2 2 0 0 1-2 2z\"/><path d=\"M14 2v5a1 1 0 0 0 1 1h5\"/></g>";
+}, {
+    readonly name: "lucide:folder";
+    readonly label: "Folder";
+    readonly category: "Objects";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2Z\"/>";
+}, {
+    readonly name: "lucide:image";
+    readonly label: "Image";
+    readonly category: "Objects";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><rect width=\"18\" height=\"18\" x=\"3\" y=\"3\" rx=\"2\" ry=\"2\"/><circle cx=\"9\" cy=\"9\" r=\"2\"/><path d=\"m21 15l-3.086-3.086a2 2 0 0 0-2.828 0L6 21\"/></g>";
+}, {
+    readonly name: "lucide:link";
+    readonly label: "Link";
+    readonly category: "Objects";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71\"/><path d=\"M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71\"/></g>";
+}, {
+    readonly name: "lucide:paperclip";
+    readonly label: "Paperclip";
+    readonly category: "Objects";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"m16 6l-8.414 8.586a2 2 0 0 0 2.829 2.829l8.414-8.586a4 4 0 1 0-5.657-5.657l-8.379 8.551a6 6 0 1 0 8.485 8.485l8.379-8.551\"/>";
+}, {
+    readonly name: "lucide:pin";
+    readonly label: "Pin";
+    readonly category: "Objects";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M12 17v5M9 10.76a2 2 0 0 1-1.11 1.79l-1.78.9A2 2 0 0 0 5 15.24V16a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-.76a2 2 0 0 0-1.11-1.79l-1.78-.9A2 2 0 0 1 15 10.76V7a1 1 0 0 1 1-1a2 2 0 0 0 0-4H8a2 2 0 0 0 0 4a1 1 0 0 1 1 1z\"/>";
+}, {
+    readonly name: "lucide:map-pin";
+    readonly label: "Map pin";
+    readonly category: "Objects";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M20 10c0 4.993-5.539 10.193-7.399 11.799a1 1 0 0 1-1.202 0C9.539 20.193 4 14.993 4 10a8 8 0 0 1 16 0\"/><circle cx=\"12\" cy=\"10\" r=\"3\"/></g>";
+}, {
+    readonly name: "lucide:search";
+    readonly label: "Search";
+    readonly category: "Objects";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"m21 21l-4.34-4.34\"/><circle cx=\"11\" cy=\"11\" r=\"8\"/></g>";
+}, {
+    readonly name: "lucide:settings";
+    readonly label: "Settings";
+    readonly category: "Objects";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M9.671 4.136a2.34 2.34 0 0 1 4.659 0a2.34 2.34 0 0 0 3.319 1.915a2.34 2.34 0 0 1 2.33 4.033a2.34 2.34 0 0 0 0 3.831a2.34 2.34 0 0 1-2.33 4.033a2.34 2.34 0 0 0-3.319 1.915a2.34 2.34 0 0 1-4.659 0a2.34 2.34 0 0 0-3.32-1.915a2.34 2.34 0 0 1-2.33-4.033a2.34 2.34 0 0 0 0-3.831A2.34 2.34 0 0 1 6.35 6.051a2.34 2.34 0 0 0 3.319-1.915\"/><circle cx=\"12\" cy=\"12\" r=\"3\"/></g>";
+}, {
+    readonly name: "lucide:trash-2";
+    readonly label: "Trash";
+    readonly category: "Objects";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M10 11v6m4-6v6m5-11v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6M3 6h18M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2\"/>";
+}, {
+    readonly name: "lucide:lock";
+    readonly label: "Lock";
+    readonly category: "Objects";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><rect width=\"18\" height=\"11\" x=\"3\" y=\"11\" rx=\"2\" ry=\"2\"/><path d=\"M7 11V7a5 5 0 0 1 10 0v4\"/></g>";
+}, {
+    readonly name: "lucide:key";
+    readonly label: "Key";
+    readonly category: "Objects";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"m15.5 7.5l2.3 2.3a1 1 0 0 0 1.4 0l2.1-2.1a1 1 0 0 0 0-1.4L19 4m2-2l-9.6 9.6\"/><circle cx=\"7.5\" cy=\"15.5\" r=\"5.5\"/></g>";
+}, {
+    readonly name: "lucide:code";
+    readonly label: "Code";
+    readonly category: "Tech";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"m16 18l6-6l-6-6M8 6l-6 6l6 6\"/>";
+}, {
+    readonly name: "lucide:database";
+    readonly label: "Database";
+    readonly category: "Tech";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><ellipse cx=\"12\" cy=\"5\" rx=\"9\" ry=\"3\"/><path d=\"M3 5v14a9 3 0 0 0 18 0V5\"/><path d=\"M3 12a9 3 0 0 0 18 0\"/></g>";
+}, {
+    readonly name: "lucide:server";
+    readonly label: "Server";
+    readonly category: "Tech";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><rect width=\"20\" height=\"8\" x=\"2\" y=\"2\" rx=\"2\" ry=\"2\"/><rect width=\"20\" height=\"8\" x=\"2\" y=\"14\" rx=\"2\" ry=\"2\"/><path d=\"M6 6h.01M6 18h.01\"/></g>";
+}, {
+    readonly name: "lucide:cloud";
+    readonly label: "Cloud";
+    readonly category: "Tech";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M17.5 19H9a7 7 0 1 1 6.71-9h1.79a4.5 4.5 0 1 1 0 9\"/>";
+}, {
+    readonly name: "lucide:git-branch";
+    readonly label: "Branch";
+    readonly category: "Tech";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M15 6a9 9 0 0 0-9 9V3\"/><circle cx=\"18\" cy=\"6\" r=\"3\"/><circle cx=\"6\" cy=\"18\" r=\"3\"/></g>";
+}, {
+    readonly name: "lucide:terminal";
+    readonly label: "Terminal";
+    readonly category: "Tech";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M12 19h8M4 17l6-6l-6-6\"/>";
+}, {
+    readonly name: "lucide:cpu";
+    readonly label: "CPU";
+    readonly category: "Tech";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M12 20v2m0-20v2m5 16v2m0-20v2M2 12h2m-2 5h2M2 7h2m16 5h2m-2 5h2M20 7h2M7 20v2M7 2v2\"/><rect width=\"16\" height=\"16\" x=\"4\" y=\"4\" rx=\"2\"/><rect width=\"8\" height=\"8\" x=\"8\" y=\"8\" rx=\"1\"/></g>";
+}, {
+    readonly name: "lucide:bug";
+    readonly label: "Bug";
+    readonly category: "Tech";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M12 20v-9m2-4a4 4 0 0 1 4 4v3a6 6 0 0 1-12 0v-3a4 4 0 0 1 4-4zm.12-3.12L16 2\"/><path d=\"M21 21a4 4 0 0 0-3.81-4M21 5a4 4 0 0 1-3.55 3.97M22 13h-4M3 21a4 4 0 0 1 3.81-4M3 5a4 4 0 0 0 3.55 3.97M6 13H2M8 2l1.88 1.88M9 7.13V6a3 3 0 1 1 6 0v1.13\"/></g>";
+}, {
+    readonly name: "lucide:lightbulb";
+    readonly label: "Idea";
+    readonly category: "Ideas";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M15 14c.2-1 .7-1.7 1.5-2.5c1-.9 1.5-2.2 1.5-3.5A6 6 0 0 0 6 8c0 1 .2 2.2 1.5 3.5c.7.7 1.3 1.5 1.5 2.5m0 4h6m-5 4h4\"/>";
+}, {
+    readonly name: "lucide:zap";
+    readonly label: "Zap";
+    readonly category: "Ideas";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M15.914 4a1.5 1.5 0 0 0-2.474-1.561l-9 9A1.5 1.5 0 0 0 5.5 14h4.002a.5.5 0 0 1 .471.666L8.086 20a1.5 1.5 0 0 0 2.475 1.56l9-9A1.5 1.5 0 0 0 18.5 10h-3.997a.5.5 0 0 1-.472-.667z\"/>";
+}, {
+    readonly name: "lucide:target";
+    readonly label: "Target";
+    readonly category: "Ideas";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><circle cx=\"12\" cy=\"12\" r=\"10\"/><circle cx=\"12\" cy=\"12\" r=\"6\"/><circle cx=\"12\" cy=\"12\" r=\"2\"/></g>";
+}, {
+    readonly name: "lucide:rocket";
+    readonly label: "Rocket";
+    readonly category: "Ideas";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M12 15v5s3.03-.55 4-2c1.08-1.62 0-5 0-5M4.5 16.5c-1.5 1.26-2 5-2 5s3.74-.5 5-2c.71-.84.7-2.13-.09-2.91a2.18 2.18 0 0 0-2.91-.09\"/><path d=\"M9 12a22 22 0 0 1 2-3.95A12.88 12.88 0 0 1 22 2c0 2.72-.78 7.5-6 11a22.4 22.4 0 0 1-4 2z\"/><path d=\"M9 12H4s.55-3.03 2-4c1.62-1.08 5 .05 5 .05\"/></g>";
+}, {
+    readonly name: "lucide:trophy";
+    readonly label: "Trophy";
+    readonly category: "Ideas";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M10 14.66V17a1 1 0 0 1-1 1a2 2 0 0 0-2 2v2m7-7.34V17a1 1 0 0 0 1 1a2 2 0 0 1 2 2v2m.916-12H19.5A2.5 2.5 0 0 0 22 7.5V5a1 1 0 0 0-1-1h-3M4 22h16\"/><path d=\"M6 9a6 6 0 0 0 12 0V3a1 1 0 0 0-1-1H7a1 1 0 0 0-1 1z\"/><path d=\"M6.084 10H4.5A2.5 2.5 0 0 1 2 7.5V5a1 1 0 0 1 1-1h3\"/></g>";
+}, {
+    readonly name: "lucide:gift";
+    readonly label: "Gift";
+    readonly category: "Ideas";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M12 7v14m8-10v8a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2v-8m3.5-4a1 1 0 0 1 0-5A4.8 8 0 0 1 12 7a4.8 8 0 0 1 4.5-5a1 1 0 0 1 0 5\"/><rect width=\"18\" height=\"4\" x=\"3\" y=\"7\" rx=\"1\"/></g>";
+}, {
+    readonly name: "lucide:coffee";
+    readonly label: "Coffee";
+    readonly category: "Ideas";
+    readonly body: "<path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M10 2v2m4-2v2m2 4a1 1 0 0 1 1 1v8a4 4 0 0 1-4 4H7a4 4 0 0 1-4-4V9a1 1 0 0 1 1-1h14a4 4 0 1 1 0 8h-1M6 2v2\"/>";
+}, {
+    readonly name: "lucide:smile";
+    readonly label: "Smile";
+    readonly category: "Ideas";
+    readonly body: "<g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><circle cx=\"12\" cy=\"12\" r=\"10\"/><path d=\"M8 14s1.5 2 4 2s4-2 4-2M9 9h.01M15 9h.01\"/></g>";
+}];
+/** Every vendored icon's id, as a literal union. */
+type IconName = (typeof ICON_LIBRARY)[number]["name"];
+
+declare const EMOJI_LIBRARY: readonly [{
+    readonly name: "emoji:grinning";
+    readonly label: "Grinning face";
+    readonly category: "Smileys";
+    readonly char: "😀";
+}, {
+    readonly name: "emoji:joy";
+    readonly label: "Tears of joy";
+    readonly category: "Smileys";
+    readonly char: "😂";
+}, {
+    readonly name: "emoji:smiling";
+    readonly label: "Smiling face";
+    readonly category: "Smileys";
+    readonly char: "😊";
+}, {
+    readonly name: "emoji:heart-eyes";
+    readonly label: "Heart eyes";
+    readonly category: "Smileys";
+    readonly char: "😍";
+}, {
+    readonly name: "emoji:thinking";
+    readonly label: "Thinking face";
+    readonly category: "Smileys";
+    readonly char: "🤔";
+}, {
+    readonly name: "emoji:sunglasses";
+    readonly label: "Sunglasses";
+    readonly category: "Smileys";
+    readonly char: "😎";
+}, {
+    readonly name: "emoji:crying";
+    readonly label: "Crying face";
+    readonly category: "Smileys";
+    readonly char: "😢";
+}, {
+    readonly name: "emoji:angry";
+    readonly label: "Angry face";
+    readonly category: "Smileys";
+    readonly char: "😡";
+}, {
+    readonly name: "emoji:sleeping";
+    readonly label: "Sleeping face";
+    readonly category: "Smileys";
+    readonly char: "😴";
+}, {
+    readonly name: "emoji:mind-blown";
+    readonly label: "Mind blown";
+    readonly category: "Smileys";
+    readonly char: "🤯";
+}, {
+    readonly name: "emoji:grimacing";
+    readonly label: "Grimacing face";
+    readonly category: "Smileys";
+    readonly char: "😬";
+}, {
+    readonly name: "emoji:partying";
+    readonly label: "Partying face";
+    readonly category: "Smileys";
+    readonly char: "🥳";
+}, {
+    readonly name: "emoji:thumbs-up";
+    readonly label: "Thumbs up emoji";
+    readonly category: "Gestures";
+    readonly char: "👍";
+}, {
+    readonly name: "emoji:thumbs-down";
+    readonly label: "Thumbs down emoji";
+    readonly category: "Gestures";
+    readonly char: "👎";
+}, {
+    readonly name: "emoji:clap";
+    readonly label: "Clapping hands";
+    readonly category: "Gestures";
+    readonly char: "👏";
+}, {
+    readonly name: "emoji:raised-hands";
+    readonly label: "Raised hands";
+    readonly category: "Gestures";
+    readonly char: "🙌";
+}, {
+    readonly name: "emoji:folded-hands";
+    readonly label: "Folded hands";
+    readonly category: "Gestures";
+    readonly char: "🙏";
+}, {
+    readonly name: "emoji:eyes";
+    readonly label: "Eyes";
+    readonly category: "Gestures";
+    readonly char: "👀";
+}, {
+    readonly name: "emoji:muscle";
+    readonly label: "Flexed biceps";
+    readonly category: "Gestures";
+    readonly char: "💪";
+}, {
+    readonly name: "emoji:wave";
+    readonly label: "Waving hand";
+    readonly category: "Gestures";
+    readonly char: "👋";
+}, {
+    readonly name: "emoji:red-heart";
+    readonly label: "Red heart";
+    readonly category: "Symbols";
+    readonly char: "❤️";
+}, {
+    readonly name: "emoji:fire";
+    readonly label: "Flame";
+    readonly category: "Symbols";
+    readonly char: "🔥";
+}, {
+    readonly name: "emoji:star";
+    readonly label: "Medium star";
+    readonly category: "Symbols";
+    readonly char: "⭐";
+}, {
+    readonly name: "emoji:check";
+    readonly label: "Check mark button";
+    readonly category: "Symbols";
+    readonly char: "✅";
+}, {
+    readonly name: "emoji:cross";
+    readonly label: "Cross mark";
+    readonly category: "Symbols";
+    readonly char: "❌";
+}, {
+    readonly name: "emoji:warning";
+    readonly label: "Warning sign";
+    readonly category: "Symbols";
+    readonly char: "⚠️";
+}, {
+    readonly name: "emoji:question";
+    readonly label: "Red question mark";
+    readonly category: "Symbols";
+    readonly char: "❓";
+}, {
+    readonly name: "emoji:hundred";
+    readonly label: "Hundred points";
+    readonly category: "Symbols";
+    readonly char: "💯";
+}, {
+    readonly name: "emoji:light-bulb";
+    readonly label: "Light bulb";
+    readonly category: "Symbols";
+    readonly char: "💡";
+}, {
+    readonly name: "emoji:bullseye";
+    readonly label: "Bullseye";
+    readonly category: "Symbols";
+    readonly char: "🎯";
+}, {
+    readonly name: "emoji:party-popper";
+    readonly label: "Party popper";
+    readonly category: "Objects";
+    readonly char: "🎉";
+}, {
+    readonly name: "emoji:rocket";
+    readonly label: "Rocket emoji";
+    readonly category: "Objects";
+    readonly char: "🚀";
+}, {
+    readonly name: "emoji:trophy";
+    readonly label: "Trophy emoji";
+    readonly category: "Objects";
+    readonly char: "🏆";
+}, {
+    readonly name: "emoji:pushpin";
+    readonly label: "Pushpin";
+    readonly category: "Objects";
+    readonly char: "📌";
+}, {
+    readonly name: "emoji:memo";
+    readonly label: "Memo";
+    readonly category: "Objects";
+    readonly char: "📝";
+}, {
+    readonly name: "emoji:calendar";
+    readonly label: "Tear-off calendar";
+    readonly category: "Objects";
+    readonly char: "📅";
+}, {
+    readonly name: "emoji:alarm-clock";
+    readonly label: "Alarm clock";
+    readonly category: "Objects";
+    readonly char: "⏰";
+}, {
+    readonly name: "emoji:speech-balloon";
+    readonly label: "Speech balloon";
+    readonly category: "Objects";
+    readonly char: "💬";
+}];
+type EmojiName = (typeof EMOJI_LIBRARY)[number]["name"];
+
+/**
+ * What the stamp tool will drop next: one of the six built-in stamp-pad
+ * stickers, an emoji, or any vendored icon. All land on the board the same way
+ * — as an image whose `stamp` field records which one it was (see `placeStamp`).
+ */
+type StickerKind = StampKind | EmojiName | IconName;
+
 type SerializedBoardDocument = CurrentSerializedDocument;
 
 interface AssetExportFailure {
@@ -559,16 +1299,30 @@ interface BoardStyle {
     readonly noteColor: string;
     readonly tableRows: number;
     readonly tableCols: number;
-    readonly stampKind: StampKind;
+    /** A stamp-pad kind or any vendored icon name (see `ICON_LIBRARY`). */
+    readonly stampKind: StickerKind;
     readonly timerDurationMs: number;
 }
+/** A page listed in the Board navigator. `default` is the original first page. */
+interface BoardPage {
+    readonly id: string;
+    readonly name: string;
+    readonly sectionId: string;
+}
 interface BoardSnapshot {
+    readonly notebooks: readonly BoardNotebook[];
+    readonly sections: readonly BoardSection[];
+    readonly activeNotebookId: string;
+    readonly activeSectionId: string;
+    readonly pages: readonly BoardPage[];
+    readonly activePageId: string;
     readonly status: "loading" | "ready" | "disposed";
     readonly documentId: string;
     readonly tool: BuiltInTool | (string & {});
     readonly zoom: number;
     readonly readOnly: boolean;
     readonly selection: readonly string[];
+    readonly focusedItem: FocusedItem | null;
     readonly strokeCount: number;
     readonly objectCount: number;
     readonly canUndo: boolean;
@@ -579,6 +1333,27 @@ interface BoardSnapshot {
         readonly collaboration: CollaborationSnapshot;
     };
 }
+/**
+ * `selection` collapsed into the one thing a selected-object toolbar needs:
+ * what's selected, its lock state, and where to anchor above it. `null`
+ * when nothing is selected, or when the selection mixes types/objects that
+ * don't resolve to a single focus (anything but one object, or several
+ * strokes sharing a `clusterId` — a multi-stroke shape).
+ *
+ * Raw lock fields, not a derived `canUnlock` — this API has no notion of
+ * "the local user" to judge that against (see `canUnlockItem` in `../core`,
+ * which takes a `userId` the Host already owns). A Custom object's lock
+ * shape doesn't carry a holder name, so it always reports `locked: false`
+ * here, matching the engine's own internal selection-badge behavior.
+ */
+interface FocusedItem {
+    readonly type: "stroke" | "note" | "text" | "table" | "image" | "timer" | "rectangle" | "ellipse" | "group" | "line" | "arrow" | "polygon" | "star" | "heart" | "custom";
+    readonly id: string;
+    readonly locked: boolean;
+    readonly lockedBy?: string;
+    readonly lockedByName?: string;
+    readonly screenPosition?: ScreenPoint;
+}
 interface BoardControllerError {
     source: "controller" | "renderer" | "persistence" | "collaboration";
     code: string;
@@ -587,6 +1362,9 @@ interface BoardControllerError {
 }
 interface BoardEventMap {
     change: BoardSnapshot;
+    "page-changing": {
+        pageId: string;
+    };
     "tool-change": {
         tool: string;
     };
@@ -653,6 +1431,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;
@@ -672,6 +1452,27 @@ interface BoardView {
     y: number;
     zoom: number;
 }
+/**
+ * The rendered board surface's color, reference grid, and shape stroke
+ * width — the subset of {@link ScrawlTheme} that reaches the rendering
+ * engine directly (everything else is UI-chrome-only, applied as CSS). Any
+ * field left unset keeps its current value.
+ */
+interface BoardThemeOptions {
+    /** The board/canvas background color — distinct from UI chrome panels. */
+    surface?: string;
+    /** `"flat"` (default): a plain, uniform board surface. `"textured"`: a subtle "melamine" micro-noise + satin sheen, like a physical whiteboard. */
+    surfaceTexture?: "flat" | "textured";
+    /** `"none"` (default) keeps the board a plain surface; `"line"`/`"dot"` draw a zoom-adaptive reference grid. */
+    gridMode?: "none" | "line" | "dot";
+    gridColor?: string;
+    /** Grid spacing in board units at 100% zoom. Ignored when `gridMode` is `"none"`. */
+    gridSpacing?: number;
+    /** On-screen grid line/dot width in CSS pixels — stays this width at any zoom, since the grid is a reference aid, not content. */
+    gridLineWidth?: number;
+    /** Shape (rectangle, ellipse, arrow, ...) border width, in board units — scales with zoom like ink, since it's part of the drawn content. */
+    shapeStrokeWidth?: number;
+}
 /**
  * A Host-owned comment, summarized for Board-side search and marker
  * rendering. Comments are not Document content — they carry no undo
@@ -695,9 +1496,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;
@@ -706,6 +1510,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
@@ -733,6 +1545,22 @@ type BoardObject = ({
 } & ImageBlock) | ({
     type: "timer";
 } & KitchenTimer) | ({
+    type: "rectangle";
+} & RectangleObject) | ({
+    type: "ellipse";
+} & EllipseObject) | ({
+    type: "group";
+} & GroupObject) | ({
+    type: "line";
+} & LineObject) | ({
+    type: "arrow";
+} & ArrowObject) | ({
+    type: "polygon";
+} & PolygonObject) | ({
+    type: "star";
+} & StarObject) | ({
+    type: "heart";
+} & HeartObject) | ({
     type: "custom";
     customType: ObjectType;
 } & Omit<CustomBoardObject, "type">);
@@ -761,6 +1589,30 @@ type BoardObjectInput = {
     type: "timer";
     id?: string;
 } & Omit<KitchenTimer, "id">) | ({
+    type: "rectangle";
+    id?: string;
+} & Omit<RectangleObject, "id">) | ({
+    type: "ellipse";
+    id?: string;
+} & Omit<EllipseObject, "id">) | ({
+    type: "group";
+    id?: string;
+} & Omit<GroupObject, "id">) | ({
+    type: "line";
+    id?: string;
+} & Omit<LineObject, "id">) | ({
+    type: "arrow";
+    id?: string;
+} & Omit<ArrowObject, "id">) | ({
+    type: "polygon";
+    id?: string;
+} & Omit<PolygonObject, "id">) | ({
+    type: "star";
+    id?: string;
+} & Omit<StarObject, "id">) | ({
+    type: "heart";
+    id?: string;
+} & Omit<HeartObject, "id">) | ({
     type: "custom";
     id?: string;
     customType: ObjectType;
@@ -791,10 +1643,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
@@ -818,14 +1694,61 @@ 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;
     kind: "upsert" | "restore" | "remove";
-    objectType: "stroke" | "note" | "text" | "table" | "image" | "timer" | "custom";
+    objectType: "stroke" | "note" | "text" | "table" | "image" | "timer" | "rectangle" | "ellipse" | "group" | "line" | "arrow" | "polygon" | "star" | "heart" | "custom"
+    /**
+     * A whole-document paint-order sync (Phase 3), not a per-object type —
+     * `objectId` is always the fixed sentinel `"order"` and `payload` is
+     * `{ order: string[] }`. The only `objectType` with no matching
+     * `BoardObject`/document collection; kept in this same union (rather
+     * than a separate wire message) so it flows through the existing
+     * `PersistenceAdapter`/`CollaborationAdapter` opaquely, unchanged.
+     */
+     | "order" | "page" | "notebook" | "section";
+    /** Absent for the original page; scopes content and order Ops to an additional page. */
+    pageId?: string;
     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;
@@ -836,14 +1759,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 {
@@ -863,24 +1844,133 @@ interface CreateBoardControllerOptions {
      * Trusted Custom tool/object registrations (ticket #22, design:
      * docs/research/extension-contracts.md). Validated atomically at
      * construction; registration failure throws before any controller is
-     * returned. Not yet re-exported from a public package entry point —
-     * internal-only until the reference Extension proves the seam.
+     * returned.
      */
     extensions?: readonly ScrawlExtension[];
     /**
      * Optional Host-managed Asset capabilities (ticket #23, design:
      * docs/research/asset-resolution-resource-policy.md). Without a
      * resolver, referenced Assets preserve their Document geometry and
-     * render an accessible placeholder. Not yet re-exported from a public
-     * package entry point — internal-only until the reference resolver
-     * proves the seam, matching how `extensions` is scoped.
+     * render an accessible placeholder.
      */
     assetResolver?: AssetResolver;
     assetIngestor?: AssetIngestor;
     /** Clamped to 64–512MiB; defaults to 256MiB. */
     assetCacheBytes?: number;
+    /**
+     * The rendered board surface's color and reference grid. Defaults to the
+     * light theme preset's values; `<Scrawl>` keeps this current across theme
+     * changes via `boardTheme.set` below — a headless/browser-tier Host that
+     * 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 notebooks: {
+        /** Create a notebook containing one section and an empty page; select it. */
+        add(name?: string): string;
+        select(id: string): void;
+        rename(id: string, name: string): void;
+        list(): readonly BoardNotebook[];
+        current(): string;
+    };
+    readonly sections: {
+        /** Create a section in the current or specified notebook, with one empty page. */
+        add(name?: string, notebookId?: string): string;
+        select(id: string): void;
+        rename(id: string, name: string): void;
+        list(notebookId?: string): readonly BoardSection[];
+        current(): string;
+    };
+    readonly pages: {
+        /** Add an empty page and switch to it. */
+        add(name?: string, sectionId?: string): string;
+        select(id: string): void;
+        rename(id: string, name: string): void;
+        list(sectionId?: string): readonly BoardPage[];
+        current(): string;
+    };
     readonly document: ReadonlyBoardDocument;
     readonly tools: {
         select(tool: BuiltInTool | (string & {})): void;
@@ -895,7 +1985,7 @@ interface BoardController {
             noteColor: string;
             tableRows: number;
             tableCols: number;
-            stampKind: StampKind;
+            stampKind: StickerKind;
             timerDurationMs: number;
         }>): void;
         current(): BoardStyle;
@@ -904,10 +1994,35 @@ interface BoardController {
         undo(): void;
         redo(): void;
     };
+    readonly boardTheme: {
+        /** Live update of the board surface color/grid/shape-stroke-width — the controller's identity stays fixed across theme changes. */
+        set(theme: BoardThemeOptions): void;
+    };
     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;
+        /**
+         * Tell the canvas an inline text editor is open over a text block (`{ id }`)
+         * or a table cell (`{ id, row, col }`), so it stops drawing that text until
+         * the editor closes (`null`) and the two copies don't overlap. The default
+         * UI's inline editors call this; a Host with its own editors should too.
+         * Presentation only — never touches the Document. A no-op when headless.
+         */
+        setInlineEditing(target: {
+            id: string;
+            row?: number;
+            col?: number;
+        } | null): void;
         get(): BoardView;
         boardToScreen(point: BoardPoint): ScreenPoint;
         screenToBoard(point: ScreenPoint): BoardPoint;
@@ -916,6 +2031,75 @@ interface BoardController {
         add(input: BoardObjectInput): string;
         update(id: string, patch: BoardObjectPatch): void;
         remove(ids: readonly string[]): void;
+        /**
+         * Clone each given object as a new, unlocked copy offset by a small
+         * fixed cascade (matching the Duplicate affordance's established Host
+         * convention), as one undoable step. Order-preserving: `result[i]` is
+         * the clone of `ids[i]`. Strokes that share a `clusterId` among the
+         * given ids get a single fresh shared `clusterId` in the result, so
+         * duplicating a whole multi-stroke shape (e.g. an arrow's shaft + head)
+         * keeps it one shape — pass every member's id together, not just one.
+         * Unknown ids are silently skipped, matching `remove`'s convention.
+         */
+        duplicate(ids: readonly string[]): readonly string[];
+        /**
+         * Creates a new Group referencing `ids` as its children and returns its
+         * id, as one undoable step. Unknown ids are silently skipped, matching
+         * `duplicate`/`remove`'s convention. A child id that's itself a group
+         * makes a nested group — expanding nested groups into their leaf
+         * members is always the caller's job, never assumed here (matches the
+         * document-model `GroupObject` itself).
+         */
+        group(ids: readonly string[]): string;
+        /**
+         * Dissolves one group, returning its immediate children's ids (a nested
+         * subgroup among them stays intact, itself still a group) — the group
+         * record itself is removed, the children are untouched. A no-op
+         * (returns `[]`) if `groupId` isn't a group.
+         */
+        ungroup(groupId: string): readonly string[];
+        /**
+         * Aligns every given object's matching edge/center to the corresponding
+         * edge/center of their combined bounding box, as one undoable step.
+         * `"top"`/`"bottom"` follow board space's Y-up convention (`"top"` is
+         * the larger Y). Ids that don't resolve, or resolve to a Group (which
+         * has no position of its own), are skipped. A no-op under 2 resolvable
+         * ids — there's nothing to align relative to.
+         */
+        align(ids: readonly string[], edge: "left" | "right" | "top" | "bottom" | "centerX" | "centerY"): void;
+        /**
+         * Spaces the middle objects' centers evenly between the first and last
+         * (sorted along `axis`), as one undoable step — the two endpoints don't
+         * move. Ids that don't resolve, or resolve to a Group, are skipped. A
+         * no-op under 3 resolvable ids — there's no "middle" to distribute.
+         */
+        distribute(ids: readonly string[], axis: "x" | "y"): void;
+        /**
+         * Snapshots `ids` (recursively expanded through any group, same as
+         * `duplicate`) into an internal in-memory clipboard — never
+         * `navigator.clipboard`, scoped to this one controller instance and
+         * replaced wholesale by the next `copy`/`cut`. Read-only; works even
+         * on a read-only board.
+         */
+        copy(ids: readonly string[]): void;
+        /** `copy`, then removes every resolved object (recursively through any group) as one undoable step. */
+        cut(ids: readonly string[]): void;
+        /**
+         * Clones the current clipboard contents onto the board as one undoable
+         * step, offset the same small cascade `duplicate` uses (no cursor
+         * position to paste relative to yet). Returns the new top-level ids —
+         * a pasted group's own id stands for its (also-pasted) children, which
+         * 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;
@@ -926,6 +2110,29 @@ interface BoardController {
         };
         select(ids: readonly string[]): void;
         import(document: SerializedBoardDocument): readonly string[];
+        /**
+         * Toggle lock state for the current selection (or focused note/text/
+         * table/image/timer), matching whatever a single Host lock/unlock
+         * control already does per object type. A no-op with nothing selected,
+         * on a headless board, or when every actionable target is locked by
+         * 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;
@@ -954,6 +2161,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;
@@ -979,6 +2195,7 @@ interface BoardController {
     }>;
     dispose(): Promise<void>;
 }
+/** @deprecated Use `BoardController.getSnapshot()`'s return type instead. */
 type LocalBoardSnapshot = {
     documentId: string;
     selectedStrokeId: string | null;
@@ -987,6 +2204,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;
@@ -1000,30 +2218,83 @@ type LocalBoard = {
 
 type ScrawlThemePreset = "light" | "dark";
 type ScrawlDensity = "comfortable" | "compact";
+type ScrawlGridMode = "none" | "line" | "dot";
+type ScrawlSurfaceTexture = "flat" | "textured";
+/**
+ * Every field is optional — anything you don't set falls back to the
+ * chosen `preset` ("light" or "dark", see {@link resolveScrawlTheme}).
+ * Overrides are semantic, board-local runtime configuration: they never
+ * get written into the Document or into exports, so switching themes is
+ * always non-destructive.
+ */
 interface ScrawlTheme {
+    /** UI chrome background — toolbar/panel base surface. Distinct from `boardSurface` (the canvas itself). */
     surface?: string;
+    /** UI chrome background, one step up from `surface` — popovers, dropdowns, elevated panels. */
     surfaceRaised?: string;
+    /** UI chrome background, one step down from `surface` — subtle fills, hover states. */
     surfaceMuted?: string;
+    /** Primary UI text color. Checked for contrast against `surface`. */
     text?: string;
+    /** Secondary/de-emphasized UI text color. Checked for contrast against `surface`. */
     textMuted?: string;
+    /** Borders and dividers between UI chrome elements. */
     edge?: string;
+    /**
+     * Brand accent color. Drives the active/selected state of toolbar
+     * controls (e.g. the active tool button): its icon/text render in this
+     * color, and its background is automatically derived as a light tint of
+     * it (via `color-mix`) — set this one token and both follow.
+     */
+    primary?: string;
+    /** Focus ring color. Checked for contrast against `surface`. */
     focus?: string;
+    /** Selection highlight color (e.g. selected list items, not board object selection). */
     selection?: string;
+    /** Destructive/error state color (delete confirmations, error text). */
     danger?: string;
+    /** Warning state color. */
     warning?: string;
+    /** Success/confirmation state color. */
     success?: string;
+    /** Font stack for UI chrome (toolbar labels, menus, dialogs). */
     uiFontFamily?: string;
+    /** Font stack for board content and data (e.g. table cell text). */
     dataFontFamily?: string;
+    /** Base UI font size in px. Range: 12–24. */
     baseFontSize?: number;
+    /** Regular UI font weight. Range: 300–900. */
     regularWeight?: number;
+    /** Emphasized UI font weight (headings, active states). Range: 300–900. */
     strongWeight?: number;
+    /** Corner radius for small controls (buttons, inputs) in px. Range: 0–32. */
     controlRadius?: number;
+    /** Corner radius for panels/dialogs in px. Range: 0–32. */
     panelRadius?: number;
+    /** CSS `box-shadow` value for subtle elevation (e.g. toolbar). */
     elevationLow?: string;
+    /** CSS `box-shadow` value for prominent elevation (e.g. modals). */
     elevationHigh?: string;
+    /** UI transition duration in ms. Range: 0–500. */
     motionDuration?: number;
+    /** CSS easing function for UI transitions. */
     motionEasing?: string;
+    /** UI chrome spacing/sizing scale. */
     density?: ScrawlDensity;
+    /** The rendered board/canvas surface color — distinct from `surface` (UI chrome panels). */
+    boardSurface?: string;
+    /** `"flat"` (default): a plain, uniform board surface. `"textured"`: a subtle "melamine" micro-noise + satin sheen, like a physical whiteboard. */
+    boardSurfaceTexture?: ScrawlSurfaceTexture;
+    /** `"none"` (default) keeps the board a plain surface; `"line"`/`"dot"` draw a zoom-adaptive reference grid. */
+    gridMode?: ScrawlGridMode;
+    /** Grid line/dot color. Ignored when `gridMode` is `"none"`. */
+    gridColor?: string;
+    /** Grid spacing in board units at 100% zoom. Ignored when `gridMode` is `"none"`. */
+    gridSpacing?: number;
+    /** On-screen grid line/dot width in CSS pixels. Range: 0.5–8. A reference aid, so unlike shape/ink strokes it stays this width at any zoom. */
+    gridLineWidth?: number;
+    /** Shape (rectangle, ellipse, arrow, ...) border width, in board units. Range: 0.01–5. Scales with zoom like ink, since it's part of the drawn content. */
+    shapeStrokeWidth?: number;
 }
 type ResolvedScrawlTheme = Required<ScrawlTheme>;
 interface ScrawlThemeDiagnostic {
@@ -1040,6 +2311,11 @@ declare const scrawlThemePresets: Readonly<Record<ScrawlThemePreset, Readonly<Re
 declare function validateScrawlTheme(theme: ScrawlTheme | Record<string, unknown>): ScrawlThemeDiagnostic[];
 declare function resolveScrawlTheme(preset?: ScrawlThemePreset, theme?: ScrawlTheme | Record<string, unknown>): ScrawlResolvedTheme;
 
+interface CommentAuthor {
+    name: string;
+    color?: string;
+}
+
 interface DefaultBoardChromeProps {
     controller: BoardController;
     snapshot: BoardSnapshot;
@@ -1048,8 +2324,22 @@ interface DefaultBoardChromeProps {
     style?: React.CSSProperties;
     regions?: Partial<Record<DefaultUIRegion, boolean>>;
     slots?: DefaultUISlots;
+    /**
+     * Override any built-in tool icon. Tools without an override keep the
+     * SDK's outline icon. Accessible labels and shortcut tooltips are preserved.
+     */
+    icons?: Partial<Record<BuiltInTool, ReactNode>>;
+    /** Name (and pin colour) shown on comments left through the default comment UI. Defaults to "You". */
+    commentAuthor?: CommentAuthor;
 }
-type DefaultUIRegion = "tools" | "history" | "view" | "style" | "search" | "import" | "export" | "inlineEditing" | "styleShelf";
+
+/**
+ * `comments` is the built-in comment composer/thread, which keeps comments for
+ * the session; `images` is the Image tool's file picker plus drag-and-drop.
+ * Turn either off when the Host handles `comment-draft-request`/
+ * `comment-open-request` or `import-request` itself.
+ */
+type DefaultUIRegion = "tools" | "history" | "view" | "style" | "search" | "import" | "export" | "inlineEditing" | "styleShelf" | "focusedItemToolbar" | "emptyState" | "pages" | "comments" | "images";
 /** Props for the toolbar/topBar/stylePanel/contextMenu slots. */
 interface BoardSlotProps {
     controller: BoardController;
@@ -1077,7 +2367,7 @@ interface DefaultUISlots {
      */
     contextMenu?: ComponentType<BoardSlotProps> | null;
 }
-declare function DefaultBoardChrome({ controller, snapshot, renderPortal, className, style, regions, slots }: DefaultBoardChromeProps): react.JSX.Element;
+declare function DefaultBoardChrome({ controller, snapshot, renderPortal, className, style, regions, slots, icons, commentAuthor }: DefaultBoardChromeProps): react.JSX.Element;
 
 interface InlineEditorsProps {
     controller: BoardController;
@@ -1102,12 +2392,68 @@ interface MultiplayerCursorsProps {
  */
 declare function MultiplayerCursors({ controller, onSelectUser, onJumpToUser }: MultiplayerCursorsProps): react.JSX.Element | null;
 
+interface FocusedItemToolbarProps {
+    controller: BoardController;
+    snapshot: BoardSnapshot;
+}
+/**
+ * Floating toolbar above the focused note, shape, text block, or semantic
+ * Rectangle/Ellipse — Colour, Size (note/text) or Width (shape), Fill/Stroke
+ * (Rectangle/Ellipse), Lock/Unlock, Duplicate, Delete. Images (photos and
+ * placed emoji/icons) get Lock/Duplicate/Delete only — the native gizmo
+ * already resizes them. Table/timer/custom objects and plain (non-shape) ink
+ * strokes never get a toolbar here — out of scope for this destination.
+ *
+ * Rectangle/Ellipse (Phase 2) are a second, parallel "shape" concept from
+ * the legacy ink-stroke shape below: both draw from the same toolbar
+ * buttons and look the same to a user, but a Rectangle/Ellipse is a real
+ * BoardObject with its own resize handles (independent width/height,
+ * `ShapeResizeHandle`), while a legacy shape-stroke keeps going through the
+ * native selection gizmo. This duality is deliberate and temporary — see
+ * docs/reports/phase-2-document-object-model.md.
+ *
+ * Lock/Unlock carries no per-user ownership gating: nothing else in this
+ * SDK enforces lock ownership either (`content.update` never checks
+ * `locked`, and the engine's own internal unlock check has no way for a
+ * Host to ever supply a real user id) — locking is advisory UI state
+ * throughout, and this toolbar matches that rather than inventing an
+ * enforcement story alone.
+ *
+ * A shape can be several strokes sharing one `clusterId` (e.g. an arrow's
+ * shaft + head) — every action here applies to the whole cluster. Resolved
+ * via `query.all()` + `clusterId`, not `snapshot.selection`: a canvas click
+ * on one member selects every member internally, but the public selection
+ * bridge only ever reports one id (`FocusedItem.id` is singular by design),
+ * so reconstructing the cluster from the document is the reliable path
+ * regardless of how the selection was made.
+ *
+ * A focused note also gets drag-to-resize corner handles — notes have no
+ * gizmo of their own (the native selection gizmo is ink-stroke/shape-only),
+ * so this is that capability's default-ui-owned equivalent. Proportional
+ * (always-square) resize from the note's own centre, clamped to
+ * `[MIN_SIZE, MAX_SIZE]`, independent of which corner is grabbed.
+ */
+declare function FocusedItemToolbar({ controller, snapshot }: FocusedItemToolbarProps): react.JSX.Element | null;
+
 interface StyleShelfProps {
     controller: BoardController;
     snapshot: BoardSnapshot;
+    /**
+     * Root-relative point beside the active tool. DefaultBoardChrome supplies
+     * this automatically and keeps the shelf within the board bounds.
+     */
+    anchor?: {
+        x: number;
+        y: number;
+    };
+    /**
+     * Called after an option is picked (not while typing table dimensions or a
+     * sticker search). DefaultBoardChrome uses it to close the shelf.
+     */
+    onChoose?(): void;
 }
 /** Contextual per-tool style controls — visible while a styleable tool is active. */
-declare function StyleShelf({ controller, snapshot }: StyleShelfProps): react.JSX.Element | null;
+declare function StyleShelf({ controller, snapshot, anchor, onChoose }: StyleShelfProps): react.JSX.Element | null;
 
 type ThemeStyle = CSSProperties & Record<`--scrawl-${string}`, string | number | undefined>;
 interface ScrawlProviderProps {
@@ -1121,6 +2467,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;
@@ -1134,8 +2490,25 @@ interface ScrawlProps extends Omit<CreateBoardControllerOptions, "canvas"> {
     onThemeDiagnostic?: (diagnostic: ScrawlThemeDiagnostic) => void;
     /** Provide null for a headless Board, or an existing canvas to control its identity. */
     canvas?: HTMLCanvasElement | null;
+    /**
+     * Per-tool icon override for the default toolbar and More tools buttons —
+     * only applies when you don't supply `children` (i.e. you're using the
+     * SDK's default UI). See DefaultBoardChromeProps.icons.
+     */
+    icons?: Partial<Record<BuiltInTool, ReactNode>>;
 }
-declare function Scrawl({ children, preset, theme, portalContainer, className, style, onReady, onError, onThemeDiagnostic, canvas: suppliedCanvas, ...options }: ScrawlProps): react.JSX.Element;
+/**
+ * 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;
     className?: string;
@@ -1150,14 +2523,50 @@ interface ScrawlDefaultUIProps {
     regions?: Partial<Record<DefaultUIRegion, boolean>>;
     /** Replace (component) or hide (null) a coarse region; omit for the SDK default. */
     slots?: DefaultUISlots;
+    /** Per-tool icon override for the toolbar and More tools buttons — see DefaultBoardChromeProps.icons. */
+    icons?: Partial<Record<BuiltInTool, ReactNode>>;
+    /** Author shown on comments left through the default comment UI — see DefaultBoardChromeProps.commentAuthor. */
+    commentAuthor?: CommentAuthor;
 }
-declare function ScrawlDefaultUI({ className, style, regions, slots }: ScrawlDefaultUIProps): react.JSX.Element;
+declare function ScrawlDefaultUI({ className, style, regions, slots, icons, commentAuthor }: ScrawlDefaultUIProps): react.JSX.Element;
 declare function ScrawlPortal({ children }: {
     children: ReactNode;
 }): react.ReactPortal | null;
 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;
@@ -1165,7 +2574,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 { DefaultBoardChrome, InlineEditors, MultiplayerCursors, Scrawl, ScrawlBoard, ScrawlCanvas, ScrawlDefaultUI, ScrawlPortal, ScrawlProvider, StyleShelf, resolveScrawlTheme, scrawlThemePresets, useScrawlController, useScrawlSnapshot, useScrawlTheme, validateScrawlTheme };
-export type { BoardController, BoardSlotProps, BoardSnapshot, BoardStyle, CommentMarker, CreateBoardControllerOptions, DefaultBoardChromeProps, DefaultUIRegion, DefaultUISlot, DefaultUISlots, DialogSlotProps, InlineEditorsProps, LocalBoard, LocalBoardSnapshot, MultiplayerCursorsProps, PresenceCursor, PresenceUser, PresenceView, ScrawlBoardProps, ScrawlCanvasProps, ScrawlDefaultUIProps, ScrawlProps, ScrawlProviderProps, ScrawlResolvedTheme, ScrawlTheme, ScrawlThemeDiagnostic, ScrawlThemePreset, StyleShelfProps };
+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, BoardNotebook, BoardPage, BoardPointerInput, BoardScene, BoardSection, BoardSlotProps, BoardSnapshot, BoardStyle, BoardThemeOptions, CollaborationSnapshot, CommentAuthor, 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 };