@scrawl-board/board 0.1.0-beta.0

package/dist/core.d.ts

@@ -0,0 +1,1084 @@
+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 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;
+    };
+}
+
+/** 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;
+
+export { AddImageCommand, AddNoteCommand, AddStrokesCommand, AddTableCommand, AddTextCommand, AddTimerCommand, BEACON_INSET, BOARD_COLOR, BoardDocument, CURRENT_DOCUMENT_SCHEMA_VERSION, ClusterStore, DeleteImageCommand, DeleteNoteCommand, DeleteStrokesCommand, DeleteTableCommand, DeleteTextCommand, DeleteTimerCommand, DocumentRecoveryError, END_TAPER, ERASE_THRESHOLD, EraseCommand, FOG_COLOR, HIGHLIGHT_COLORS, History, IDENTITY, INK_COLORS, LockItemsCommand, MIN_WIDTH_FACTOR, 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, SpatialIndex, 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, documentId, documentToSVG, formatTimer, invert, isIdentity, isStampKind, loadDocumentBytes, measureTable, measureTextBlock, migrateDocument, mul, pauseTimer, placePresenceBeacon, ribbonEdges, rotationAbout, scalingAbout, searchBoard, serializeDocument, serializeLock, serializeStroke, setTimerDuration, stampDataUrl, startTimer, strokeId, timerExpired, timerRemaining, toggleTimer, translation };
+export type { BBox, BoardBounds, BoardPoint, BoardScene, BoardStroke, ClusterIdFactory, Command, CommandKind, CurrentSerializedDocument, CurrentSerializedStroke, DocumentChange, DocumentId, DocumentLoadResult, DocumentRecoveryCode, ImageBlock, KitchenTimer, LockHolder, LockTarget, Lockable, Mat2x3, NoteVote, Op, OpCollection, PresencePlacement, RibbonEdgePoint, ScenePath, SearchHit, SearchHitKind, SearchableBoard, SearchableComment, SerializedBoardDocument, SerializedBoardStroke, SerializedPoint, SerializedStroke, StampKind, StickyNote, Stroke, StrokeId, StrokePoint, StrokeTool, TableBlock, TextBlock, ViewportInset };