@scrawl-board/board 0.1.0-beta.0

package/dist/index.d.ts

@@ -0,0 +1,1797 @@
+import * as react from 'react';
+import { ReactNode, ComponentType, CSSProperties } from 'react';
+
+declare const documentIdBrand: unique symbol;
+declare const strokeIdBrand: unique symbol;
+type DocumentId = string & {
+    readonly [documentIdBrand]: "DocumentId";
+};
+type StrokeId = string & {
+    readonly [strokeIdBrand]: "StrokeId";
+};
+declare function documentId(value: string): DocumentId;
+declare function strokeId(value: string): 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];
+declare const IDENTITY: Mat2x3;
+declare function isIdentity(m: Mat2x3): boolean;
+/** Compose: apply `first`, then `second`. */
+declare function mul(second: Mat2x3, first: Mat2x3): Mat2x3;
+declare function invert(m: Mat2x3): Mat2x3;
+declare function apply(m: Mat2x3, p: BoardPoint): BoardPoint;
+declare function translation(dx: number, dy: number): Mat2x3;
+declare function rotationAbout(angle: number, cx: number, cy: number): Mat2x3;
+declare function scalingAbout(sx: number, sy: number, cx: number, cy: number): Mat2x3;
+/** Approximate uniform length scale (average of the axis scales). */
+declare function avgScale(m: Mat2x3): 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$1;
+}
+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$1[];
+}
+interface ScenePath$1 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$1 = SceneGroup | ScenePath$1 | 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$1): 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;
+}
+
+/** Who holds a lock. Stored on the item so only they can take it off. */
+interface LockHolder {
+    userId: string;
+    name: string;
+}
+interface Lockable {
+    locked?: boolean;
+    lockedBy?: string;
+    lockedByName?: string;
+}
+/**
+ * Apply or clear a lock in place. Unlock always drops the holder so a stale
+ * name cannot linger on an unlocked item.
+ */
+declare function applyItemLock(item: Lockable, locked: boolean, by?: LockHolder | null): void;
+/**
+ * Only the person who locked it can unlock it. Items locked before ownership
+ * existed (no `lockedBy`) stay unlockable by anyone, so old boards don't brick.
+ */
+declare function canUnlockItem(item: Lockable | undefined, userId: string | undefined): boolean;
+/** Wire fields for a locked item; omitted entirely when unlocked. */
+declare function serializeLock(item: Lockable): Lockable;
+
+/** 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;
+}
+declare const TIMER_DEFAULT_SIZE = 12;
+declare const TIMER_DEFAULT_DURATION_MS: number;
+declare const TIMER_PRESETS_MS: readonly [60000, number, number, number];
+declare function cloneTimer(timer: KitchenTimer): KitchenTimer;
+declare function timerRemaining(timer: KitchenTimer, now: number): number;
+declare function timerExpired(timer: KitchenTimer, now: number): boolean;
+declare function startTimer(timer: KitchenTimer, now: number): KitchenTimer;
+declare function pauseTimer(timer: KitchenTimer, now: number): KitchenTimer;
+declare function toggleTimer(timer: KitchenTimer, now: number): KitchenTimer;
+declare function setTimerDuration(timer: KitchenTimer, durationMs: number): KitchenTimer;
+declare function formatTimer(ms: number): string;
+
+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;
+}
+/** Erasure level at which a point counts as fully erased. */
+declare const ERASE_THRESHOLD = 0.95;
+declare function cloneStroke(stroke: Stroke): Stroke;
+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[];
+}
+declare const INK_COLORS: {
+    readonly black: "#1C1C1E";
+    readonly red: "#E0333D";
+    readonly blue: "#2563EB";
+    readonly green: "#16A34A";
+};
+declare const HIGHLIGHT_COLORS: {
+    readonly yellow: "#FDE047";
+    readonly green: "#86EFAC";
+    readonly pink: "#F9A8D4";
+    readonly blue: "#93C5FD";
+};
+declare const NOTE_COLORS: {
+    readonly yellow: "#FDE68A";
+    readonly pink: "#FBCFE8";
+    readonly blue: "#BFDBFE";
+    readonly green: "#BBF7D0";
+};
+/**
+ * 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;
+}
+declare const TEXT_DEFAULT_SIZE = 1.8;
+declare function cloneText(block: TextBlock): TextBlock;
+/**
+ * Estimated bounds of a text block (average-glyph-width heuristic — no DOM,
+ * usable from clustering, export, and tests alike).
+ */
+declare function measureTextBlock(text: string, fontSize: number): {
+    width: number;
+    height: number;
+};
+declare const NOTE_DEFAULT_SIZE = 10;
+declare const NOTE_DEFAULT_Z = 1;
+declare const NOTE_MIN_Z = 0.4;
+declare const NOTE_MAX_Z = 6;
+declare const NOTE_PEEL_STEP = 0.7;
+declare function cloneNote(note: StickyNote): StickyNote;
+/**
+ * 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;
+}
+declare const TABLE_DEFAULT_CELL_WIDTH = 8;
+declare const TABLE_DEFAULT_CELL_HEIGHT = 3.6;
+declare const TABLE_DEFAULT_FONT_SIZE = 1.25;
+declare function cloneTable(table: TableBlock): TableBlock;
+declare function measureTable(table: TableBlock): {
+    width: number;
+    height: number;
+};
+declare const BOARD_COLOR = "#FFFFFF";
+declare const FOG_COLOR = "#FFFFFF";
+/**
+ * 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 function cloneImage(img: ImageBlock): ImageBlock;
+
+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[];
+}
+type DocumentRecoveryCode = "DOCUMENT_JSON_INVALID" | "DOCUMENT_VALIDATION_FAILED" | "DOCUMENT_VERSION_UNSUPPORTED";
+declare class DocumentRecoveryError extends Error {
+    readonly code: DocumentRecoveryCode;
+    readonly originalBytes?: string | undefined;
+    readonly path?: string | undefined;
+    constructor(code: DocumentRecoveryCode, message: string, originalBytes?: string | undefined, path?: string | undefined);
+}
+type DocumentLoadResult = {
+    ok: true;
+    document: CurrentSerializedDocument;
+    migratedFrom: 0 | 1;
+} | {
+    ok: false;
+    error: DocumentRecoveryError;
+};
+declare function loadDocumentBytes(originalBytes: string): DocumentLoadResult;
+declare function migrateDocument(raw: unknown): DocumentLoadResult;
+declare function serializeDocument(document: unknown): string;
+
+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;
+}
+interface SearchableBoard {
+    notes: Iterable<StickyNote>;
+    texts: Iterable<TextBlock>;
+    tables: Iterable<TableBlock>;
+    images: Iterable<ImageBlock>;
+    timers?: Iterable<KitchenTimer>;
+    comments: Iterable<SearchableComment>;
+}
+/**
+ * Find notes, text, table cells, stamps, and comments whose text contains
+ * `query`. Empty / whitespace queries return nothing.
+ */
+declare function searchBoard(query: string, board: SearchableBoard): SearchHit[];
+
+/**
+ * The one place a live Stroke becomes its wire representation — in
+ * particular, points collapse from {x,y,pressure,erase?} objects into
+ * [x,y,pressure,erase] tuples. Anything that persists a stroke (toJSON, and
+ * the incremental ops opSync.ts sends) must go through this, or the two
+ * paths drift: a stroke saved with points-as-objects looks fine until the
+ * next load, where deserializeStrokes' array-destructuring throws "object is
+ * not iterable" — exactly what shipping the live object straight into an op
+ * used to do.
+ */
+declare function serializeStroke(s: Stroke): SerializedStroke;
+interface BBox {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+interface DocumentChange {
+    added: Stroke[];
+    /** Ids of removed strokes. */
+    removed: string[];
+    /** Strokes whose points mutated in place (erasure decay); geometry must rebuild. */
+    updated: Stroke[];
+    /** Strokes whose matrix changed; geometry is untouched, placement moved. */
+    transformed: Stroke[];
+    notesAdded: StickyNote[];
+    /** Ids of removed notes. */
+    notesRemoved: string[];
+    notesUpdated: StickyNote[];
+    textAdded: TextBlock[];
+    /** Ids of removed text blocks. */
+    textRemoved: string[];
+    textUpdated: TextBlock[];
+    tablesAdded: TableBlock[];
+    /** Ids of removed tables. */
+    tablesRemoved: string[];
+    tablesUpdated: TableBlock[];
+    imagesAdded: ImageBlock[];
+    /** Ids of removed images. */
+    imagesRemoved: string[];
+    imagesUpdated: ImageBlock[];
+    timersAdded: KitchenTimer[];
+    /** Ids of removed timers. */
+    timersRemoved: string[];
+    timersUpdated: KitchenTimer[];
+    /** Custom board objects (ticket #22) — one map for every registered type, keyed by id. */
+    customObjectsAdded: CustomBoardObject[];
+    /** Ids of removed custom objects. */
+    customObjectsRemoved: string[];
+    customObjectsUpdated: CustomBoardObject[];
+}
+type Listener = (change: DocumentChange) => void;
+declare class BoardDocument {
+    readonly id: DocumentId;
+    /** Last version acknowledged by the server; 0 = never saved. */
+    version: number;
+    private readonly strokes;
+    private readonly notes;
+    private readonly texts;
+    private readonly tables;
+    private readonly images;
+    private readonly timers;
+    /** All Custom board object types share one map, keyed by id — the envelope is already uniform. */
+    private readonly customObjects;
+    private readonly bboxes;
+    private readonly listeners;
+    constructor(id: DocumentId);
+    get(id: string): Stroke | undefined;
+    all(): IterableIterator<Stroke>;
+    bbox(id: string): BBox | undefined;
+    subscribe(listener: Listener): () => void;
+    addStrokes(strokes: Stroke[]): void;
+    removeStrokes(ids: string[]): void;
+    /** Announce in-place point mutations (erasure decay; bbox is unchanged). */
+    touchStrokes(strokes: Stroke[]): void;
+    /** Announce matrix changes; recomputes world bboxes. */
+    transformStrokes(strokes: Stroke[]): void;
+    getNote(id: string): StickyNote | undefined;
+    allNotes(): IterableIterator<StickyNote>;
+    addNotes(notes: StickyNote[]): void;
+    removeNotes(ids: string[]): void;
+    /** Replace a note's contents (move, peel, retext) under the same id. */
+    setNote(note: StickyNote): void;
+    getText(id: string): TextBlock | undefined;
+    allTexts(): IterableIterator<TextBlock>;
+    addTexts(blocks: TextBlock[]): void;
+    removeTexts(ids: string[]): void;
+    /** Replace a text block's contents (move, retext) under the same id. */
+    setText(block: TextBlock): void;
+    getTable(id: string): TableBlock | undefined;
+    allTables(): IterableIterator<TableBlock>;
+    addTables(tables: TableBlock[]): void;
+    removeTables(ids: string[]): void;
+    /** Replace a table's contents (move, resize, change cells) under the same id. */
+    setTable(table: TableBlock): void;
+    getImage(id: string): ImageBlock | undefined;
+    allImages(): IterableIterator<ImageBlock>;
+    addImages(images: ImageBlock[]): void;
+    removeImages(ids: string[]): void;
+    /** Replace an image block's contents (move, resize) under the same id. */
+    setImage(image: ImageBlock): void;
+    getTimer(id: string): KitchenTimer | undefined;
+    allTimers(): IterableIterator<KitchenTimer>;
+    addTimers(timers: KitchenTimer[]): void;
+    removeTimers(ids: string[]): void;
+    setTimer(timer: KitchenTimer): void;
+    getCustomObject(id: string): CustomBoardObject | undefined;
+    allCustomObjects(): IterableIterator<CustomBoardObject>;
+    addCustomObjects(objects: CustomBoardObject[]): void;
+    removeCustomObjects(ids: string[]): void;
+    /** Replace a custom object's contents under the same id. */
+    setCustomObject(object: CustomBoardObject): void;
+    setStrokeLocked(id: string, locked: boolean, by?: LockHolder | null): void;
+    setStrokesLocked(ids: string[], locked: boolean, by?: LockHolder | null): void;
+    setNoteLocked(id: string, locked: boolean, by?: LockHolder | null): void;
+    setTextLocked(id: string, locked: boolean, by?: LockHolder | null): void;
+    setTableLocked(id: string, locked: boolean, by?: LockHolder | null): void;
+    setImageLocked(id: string, locked: boolean, by?: LockHolder | null): void;
+    setTimerLocked(id: string, locked: boolean, by?: LockHolder | null): void;
+    /** Replace all content (initial load). Does not touch `version`. */
+    replaceAll(strokes: Stroke[], notes: StickyNote[], texts: TextBlock[], tables?: TableBlock[], images?: ImageBlock[], timers?: KitchenTimer[], customObjects?: CustomBoardObject[]): void;
+    /** Apply incremental real-time change received from a remote collaborator over WebSocket. */
+    applyRemoteChange(change: Partial<DocumentChange>): void;
+    toJSON(): SerializedDocument;
+    static deserializeCustomObjects(data: SerializedDocument): CustomBoardObject[];
+    static deserializeImages(data: SerializedDocument): ImageBlock[];
+    static deserializeTimers(data: SerializedDocument): KitchenTimer[];
+    static deserializeNotes(data: SerializedDocument): StickyNote[];
+    static deserializeTexts(data: SerializedDocument): TextBlock[];
+    static deserializeTables(data: SerializedDocument): TableBlock[];
+    static deserializeStrokes(data: SerializedDocument): Stroke[];
+    private emit;
+}
+
+type ClusterIdFactory = () => string;
+declare class ClusterStore {
+    private readonly doc;
+    private readonly createId;
+    private readonly now;
+    private readonly clusters;
+    private readonly byStroke;
+    private readonly unsubscribe;
+    constructor(doc: BoardDocument, createId: ClusterIdFactory, now: () => number);
+    /**
+     * Pick (or create) the cluster for a freshly drawn stroke and stamp its
+     * clusterId. Gap threshold scales with stroke height, per the build prompt.
+     */
+    assign(stroke: Stroke, now?: number): void;
+    /** Same assignment for a typed text block, using its estimated bounds. */
+    assignText(block: TextBlock, now?: number): void;
+    private pick;
+    /** All strokes in the same cluster; a clusterless stroke is its own group. */
+    membersOf(strokeId: string): string[];
+    dispose(): void;
+    /** Strokes and text blocks index identically; bbox source differs. */
+    private memberBBox;
+    private addMember;
+    private removeMember;
+    private recompute;
+}
+
+interface Command {
+    readonly label: string;
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+/** How a command reached the document — undo/redo are audited distinctly. */
+type CommandKind = "do" | "undo" | "redo";
+declare class History {
+    private readonly doc;
+    private readonly undoStack;
+    private readonly redoStack;
+    /**
+     * Observer for every mutation, in one place: all board edits funnel
+     * through record/undo/redo. The audit trail listens here.
+     */
+    onCommand: ((command: Command, kind: CommandKind) => void) | null;
+    private undoing;
+    constructor(doc: BoardDocument);
+    /** Apply a command and make it undoable. */
+    execute(command: Command): void;
+    /** Make an already-applied change undoable (e.g. a live erase swipe). */
+    record(command: Command): void;
+    /**
+     * True while a revert is in flight. Persistence reads this: re-adding
+     * something the author deleted must be sent as a `restore`, the only op the
+     * server lets past a tombstone (ADR 0006).
+     */
+    get isUndoing(): boolean;
+    undo(): void;
+    redo(): void;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    clear(): void;
+}
+
+/** One drawing action — a marker stroke, or a shape's strokes as one unit. */
+declare class AddStrokesCommand implements Command {
+    readonly label = "draw";
+    private readonly strokes;
+    constructor(strokes: Stroke[]);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+/**
+ * One eraser swipe (ADR 0003): `before` are the touched strokes as they were
+ * at swipe start; `after` is what survived — smudged, split, or gone.
+ */
+declare class EraseCommand implements Command {
+    readonly label = "erase";
+    private readonly before;
+    private readonly after;
+    constructor(before: Stroke[], after: Stroke[]);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+/**
+ * One transform gesture: `delta` composed onto each member's matrix
+ * (`child = delta × child`, per §6.3 — never baked into geometry).
+ */
+declare class TransformCommand implements Command {
+    private readonly ids;
+    private readonly delta;
+    readonly label = "transform selection";
+    private readonly inverse;
+    constructor(ids: string[], delta: Mat2x3);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+    private compose;
+}
+declare class AddNoteCommand implements Command {
+    readonly label = "add note";
+    private readonly note;
+    constructor(note: StickyNote);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+/** Any note mutation — move, peel, recolor, retext — as before/after. */
+declare class UpdateNoteCommand implements Command {
+    readonly label = "update note";
+    private readonly before;
+    private readonly after;
+    constructor(before: StickyNote, after: StickyNote);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class DeleteNoteCommand implements Command {
+    readonly label = "delete note";
+    private readonly note;
+    constructor(note: StickyNote);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class AddTextCommand implements Command {
+    readonly label = "add text";
+    private readonly block;
+    constructor(block: TextBlock);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+/** Any text-block mutation — move or retext — as before/after. */
+declare class UpdateTextCommand implements Command {
+    readonly label = "update text";
+    private readonly before;
+    private readonly after;
+    constructor(before: TextBlock, after: TextBlock);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class DeleteTextCommand implements Command {
+    readonly label = "delete text";
+    private readonly block;
+    constructor(block: TextBlock);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class AddTableCommand implements Command {
+    readonly label = "add table";
+    private readonly table;
+    constructor(table: TableBlock);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+/** Any table mutation — move, resize, cell text edit — as before/after. */
+declare class UpdateTableCommand implements Command {
+    readonly label = "update table";
+    private readonly before;
+    private readonly after;
+    constructor(before: TableBlock, after: TableBlock);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class DeleteTableCommand implements Command {
+    readonly label = "delete table";
+    private readonly table;
+    constructor(table: TableBlock);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class DeleteStrokesCommand implements Command {
+    readonly label = "delete selection";
+    private readonly strokes;
+    constructor(strokes: Stroke[]);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class AddImageCommand implements Command {
+    readonly label = "add image";
+    private readonly image;
+    constructor(image: ImageBlock);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+/** Any image mutation — move, resize — as before/after. */
+declare class UpdateImageCommand implements Command {
+    readonly label = "update image";
+    private readonly before;
+    private readonly after;
+    constructor(before: ImageBlock, after: ImageBlock);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class DeleteImageCommand implements Command {
+    readonly label = "delete image";
+    private readonly image;
+    constructor(image: ImageBlock);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class AddTimerCommand implements Command {
+    readonly label = "add timer";
+    private readonly timer;
+    constructor(timer: KitchenTimer);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class UpdateTimerCommand implements Command {
+    readonly label = "update timer";
+    private readonly before;
+    private readonly after;
+    constructor(before: KitchenTimer, after: KitchenTimer);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class DeleteTimerCommand implements Command {
+    readonly label = "delete timer";
+    private readonly timer;
+    constructor(timer: KitchenTimer);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+interface LockTarget {
+    type: "stroke" | "note" | "text" | "table" | "image" | "timer";
+    id: string;
+    locked: boolean;
+    lockedBy?: string;
+    lockedByName?: string;
+}
+declare class LockItemsCommand implements Command {
+    readonly label = "toggle lock";
+    private readonly targets;
+    private readonly targetState;
+    private readonly actor;
+    constructor(targets: LockTarget[], targetState: boolean, actor?: LockHolder | null);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+    private applyLock;
+}
+
+type OpCollection = "strokes" | "notes" | "textBlocks" | "tables" | "images" | "timers" | "customObjects";
+type Op = {
+    kind: "upsert";
+    collection: OpCollection;
+    object: {
+        id: string;
+    };
+} | {
+    kind: "restore";
+    collection: OpCollection;
+    object: {
+        id: string;
+    };
+} | {
+    kind: "remove";
+    collection: OpCollection;
+    id: string;
+};
+/** Convert a canonical Document change into durable, renderer-neutral Ops. */
+declare function changeToOps(change: DocumentChange, restoring?: boolean): Op[];
+
+declare const MIN_WIDTH_FACTOR = 0.35;
+declare const END_TAPER = 0.55;
+interface RibbonEdgePoint {
+    lx: number;
+    ly: number;
+    rx: number;
+    ry: number;
+    /** 1 = intact ink, 0 = fully erased (from the erasure channel). */
+    alpha: number;
+}
+declare function ribbonEdges(points: StrokePoint[], baseWidth: number): RibbonEdgePoint[];
+
+declare class SpatialIndex {
+    private readonly doc;
+    private readonly cells;
+    private readonly strokeCells;
+    private readonly unsubscribe;
+    constructor(doc: BoardDocument);
+    /** Ids of strokes whose bbox may overlap the query rect. */
+    query(minX: number, minY: number, maxX: number, maxY: number): Set<string>;
+    dispose(): void;
+    private insert;
+    private remove;
+}
+
+/** 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 STAMP_SIZE = 6;
+declare const STAMPS: {
+    kind: StampKind;
+    label: string;
+    glyph: string;
+}[];
+declare function stampDataUrl(kind: StampKind): string;
+declare function isStampKind(value: unknown): value is StampKind;
+
+interface ViewportInset {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/** Keep beacons clear of typical chrome at the top and bottom of the Board. */
+declare const BEACON_INSET: ViewportInset;
+type PresencePlacement = {
+    kind: "on-screen";
+    x: number;
+    y: number;
+} | {
+    kind: "edge";
+    x: number;
+    y: number;
+    angle: number;
+};
+/**
+ * If a collaborator is in the usable viewport, return their screen position.
+ * If they are outside it, clamp to the nearest edge and return the angle a
+ * chevron should point (screen space, radians, 0 = right, clockwise).
+ */
+declare function placePresenceBeacon(screen: {
+    x: number;
+    y: number;
+}, viewport: {
+    width: number;
+    height: number;
+}, inset?: ViewportInset): PresencePlacement;
+
+interface ExtensionRegistry {
+    readonly extensions: readonly ScrawlExtension[];
+    tool(id: ToolId): CustomToolDefinition | undefined;
+    objectType(type: ObjectType): CustomObjectDefinition | undefined;
+}
+
+/**
+ * `registry` is optional and only enables rendering Custom objects through
+ * their own `describe()` — without it (or for an object whose extension
+ * isn't in it), Custom objects still export via the standard fallback
+ * placeholder (`fallback.bounds`/`label`), never silently dropped.
+ *
+ * `resolvedAssets` (ticket #23) maps an Asset reference to an already-
+ * resolved `data:` URI — see `assetExport.ts`'s `exportDocumentSVGWithAssets`,
+ * which is the only intended caller that ever passes one. Without it, every
+ * `ref`-backed image (built-in or Custom `SceneImage`) renders its
+ * placeholder instead of guessing at a URL; a legacy `src`-backed image is
+ * unaffected either way.
+ */
+declare function documentToSVG(doc: SerializedDocument, now?: number, registry?: ExtensionRegistry, resolvedAssets?: ReadonlyMap<AssetRef, string>): string;
+
+declare const SDK_PACKAGE_NAME = "@scrawl-board/board";
+declare const SDK_DEVELOPMENT_VERSION = "0.0.0-development";
+
+type BoardBounds = {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+};
+type ScenePath = {
+    id: string;
+    color: string;
+    width: number;
+    points: readonly BoardPoint[];
+};
+type BoardScene = {
+    bounds: BoardBounds;
+    paths: readonly ScenePath[];
+};
+type BoardStroke = Stroke;
+type SerializedBoardStroke = SerializedStroke;
+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>;
+}
+declare function createBoardController(options: CreateBoardControllerOptions): BoardController;
+type LocalBoardSnapshot = {
+    documentId: string;
+    selectedStrokeId: string | null;
+    strokeCount: number;
+    canUndo: boolean;
+    canRedo: boolean;
+    disposed: boolean;
+};
+type LocalBoardOptions = {
+    documentId: string;
+    initialDocument?: SerializedBoardDocument;
+};
+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>;
+};
+declare function createLocalBoard(options: LocalBoardOptions): LocalBoard;
+
+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 { AddImageCommand, AddNoteCommand, AddStrokesCommand, AddTableCommand, AddTextCommand, AddTimerCommand, BEACON_INSET, BOARD_COLOR, BoardDocument, CURRENT_DOCUMENT_SCHEMA_VERSION, ClusterStore, DefaultBoardChrome, DeleteImageCommand, DeleteNoteCommand, DeleteStrokesCommand, DeleteTableCommand, DeleteTextCommand, DeleteTimerCommand, DocumentRecoveryError, END_TAPER, ERASE_THRESHOLD, EraseCommand, FOG_COLOR, HIGHLIGHT_COLORS, History, IDENTITY, INK_COLORS, InlineEditors, LockItemsCommand, MIN_WIDTH_FACTOR, MultiplayerCursors, NOTE_COLORS, NOTE_DEFAULT_SIZE, NOTE_DEFAULT_Z, NOTE_MAX_Z, NOTE_MIN_Z, NOTE_PEEL_STEP, SDK_DEVELOPMENT_VERSION, SDK_PACKAGE_NAME, STAMPS, STAMP_SIZE, Scrawl, ScrawlBoard, ScrawlCanvas, ScrawlDefaultUI, ScrawlPortal, ScrawlProvider, SpatialIndex, StyleShelf, TABLE_DEFAULT_CELL_HEIGHT, TABLE_DEFAULT_CELL_WIDTH, TABLE_DEFAULT_FONT_SIZE, TEXT_DEFAULT_SIZE, TIMER_DEFAULT_DURATION_MS, TIMER_DEFAULT_SIZE, TIMER_PRESETS_MS, TransformCommand, UpdateImageCommand, UpdateNoteCommand, UpdateTableCommand, UpdateTextCommand, UpdateTimerCommand, apply, applyItemLock, avgScale, canUnlockItem, changeToOps, cloneImage, cloneNote, cloneStroke, cloneTable, cloneText, cloneTimer, createBoardController, createLocalBoard, documentId, documentToSVG, formatTimer, invert, isIdentity, isStampKind, loadDocumentBytes, measureTable, measureTextBlock, migrateDocument, mul, pauseTimer, placePresenceBeacon, resolveScrawlTheme, ribbonEdges, rotationAbout, scalingAbout, scrawlThemePresets, searchBoard, serializeDocument, serializeLock, serializeStroke, setTimerDuration, stampDataUrl, startTimer, strokeId, timerExpired, timerRemaining, toggleTimer, translation, useScrawlController, useScrawlSnapshot, useScrawlTheme, validateScrawlTheme };
+export type { ApplyOpsResult, BBox, BoardBounds, BoardController, BoardControllerError, BoardEventMap, BoardObject, BoardObjectInput, BoardObjectPatch, BoardPoint, BoardScene, BoardSlotProps, BoardSnapshot, BoardStroke, BoardStyle, BoardView, BuiltInTool, ClusterIdFactory, CollaborationAdapter, CollaborationReceiver, CollaborationSession, CollaborationSnapshot, CollaboratorIdentity, Command, CommandKind, CommentMarker, ControllerOp, CreateBoardControllerOptions, CurrentSerializedDocument, CurrentSerializedStroke, DeepReadonly, DefaultBoardChromeProps, DefaultUIRegion, DefaultUISlot, DefaultUISlots, DialogSlotProps, DocumentChange, DocumentContext, DocumentId, DocumentLoadResult, DocumentRecoveryCode, ImageBlock, InlineEditorsProps, KitchenTimer, LoadResult, LocalBoard, LocalBoardOptions, LocalBoardSnapshot, LockHolder, LockTarget, Lockable, Mat2x3, MultiplayerCursorsProps, NoteVote, Op, OpCollection, PersistenceAdapter, PersistenceDiagnostic, PersistenceSnapshot, PresenceCursor, PresencePlacement, PresenceUser, PresenceView, ReadonlyBoardDocument, ReadonlyDocumentChange, RibbonEdgePoint, ScenePath, ScrawlBoardProps, ScrawlCanvasProps, ScrawlDefaultUIProps, ScrawlProps, ScrawlProviderProps, ScrawlResolvedTheme, ScrawlTheme, ScrawlThemeDiagnostic, ScrawlThemePreset, ScreenPoint, ScreenRect, SearchHit, SearchHitKind, SearchableBoard, SearchableComment, SerializedBoardDocument, SerializedBoardStroke, SerializedPoint, SerializedStroke, StampKind, StickyNote, Stroke, StrokeId, StrokePoint, StrokeTool, StyleShelfProps, TableBlock, TextBlock, ViewportInset };