@scrawl-board/board 0.1.0-beta.0

package/dist/react.d.ts

@@ -0,0 +1,1171 @@
+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;
+type AssetKind = "image";
+type AssetPurpose = "render" | "thumbnail" | "export";
+interface AssetResolveRequest {
+    ref: AssetRef;
+    kind: AssetKind;
+    purpose: AssetPurpose;
+    signal: AbortSignal;
+}
+interface AssetResolveResult {
+    bytes: Uint8Array;
+    mediaType: string;
+}
+/**
+ * Host-owned lookup. Scrawl passes only the reference, kind, purpose, and
+ * signal — never Document contents, an Extension instance, or credentials.
+ * The returned bytes are copied into SDK-owned storage and independently
+ * validated before use; a resolver's claimed `mediaType` is never trusted
+ * on its own (see `assetValidation.ts`).
+ */
+interface AssetResolver {
+    resolve(request: AssetResolveRequest): Promise<AssetResolveResult>;
+}
+interface AssetIngestRequest {
+    bytes: Uint8Array;
+    mediaType: string;
+    name?: string;
+    signal: AbortSignal;
+}
+interface AssetIngestResult {
+    ref: AssetRef;
+}
+/**
+ * Host-owned upload/creation path. Scrawl validates the candidate against
+ * SDK limits before calling this, and validates the returned reference
+ * before it can enter any command. Cancellation or failure creates no
+ * Document object, Op, or history entry.
+ */
+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";
+/** Runtime event for a resolution/ingestion failure — never carries credentials or a fetchable location. */
+interface AssetDiagnostic {
+    code: AssetResolutionErrorCode;
+    ref?: AssetRef;
+    objectId: string;
+    objectKind: "image" | "custom";
+    retryable: boolean;
+}
+
+type Mat2x3 = [number, number, number, number, number, number];
+
+/** A stable namespaced string, e.g. `com.acme.kanban`. Never a display name. */
+type ExtensionId = string;
+/** A stable namespaced string, e.g. `com.acme.kanban/card-tool`. */
+type ToolId = string;
+/** A stable namespaced string, e.g. `com.acme.kanban/card`. */
+type ObjectType = string;
+interface ExtensionRequirement {
+    extensionId: ExtensionId;
+    extensionApiVersion: 1;
+}
+interface ScrawlExtension {
+    id: ExtensionId;
+    extensionApiVersion: 1;
+    requires?: readonly ExtensionRequirement[];
+    tools?: readonly CustomToolDefinition[];
+    objectTypes?: readonly CustomObjectDefinition[];
+}
+type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+type JsonObject = {
+    readonly [key: string]: JsonValue;
+};
+interface CustomBoardObject {
+    id: string;
+    type: ObjectType;
+    schemaVersion: number;
+    transform: Mat2x3;
+    /** Safe placeholder geometry, refreshed by the SDK on every valid command. */
+    fallback: {
+        bounds: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        label?: string;
+    };
+    lock?: {
+        holderId: string;
+        acquiredAt: number;
+    };
+    props: JsonValue;
+}
+/**
+ * The read-only view handed to `describe`. Deep-readonly by construction
+ * (not derived via a shallow `Readonly<>`) because `describe` must treat its
+ * input as a pure snapshot — see the spec's "treat `describe` as a pure
+ * function" rule.
+ */
+type ReadonlyCustomObject<Props extends JsonValue = JsonValue> = Readonly<{
+    id: string;
+    type: ObjectType;
+    schemaVersion: number;
+    transform: Mat2x3;
+    fallback: Readonly<{
+        bounds: Readonly<{
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        }>;
+        label?: string;
+    }>;
+    lock?: Readonly<{
+        holderId: string;
+        acquiredAt: number;
+    }>;
+    props: Props;
+}>;
+interface ObjectDescribeContext {
+    /** True while this object is part of the current selection. */
+    selected: boolean;
+}
+interface CustomObjectDefinition<Props extends JsonValue = JsonValue> {
+    type: ObjectType;
+    currentSchemaVersion: number;
+    /** Validates untrusted persisted/imported/pasted/remote data. Must be pure. */
+    parse(input: unknown, schemaVersion: number): Props;
+    /** One pure, synchronous step per consecutive schema version. */
+    migrate?: Readonly<Record<number, (oldProps: JsonValue) => JsonValue>>;
+    describe(object: ReadonlyCustomObject<Props>, context: ObjectDescribeContext): BoardScene;
+}
+interface SceneNodeBase {
+    key: string;
+    transform?: Mat2x3;
+    opacity?: number;
+    /** Semantic hit-region id (e.g. `resize-handle`, `cell:2:3`); never a renderer object. */
+    interactionRegion?: string;
+}
+interface SceneRect extends SceneNodeBase {
+    kind: "rect";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    cornerRadius?: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+}
+interface SceneText extends SceneNodeBase {
+    kind: "text";
+    x: number;
+    y: number;
+    text: string;
+    fontSize: number;
+    color: string;
+    /** Horizontal alignment relative to (x, y); defaults to "start". */
+    align?: "start" | "center" | "end";
+}
+interface SceneGroup extends SceneNodeBase {
+    kind: "group";
+    children: readonly BoardScene[];
+}
+interface ScenePath extends SceneNodeBase {
+    kind: "path";
+    /** SVG-style path data, board-local coordinates. */
+    d: string;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+}
+interface SceneImage extends SceneNodeBase {
+    kind: "image";
+    /** Resolved through the Host asset resolver (ticket #23); never a raw Blob/File/URL. */
+    ref: AssetRef;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** How the image fills its declared (x, y, width, height) box; defaults to "fill". */
+    fit?: "fill" | "contain" | "cover";
+    /** Bounded plain-text accessible label, or an explicit decorative opt-out. */
+    alt: string | {
+        readonly decorative: true;
+    };
+}
+interface SceneEllipse extends SceneNodeBase {
+    kind: "ellipse";
+    cx: number;
+    cy: number;
+    rx: number;
+    ry: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+}
+type BoardScene = SceneGroup | ScenePath | SceneText | SceneImage | SceneRect | SceneEllipse;
+type ToolCursor = "default" | "crosshair" | "pointer" | "grab" | "grabbing" | "text";
+type ToolCancelReason = "escape-key" | "tool-switched" | "pointer-lost" | "error";
+interface InputModifiers {
+    shift: boolean;
+    alt: boolean;
+    ctrl: boolean;
+    meta: boolean;
+}
+interface BoardPointerInput {
+    board: BoardPoint;
+    viewport: BoardPoint;
+    pointerId: number;
+    pointerType: "mouse" | "pen" | "touch";
+    pressure: number;
+    buttons: number;
+    modifiers: InputModifiers;
+}
+interface BoardKeyInput {
+    key: string;
+    modifiers: InputModifiers;
+}
+interface CustomToolDefinition {
+    id: ToolId;
+    label: string;
+    suggestedShortcut?: string;
+    cursor?: ToolCursor;
+    create(context: ToolCapabilities): CustomTool;
+}
+/** All handlers are synchronous — see the spec's "Lifecycle handlers are synchronous" rule. */
+interface CustomTool {
+    activate?(): void;
+    pointerDown?(input: BoardPointerInput): void;
+    pointerMove?(input: BoardPointerInput): void;
+    pointerUp?(input: BoardPointerInput): void;
+    keyDown?(input: BoardKeyInput): void;
+    keyUp?(input: BoardKeyInput): void;
+    cancel?(reason: ToolCancelReason): void;
+    deactivate?(): void;
+}
+/**
+ * What an Extension supplies to add a Custom board object. `id` is optional
+ * (the controller assigns one when omitted); `schemaVersion` and `fallback`
+ * defaults are derived by the controller from the object's definition.
+ */
+interface CustomObjectAddInput {
+    type: ObjectType;
+    id?: string;
+    transform?: Mat2x3;
+    fallback?: {
+        bounds: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        label?: string;
+    };
+    props: JsonValue;
+}
+type ObjectIntent = {
+    kind: "add";
+    object: CustomObjectAddInput;
+} | {
+    kind: "update";
+    id: string;
+    patch: JsonObject;
+} | {
+    kind: "remove";
+    id: string;
+};
+interface ExtensionCommand {
+    label?: string;
+    changes: readonly ObjectIntent[];
+}
+/** A structural, read-only view of any board object (built-in or Custom). */
+type QueryableBoardObject = Readonly<{
+    id: string;
+    type: string;
+}> & Readonly<Record<string, unknown>>;
+interface ExtensionHitResult {
+    readonly objectId: string;
+    readonly interactionRegion?: string;
+}
+interface ToolCapabilities {
+    query: {
+        get(id: string): QueryableBoardObject | undefined;
+        selection(): readonly string[];
+        hitTest(point: BoardPoint): ExtensionHitResult | undefined;
+    };
+    coordinates: {
+        boardToViewport(point: BoardPoint): BoardPoint;
+        viewportToBoard(point: BoardPoint): BoardPoint;
+    };
+    /** Session-only geometry — never enters Document/history/persistence/collaboration. */
+    preview: {
+        set(scene: BoardScene): void;
+        clear(): void;
+    };
+    /** Constructs, validates, and commits one atomic command; controller derives Ops. */
+    submit(command: ExtensionCommand): void;
+    tools: {
+        select(toolId: ToolId | "select"): void;
+        cancel(): void;
+    };
+}
+interface ExtensionDiagnostic {
+    extensionId: ExtensionId;
+    phase: "parse" | "migrate" | "describe" | "tool-lifecycle" | "react-companion" | "asset-resolution";
+    toolId?: ToolId;
+    objectId?: string;
+    objectType?: ObjectType;
+    recoverable: boolean;
+    cause: unknown;
+}
+
+interface Lockable {
+    locked?: boolean;
+    lockedBy?: string;
+    lockedByName?: string;
+}
+
+/** A kitchen timer sitting on the board. Remaining time is derived, not ticked. */
+interface KitchenTimer extends Lockable {
+    id: string;
+    x: number;
+    y: number;
+    /** Face diameter in board units. */
+    size: number;
+    /** What you set it to — 1, 5, 10, 15 minutes. */
+    durationMs: number;
+    /** Remaining at the last start or pause. */
+    remainingMs: number;
+    /** Wall-clock ms when the current run started. Absent means paused. */
+    runningSince?: number;
+}
+
+interface BoardPoint {
+    x: number;
+    y: number;
+}
+interface StrokePoint extends BoardPoint {
+    /** Resolved pressure in [0, 1] — real stylus pressure or velocity simulation. */
+    pressure: number;
+    /**
+     * Erasure channel (ADR 0003), 0..1. Undefined means 0. At or above
+     * ERASE_THRESHOLD the point is removed and the stroke may split.
+     */
+    erase?: number;
+}
+/** Which drawing tool made a stroke; undefined means marker (back-compat). */
+type StrokeTool = "marker" | "highlighter";
+interface Stroke extends Lockable {
+    id: string;
+    color: string;
+    baseWidth: number;
+    tool?: StrokeTool;
+    /** Points are stroke-local; `matrix` places them on the board. */
+    points: StrokePoint[];
+    /** 2D affine transform [a b c d tx ty]; undefined means identity. */
+    matrix?: [number, number, number, number, number, number];
+    /**
+     * Spatial group membership (ADR 0005). Assigned when the stroke is drawn;
+     * cluster records are derived from these ids, never stored themselves.
+     */
+    clusterId?: string;
+}
+type SerializedPoint = [number, number, number, number];
+interface SerializedStroke extends Lockable {
+    id: string;
+    color: string;
+    baseWidth: number;
+    tool?: StrokeTool;
+    points: SerializedPoint[];
+    /** Omitted when identity. */
+    matrix?: [number, number, number, number, number, number];
+    clusterId?: string;
+}
+interface SerializedDocument {
+    /** Absent in every historical document; current saves always write 1. */
+    schemaVersion?: 1;
+    strokes: SerializedStroke[];
+    /** Absent in documents saved before notes existed. */
+    notes?: StickyNote[];
+    /** Absent in documents saved before the text tool existed. */
+    textBlocks?: TextBlock[];
+    /** Absent in documents saved before interactive tables existed. */
+    tables?: TableBlock[];
+    /** Absent in documents saved before images existed. */
+    images?: ImageBlock[];
+    /** Absent in documents saved before kitchen timers existed. */
+    timers?: KitchenTimer[];
+    /** Absent in documents saved before Custom board objects existed (ticket #22). */
+    customObjects?: CustomBoardObject[];
+}
+/**
+ * One collaborator's vote on a note. One per person; toggling removes it.
+ */
+interface NoteVote {
+    userId: string;
+    name: string;
+    color: string;
+}
+/**
+ * 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 {
+    id: string;
+    x: number;
+    y: number;
+    /** Square side length in board units. */
+    size: number;
+    /** Height above the board surface; drives shadow offset, blur, and opacity. */
+    zOffset: number;
+    color: string;
+    text: string;
+    /** One vote per collaborator. Peel follows the count. */
+    votes?: NoteVote[];
+}
+/**
+ * Typed text on the board surface, rendered as SDF glyphs. Position is the
+ * top-left corner; lines flow downward (-y). Text joins the clustering
+ * system like handwriting (build prompt §6.4).
+ */
+interface TextBlock extends Lockable {
+    id: string;
+    x: number;
+    y: number;
+    text: string;
+    /** Line height in board units. */
+    fontSize: number;
+    color: string;
+    clusterId?: string;
+}
+/**
+ * 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 {
+    id: string;
+    x: number;
+    y: number;
+    rows: number;
+    cols: number;
+    colWidths: number[];
+    rowHeights: number[];
+    cells: Record<string, string>;
+    color?: string;
+    backgroundColor?: string;
+    clusterId?: string;
+}
+/**
+ * An imported image block on the board plane.
+ * Coordinates (x, y) represent the center of the image in board space.
+ */
+interface ImageBlock extends Lockable {
+    id: string;
+    /**
+     * A legacy, read-only data URL (or, historically, an arbitrary string) —
+     * never written by new code once `ref` exists. Ticket #23's Host-managed
+     * Assets add `ref` as the durable path going forward; `src` and `ref` are
+     * mutually exclusive in practice, but both fields exist on every
+     * `ImageBlock` so old and new objects share one shape.
+     */
+    src: string;
+    /** Opaque Asset reference (ticket #23); when present, `src` is ignored. */
+    ref?: AssetRef;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    aspectRatio: number;
+    name?: string;
+    createdAt?: string;
+    /** Present when this image is a stamp from the pad, not a photo. */
+    stamp?: string;
+}
+
+declare const CURRENT_DOCUMENT_SCHEMA_VERSION: 1;
+type CurrentSerializedStroke = Omit<SerializedStroke, "id"> & {
+    id: StrokeId;
+};
+interface CurrentSerializedDocument extends Required<SerializedDocument> {
+    schemaVersion: typeof CURRENT_DOCUMENT_SCHEMA_VERSION;
+    strokes: CurrentSerializedStroke[];
+}
+
+interface SearchableComment {
+    id: string;
+    text: string;
+    authorName: string;
+    x: number;
+    y: number;
+    replies: readonly {
+        text: string;
+    }[];
+}
+type SearchHitKind = "note" | "text" | "table" | "comment" | "stamp";
+interface SearchHit {
+    kind: SearchHitKind;
+    id: string;
+    title: string;
+    snippet: string;
+    x: number;
+    y: number;
+}
+
+/** A stamp is a small sticker dropped on the board — not ink, not a photo. */
+type StampKind = "star" | "check" | "ship" | "heart" | "plus" | "fire";
+
+type SerializedBoardDocument = CurrentSerializedDocument;
+
+interface AssetExportFailure {
+    objectId: string;
+    ref: AssetRef;
+    code: AssetResolutionErrorCode;
+}
+interface ExportDocumentSVGOptions {
+    missingAssets?: "placeholder";
+    signal?: AbortSignal;
+}
+interface ExportDocumentSVGResult {
+    svg: string;
+    missingAssets: readonly AssetExportFailure[];
+}
+
+type BuiltInTool = "select" | "pan" | "marker" | "highlighter" | "eraser" | "text" | "note" | "table" | "image" | "comment" | "stamp" | "timer" | `shape:${string}`;
+type PersistenceSnapshot = {
+    state: "disabled";
+} | {
+    state: "loading" | "idle" | "saving" | "saved";
+} | {
+    state: "offline" | "error";
+    error?: BoardControllerError;
+};
+type CollaborationSnapshot = {
+    state: "disabled";
+} | {
+    state: "connecting" | "online" | "reconnecting";
+} | {
+    state: "offline" | "error";
+    error?: BoardControllerError;
+};
+interface BoardStyle {
+    readonly inkColor: string;
+    readonly highlightColor: string;
+    readonly eraserRadius: number;
+    readonly noteColor: string;
+    readonly tableRows: number;
+    readonly tableCols: number;
+    readonly stampKind: StampKind;
+    readonly timerDurationMs: number;
+}
+interface BoardSnapshot {
+    readonly status: "loading" | "ready" | "disposed";
+    readonly documentId: string;
+    readonly tool: BuiltInTool | (string & {});
+    readonly zoom: number;
+    readonly readOnly: boolean;
+    readonly selection: readonly string[];
+    readonly strokeCount: number;
+    readonly objectCount: number;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    readonly style: BoardStyle;
+    readonly connection: {
+        readonly persistence: PersistenceSnapshot;
+        readonly collaboration: CollaborationSnapshot;
+    };
+}
+interface BoardControllerError {
+    source: "controller" | "renderer" | "persistence" | "collaboration";
+    code: string;
+    retryable: boolean;
+    cause?: unknown;
+}
+interface BoardEventMap {
+    change: BoardSnapshot;
+    "tool-change": {
+        tool: string;
+    };
+    "view-change": {
+        x: number;
+        y: number;
+        zoom: number;
+    };
+    "selection-change": {
+        ids: readonly string[];
+    };
+    "style-change": BoardStyle;
+    "edit-request": {
+        kind: "note";
+        id: string;
+        text: string;
+        color: string;
+        screenRect: ScreenRect;
+    } | {
+        kind: "text";
+        id: string | null;
+        boardX: number;
+        boardY: number;
+        text: string;
+        color: string;
+        fontSizePx: number;
+        screenRect: ScreenRect;
+    } | {
+        kind: "table-cell";
+        id: string;
+        row: number;
+        col: number;
+        text: string;
+        fontSizePx: number;
+        screenRect: ScreenRect;
+    };
+    "import-request": {
+        accept: readonly string[];
+    };
+    "comment-open-request": {
+        id: string;
+    };
+    "comment-draft-request": {
+        board: BoardPoint;
+        screen: ScreenPoint;
+    };
+    "pointer-move": {
+        board: BoardPoint;
+        velocity: BoardPoint;
+    };
+    "user-navigate": undefined;
+    "live-stroke-preview": {
+        stroke: Readonly<Stroke>;
+    };
+    "live-stroke-end": {
+        id: string;
+    };
+    "timer-expired": {
+        id: string;
+    };
+    /** A Custom object failed to parse/migrate/describe, or a Custom tool handler threw. */
+    "extension-diagnostic": ExtensionDiagnostic;
+    /** An Asset failed to resolve/ingest for a built-in image or a Custom `SceneImage` (ticket #23). */
+    "asset-diagnostic": AssetDiagnostic;
+    /** A batch of Ops was reconciled (not applied as-sent) by the persistence adapter (ticket #24). */
+    "persistence-diagnostic": PersistenceDiagnostic;
+    audit: unknown;
+    error: BoardControllerError;
+    disposed: undefined;
+}
+interface ScreenPoint {
+    x: number;
+    y: number;
+}
+interface ScreenRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+interface BoardView {
+    x: number;
+    y: number;
+    zoom: number;
+}
+/**
+ * A Host-owned comment, summarized for Board-side search and marker
+ * rendering. Comments are not Document content — they carry no undo
+ * history and never enter the Ops/collaboration pipeline — so this is a
+ * read/query capability, not a `content` object type.
+ */
+interface CommentMarker extends SearchableComment {
+    readonly authorColor: string;
+    readonly resolved: boolean;
+}
+interface PresenceCursor {
+    readonly boardX: number;
+    readonly boardY: number;
+    readonly vx?: number;
+    readonly vy?: number;
+}
+/** The engine's native camera shape — not BoardView's zoom, the raw height a peer's camera broadcasts. */
+interface PresenceView {
+    readonly x: number;
+    readonly y: number;
+    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.
+ */
+interface PresenceUser {
+    readonly id: string;
+    readonly name: string;
+    readonly color: string;
+    readonly tool?: string;
+    readonly cursor?: PresenceCursor;
+    readonly view?: PresenceView;
+}
+/**
+ * The Custom arm wraps `CustomBoardObject` under the same `type` discriminant
+ * convention the six built-ins use — `type: "custom"` plus a `customType`
+ * field carrying the registered Extension object type (e.g.
+ * `"com.scrawl.examples/badge"`). This is deliberate, not cosmetic: giving
+ * the arm a literal `"custom"` discriminant (instead of exposing
+ * `CustomBoardObject`'s own `type: string` directly) keeps every existing
+ * `object.type === "table"`-style check elsewhere in this codebase safely
+ * exhaustive — a non-literal `string` arm mixed into this union would make
+ * TypeScript unable to prove any built-in case excludes it. `toBoardObject`/
+ * `toCustomBoardObject` convert to/from the unwrapped `CustomBoardObject`
+ * envelope at the boundaries (document storage, wire Ops) that use it directly.
+ */
+type BoardObject = ({
+    type: "stroke";
+} & Stroke) | ({
+    type: "note";
+} & StickyNote) | ({
+    type: "text";
+} & TextBlock) | ({
+    type: "table";
+} & TableBlock) | ({
+    type: "image";
+} & ImageBlock) | ({
+    type: "timer";
+} & KitchenTimer) | ({
+    type: "custom";
+    customType: ObjectType;
+} & Omit<CustomBoardObject, "type">);
+type BoardObjectInput = {
+    type: "stroke";
+    id?: string;
+    color: string;
+    baseWidth: number;
+    tool?: Stroke["tool"];
+    points: StrokePoint[];
+    matrix?: Stroke["matrix"];
+    clusterId?: string;
+} | ({
+    type: "note";
+    id?: string;
+} & Omit<StickyNote, "id">) | ({
+    type: "text";
+    id?: string;
+} & Omit<TextBlock, "id">) | ({
+    type: "table";
+    id?: string;
+} & Omit<TableBlock, "id">) | ({
+    type: "image";
+    id?: string;
+} & Omit<ImageBlock, "id">) | ({
+    type: "timer";
+    id?: string;
+} & Omit<KitchenTimer, "id">) | ({
+    type: "custom";
+    id?: string;
+    customType: ObjectType;
+} & Omit<CustomObjectAddInput, "type" | "id">);
+type BoardObjectPatch = Record<string, unknown>;
+type DeepReadonly<T> = T extends (...args: never[]) => unknown ? T : T extends readonly (infer Item)[] ? readonly DeepReadonly<Item>[] : T extends object ? {
+    readonly [Key in keyof T]: DeepReadonly<T[Key]>;
+} : T;
+interface ReadonlyDocumentChange {
+    readonly added: readonly DeepReadonly<BoardObject>[];
+    readonly updated: readonly DeepReadonly<BoardObject>[];
+    readonly removed: readonly string[];
+}
+interface ReadonlyBoardDocument {
+    readonly id: string;
+    get(id: string): DeepReadonly<BoardObject> | undefined;
+    all(): IterableIterator<DeepReadonly<BoardObject>>;
+    subscribe(listener: (change: ReadonlyDocumentChange) => void): () => void;
+}
+interface DocumentContext {
+    documentId: string;
+    signal: AbortSignal;
+}
+type LoadResult = {
+    state: "found";
+    document: CurrentSerializedDocument;
+    revision: string;
+} | {
+    state: "missing";
+};
+interface PersistenceAdapter {
+    load(context: DocumentContext): Promise<LoadResult>;
+    applyOps(context: DocumentContext, ops: readonly ControllerOp[]): Promise<ApplyOpsResult>;
+    replace(context: DocumentContext, document: CurrentSerializedDocument, baseRevision: string): Promise<unknown>;
+}
+/**
+ * `"reconcile"` (ticket #24) means the server authoritatively resolved the
+ * whole batch — some Ops it accepted, `rejectedOpIds` it didn't (a stale
+ * tombstoned id, a permission change, an unrecognized schema, or a
+ * conflicting concurrent edit). The batch is never re-queued in this case;
+ * the controller instead reloads authoritative state via `load()`.
+ */
+type ApplyOpsResult = {
+    state: "applied";
+    revision: string;
+} | {
+    state: "reconcile";
+    revision: string;
+    rejectedOpIds: readonly string[];
+    reason: "tombstone" | "permission" | "schema" | "conflict";
+};
+/** A batch of Ops was reconciled (not applied as-sent) by the persistence adapter (ticket #24). */
+interface PersistenceDiagnostic {
+    code: "tombstone" | "permission" | "schema" | "conflict";
+    rejectedOpIds: readonly string[];
+    revision: string;
+}
+interface ControllerOp {
+    id: string;
+    schemaVersion: 1;
+    kind: "upsert" | "restore" | "remove";
+    objectType: "stroke" | "note" | "text" | "table" | "image" | "timer" | "custom";
+    objectId: string;
+    payload?: unknown;
+}
+interface CollaborationAdapter {
+    connect(options: DocumentContext & {
+        identity: CollaboratorIdentity;
+        receive: CollaborationReceiver;
+    }): Promise<CollaborationSession>;
+}
+interface CollaboratorIdentity {
+    id: string;
+    name: string;
+    color?: string;
+}
+interface CollaborationReceiver {
+    ops(ops: readonly ControllerOp[]): void;
+    status(state: "online" | "reconnecting" | "offline"): void;
+    error(cause: unknown): void;
+}
+interface CollaborationSession {
+    sendOps(ops: readonly ControllerOp[]): void;
+    close(): Promise<void>;
+}
+interface CreateBoardControllerOptions {
+    document: {
+        id: string;
+        initial?: SerializedBoardDocument;
+    };
+    /** Canvas-backed controllers delegate rendering and normalized input to the private engine. */
+    canvas?: HTMLCanvasElement;
+    adapters?: {
+        persistence?: PersistenceAdapter;
+        collaboration?: CollaborationAdapter;
+    };
+    identity?: CollaboratorIdentity;
+    createId?: () => string;
+    /**
+     * 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.
+     */
+    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.
+     */
+    assetResolver?: AssetResolver;
+    assetIngestor?: AssetIngestor;
+    /** Clamped to 64–512MiB; defaults to 256MiB. */
+    assetCacheBytes?: number;
+}
+interface BoardController {
+    readonly document: ReadonlyBoardDocument;
+    readonly tools: {
+        select(tool: BuiltInTool | (string & {})): void;
+        current(): string;
+    };
+    readonly style: {
+        setInkColor(color: string): void;
+        set(patch: Partial<{
+            inkColor: string;
+            highlightColor: string;
+            eraserRadius: number;
+            noteColor: string;
+            tableRows: number;
+            tableCols: number;
+            stampKind: StampKind;
+            timerDurationMs: number;
+        }>): void;
+        current(): BoardStyle;
+    };
+    readonly history: {
+        undo(): void;
+        redo(): void;
+    };
+    readonly view: {
+        fit(): void;
+        zoomTo(value: number): void;
+        centerOn(point: BoardPoint): void;
+        get(): BoardView;
+        boardToScreen(point: BoardPoint): ScreenPoint;
+        screenToBoard(point: ScreenPoint): BoardPoint;
+    };
+    readonly content: {
+        add(input: BoardObjectInput): string;
+        update(id: string, patch: BoardObjectPatch): void;
+        remove(ids: readonly string[]): void;
+        table: {
+            addRow(tableId: string): void;
+            addCol(tableId: string): void;
+            deleteRow(tableId: string, rowIndex?: number): void;
+            deleteCol(tableId: string, colIndex?: number): void;
+            /** Commit one cell's text, auto-growing its row height for wrapped content. */
+            commitCell(tableId: string, row: number, col: number, text: string): void;
+        };
+        select(ids: readonly string[]): void;
+        import(document: SerializedBoardDocument): readonly string[];
+    };
+    readonly query: {
+        get(id: string): DeepReadonly<BoardObject> | undefined;
+        all(): readonly DeepReadonly<BoardObject>[];
+        search(query: string): readonly SearchHit[];
+    };
+    /** Host-owned comments, synced in for search and marker rendering only — see CommentMarker. */
+    readonly comments: {
+        sync(comments: readonly CommentMarker[]): void;
+        open(id: string): void;
+        setActive(id: string | null): void;
+    };
+    /**
+     * Host-owned collaborator roster, synced in for cursor rendering and
+     * view-following only — see PresenceUser. `subscribe` is intentionally
+     * separate from the controller's own `subscribe`/`getSnapshot`: cursor
+     * updates arrive at pointer-move frequency per remote user, and routing
+     * that through the main snapshot cycle would re-render the whole Board
+     * chrome on every remote mouse move.
+     */
+    readonly presence: {
+        sync(users: readonly PresenceUser[]): void;
+        list(): readonly PresenceUser[];
+        subscribe(listener: () => void): () => void;
+        /** Snap the camera to a peer's view; a no-op while the local user is mid-stroke. */
+        follow(view: PresenceView): void;
+        /** Ease the camera to a peer's view; returns false (no-op) while mid-stroke. */
+        gather(view: PresenceView): boolean;
+    };
+    readonly export: {
+        svg(): string;
+        /** `awaitAssets` (ticket #23) is a best-effort, not-strict wait — see ScrawlEngine.exportPNG. */
+        png(options?: {
+            maxSide?: number;
+            awaitAssets?: boolean;
+        }): Promise<Blob | null>;
+        json(): CurrentSerializedDocument;
+        /** Async, self-contained SVG export (ticket #23) — see ExportDocumentSVGOptions. */
+        svgAsync(options?: ExportDocumentSVGOptions): Promise<ExportDocumentSVGResult>;
+    };
+    /** Host-managed Asset ingestion (ticket #23); throws if no `assetIngestor` is configured. */
+    readonly assets: {
+        ingest(bytes: Uint8Array, mediaType: string, name?: string, signal?: AbortSignal): Promise<AssetRef>;
+    };
+    getSnapshot(): BoardSnapshot;
+    subscribe(listener: () => void): () => void;
+    on<K extends keyof BoardEventMap>(event: K, listener: (payload: BoardEventMap[K]) => void): () => void;
+    setReadOnly(value: boolean): void;
+    flush(): Promise<{
+        state: "idle" | "flushed" | "disabled";
+    }>;
+    dispose(): Promise<void>;
+}
+type LocalBoardSnapshot = {
+    documentId: string;
+    selectedStrokeId: string | null;
+    strokeCount: number;
+    canUndo: boolean;
+    canRedo: boolean;
+    disposed: boolean;
+};
+type LocalBoard = {
+    drawStroke(stroke: Stroke): void;
+    selectAt(point: BoardPoint): string | null;
+    undo(): void;
+    redo(): void;
+    serialize(): SerializedBoardDocument;
+    getSnapshot(): LocalBoardSnapshot;
+    subscribe(listener: () => void): () => void;
+    dispose(): Promise<void>;
+};
+
+type ScrawlThemePreset = "light" | "dark";
+type ScrawlDensity = "comfortable" | "compact";
+interface ScrawlTheme {
+    surface?: string;
+    surfaceRaised?: string;
+    surfaceMuted?: string;
+    text?: string;
+    textMuted?: string;
+    edge?: string;
+    focus?: string;
+    selection?: string;
+    danger?: string;
+    warning?: string;
+    success?: string;
+    uiFontFamily?: string;
+    dataFontFamily?: string;
+    baseFontSize?: number;
+    regularWeight?: number;
+    strongWeight?: number;
+    controlRadius?: number;
+    panelRadius?: number;
+    elevationLow?: string;
+    elevationHigh?: string;
+    motionDuration?: number;
+    motionEasing?: string;
+    density?: ScrawlDensity;
+}
+type ResolvedScrawlTheme = Required<ScrawlTheme>;
+interface ScrawlThemeDiagnostic {
+    token: string;
+    message: string;
+}
+interface ScrawlResolvedTheme {
+    preset: ScrawlThemePreset;
+    values: ResolvedScrawlTheme;
+    variables: Record<string, string>;
+    diagnostics: readonly ScrawlThemeDiagnostic[];
+}
+declare const scrawlThemePresets: Readonly<Record<ScrawlThemePreset, Readonly<ResolvedScrawlTheme>>>;
+declare function validateScrawlTheme(theme: ScrawlTheme | Record<string, unknown>): ScrawlThemeDiagnostic[];
+declare function resolveScrawlTheme(preset?: ScrawlThemePreset, theme?: ScrawlTheme | Record<string, unknown>): ScrawlResolvedTheme;
+
+interface DefaultBoardChromeProps {
+    controller: BoardController;
+    snapshot: BoardSnapshot;
+    renderPortal(children: ReactNode): ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+    regions?: Partial<Record<DefaultUIRegion, boolean>>;
+    slots?: DefaultUISlots;
+}
+type DefaultUIRegion = "tools" | "history" | "view" | "style" | "search" | "import" | "export" | "inlineEditing" | "styleShelf";
+/** Props for the toolbar/topBar/stylePanel/contextMenu slots. */
+interface BoardSlotProps {
+    controller: BoardController;
+    snapshot: BoardSnapshot;
+    /** The SDK's own default content for this slot — render it to wrap rather than fully replace. */
+    children?: ReactNode;
+}
+/** Props for the dialogs slot — parameterized by whichever panel is currently open. */
+interface DialogSlotProps {
+    label: string;
+    onClose(): void;
+    children?: ReactNode;
+}
+type DefaultUISlot = "toolbar" | "topBar" | "stylePanel" | "dialogs" | "contextMenu";
+interface DefaultUISlots {
+    toolbar?: ComponentType<BoardSlotProps> | null;
+    topBar?: ComponentType<BoardSlotProps> | null;
+    stylePanel?: ComponentType<BoardSlotProps> | null;
+    dialogs?: ComponentType<DialogSlotProps> | null;
+    /**
+     * No built-in trigger exists yet — nothing in the SDK opens a context
+     * menu today (no right-click or selection-anchored affordance). Included
+     * for API completeness; a Host-supplied component here currently has
+     * nothing to attach to.
+     */
+    contextMenu?: ComponentType<BoardSlotProps> | null;
+}
+declare function DefaultBoardChrome({ controller, snapshot, renderPortal, className, style, regions, slots }: DefaultBoardChromeProps): react.JSX.Element;
+
+interface InlineEditorsProps {
+    controller: BoardController;
+    renderPortal(children: ReactNode): ReactNode;
+}
+/** Inline note, text, and table-cell editors — driven entirely by public controller events and commands. */
+declare function InlineEditors({ controller, renderPortal }: InlineEditorsProps): react.JSX.Element;
+
+interface MultiplayerCursorsProps {
+    controller: BoardController;
+    onSelectUser?(user: PresenceUser, screenPos: {
+        x: number;
+        y: number;
+    }): void;
+    onJumpToUser?(user: PresenceUser): void;
+}
+/**
+ * Remote collaborator cursors and off-screen "jump to" beacons, driven by
+ * controller.presence. Styled entirely inline (not through styles.css) —
+ * unlike toolbar/style-shelf chrome, a Host may reasonably mount this
+ * standalone outside a `[data-scrawl-root]` wrapper.
+ */
+declare function MultiplayerCursors({ controller, onSelectUser, onJumpToUser }: MultiplayerCursorsProps): react.JSX.Element | null;
+
+interface StyleShelfProps {
+    controller: BoardController;
+    snapshot: BoardSnapshot;
+}
+/** Contextual per-tool style controls — visible while a styleable tool is active. */
+declare function StyleShelf({ controller, snapshot }: StyleShelfProps): react.JSX.Element | null;
+
+type ThemeStyle = CSSProperties & Record<`--scrawl-${string}`, string | number | undefined>;
+interface ScrawlProviderProps {
+    controller: BoardController;
+    children?: ReactNode;
+    preset?: ScrawlThemePreset;
+    theme?: ScrawlTheme;
+    portalContainer?: HTMLElement | null;
+    disposeOnUnmount?: boolean;
+    onThemeDiagnostic?: (diagnostic: ScrawlThemeDiagnostic) => void;
+    className?: string;
+    style?: ThemeStyle;
+}
+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;
+    preset?: ScrawlThemePreset;
+    theme?: ScrawlTheme;
+    portalContainer?: HTMLElement | null;
+    className?: string;
+    style?: ThemeStyle;
+    onReady?: (controller: BoardController) => void;
+    onError?: (error: unknown) => void;
+    onThemeDiagnostic?: (diagnostic: ScrawlThemeDiagnostic) => void;
+    /** Provide null for a headless Board, or an existing canvas to control its identity. */
+    canvas?: HTMLCanvasElement | null;
+}
+declare function Scrawl({ children, preset, theme, portalContainer, className, style, onReady, onError, onThemeDiagnostic, canvas: suppliedCanvas, ...options }: ScrawlProps): react.JSX.Element;
+interface ScrawlCanvasProps {
+    element?: HTMLCanvasElement;
+    className?: string;
+    style?: CSSProperties;
+    "aria-label"?: string;
+}
+declare function ScrawlCanvas({ element, className, style, "aria-label": ariaLabel }: ScrawlCanvasProps): react.JSX.Element;
+interface ScrawlDefaultUIProps {
+    className?: string;
+    style?: CSSProperties;
+    /** Disable any migrated region independently while a Host supplies its replacement. */
+    regions?: Partial<Record<DefaultUIRegion, boolean>>;
+    /** Replace (component) or hide (null) a coarse region; omit for the SDK default. */
+    slots?: DefaultUISlots;
+}
+declare function ScrawlDefaultUI({ className, style, regions, slots }: 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;
+type ScrawlBoardProps = {
+    documentId: string;
+    initialDocument?: SerializedBoardDocument;
+    onReady?: (board: LocalBoard) => void;
+    className?: string;
+    style?: CSSProperties;
+};
+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 };