@scrawl-board/board 0.1.0-beta.6 → 0.1.0-beta.7

package/dist/core.d.ts

@@ -412,6 +412,144 @@ declare function toggleTimer(timer: KitchenTimer, now: number): KitchenTimer;
 declare function setTimerDuration(timer: KitchenTimer, durationMs: number): KitchenTimer;
 declare function formatTimer(ms: number): string;
 
+declare const SHAPE_MIN_SIZE = 0.5;
+declare const SHAPE_DEFAULT_STROKE = "#1C1C1E";
+declare const SHAPE_DEFAULT_STROKE_WIDTH = 0.12;
+interface RectangleObject extends Lockable {
+    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 {
+    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;
+}
+declare function cloneRectangle(rect: RectangleObject): RectangleObject;
+declare function cloneEllipse(ellipse: EllipseObject): EllipseObject;
+/** `"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 {
+    id: string;
+    start: BoardPoint;
+    end: BoardPoint;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+}
+interface ArrowObject extends Lockable {
+    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 {
+    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;
+}
+declare function clonePolygon(polygon: PolygonObject): PolygonObject;
+/** 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 {
+    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;
+}
+declare function cloneStar(star: StarObject): StarObject;
+/** 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 {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    rotation?: number;
+}
+declare function cloneHeart(heart: HeartObject): HeartObject;
+declare function cloneLine(line: LineObject): LineObject;
+declare function cloneArrow(arrow: ArrowObject): ArrowObject;
+/**
+ * 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 {
+    id: string;
+    children: string[];
+}
+declare function cloneGroup(group: GroupObject): GroupObject;
+
 interface BoardPoint {
     x: number;
     y: number;
@@ -477,6 +615,31 @@ interface SerializedDocument {
     timers?: KitchenTimer[];
     /** Absent in documents saved before Custom board objects existed (ticket #22). */
     customObjects?: CustomBoardObject[];
+    /** Absent in documents saved before semantic Rectangle objects existed (Phase 2). */
+    rectangles?: RectangleObject[];
+    /** Absent in documents saved before semantic Ellipse objects existed (Phase 2). */
+    ellipses?: EllipseObject[];
+    /** Absent in documents saved before Groups existed (Phase 3). */
+    groups?: GroupObject[];
+    /** Absent in documents saved before semantic Line objects existed (Phase 4). */
+    lines?: LineObject[];
+    /** Absent in documents saved before semantic Arrow objects existed (Phase 4). */
+    arrows?: ArrowObject[];
+    /** Absent in documents saved before semantic Polygon objects existed (Phase 4). */
+    polygons?: PolygonObject[];
+    /** Absent in documents saved before semantic Star objects existed (Phase 4). */
+    stars?: StarObject[];
+    /** Absent in documents saved before semantic Heart objects existed (Phase 4). */
+    hearts?: HeartObject[];
+    /**
+     * Every content-object id (every type above except comments, which are
+     * host-synced and never enter this schema) in paint order, back to front.
+     * Absent in documents saved before per-object z-order existed (Phase 3) —
+     * migration synthesizes a default order preserving the old fixed-Z-band
+     * visual stacking exactly, so an existing document never visibly changes
+     * on load; only an explicit reorder action touches this from then on.
+     */
+    objectOrder?: string[];
 }
 declare const INK_COLORS: {
     readonly black: "#1C1C1E";
@@ -728,6 +891,60 @@ interface DocumentChange {
     /** Ids of removed custom objects. */
     customObjectsRemoved: string[];
     customObjectsUpdated: CustomBoardObject[];
+    /** Semantic Rectangle objects (Phase 2). */
+    rectanglesAdded: RectangleObject[];
+    /** Ids of removed rectangles. */
+    rectanglesRemoved: string[];
+    rectanglesUpdated: RectangleObject[];
+    /** Semantic Ellipse objects (Phase 2). */
+    ellipsesAdded: EllipseObject[];
+    /** Ids of removed ellipses. */
+    ellipsesRemoved: string[];
+    ellipsesUpdated: EllipseObject[];
+    /** Groups (Phase 3). */
+    groupsAdded: GroupObject[];
+    /** Ids of removed groups (ungrouping, or deleting a group). */
+    groupsRemoved: string[];
+    groupsUpdated: GroupObject[];
+    /** Semantic Line objects (Phase 4). */
+    linesAdded: LineObject[];
+    /** Ids of removed lines. */
+    linesRemoved: string[];
+    linesUpdated: LineObject[];
+    /** Semantic Arrow objects (Phase 4). */
+    arrowsAdded: ArrowObject[];
+    /** Ids of removed arrows. */
+    arrowsRemoved: string[];
+    arrowsUpdated: ArrowObject[];
+    /** Semantic Polygon objects (Phase 4) — Triangle/Diamond/Pentagon/Hexagon/Octagon. */
+    polygonsAdded: PolygonObject[];
+    /** Ids of removed polygons. */
+    polygonsRemoved: string[];
+    polygonsUpdated: PolygonObject[];
+    /** Semantic Star objects (Phase 4). */
+    starsAdded: StarObject[];
+    /** Ids of removed stars. */
+    starsRemoved: string[];
+    starsUpdated: StarObject[];
+    /** Semantic Heart objects (Phase 4). */
+    heartsAdded: HeartObject[];
+    /** Ids of removed hearts. */
+    heartsRemoved: string[];
+    heartsUpdated: HeartObject[];
+    /**
+     * The full current paint order (back to front) of every flat content
+     * object — strokes, texts, tables, images, rectangles, ellipses, lines,
+     * arrows, custom objects, and groups. Populated whenever `objectOrder`
+     * actually changed:
+     * an explicit reorder (`bringForward` etc.), or any add/remove that
+     * touches it — a removal shifts every id after it down one rank, not
+     * just the removed one, so renderers need this to resync everyone, not
+     * only the ids the same change's own `*Added`/`*Removed`/`*Updated`
+     * fields name. Notes (their own `zOffset` peel depth) and Kitchen Timers
+     * (genuine 3D objects, not a flat layer) are intentionally not part of
+     * this order at all.
+     */
+    orderChanged: readonly string[];
 }
 type Listener = (change: DocumentChange) => void;
 declare class BoardDocument {
@@ -742,12 +959,63 @@ declare class BoardDocument {
     private readonly timers;
     /** All Custom board object types share one map, keyed by id — the envelope is already uniform. */
     private readonly customObjects;
+    private readonly rectangles;
+    private readonly ellipses;
+    private readonly groups;
+    private readonly lines;
+    private readonly arrows;
+    private readonly polygons;
+    private readonly stars;
+    private readonly hearts;
     private readonly bboxes;
     private readonly listeners;
+    /** Paint order (back to front) of every flat content object — see `DocumentChange.orderChanged`'s doc comment. */
+    private objectOrder;
+    private orderIndex;
     constructor(id: DocumentId);
+    private reindexOrder;
+    /** The full current paint order, back to front. */
+    order(): readonly string[];
+    /** This object's rank in the paint order, or -1 if it doesn't participate (unknown id, a note, or a timer). */
+    orderRank(id: string): number;
+    private bringForward;
+    private sendBackward;
+    private bringToFront;
+    private sendToBack;
+    /** Reorders `id` relative to its current neighbors. A no-op for an id that doesn't participate in paint order (see `orderRank`). */
+    reorder(id: string, direction: "forward" | "backward" | "front" | "back"): void;
+    /**
+     * Overwrites the paint order directly — used only when loading a document
+     * that already carries a persisted `objectOrder`; every other order
+     * mutation goes through `reorder`/the automatic append-on-add tracking in
+     * `emit`. Ids not present in the document are dropped; ids present in the
+     * document but missing from `order` are appended at the back, so a
+     * partially-stale order (e.g. from a schema migration) never silently
+     * drops an object from paint order entirely.
+     */
+    private setOrder;
     get(id: string): Stroke | undefined;
     all(): IterableIterator<Stroke>;
-    bbox(id: string): BBox | undefined;
+    /**
+     * World-space bounds for any content object, of any type. Strokes hit
+     * their cached-on-mutation fast path (`bboxes`, populated by
+     * `addStrokes`/`transformStrokes` — many points, worth caching); every
+     * other type computes on demand via `objectBounds.ts` (cheap arithmetic,
+     * no caching needed). A group's bounds are the union of its (recursively
+     * resolved) children — `seen` guards against a cycle in nested groups.
+     */
+    bbox(id: string, seen?: Set<string>): BBox | undefined;
+    /**
+     * True if `id` exists and is locked, for any type — the same per-type
+     * probe pattern as `bbox`, for interactive gestures (drag/transform) that
+     * need to gate on lock state regardless of what's selected. Custom
+     * objects are deliberately excluded: their `lock` field is a different
+     * shape (`{holderId, acquiredAt}`, no display name) with no interactive
+     * lock UI yet, matching the existing, deliberate "always unlockable,
+     * never gates a drag" treatment already established elsewhere (e.g.
+     * `getSelectedItemInfo`'s custom branch hardcodes `isLocked: false`).
+     */
+    isLocked(id: string): boolean;
     subscribe(listener: Listener): () => void;
     addStrokes(strokes: Stroke[]): void;
     removeStrokes(ids: string[]): void;
@@ -790,6 +1058,54 @@ declare class BoardDocument {
     removeCustomObjects(ids: string[]): void;
     /** Replace a custom object's contents under the same id. */
     setCustomObject(object: CustomBoardObject): void;
+    getRectangle(id: string): RectangleObject | undefined;
+    allRectangles(): IterableIterator<RectangleObject>;
+    addRectangles(rectangles: RectangleObject[]): void;
+    removeRectangles(ids: string[]): void;
+    /** Replace a rectangle's contents (move, resize, restyle) under the same id. */
+    setRectangle(rect: RectangleObject): void;
+    getEllipse(id: string): EllipseObject | undefined;
+    allEllipses(): IterableIterator<EllipseObject>;
+    addEllipses(ellipses: EllipseObject[]): void;
+    removeEllipses(ids: string[]): void;
+    /** Replace an ellipse's contents (move, resize, restyle) under the same id. */
+    setEllipse(ellipse: EllipseObject): void;
+    getGroup(id: string): GroupObject | undefined;
+    allGroups(): IterableIterator<GroupObject>;
+    addGroups(groups: GroupObject[]): void;
+    removeGroups(ids: string[]): void;
+    /** Replace a group's contents (its children list) under the same id. */
+    setGroup(group: GroupObject): void;
+    getLine(id: string): LineObject | undefined;
+    allLines(): IterableIterator<LineObject>;
+    addLines(lines: LineObject[]): void;
+    removeLines(ids: string[]): void;
+    /** Replace a line's contents (move, restyle) under the same id. */
+    setLine(line: LineObject): void;
+    getArrow(id: string): ArrowObject | undefined;
+    allArrows(): IterableIterator<ArrowObject>;
+    addArrows(arrows: ArrowObject[]): void;
+    removeArrows(ids: string[]): void;
+    /** Replace an arrow's contents (move, restyle, change head) under the same id. */
+    setArrow(arrow: ArrowObject): void;
+    getPolygon(id: string): PolygonObject | undefined;
+    allPolygons(): IterableIterator<PolygonObject>;
+    addPolygons(polygons: PolygonObject[]): void;
+    removePolygons(ids: string[]): void;
+    /** Replace a polygon's contents (move, resize, rotate, restyle) under the same id. */
+    setPolygon(polygon: PolygonObject): void;
+    getStar(id: string): StarObject | undefined;
+    allStars(): IterableIterator<StarObject>;
+    addStars(stars: StarObject[]): void;
+    removeStars(ids: string[]): void;
+    /** Replace a star's contents (move, resize, rotate, restyle) under the same id. */
+    setStar(star: StarObject): void;
+    getHeart(id: string): HeartObject | undefined;
+    allHearts(): IterableIterator<HeartObject>;
+    addHearts(hearts: HeartObject[]): void;
+    removeHearts(ids: string[]): void;
+    /** Replace a heart's contents (move, resize, rotate, restyle) under the same id. */
+    setHeart(heart: HeartObject): 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;
@@ -797,18 +1113,58 @@ declare class BoardDocument {
     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;
+    setRectangleLocked(id: string, locked: boolean, by?: LockHolder | null): void;
+    setEllipseLocked(id: string, locked: boolean, by?: LockHolder | null): void;
+    setGroupLocked(id: string, locked: boolean, by?: LockHolder | null): void;
+    setLineLocked(id: string, locked: boolean, by?: LockHolder | null): void;
+    setArrowLocked(id: string, locked: boolean, by?: LockHolder | null): void;
+    setPolygonLocked(id: string, locked: boolean, by?: LockHolder | null): void;
+    setStarLocked(id: string, locked: boolean, by?: LockHolder | null): void;
+    setHeartLocked(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;
+    replaceAll(strokes: Stroke[], notes: StickyNote[], texts: TextBlock[], tables?: TableBlock[], images?: ImageBlock[], timers?: KitchenTimer[], customObjects?: CustomBoardObject[], rectangles?: RectangleObject[], ellipses?: EllipseObject[], groups?: GroupObject[], lines?: LineObject[], arrows?: ArrowObject[], polygons?: PolygonObject[], stars?: StarObject[], hearts?: HeartObject[], 
+    /** Persisted paint order; absent for a document saved before Phase 3, in which case one is synthesized (see `ORDERED_ADDED_FIELDS`'s doc comment). */
+    objectOrder?: readonly string[]): void;
     /** Apply incremental real-time change received from a remote collaborator over WebSocket. */
     applyRemoteChange(change: Partial<DocumentChange>): void;
     toJSON(): SerializedDocument;
+    static deserializeGroups(data: SerializedDocument): GroupObject[];
+    static deserializeLines(data: SerializedDocument): LineObject[];
+    static deserializeArrows(data: SerializedDocument): ArrowObject[];
+    static deserializePolygons(data: SerializedDocument): PolygonObject[];
+    static deserializeStars(data: SerializedDocument): StarObject[];
+    static deserializeHearts(data: SerializedDocument): HeartObject[];
     static deserializeCustomObjects(data: SerializedDocument): CustomBoardObject[];
+    static deserializeRectangles(data: SerializedDocument): RectangleObject[];
+    static deserializeEllipses(data: SerializedDocument): EllipseObject[];
     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[];
+    /**
+     * Every mutation funnels through here, so paint-order tracking lives in
+     * exactly one place rather than at every individual add/remove call site
+     * (18 of them, times `replaceAll`/`applyRemoteChange`) — new ids are
+     * appended to the back (front-most) of `objectOrder`, removed ids are
+     * spliced out. An explicit reorder (`reorder`/`setOrder`) updates
+     * `objectOrder` itself before calling this, so this step is a no-op for
+     * ids already tracked (idempotent by construction: `orderIndex.has` gates
+     * every append).
+     *
+     * `orderChanged` is populated here whenever `objectOrder` actually
+     * changed — not just for an explicit reorder, but for any add/remove too.
+     * A pure append never shifts an existing id's rank (new ids land at the
+     * tail), but a removal splices a middle id out, which *does* shift every
+     * id after it down by one — a renderer that only resynced Z on an
+     * explicit reorder would silently render those with a stale rank until
+     * something else happened to touch them, eventually colliding with a
+     * freshly-added object's freshly-computed Z. Firing this on every
+     * order-touching change (not just removes) is simpler than special-
+     * casing which kind of change actually needs it, at the cost of a
+     * redundant same-value resync on a pure append.
+     */
     private emit;
 }
 
@@ -844,6 +1200,21 @@ interface Command {
     apply(doc: BoardDocument): void;
     revert(doc: BoardDocument): void;
 }
+/**
+ * Several commands applied/reverted together as one undo step (Phase 3
+ * consolidation — this exact class used to be hand-duplicated as a private
+ * `CommandBatch` in `controller-internal.ts` and an exported
+ * `ExtensionCommandBatch` in `interaction/tools/customTool.ts`; both now
+ * import this one instead). Revert runs in reverse order, so a batch that
+ * depends on ordering (e.g. add-then-reference) undoes cleanly.
+ */
+declare class CommandBatch implements Command {
+    readonly label: string;
+    private readonly commands;
+    constructor(label: string, commands: readonly Command[]);
+    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 {
@@ -908,6 +1279,40 @@ declare class TransformCommand implements Command {
     revert(doc: BoardDocument): void;
     private compose;
 }
+/**
+ * One move gesture over a mixed-type selection (Phase 3) — the general
+ * successor to `TransformCommand` for translation. `TransformCommand`
+ * itself stays as-is (still used for scale/rotate, which remain stroke-only
+ * this phase — see `interaction/tools/selectTool.ts`'s `TransformState`):
+ * its own per-id `doc.get(id)` check already no-ops safely for any id that
+ * isn't a stroke, so it doesn't need touching for that narrower case.
+ *
+ * `delta` here is always a pure translation (never scale/rotate), so
+ * `apply(delta, point)` is a safe, uniform way to move every position-only
+ * type's `x`/`y` — translating commutes trivially regardless of a shape's
+ * own rotation. Matrix-carrying types (stroke, Custom) instead compose
+ * `delta` onto their existing matrix/transform, matching `TransformCommand`.
+ *
+ * A group id in `ids` is expanded into its (recursively resolved, cycle-
+ * safe) children every time `compose` runs — deterministic, since group
+ * membership never changes mid-command — so moving a selected group means
+ * moving every one of its members by the same delta. This expansion is
+ * `TransformObjectsCommand`'s own responsibility precisely so a caller that
+ * doesn't itself expand groups (e.g. `ScrawlEngine.nudgeSelection`) still
+ * gets correct behavior; `interaction/tools/selectTool.ts`'s `TransformState`
+ * separately expands for its own reason (live per-child drag preview), which
+ * makes this a no-op re-expansion for that caller, not a conflict.
+ */
+declare class TransformObjectsCommand implements Command {
+    private readonly ids;
+    private readonly delta;
+    readonly label = "move selection";
+    private readonly inverse;
+    constructor(ids: readonly 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;
@@ -1029,8 +1434,213 @@ declare class DeleteTimerCommand implements Command {
     apply(doc: BoardDocument): void;
     revert(doc: BoardDocument): void;
 }
+/** Add/update/delete for semantic Rectangle objects (Phase 2). */
+declare class AddRectangleCommand implements Command {
+    readonly label = "add rectangle";
+    private readonly rect;
+    constructor(rect: RectangleObject);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class UpdateRectangleCommand implements Command {
+    readonly label = "update rectangle";
+    private readonly before;
+    private readonly after;
+    constructor(before: RectangleObject, after: RectangleObject);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class DeleteRectangleCommand implements Command {
+    readonly label = "delete rectangle";
+    private readonly rect;
+    constructor(rect: RectangleObject);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+/** Add/update/delete for semantic Ellipse objects (Phase 2). */
+declare class AddEllipseCommand implements Command {
+    readonly label = "add ellipse";
+    private readonly ellipse;
+    constructor(ellipse: EllipseObject);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class UpdateEllipseCommand implements Command {
+    readonly label = "update ellipse";
+    private readonly before;
+    private readonly after;
+    constructor(before: EllipseObject, after: EllipseObject);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class DeleteEllipseCommand implements Command {
+    readonly label = "delete ellipse";
+    private readonly ellipse;
+    constructor(ellipse: EllipseObject);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+/** Add/update/delete for semantic Line objects (Phase 4). */
+declare class AddLineCommand implements Command {
+    readonly label = "add line";
+    private readonly line;
+    constructor(line: LineObject);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class UpdateLineCommand implements Command {
+    readonly label = "update line";
+    private readonly before;
+    private readonly after;
+    constructor(before: LineObject, after: LineObject);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class DeleteLineCommand implements Command {
+    readonly label = "delete line";
+    private readonly line;
+    constructor(line: LineObject);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+/** Add/update/delete for semantic Arrow objects (Phase 4). */
+declare class AddArrowCommand implements Command {
+    readonly label = "add arrow";
+    private readonly arrow;
+    constructor(arrow: ArrowObject);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class UpdateArrowCommand implements Command {
+    readonly label = "update arrow";
+    private readonly before;
+    private readonly after;
+    constructor(before: ArrowObject, after: ArrowObject);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class DeleteArrowCommand implements Command {
+    readonly label = "delete arrow";
+    private readonly arrow;
+    constructor(arrow: ArrowObject);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+/** Add/update/delete for semantic Polygon objects (Phase 4) — Triangle/Diamond/Pentagon/Hexagon/Octagon. */
+declare class AddPolygonCommand implements Command {
+    readonly label = "add polygon";
+    private readonly polygon;
+    constructor(polygon: PolygonObject);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class UpdatePolygonCommand implements Command {
+    readonly label = "update polygon";
+    private readonly before;
+    private readonly after;
+    constructor(before: PolygonObject, after: PolygonObject);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class DeletePolygonCommand implements Command {
+    readonly label = "delete polygon";
+    private readonly polygon;
+    constructor(polygon: PolygonObject);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+/** Add/update/delete for semantic Star objects (Phase 4). */
+declare class AddStarCommand implements Command {
+    readonly label = "add star";
+    private readonly star;
+    constructor(star: StarObject);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class UpdateStarCommand implements Command {
+    readonly label = "update star";
+    private readonly before;
+    private readonly after;
+    constructor(before: StarObject, after: StarObject);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class DeleteStarCommand implements Command {
+    readonly label = "delete star";
+    private readonly star;
+    constructor(star: StarObject);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+/** Add/update/delete for semantic Heart objects (Phase 4). */
+declare class AddHeartCommand implements Command {
+    readonly label = "add heart";
+    private readonly heart;
+    constructor(heart: HeartObject);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class UpdateHeartCommand implements Command {
+    readonly label = "update heart";
+    private readonly before;
+    private readonly after;
+    constructor(before: HeartObject, after: HeartObject);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class DeleteHeartCommand implements Command {
+    readonly label = "delete heart";
+    private readonly heart;
+    constructor(heart: HeartObject);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+/** Add/update/delete for Groups (Phase 3). */
+declare class AddGroupCommand implements Command {
+    readonly label = "group";
+    private readonly group;
+    constructor(group: GroupObject);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class UpdateGroupCommand implements Command {
+    readonly label = "update group";
+    private readonly before;
+    private readonly after;
+    constructor(before: GroupObject, after: GroupObject);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+declare class DeleteGroupCommand implements Command {
+    readonly label = "ungroup";
+    private readonly group;
+    constructor(group: GroupObject);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
+type ReorderDirection = "forward" | "backward" | "front" | "back";
+/**
+ * Bring-forward / send-backward / bring-to-front / send-to-back (Phase 3) —
+ * one command family covering all four directions rather than four
+ * near-identical classes, since the only difference between them is which
+ * `BoardDocument.reorder` direction to replay. Captures the full paint order
+ * on first `apply` rather than in the constructor — `BoardDocument.order()`
+ * needs the doc, which a `Command` only ever receives via `apply`/`revert` —
+ * so `revert` can restore it exactly; redo re-runs the same `reorder` call,
+ * which is deterministic because `revert` always restores the identical
+ * starting order first.
+ */
+declare class ReorderObjectCommand implements Command {
+    private readonly id;
+    private readonly direction;
+    readonly label: string;
+    private before;
+    constructor(id: string, direction: ReorderDirection);
+    apply(doc: BoardDocument): void;
+    revert(doc: BoardDocument): void;
+}
 interface LockTarget {
-    type: "stroke" | "note" | "text" | "table" | "image" | "timer";
+    type: "stroke" | "note" | "text" | "table" | "image" | "timer" | "rectangle" | "ellipse" | "group" | "line" | "arrow" | "polygon" | "star" | "heart";
     id: string;
     locked: boolean;
     lockedBy?: string;
@@ -1047,7 +1657,7 @@ declare class LockItemsCommand implements Command {
     private applyLock;
 }
 
-type OpCollection = "strokes" | "notes" | "textBlocks" | "tables" | "images" | "timers" | "customObjects";
+type OpCollection = "strokes" | "notes" | "textBlocks" | "tables" | "images" | "timers" | "rectangles" | "ellipses" | "groups" | "lines" | "arrows" | "polygons" | "stars" | "hearts" | "customObjects";
 type Op = {
     kind: "upsert";
     collection: OpCollection;
@@ -1091,10 +1701,10 @@ declare function ribbonEdges(points: StrokePoint[], baseWidth: number, handDrawn
 declare class SpatialIndex {
     private readonly doc;
     private readonly cells;
-    private readonly strokeCells;
+    private readonly objectCells;
     private readonly unsubscribe;
     constructor(doc: BoardDocument);
-    /** Ids of strokes whose bbox may overlap the query rect. */
+    /** Ids of content objects (any type except groups) whose bbox may overlap the query rect. */
     query(minX: number, minY: number, maxX: number, maxY: number): Set<string>;
     dispose(): void;
     private insert;
@@ -1176,5 +1786,5 @@ type BoardStroke = Stroke;
 type SerializedBoardStroke = SerializedStroke;
 type SerializedBoardDocument = CurrentSerializedDocument;
 
-export { ASSET_CACHE_BYTES_DEFAULT, ASSET_CACHE_BYTES_MAX, ASSET_CACHE_BYTES_MIN, ASSET_EXPORT_MAX_DECODED_MEGAPIXELS, ASSET_EXPORT_MAX_ENCODED_BYTES, ASSET_MAX_CONCURRENT_RESOLUTIONS, ASSET_MAX_DECODED_MEGAPIXELS, ASSET_MAX_DIMENSION_PX, ASSET_MAX_ENCODED_BYTES, ASSET_REF_MAX_BYTES, ASSET_REF_PATTERN, AddImageCommand, AddNoteCommand, AddStrokesCommand, AddTableCommand, AddTextCommand, AddTimerCommand, AssetResolutionError, BEACON_INSET, 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, SUPPORTED_ASSET_MEDIA_TYPES, 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, assetRef, avgScale, canUnlockItem, changeToOps, clampAssetCacheBytes, cloneCustomObject, cloneImage, cloneNote, cloneStroke, cloneTable, cloneText, cloneTimer, documentId, documentToSVG, formatTimer, invert, isAssetRef, 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 { AssetDiagnostic, AssetIngestRequest, AssetIngestResult, AssetIngestor, AssetKind, AssetPurpose, AssetRef, AssetResolutionErrorCode, AssetResolveRequest, AssetResolveResult, AssetResolver, BBox, BoardKeyInput, BoardPoint, BoardPointerInput, BoardScene, BoardStroke, ClusterIdFactory, Command, CommandKind, CurrentSerializedDocument, CurrentSerializedStroke, CustomBoardObject, CustomObjectAddInput, CustomObjectDefinition, CustomTool, CustomToolDefinition, DocumentChange, DocumentId, DocumentLoadResult, DocumentRecoveryCode, ExtensionCommand, ExtensionDiagnostic, ExtensionHitResult, ExtensionId, ExtensionRequirement, ImageBlock, InputModifiers, JsonObject, JsonValue, KitchenTimer, LockHolder, LockTarget, Lockable, Mat2x3, NoteVote, ObjectDescribeContext, ObjectIntent, ObjectType, Op, OpCollection, PresencePlacement, QueryableBoardObject, ReadonlyCustomObject, RibbonEdgePoint, SceneEllipse, SceneGroup, SceneImage, ScenePath, SceneRect, SceneText, ScrawlExtension, SearchHit, SearchHitKind, SearchableBoard, SearchableComment, SerializedBoardDocument, SerializedBoardStroke, SerializedPoint, SerializedStroke, StampKind, StickyNote, Stroke, StrokeId, StrokePoint, StrokeTool, SupportedAssetMediaType, TableBlock, TextBlock, ToolCancelReason, ToolCapabilities, ToolCursor, ToolId, ViewportInset };
+export { ASSET_CACHE_BYTES_DEFAULT, ASSET_CACHE_BYTES_MAX, ASSET_CACHE_BYTES_MIN, ASSET_EXPORT_MAX_DECODED_MEGAPIXELS, ASSET_EXPORT_MAX_ENCODED_BYTES, ASSET_MAX_CONCURRENT_RESOLUTIONS, ASSET_MAX_DECODED_MEGAPIXELS, ASSET_MAX_DIMENSION_PX, ASSET_MAX_ENCODED_BYTES, ASSET_REF_MAX_BYTES, ASSET_REF_PATTERN, AddArrowCommand, AddEllipseCommand, AddGroupCommand, AddHeartCommand, AddImageCommand, AddLineCommand, AddNoteCommand, AddPolygonCommand, AddRectangleCommand, AddStarCommand, AddStrokesCommand, AddTableCommand, AddTextCommand, AddTimerCommand, AssetResolutionError, BEACON_INSET, BoardDocument, CURRENT_DOCUMENT_SCHEMA_VERSION, ClusterStore, CommandBatch, DeleteArrowCommand, DeleteEllipseCommand, DeleteGroupCommand, DeleteHeartCommand, DeleteImageCommand, DeleteLineCommand, DeleteNoteCommand, DeletePolygonCommand, DeleteRectangleCommand, DeleteStarCommand, 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, ReorderObjectCommand, SDK_DEVELOPMENT_VERSION, SDK_PACKAGE_NAME, SHAPE_DEFAULT_STROKE, SHAPE_DEFAULT_STROKE_WIDTH, SHAPE_MIN_SIZE, STAMPS, STAMP_SIZE, SUPPORTED_ASSET_MEDIA_TYPES, 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, TransformObjectsCommand, UpdateArrowCommand, UpdateEllipseCommand, UpdateGroupCommand, UpdateHeartCommand, UpdateImageCommand, UpdateLineCommand, UpdateNoteCommand, UpdatePolygonCommand, UpdateRectangleCommand, UpdateStarCommand, UpdateTableCommand, UpdateTextCommand, UpdateTimerCommand, apply, applyItemLock, assetRef, avgScale, canUnlockItem, changeToOps, clampAssetCacheBytes, cloneArrow, cloneCustomObject, cloneEllipse, cloneGroup, cloneHeart, cloneImage, cloneLine, cloneNote, clonePolygon, cloneRectangle, cloneStar, cloneStroke, cloneTable, cloneText, cloneTimer, documentId, documentToSVG, formatTimer, invert, isAssetRef, 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 { ArrowHeadStyle, ArrowObject, AssetDiagnostic, AssetIngestRequest, AssetIngestResult, AssetIngestor, AssetKind, AssetPurpose, AssetRef, AssetResolutionErrorCode, AssetResolveRequest, AssetResolveResult, AssetResolver, BBox, BoardKeyInput, BoardPoint, BoardPointerInput, BoardScene, BoardStroke, ClusterIdFactory, Command, CommandKind, CurrentSerializedDocument, CurrentSerializedStroke, CustomBoardObject, CustomObjectAddInput, CustomObjectDefinition, CustomTool, CustomToolDefinition, DocumentChange, DocumentId, DocumentLoadResult, DocumentRecoveryCode, EllipseObject, ExtensionCommand, ExtensionDiagnostic, ExtensionHitResult, ExtensionId, ExtensionRequirement, GroupObject, HeartObject, ImageBlock, InputModifiers, JsonObject, JsonValue, KitchenTimer, LineObject, LockHolder, LockTarget, Lockable, Mat2x3, NoteVote, ObjectDescribeContext, ObjectIntent, ObjectType, Op, OpCollection, PolygonObject, PresencePlacement, QueryableBoardObject, ReadonlyCustomObject, RectangleObject, ReorderDirection, RibbonEdgePoint, SceneEllipse, SceneGroup, SceneImage, ScenePath, SceneRect, SceneText, ScrawlExtension, SearchHit, SearchHitKind, SearchableBoard, SearchableComment, SerializedBoardDocument, SerializedBoardStroke, SerializedPoint, SerializedStroke, StampKind, StarObject, StickyNote, Stroke, StrokeId, StrokePoint, StrokeTool, SupportedAssetMediaType, TableBlock, TextBlock, ToolCancelReason, ToolCapabilities, ToolCursor, ToolId, ViewportInset };