@scrawl-board/board 0.1.0-beta.1 → 0.1.0-beta.11

package/dist/local.d.ts

@@ -0,0 +1,518 @@
+/** Wire grammar: `asset:<namespace>:<opaque-id>`. Interpreted only by the Host. */
+type AssetRef = string;
+
+type Mat2x3 = [number, number, number, number, number, number];
+
+/** A stable namespaced string, e.g. `com.acme.kanban/card`. */
+type ObjectType = string;
+type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    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;
+}
+
+interface Lockable {
+    locked?: boolean;
+    lockedBy?: string;
+    lockedByName?: string;
+}
+
+/**
+ * Per-object visibility (Phase 8) — mirrors `itemLock.ts`'s `Lockable`
+ * pattern exactly, but simpler: unlike a lock, hidden state carries no
+ * holder/ownership concept, so there's no analogue to `LockHolder`/
+ * `canUnlockItem`. A hidden object stays fully present in the Document
+ * (still serializes, persists, syncs, undoes/redoes) — it just skips
+ * rendering and hit-testing/selection candidacy. `hidden` absent or
+ * `false` means visible; this keeps every pre-Phase-8 document (which has
+ * no `hidden` field on any object at all) implicitly fully visible with
+ * zero migration needed.
+ */
+interface Hideable {
+    hidden?: boolean;
+}
+
+/** A kitchen timer sitting on the board. Remaining time is derived, not ticked. */
+interface KitchenTimer extends Lockable, Hideable {
+    id: string;
+    x: number;
+    y: number;
+    /** Face diameter in board units. */
+    size: number;
+    /** What you set it to — 1, 5, 10, 15 minutes. */
+    durationMs: number;
+    /** Remaining at the last start or pause. */
+    remainingMs: number;
+    /** Wall-clock ms when the current run started. Absent means paused. */
+    runningSince?: number;
+}
+
+interface RectangleObject extends Lockable, Hideable {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    /** Corner radius in board units; clamped to at most half the shorter side at render time. */
+    cornerRadius?: number;
+    /** `[0, 1]`; undefined means fully opaque (Phase 4). */
+    opacity?: number;
+    /**
+     * Radians, about the shape's own center `(x + width/2, y - height/2)`.
+     * Undefined means 0 (Phase 3). `x`/`y`/`width`/`height` stay in the
+     * shape's own unrotated local frame — rotation is a separate, applied-last
+     * transform, not baked into them, matching how Stroke/CustomBoardObject
+     * keep geometry and placement independent via their own `matrix`.
+     */
+    rotation?: number;
+}
+interface EllipseObject extends Lockable, Hideable {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    /** `[0, 1]`; undefined means fully opaque (Phase 4). */
+    opacity?: number;
+    /** Radians, about the shape's own center — see RectangleObject's `rotation` doc. */
+    rotation?: number;
+}
+/** `"none"` is a plain line with no arrowhead; today's only real head shape is `"triangle"`. New head shapes extend this union without touching `ArrowObject`'s own fields. */
+type ArrowHeadStyle = "triangle" | "none";
+interface LineObject extends Lockable, Hideable {
+    id: string;
+    start: BoardPoint;
+    end: BoardPoint;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+}
+/** An endpoint anchored to a normalized position on another object's bounds. */
+interface ConnectorBinding {
+    objectId: string;
+    /** Horizontal and vertical fractions of the target's axis-aligned bounds. */
+    x: number;
+    y: number;
+}
+interface ArrowObject extends Lockable, Hideable {
+    /** Omitted for legacy arrows. Connectors share Arrow's persistence/history contract. */
+    routing?: "straight" | "curved" | "polyline";
+    /** Intermediate board-space vertices for a multi-point connector. */
+    waypoints?: BoardPoint[];
+    startBinding?: ConnectorBinding;
+    endBinding?: ConnectorBinding;
+    id: string;
+    start: BoardPoint;
+    end: BoardPoint;
+    head?: ArrowHeadStyle;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+}
+/**
+ * Triangle(3)/Diamond(4)/Pentagon(5)/Hexagon(6)/Octagon(8) as one shared
+ * type instead of five near-duplicate interfaces — a regular N-gon
+ * inscribed in the same `x`/`y`/`width`/`height`/`rotation` bounding box
+ * Rectangle already uses, parameterized by `sides`. Diamond is exactly a
+ * 4-sided regular polygon with vertex 0 pointing right (not up, like
+ * Triangle/Pentagon/Hexagon) — see `polygonGeometry.ts`'s
+ * `polygonStartAngle`, which encodes each side count's own vertex
+ * orientation so the outline always matches the legacy drag-preview shape.
+ */
+interface PolygonObject extends Lockable, Hideable {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    sides: 3 | 4 | 5 | 6 | 8;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    /** Radians, about the shape's own center — see RectangleObject's `rotation` doc. */
+    rotation?: number;
+}
+/** Same bounding-box/rotation convention as Rectangle; a 5-pointed star with a tuned inner-radius ratio, matching the legacy tool's own default (see `polygonGeometry.ts`'s `starPoints`). */
+interface StarObject extends Lockable, Hideable {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Vertex count; today's only shipped preset is 5, matching the legacy tool. */
+    points: number;
+    /** `(0, 1)` — inner vertex radius as a fraction of the outer radius. */
+    innerRadiusRatio: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    rotation?: number;
+}
+/** Same bounding-box/rotation convention as Rectangle; the standard parametric heart curve (see `polygonGeometry.ts`'s `heartPoints`), no extra parameters beyond the shared shape fields. */
+interface HeartObject extends Lockable, Hideable {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    rotation?: number;
+}
+/**
+ * A logical grouping of other board objects (Phase 3 — Selection,
+ * Transformation & Grouping). Deliberately has no `x`/`y`/`transform` of its
+ * own — a group's bounds are always derived on demand from its (recursively
+ * resolved) children, and "moving/rotating/scaling the group" is exactly a
+ * multi-object transform applied to those children, nothing more. A group
+ * has no renderer/mesh of its own; its only visual presence is the
+ * selection gizmo's bounding box while it's the current selection.
+ *
+ * `children` may itself contain other group ids (nested groups) — expanding
+ * a group into its leaf members is always done by the caller (recursively,
+ * with cycle protection), never assumed here.
+ */
+interface GroupObject extends Lockable, Hideable {
+    id: string;
+    children: string[];
+}
+
+interface BoardPoint {
+    x: number;
+    y: number;
+}
+/**
+ * Which drawing tool made a stroke; undefined means marker (back-compat).
+ * `"shape"` (rect/ellipse/line/arrow/polygon/star/heart) renders at its
+ * exact configured width with no pressure variance or end taper — a
+ * geometric outline, not an expressive ink mark.
+ */
+type StrokeTool = "marker" | "highlighter" | "shape";
+type SerializedPoint = [number, number, number, number];
+interface SerializedStroke extends Lockable, Hideable {
+    id: string;
+    color: string;
+    baseWidth: number;
+    tool?: StrokeTool;
+    points: SerializedPoint[];
+    /** Omitted when identity. */
+    matrix?: [number, number, number, number, number, number];
+    clusterId?: string;
+}
+/** A named notebook containing sections. */
+interface BoardNotebook {
+    readonly id: string;
+    readonly name: string;
+    readonly color: string;
+}
+/** A named section containing pages. */
+interface BoardSection {
+    readonly id: string;
+    readonly notebookId: string;
+    readonly name: string;
+    readonly color: string;
+}
+/** An additional page. The first page remains in the document's top-level collections. */
+interface SerializedBoardPage {
+    id: string;
+    sectionId?: string;
+    name: string;
+    content: SerializedDocument;
+}
+interface SerializedDocument {
+    /** Notebook and section metadata. Older boards use an implicit default of each. */
+    notebooks?: BoardNotebook[];
+    sections?: BoardSection[];
+    /** Section of the original first page; defaults to `default`. */
+    pageSectionId?: string;
+    /** Display name of the first page (id `default`). */
+    pageName?: string;
+    /** Additional pages, in sidebar order. Nested pages are not allowed. */
+    pages?: SerializedBoardPage[];
+    /** Absent in every historical document; current saves always write 1. */
+    schemaVersion?: 1;
+    strokes: SerializedStroke[];
+    /** 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[];
+    /** Absent in documents saved before semantic Rectangle objects existed (Phase 2). */
+    rectangles?: RectangleObject[];
+    /** Absent in documents saved before semantic Ellipse objects existed (Phase 2). */
+    ellipses?: EllipseObject[];
+    /** Absent in documents saved before Groups existed (Phase 3). */
+    groups?: GroupObject[];
+    /** Absent in documents saved before semantic Line objects existed (Phase 4). */
+    lines?: LineObject[];
+    /** Absent in documents saved before semantic Arrow objects existed (Phase 4). */
+    arrows?: ArrowObject[];
+    /** Absent in documents saved before semantic Polygon objects existed (Phase 4). */
+    polygons?: PolygonObject[];
+    /** Absent in documents saved before semantic Star objects existed (Phase 4). */
+    stars?: StarObject[];
+    /** Absent in documents saved before semantic Heart objects existed (Phase 4). */
+    hearts?: HeartObject[];
+    /**
+     * Every content-object id (every type above except comments, which are
+     * host-synced and never enter this schema) in paint order, back to front.
+     * Absent in documents saved before per-object z-order existed (Phase 3) —
+     * migration synthesizes a default order preserving the old fixed-Z-band
+     * visual stacking exactly, so an existing document never visibly changes
+     * on load; only an explicit reorder action touches this from then on.
+     */
+    objectOrder?: string[];
+}
+/**
+ * One collaborator's vote on a note. One per person; toggling removes it.
+ */
+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, Hideable {
+    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, Hideable {
+    id: string;
+    x: number;
+    y: number;
+    text: string;
+    /** Line height in board units. */
+    fontSize: number;
+    color: string;
+    clusterId?: string;
+}
+/**
+ * Interactive structured table on the board. Position (x, y) is top-left in board units.
+ * Cells are indexed as `${row},${col}` keys mapping to cell text content.
+ */
+interface TableBlock extends Lockable, Hideable {
+    id: string;
+    x: number;
+    y: number;
+    rows: number;
+    cols: number;
+    colWidths: number[];
+    rowHeights: number[];
+    cells: Record<string, string>;
+    color?: string;
+    backgroundColor?: string;
+    clusterId?: string;
+}
+/**
+ * An imported image block on the board plane.
+ * Coordinates (x, y) represent the center of the image in board space.
+ */
+interface ImageBlock extends Lockable, Hideable {
+    id: string;
+    /**
+     * A legacy, read-only data URL (or, historically, an arbitrary string) —
+     * never written by new code once `ref` exists. Ticket #23's Host-managed
+     * Assets add `ref` as the durable path going forward; `src` and `ref` are
+     * mutually exclusive in practice, but both fields exist on every
+     * `ImageBlock` so old and new objects share one shape.
+     */
+    src: string;
+    /** Opaque Asset reference (ticket #23); when present, `src` is ignored. */
+    ref?: AssetRef;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    aspectRatio: number;
+    name?: string;
+    createdAt?: string;
+    /** Present when this image is a stamp from the pad, not a photo. */
+    stamp?: string;
+}
+
+declare const strokeIdBrand: unique symbol;
+type StrokeId = string & {
+    readonly [strokeIdBrand]: "StrokeId";
+};
+
+declare const CURRENT_DOCUMENT_SCHEMA_VERSION: 1;
+type CurrentSerializedStroke = Omit<SerializedStroke, "id"> & {
+    id: StrokeId;
+};
+interface CurrentSerializedDocument extends Required<Omit<SerializedDocument, "pages" | "pageName" | "notebooks" | "sections" | "pageSectionId">> {
+    schemaVersion: typeof CURRENT_DOCUMENT_SCHEMA_VERSION;
+    strokes: CurrentSerializedStroke[];
+    pageName?: string;
+    notebooks?: BoardNotebook[];
+    sections?: BoardSection[];
+    pageSectionId?: string;
+    pages?: SerializedBoardPage[];
+}
+
+interface DocumentContext {
+    documentId: string;
+    signal: AbortSignal;
+}
+type LoadResult = {
+    state: "found";
+    document: CurrentSerializedDocument;
+    revision: string;
+} | {
+    state: "missing";
+};
+/**
+ * Result of a whole-document `PersistenceAdapter.replace()` call (ADR 0006:
+ * "Whole-document writes survive only for create, clear-board and import,
+ * where replacing everything is the actual intent"). Revision-gated, unlike
+ * `applyOps` — `conflict` means `baseRevision` was stale (someone else's
+ * write landed first); the caller must reload and never overwrites blind.
+ */
+type ReplaceResult = {
+    state: "applied";
+    revision: string;
+} | {
+    state: "conflict";
+    currentRevision: string;
+};
+/**
+ * The one sanctioned seam for persisting a Board's Document to a Host's own
+ * storage — implement this against a database, an HTTP API, IndexedDB
+ * (see `@scrawl-board/board/local`'s `createIndexedDBPersistence`), or
+ * anything else. `load()` fetches the current state on connect; `applyOps()`
+ * streams incremental Ops as edits happen; `replace()` is only for
+ * whole-document writes (create, clear-board, import — see ADR 0006) and is
+ * revision-gated so a stale write never silently clobbers a newer one.
+ * Passed via `createBoardController({ adapters: { persistence } })`.
+ */
+interface PersistenceAdapter {
+    load(context: DocumentContext): Promise<LoadResult>;
+    applyOps(context: DocumentContext, ops: readonly ControllerOp[]): Promise<ApplyOpsResult>;
+    replace(context: DocumentContext, document: CurrentSerializedDocument, baseRevision: string): Promise<ReplaceResult>;
+}
+/**
+ * `"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";
+};
+interface ControllerOp {
+    id: string;
+    schemaVersion: 1;
+    kind: "upsert" | "restore" | "remove";
+    objectType: "stroke" | "note" | "text" | "table" | "image" | "timer" | "rectangle" | "ellipse" | "group" | "line" | "arrow" | "polygon" | "star" | "heart" | "custom"
+    /**
+     * A whole-document paint-order sync (Phase 3), not a per-object type —
+     * `objectId` is always the fixed sentinel `"order"` and `payload` is
+     * `{ order: string[] }`. The only `objectType` with no matching
+     * `BoardObject`/document collection; kept in this same union (rather
+     * than a separate wire message) so it flows through the existing
+     * `PersistenceAdapter`/`CollaborationAdapter` opaquely, unchanged.
+     */
+     | "order" | "page" | "notebook" | "section";
+    /** Absent for the original page; scopes content and order Ops to an additional page. */
+    pageId?: string;
+    objectId: string;
+    payload?: unknown;
+    /**
+     * This op's position in its own originating client's local sequence
+     * (Phase 7) — 1, 2, 3, ... per controller instance, distinct from `id`
+     * (an opaque, globally-unique identifier used for dedup/ack, not
+     * ordering) and from a server's own authoritative ordering (e.g.
+     * `referenceCollaborationServer.ts`'s per-room `version` counter).
+     * Present on every op this SDK originates locally; a remote peer's op
+     * carries whatever its own origin set, unchanged — never renumbered in
+     * transit. Absent on an op minted by decoding the legacy wire envelope
+     * (`scrawlOpEnvelope.ts`), which predates this field and has no
+     * per-client sequence concept of its own.
+     */
+    clientSequence?: number;
+    /**
+     * The `CollaboratorIdentity.id` of this op's originating client (Phase
+     * 7) — set for every op this SDK originates locally when `identity` is
+     * configured, omitted entirely otherwise (never sent as `undefined`).
+     * The explicit foundation for a future per-author undo filter (a local
+     * user's own undo should only ever touch their own ops) — no undo-stack
+     * behavior itself changes this phase.
+     */
+    clientId?: string;
+}
+
+interface CreateIndexedDBPersistenceOptions {
+    /** IndexedDB database name — change to isolate multiple boards sharing an origin. Defaults to `"scrawl-board"`. */
+    databaseName?: string;
+    /** Injectable for tests (e.g. `fake-indexeddb`) or a non-`window` runtime that still provides IndexedDB. Defaults to `globalThis.indexedDB`. */
+    indexedDB?: IDBFactory;
+}
+/**
+ * Creates a `PersistenceAdapter` backed by the browser's IndexedDB. One
+ * instance can back multiple documents (keyed by
+ * `DocumentContext.documentId`), stored in object-level records so a
+ * partial save never corrupts unrelated objects.
+ */
+declare function createIndexedDBPersistence(options?: CreateIndexedDBPersistenceOptions): PersistenceAdapter;
+
+export { createIndexedDBPersistence };
+export type { CreateIndexedDBPersistenceOptions };