@memberjunction/ng-whiteboard 0.0.1 → 5.41.0

package/dist/lib/whiteboard-state.js

@@ -0,0 +1,1396 @@
+import { Subject } from 'rxjs';
+import { UUIDsEqual } from '@memberjunction/global';
+/**
+ * Curated font-size steps for text labels and sticky notes. The toolbar's text-style flyout
+ * and the agent's `fontSize` tool params both restrict to these values.
+ */
+export const WHITEBOARD_FONT_SIZES = [12, 14, 18, 24, 32];
+/** Render-time default dimensions for items whose size is content-driven. */
+export const WHITEBOARD_DEFAULTS = {
+    StickyW: 172,
+    StickyH: 96,
+    ImageW: 198,
+    ImageH: 134,
+    TextW: 132,
+    TextH: 18,
+    ShapeMinH: 56,
+    MarkdownW: 280,
+    MarkdownMinH: 96,
+    HtmlW: 360,
+    HtmlH: 240
+};
+/**
+ * Whether an item kind is BOX-RESIZABLE by the user — i.e. the selection chrome shows the
+ * 8 resize handles for it. Everything with a box model resizes: stickies, shapes, text
+ * labels, images, markdown panels, HTML widgets and highlight regions. Ink strokes and
+ * connectors are path-based and are not box-resizable.
+ */
+export function IsResizableKind(kind) {
+    return kind === 'sticky' || kind === 'shape' || kind === 'text' || kind === 'image'
+        || kind === 'highlight' || kind === 'markdown' || kind === 'html';
+}
+/**
+ * The patch a COMMITTED resize gesture applies for an item kind, given the gesture's
+ * final bounds:
+ *  - full-box kinds (`shape`, `highlight`, `html`) commit X / Y / W / H;
+ *  - content-driven-height kinds (`sticky`, `text`, `image`, `markdown`) commit
+ *    X / Y / W only — their rendered height stays content-driven (markdown's optional
+ *    `H` max-height cap is set by tools/agents, never by the drag gesture);
+ *  - non-resizable kinds (`ink`, `connector`) return `null` (nothing to commit).
+ */
+export function BuildResizeCommitPatch(kind, bounds) {
+    if (kind === 'shape' || kind === 'highlight' || kind === 'html') {
+        return { X: bounds.X, Y: bounds.Y, W: bounds.W, H: bounds.H };
+    }
+    if (kind === 'sticky' || kind === 'text' || kind === 'image' || kind === 'markdown') {
+        return { X: bounds.X, Y: bounds.Y, W: bounds.W };
+    }
+    return null;
+}
+/** Truncate long item text for summary fragments. */
+function clip(text, max = 42) {
+    const t = (text || '').replace(/\s+/g, ' ').trim();
+    return t.length > max ? `${t.slice(0, max).trimEnd()}…` : t;
+}
+/**
+ * The whiteboard engine: items + ordered render list, single selection, snapshot-based
+ * undo/redo (one entry per user gesture or per agent tool call via {@link RunBatch}),
+ * change journal + coalesced scene deltas, JSON persistence, and the cancelable
+ * BEFORE / AFTER mutation event surface.
+ *
+ * ## Before / after events
+ *
+ * Every targeted mutation raises a cancelable BEFORE event and, when it applies, a
+ * matching AFTER event:
+ *
+ * | Mutation | Before (cancelable) | After |
+ * |---|---|---|
+ * | {@link AddItem} (incl. {@link Highlight}, {@link DuplicateItem}) | {@link ItemAdding$} | {@link ItemAdded$} |
+ * | {@link UpdateItem} / {@link MoveItem} / {@link BringToFront} / {@link SendToBack} | {@link ItemUpdating$} | {@link ItemUpdated$} |
+ * | {@link UpdateItem} touching content fields (Text / Label / Sub / Markdown / Html / Title) | {@link ContentChanging$} (after ItemUpdating$) | {@link ContentChanged$} |
+ * | {@link RemoveItem} | {@link ItemRemoving$} | {@link ItemRemoved$} |
+ * | {@link AddPage} | {@link PageAdding$} | {@link PageAdded$} |
+ * | {@link SwitchPage} | {@link PageSwitching$} | {@link PageSwitched$} |
+ * | {@link RenamePage} | {@link PageRenaming$} | {@link PageRenamed$} |
+ * | {@link RemovePage} | {@link PageRemoving$} | {@link PageRemoved$} |
+ * | {@link Select} (and implicit clears) | — | {@link SelectionChanged$} |
+ * | {@link Clear} | — | {@link BoardCleared$} |
+ * | {@link LoadFromJSON} | — | {@link BoardLoaded$} |
+ *
+ * Handlers run synchronously during the emit; setting `Cancel = true` on the event args
+ * aborts the mutation (the caller sees `null` / `false`) with no undo snapshot, journal
+ * entry or {@link Changed$} emission. These events layer ALONGSIDE the existing
+ * {@link Changed$} / journal / perception machinery — they never replace it. Undo / redo
+ * whole-scene replacements are NOT item mutations and only surface through
+ * {@link Changed$} as `'replace'` ops.
+ */
+export class WhiteboardState {
+    constructor() {
+        /**
+         * The ordered page list. A fresh board has one page named "Page 1". Every item
+         * operation reads/writes the ACTIVE page's map through the `items` accessor below, so
+         * the entire pre-pages mutation surface is page-scoped without per-call changes.
+         */
+        this.pages = [{ ID: 'page-1', Name: 'Page 1', Author: 'user', Items: new Map() }];
+        /** ID of the active page (always present in {@link pages}). */
+        this.activePageId = 'page-1';
+        /** Monotonic page counter — mints page IDs and the "Page N" auto-names. */
+        this.pageCounter = 1;
+        this.idCounter = 0;
+        this.zCounter = 0;
+        this.seq = 0;
+        this.undoStack = [];
+        this.redoStack = [];
+        this.batchDepth = 0;
+        this.journal = [];
+        /** Per-item snapshot of "did this item exist at journal-trim time" is not needed because
+         * trimming forces reset semantics for tokens older than the journal window. */
+        this.journalTrimmedBeforeSeq = 0;
+        this.changed = new Subject();
+        /** Fires after every mutation (including undo/redo `'replace'` events). */
+        this.Changed$ = this.changed.asObservable();
+        this.itemAdding = new Subject();
+        /**
+         * Cancelable BEFORE event of {@link AddItem} (and {@link Highlight} /
+         * {@link DuplicateItem}, which add through it). Set `Cancel = true` synchronously to
+         * veto the add — {@link AddItem} then returns `null` and nothing changes.
+         */
+        this.ItemAdding$ = this.itemAdding.asObservable();
+        this.itemAdded = new Subject();
+        /** AFTER event: an item was added (fires once per applied {@link AddItem}). */
+        this.ItemAdded$ = this.itemAdded.asObservable();
+        this.itemUpdating = new Subject();
+        /**
+         * Cancelable BEFORE event of {@link UpdateItem} (`Operation: 'update'`),
+         * {@link MoveItem} (`'move'`) and {@link BringToFront} / {@link SendToBack}
+         * (`'reorder'`). Set `Cancel = true` synchronously to veto — the mutator returns `false`.
+         */
+        this.ItemUpdating$ = this.itemUpdating.asObservable();
+        this.itemUpdated = new Subject();
+        /** AFTER event: an item changed (patch applied / moved / z-reordered). */
+        this.ItemUpdated$ = this.itemUpdated.asObservable();
+        this.itemRemoving = new Subject();
+        /**
+         * Cancelable BEFORE event of {@link RemoveItem}. Set `Cancel = true` synchronously to
+         * keep the item — {@link RemoveItem} then returns `false` and nothing changes.
+         */
+        this.ItemRemoving$ = this.itemRemoving.asObservable();
+        this.itemRemoved = new Subject();
+        /** AFTER event: an item was removed from the board. */
+        this.ItemRemoved$ = this.itemRemoved.asObservable();
+        this.contentChanging = new Subject();
+        /**
+         * Cancelable BEFORE event raised — in addition to {@link ItemUpdating$} — when an
+         * {@link UpdateItem} patch touches CONTENT fields (Text / Label / Sub / Markdown /
+         * Html / Title). The dedicated hook for content governance: set `Cancel = true`
+         * synchronously to veto the whole update.
+         */
+        this.ContentChanging$ = this.contentChanging.asObservable();
+        this.contentChanged = new Subject();
+        /** AFTER event: an item's content fields changed (markdown / html / text edits). */
+        this.ContentChanged$ = this.contentChanged.asObservable();
+        this.selectionChanged = new Subject();
+        /**
+         * AFTER event: the single selection changed — via {@link Select} or implicitly (the
+         * selected item was removed / dropped by a restore). Selection is transient UI state,
+         * so this is a notification only (never cancelable, never journaled).
+         */
+        this.SelectionChanged$ = this.selectionChanged.asObservable();
+        this.boardCleared = new Subject();
+        /** AFTER event: {@link Clear} removed everything from the board (one undo step). */
+        this.BoardCleared$ = this.boardCleared.asObservable();
+        this.boardLoaded = new Subject();
+        /** AFTER event: {@link LoadFromJSON} rehydrated a persisted board into this instance. */
+        this.BoardLoaded$ = this.boardLoaded.asObservable();
+        this.pageAdding = new Subject();
+        /**
+         * Cancelable BEFORE event of {@link AddPage}. Set `Cancel = true` synchronously to
+         * veto — {@link AddPage} then returns `null` and nothing changes.
+         */
+        this.PageAdding$ = this.pageAdding.asObservable();
+        this.pageAdded = new Subject();
+        /** AFTER event: a page was added (and became the active page). */
+        this.PageAdded$ = this.pageAdded.asObservable();
+        this.pageSwitching = new Subject();
+        /**
+         * Cancelable BEFORE event of {@link SwitchPage}. Set `Cancel = true` synchronously to
+         * stay on the current page — {@link SwitchPage} then returns `false`.
+         */
+        this.PageSwitching$ = this.pageSwitching.asObservable();
+        this.pageSwitched = new Subject();
+        /** AFTER event: the active page changed via {@link SwitchPage}. */
+        this.PageSwitched$ = this.pageSwitched.asObservable();
+        this.pageRenaming = new Subject();
+        /**
+         * Cancelable BEFORE event of {@link RenamePage}. Handlers may rewrite `NewName`; set
+         * `Cancel = true` synchronously to veto — {@link RenamePage} then returns `false`.
+         */
+        this.PageRenaming$ = this.pageRenaming.asObservable();
+        this.pageRenamed = new Subject();
+        /** AFTER event: a page was renamed. */
+        this.PageRenamed$ = this.pageRenamed.asObservable();
+        this.pageRemoving = new Subject();
+        /**
+         * Cancelable BEFORE event of {@link RemovePage} (never raised for the guarded
+         * last-page case). Set `Cancel = true` synchronously to keep the page.
+         */
+        this.PageRemoving$ = this.pageRemoving.asObservable();
+        this.pageRemoved = new Subject();
+        /** AFTER event: a page (and all of its items) was removed from the board. */
+        this.PageRemoved$ = this.pageRemoved.asObservable();
+        /**
+         * The MULTI-selection, in selection order (last entry is the primary selection).
+         * Selection is volatile UI state — never journaled, never undoable, never persisted,
+         * and cleared on page switches and whole-scene restores.
+         */
+        this.selectedIds = [];
+    }
+    static { this.UndoMax = 100; }
+    static { this.JournalMax = 1000; }
+    /** The ACTIVE page's item map (accessor keeps all item mutations page-scoped). */
+    get items() {
+        return this.activePage.Items;
+    }
+    set items(value) {
+        this.activePage.Items = value;
+    }
+    /** The active page record (defensive fallback to the first page — never undefined). */
+    get activePage() {
+        return this.pages.find((p) => UUIDsEqual(p.ID, this.activePageId)) ?? this.pages[0];
+    }
+    /**
+     * The PRIMARY selected item's ID (the most recently selected member of the
+     * multi-selection), or null when nothing is selected. Selection is UI state — not
+     * persisted. For the full multi-selection see {@link SelectedIDs}.
+     */
+    get SelectedID() {
+        return this.selectedIds.length > 0 ? this.selectedIds[this.selectedIds.length - 1] : null;
+    }
+    /** All selected item IDs in selection order (last = primary). Returns a copy. */
+    get SelectedIDs() {
+        return [...this.selectedIds];
+    }
+    // ────────────────────────────────────────────── reads
+    /** All items on the ACTIVE page in render order (ascending Z). */
+    get Items() {
+        return Array.from(this.items.values()).sort((a, b) => a.Z - b.Z);
+    }
+    /** The ordered page list (read-only snapshots — see {@link WhiteboardPageInfo}). */
+    get Pages() {
+        return this.pages.map((p) => this.pageInfo(p));
+    }
+    /** ID of the active page (every item operation targets this page). */
+    get ActivePageID() {
+        return this.activePage.ID;
+    }
+    /** Display name of the active page. */
+    get ActivePageName() {
+        return this.activePage.Name;
+    }
+    /** Total item count summed across ALL pages (the active-page count is {@link ElementCount}). */
+    get TotalItemCount() {
+        return this.pages.reduce((n, p) => n + p.Items.size, 0);
+    }
+    /**
+     * Tolerant page lookup: by exact ID first, then by case-insensitive, trimmed name
+     * (first match wins on duplicate names). Returns `undefined` when nothing matches.
+     */
+    FindPage(idOrName) {
+        const page = this.resolvePage(idOrName);
+        return page ? this.pageInfo(page) : undefined;
+    }
+    /** Current sequence number — use as the `sinceToken` for the next {@link BuildSceneDelta}. */
+    get CurrentSeq() {
+        return this.seq;
+    }
+    /** Look up one ACTIVE-page item by ID (items on other pages are not visible here). */
+    GetItem(id) {
+        return this.items.get(id);
+    }
+    /** ACTIVE-page "elements" as the status footer reports them (transient highlights excluded). */
+    get ElementCount() {
+        return this.Items.filter((i) => i.Kind !== 'highlight').length;
+    }
+    /** Active-page elements by author (highlights excluded, same basis as {@link ElementCount}). */
+    CountByAuthor(author) {
+        return this.Items.filter((i) => i.Kind !== 'highlight' && i.Author === author).length;
+    }
+    get CanUndo() {
+        return this.undoStack.length > 0;
+    }
+    get CanRedo() {
+        return this.redoStack.length > 0;
+    }
+    // ────────────────────────────────────────────── geometry
+    /** Axis-aligned bounds for any item (estimates for content-sized kinds). */
+    ItemBounds(item) {
+        switch (item.Kind) {
+            case 'sticky':
+                return { X: item.X, Y: item.Y, W: item.W ?? WHITEBOARD_DEFAULTS.StickyW, H: WHITEBOARD_DEFAULTS.StickyH };
+            case 'shape':
+                return { X: item.X, Y: item.Y, W: item.W, H: item.H };
+            case 'text': {
+                // estimate scales with the chosen font size (the CSS default renders ~12px);
+                // an explicit wrap width (item.W) wins over the single-line estimate
+                const scale = item.FontSize ? item.FontSize / 12 : 1;
+                return {
+                    X: item.X,
+                    Y: item.Y,
+                    W: item.W ?? Math.round(WHITEBOARD_DEFAULTS.TextW * scale),
+                    H: Math.round(WHITEBOARD_DEFAULTS.TextH * scale)
+                };
+            }
+            case 'image':
+                return { X: item.X, Y: item.Y, W: item.W ?? WHITEBOARD_DEFAULTS.ImageW, H: WHITEBOARD_DEFAULTS.ImageH };
+            case 'highlight':
+                return { X: item.X, Y: item.Y, W: item.W, H: item.H };
+            case 'markdown':
+                // content-driven height: an explicit max (H) wins, otherwise estimate from line count
+                return { X: item.X, Y: item.Y, W: item.W, H: item.H ?? WhiteboardState.markdownHeightEstimate(item.Markdown) };
+            case 'html':
+                return { X: item.X, Y: item.Y, W: item.W, H: item.H };
+            case 'ink': {
+                return WhiteboardState.pointsBounds(item.Points, item.StrokeWidth);
+            }
+            case 'connector': {
+                const from = this.ResolveEndpoint(item, 'from');
+                const to = this.ResolveEndpoint(item, 'to');
+                return WhiteboardState.pointsBounds([from, to], 2);
+            }
+        }
+    }
+    /** Rough rendered height of a markdown panel (line count · line height + card padding). */
+    static markdownHeightEstimate(markdown) {
+        const lines = (markdown || '').split('\n').length;
+        return Math.max(WHITEBOARD_DEFAULTS.MarkdownMinH, Math.min(520, 44 + lines * 19));
+    }
+    static pointsBounds(points, pad) {
+        if (points.length === 0) {
+            return { X: 0, Y: 0, W: 0, H: 0 };
+        }
+        let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+        for (const p of points) {
+            minX = Math.min(minX, p.X);
+            minY = Math.min(minY, p.Y);
+            maxX = Math.max(maxX, p.X);
+            maxY = Math.max(maxY, p.Y);
+        }
+        return { X: minX - pad, Y: minY - pad, W: maxX - minX + pad * 2, H: maxY - minY + pad * 2 };
+    }
+    /** Bounding box of all items (null when the board is empty). Powers fit-to-content + minimap. */
+    ContentBounds() {
+        const all = this.Items;
+        if (all.length === 0) {
+            return null;
+        }
+        let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+        for (const item of all) {
+            const b = this.ItemBounds(item);
+            minX = Math.min(minX, b.X);
+            minY = Math.min(minY, b.Y);
+            maxX = Math.max(maxX, b.X + b.W);
+            maxY = Math.max(maxY, b.Y + b.H);
+        }
+        return { X: minX, Y: minY, W: maxX - minX, H: maxY - minY };
+    }
+    /**
+     * Resolve one connector endpoint: anchored to the referenced item's bounds-center when the
+     * item still exists, otherwise the absolute fallback point (floating endpoint).
+     */
+    ResolveEndpoint(conn, end) {
+        const refId = end === 'from' ? conn.FromItemID : conn.ToItemID;
+        const fallback = end === 'from' ? conn.FromPoint : conn.ToPoint;
+        if (refId) {
+            const target = this.items.get(refId);
+            if (target) {
+                const b = this.ItemBounds(target);
+                return { X: b.X + b.W / 2, Y: b.Y + b.H / 2 };
+            }
+        }
+        return fallback ?? { X: 0, Y: 0 };
+    }
+    // ────────────────────────────────────────────── selection
+    /**
+     * Set (or clear) the selection to a SINGLE item. Unknown IDs clear the selection.
+     * Fires {@link SelectionChanged$} when the effective selection actually changes.
+     */
+    Select(id) {
+        this.applySelection(id != null && this.items.has(id) ? [id] : []);
+    }
+    /**
+     * Toggle one item's membership in the multi-selection WITHOUT clearing the rest —
+     * the shift-click semantics. A newly added item becomes the primary selection
+     * ({@link SelectedID}); unknown IDs are a no-op.
+     */
+    ToggleSelect(id) {
+        if (!this.items.has(id)) {
+            return;
+        }
+        this.applySelection(this.selectedIds.includes(id)
+            ? this.selectedIds.filter((s) => s !== id)
+            : [...this.selectedIds, id]);
+    }
+    /**
+     * Replace the selection with a set of items (the marquee result). Unknown IDs are
+     * dropped and duplicates collapse to their first occurrence; order is preserved
+     * (the last surviving entry becomes the primary selection). An empty / fully-unknown
+     * list clears the selection.
+     */
+    SelectMany(ids) {
+        const seen = new Set();
+        const next = [];
+        for (const id of ids) {
+            if (id != null && this.items.has(id) && !seen.has(id)) {
+                seen.add(id);
+                next.push(id);
+            }
+        }
+        this.applySelection(next);
+    }
+    /** Whether an item is part of the current (single or multi) selection. */
+    IsItemSelected(id) {
+        return this.selectedIds.includes(id);
+    }
+    /**
+     * All ACTIVE-page items whose axis-aligned bounds intersect the given rectangle —
+     * the marquee (rubber-band) hit test, in render order. Transient highlight regions
+     * are excluded: they are "pointing" chrome dismissed by click, never selected.
+     * Edge-touching items (zero overlap area) do NOT count as intersecting.
+     */
+    ItemsIntersecting(rect) {
+        return this.Items.filter((item) => {
+            if (item.Kind === 'highlight') {
+                return false;
+            }
+            const b = this.ItemBounds(item);
+            return b.X < rect.X + rect.W && b.X + b.W > rect.X
+                && b.Y < rect.Y + rect.H && b.Y + b.H > rect.Y;
+        });
+    }
+    /** Apply a SINGLE-or-clear selection change (legacy internal path). */
+    changeSelection(next) {
+        this.applySelection(next != null ? [next] : []);
+    }
+    /** Swap the multi-selection and fire {@link SelectionChanged$} when it differs. */
+    applySelection(next) {
+        const current = this.selectedIds;
+        if (next.length === current.length && next.every((id, i) => id === current[i])) {
+            return;
+        }
+        const previous = this.SelectedID;
+        this.selectedIds = next;
+        this.selectionChanged.next({ SelectedID: this.SelectedID, PreviousID: previous, SelectedIDs: [...next] });
+    }
+    // ────────────────────────────────────────────── mutations
+    /**
+     * Add an item; the engine stamps ID, Z and Author and emits one change.
+     *
+     * Raises the cancelable {@link ItemAdding$} BEFORE event first — when a handler
+     * cancels, nothing changes and `null` is returned. On success the stamped item is
+     * returned and {@link ItemAdded$} fires after the journal/{@link Changed$} emission.
+     */
+    AddItem(input, author) {
+        const adding = { Input: input, Author: author, Cancel: false };
+        this.itemAdding.next(adding);
+        if (adding.Cancel) {
+            return null;
+        }
+        this.beforeMutate();
+        const item = { ...adding.Input, ID: this.nextId(adding.Input.Kind), Z: ++this.zCounter, Author: author };
+        this.items.set(item.ID, item);
+        this.record('add', item.ID, author, `added ${WhiteboardState.describe(item)}`);
+        this.itemAdded.next({ Item: item, Author: author });
+        return item;
+    }
+    /**
+     * Patch an item's mutable fields. Returns false when the ID is unknown — or when a
+     * handler of the cancelable {@link ItemUpdating$} BEFORE event (or, for patches that
+     * touch content fields, the cancelable {@link ContentChanging$} event) vetoed the
+     * change. On success {@link ItemUpdated$} — and {@link ContentChanged$} for content
+     * patches — fires after the journal/{@link Changed$} emission.
+     */
+    UpdateItem(id, patch, author) {
+        const item = this.items.get(id);
+        if (!item) {
+            return false;
+        }
+        const updating = { Item: item, Operation: 'update', Patch: patch, Author: author, Cancel: false };
+        this.itemUpdating.next(updating);
+        if (updating.Cancel) {
+            return false;
+        }
+        const effective = updating.Patch ?? patch;
+        const isContent = WhiteboardState.isContentPatch(effective);
+        if (isContent) {
+            const changing = { Item: item, Patch: effective, Author: author, Cancel: false };
+            this.contentChanging.next(changing);
+            if (changing.Cancel) {
+                return false;
+            }
+        }
+        this.beforeMutate();
+        const target = item;
+        for (const [key, value] of Object.entries(effective)) {
+            if (value !== undefined) {
+                target[key] = value;
+            }
+        }
+        this.record('update', id, author, `updated ${WhiteboardState.describe(item)}`);
+        this.itemUpdated.next({ Item: item, Operation: 'update', Author: author });
+        if (isContent) {
+            this.contentChanged.next({ Item: item, Patch: effective, Author: author });
+        }
+        return true;
+    }
+    /** Whether a patch touches CONTENT fields (drives the ContentChanging/Changed pair). */
+    static isContentPatch(patch) {
+        return patch.Text !== undefined || patch.Label !== undefined || patch.Sub !== undefined
+            || patch.Markdown !== undefined || patch.Html !== undefined || patch.Title !== undefined;
+    }
+    /**
+     * Move an item to an absolute board position. Positioned kinds move their origin; ink
+     * strokes translate every point; connectors translate their floating endpoints.
+     *
+     * Raises the cancelable {@link ItemUpdating$} BEFORE event (`Operation: 'move'`,
+     * `Position` = the requested top-left) — returns false when vetoed or the ID is
+     * unknown; fires {@link ItemUpdated$} after an applied move.
+     */
+    MoveItem(id, x, y, author) {
+        const item = this.items.get(id);
+        if (!item) {
+            return false;
+        }
+        const moving = { Item: item, Operation: 'move', Position: { X: x, Y: y }, Author: author, Cancel: false };
+        this.itemUpdating.next(moving);
+        if (moving.Cancel) {
+            return false;
+        }
+        this.beforeMutate();
+        const bounds = this.ItemBounds(item);
+        const dx = x - bounds.X;
+        const dy = y - bounds.Y;
+        if (item.Kind === 'ink') {
+            item.Points = item.Points.map((p) => ({ X: p.X + dx, Y: p.Y + dy }));
+        }
+        else if (item.Kind === 'connector') {
+            if (item.FromPoint) {
+                item.FromPoint = { X: item.FromPoint.X + dx, Y: item.FromPoint.Y + dy };
+            }
+            if (item.ToPoint) {
+                item.ToPoint = { X: item.ToPoint.X + dx, Y: item.ToPoint.Y + dy };
+            }
+        }
+        else {
+            item.X = x;
+            item.Y = y;
+        }
+        this.record('move', id, author, `moved ${WhiteboardState.describe(item)}`);
+        this.itemUpdated.next({ Item: item, Operation: 'move', Author: author });
+        return true;
+    }
+    /**
+     * Remove an item. Connectors that referenced it survive: their endpoint freezes to the
+     * removed item's last center (the floating-endpoint fallback).
+     *
+     * Raises the cancelable {@link ItemRemoving$} BEFORE event — returns false when vetoed
+     * or the ID is unknown; fires {@link ItemRemoved$} after an applied removal.
+     */
+    RemoveItem(id, author) {
+        const item = this.items.get(id);
+        if (!item) {
+            return false;
+        }
+        const removing = { Item: item, Author: author, Cancel: false };
+        this.itemRemoving.next(removing);
+        if (removing.Cancel) {
+            return false;
+        }
+        this.beforeMutate();
+        // Freeze any connector endpoints anchored to the item being removed.
+        const center = (() => {
+            const b = this.ItemBounds(item);
+            return { X: b.X + b.W / 2, Y: b.Y + b.H / 2 };
+        })();
+        for (const other of this.items.values()) {
+            if (other.Kind === 'connector') {
+                if (other.FromItemID === id) {
+                    other.FromItemID = null;
+                    other.FromPoint = { ...center };
+                }
+                if (other.ToItemID === id) {
+                    other.ToItemID = null;
+                    other.ToPoint = { ...center };
+                }
+            }
+        }
+        this.items.delete(id);
+        if (this.selectedIds.includes(id)) {
+            this.applySelection(this.selectedIds.filter((s) => s !== id));
+        }
+        this.record('remove', id, author, `removed ${WhiteboardState.describe(item)}`);
+        this.itemRemoved.next({ Item: item, Author: author });
+        return true;
+    }
+    /**
+     * Duplicate an item: a DEEP clone (ink points included) with a fresh engine-stamped
+     * identity, offset +16/+16 from the source so the copy is visibly distinct. Connectors
+     * (which reference other items) and transient highlights cannot be duplicated — returns
+     * `null` without mutating. The clone lands through {@link AddItem}, so it journals as a
+     * normal `'add'`, is one undo step, and raises the {@link ItemAdding$} /
+     * {@link ItemAdded$} pair (a canceled add also returns `null`).
+     */
+    DuplicateItem(id, author) {
+        const source = this.items.get(id);
+        if (!source || source.Kind === 'connector' || source.Kind === 'highlight') {
+            return null;
+        }
+        const { ID: _id, Z: _z, Author: _author, ...rest } = JSON.parse(JSON.stringify(source));
+        const input = rest;
+        if (input.Kind === 'ink') {
+            input.Points = input.Points.map((p) => ({ X: p.X + 16, Y: p.Y + 16 }));
+        }
+        else if (input.Kind !== 'connector') {
+            input.X += 16;
+            input.Y += 16;
+        }
+        return this.AddItem(input, author);
+    }
+    /**
+     * Raise an item above everything else. Follows the engine's existing Z handling:
+     * `++zCounter` is by construction greater than every assigned Z (max + 1), exactly how
+     * {@link AddItem} stamps new items. Journals as an `'update'`.
+     *
+     * Raises the cancelable {@link ItemUpdating$} BEFORE event (`Operation: 'reorder'`) —
+     * returns false when vetoed or the ID is unknown; fires {@link ItemUpdated$} after.
+     */
+    BringToFront(id, author) {
+        const item = this.items.get(id);
+        if (!item) {
+            return false;
+        }
+        if (!this.raiseReorder(item, author)) {
+            return false;
+        }
+        this.beforeMutate();
+        item.Z = ++this.zCounter;
+        this.record('update', id, author, `brought ${WhiteboardState.describe(item)} to the front`);
+        this.itemUpdated.next({ Item: item, Operation: 'reorder', Author: author });
+        return true;
+    }
+    /**
+     * Drop an item below everything else (current min Z − 1). Journals as an `'update'`.
+     *
+     * Raises the cancelable {@link ItemUpdating$} BEFORE event (`Operation: 'reorder'`) —
+     * returns false when vetoed or the ID is unknown; fires {@link ItemUpdated$} after.
+     */
+    SendToBack(id, author) {
+        const item = this.items.get(id);
+        if (!item) {
+            return false;
+        }
+        if (!this.raiseReorder(item, author)) {
+            return false;
+        }
+        this.beforeMutate();
+        let minZ = item.Z;
+        for (const other of this.items.values()) {
+            minZ = Math.min(minZ, other.Z);
+        }
+        item.Z = minZ - 1;
+        this.record('update', id, author, `sent ${WhiteboardState.describe(item)} to the back`);
+        this.itemUpdated.next({ Item: item, Operation: 'reorder', Author: author });
+        return true;
+    }
+    /** Raise the cancelable `'reorder'` BEFORE event; returns false when a handler vetoed. */
+    raiseReorder(item, author) {
+        const reordering = { Item: item, Operation: 'reorder', Author: author, Cancel: false };
+        this.itemUpdating.next(reordering);
+        return !reordering.Cancel;
+    }
+    /**
+     * Convenience: add a pulsing highlight region (agent "pointing without touching").
+     * Adds through {@link AddItem}, so the {@link ItemAdding$} / {@link ItemAdded$} pair
+     * fires — returns `null` when a handler canceled the add.
+     */
+    Highlight(x, y, w, h, label, author) {
+        return this.AddItem({ Kind: 'highlight', X: x, Y: y, W: w, H: h, Label: label }, author);
+    }
+    /**
+     * Remove EVERYTHING from the ACTIVE page as ONE undoable operation (other pages are
+     * untouched). Journals a single `'replace'` op (perception consumers re-read the
+     * now-empty scene) and fires {@link BoardCleared$}. Clears the selection (firing
+     * {@link SelectionChanged$} when one existed). Returns false when the active page was
+     * already empty.
+     */
+    Clear(author = 'user') {
+        if (this.items.size === 0) {
+            return false;
+        }
+        const count = this.items.size;
+        this.beforeMutate();
+        this.items = new Map();
+        this.changeSelection(null);
+        this.record('replace', '', author, 'cleared the board');
+        this.boardCleared.next({ Author: author, ItemCount: count });
+        return true;
+    }
+    /**
+     * Move EVERY selected item by the same delta as ONE undo step (the multi-select group
+     * drag). Internally one {@link RunBatch} of per-item {@link MoveItem} calls, so each
+     * member still raises its own cancelable `'move'` BEFORE event (a veto skips just that
+     * member) and journals normally — but a single Undo reverts the whole group move.
+     * Returns how many items actually moved (0 when nothing is selected or the delta is 0).
+     */
+    MoveSelectedBy(dx, dy, author) {
+        const ids = this.selectedIds.filter((id) => this.items.has(id));
+        if (ids.length === 0 || (dx === 0 && dy === 0)) {
+            return 0;
+        }
+        return this.RunBatch(() => {
+            // capture every member's bounds BEFORE any member moves, so anchored-connector
+            // bounds (which follow their endpoints) don't skew later members' targets
+            const targets = ids
+                .map((id) => {
+                const item = this.items.get(id);
+                return item ? { id, bounds: this.ItemBounds(item) } : null;
+            })
+                .filter((t) => t !== null);
+            let moved = 0;
+            for (const t of targets) {
+                if (this.MoveItem(t.id, t.bounds.X + dx, t.bounds.Y + dy, author)) {
+                    moved++;
+                }
+            }
+            return moved;
+        });
+    }
+    /**
+     * Remove EVERY selected item as ONE undo step (the multi-select Delete key). One
+     * {@link RunBatch} of per-item {@link RemoveItem} calls — each member still raises its
+     * cancelable {@link ItemRemoving$} BEFORE event (a veto keeps just that member), and a
+     * single Undo restores the whole group. The selection empties as items are removed.
+     * Returns how many items were actually removed.
+     */
+    RemoveSelected(author) {
+        const ids = this.selectedIds.filter((id) => this.items.has(id));
+        if (ids.length === 0) {
+            return 0;
+        }
+        return this.RunBatch(() => {
+            let removed = 0;
+            for (const id of ids) {
+                if (this.RemoveItem(id, author)) {
+                    removed++;
+                }
+            }
+            return removed;
+        });
+    }
+    // ────────────────────────────────────────────── pages
+    /** Project a live page record to its public read-only descriptor. */
+    pageInfo(page) {
+        return { ID: page.ID, Name: page.Name, ItemCount: page.Items.size, Active: UUIDsEqual(page.ID, this.activePageId), Author: page.Author };
+    }
+    /** Resolve a page by exact ID first, then case-insensitive trimmed name. */
+    resolvePage(idOrName) {
+        const key = (idOrName ?? '').trim();
+        if (key.length === 0) {
+            return undefined;
+        }
+        return this.pages.find((p) => UUIDsEqual(p.ID, key))
+            ?? this.pages.find((p) => p.Name.trim().toLowerCase() === key.toLowerCase());
+    }
+    /**
+     * Add a new page and SWITCH to it. `name` is trimmed; when omitted (or blank) the page
+     * auto-names itself "Page N" from the monotonic page counter, so auto-names never
+     * repeat even after removals.
+     *
+     * Raises the cancelable {@link PageAdding$} BEFORE event (handlers may rewrite the
+     * name) — returns `null` when vetoed; fires {@link PageAdded$} after. One undoable
+     * step; journals a `'replace'` op (the agent's visible scene swaps to the new, empty
+     * page), so perception consumers re-read the scene.
+     */
+    AddPage(name, author = 'user') {
+        const autoName = `Page ${this.pageCounter + 1}`;
+        const requested = (name ?? '').trim();
+        const adding = { Name: requested.length > 0 ? requested : autoName, Author: author, Cancel: false };
+        this.pageAdding.next(adding);
+        if (adding.Cancel) {
+            return null;
+        }
+        this.beforeMutate();
+        this.pageCounter++;
+        const page = {
+            ID: `page-${this.pageCounter}`,
+            Name: (adding.Name ?? '').trim() || autoName,
+            Author: author,
+            Items: new Map()
+        };
+        this.pages.push(page);
+        this.activePageId = page.ID;
+        this.changeSelection(null);
+        this.record('replace', '', author, `added page "${page.Name}"`);
+        const info = this.pageInfo(page);
+        this.pageAdded.next({ Page: info, Author: author });
+        return info;
+    }
+    /**
+     * Make another page the active page. Tolerant lookup: exact ID first, then
+     * case-insensitive name (see {@link FindPage}). Switching to the already-active page
+     * is a successful no-op (no events, no journal entry).
+     *
+     * Raises the cancelable {@link PageSwitching$} BEFORE event — returns `false` when
+     * vetoed or the page is unknown; fires {@link PageSwitched$} after. Journals a
+     * `'replace'` op (the visible scene swaps wholesale) but deliberately pushes NO undo
+     * snapshot — switching is navigation, not a content mutation.
+     */
+    SwitchPage(idOrName, author = 'user') {
+        const target = this.resolvePage(idOrName);
+        if (!target) {
+            return false;
+        }
+        if (UUIDsEqual(target.ID, this.activePageId)) {
+            return true; // already there — successful no-op
+        }
+        const from = this.pageInfo(this.activePage);
+        const switching = { FromPage: from, ToPage: this.pageInfo(target), Author: author, Cancel: false };
+        this.pageSwitching.next(switching);
+        if (switching.Cancel) {
+            return false;
+        }
+        this.activePageId = target.ID;
+        this.changeSelection(null);
+        this.record('replace', '', author, `switched to page "${target.Name}"`);
+        this.pageSwitched.next({ FromPage: from, ToPage: this.pageInfo(target), Author: author });
+        return true;
+    }
+    /**
+     * Rename a page (tolerant lookup, same as {@link SwitchPage}). The new name is
+     * trimmed; an empty result returns `false`. Renaming to the current name is a
+     * successful no-op (no events, no journal entry).
+     *
+     * Raises the cancelable {@link PageRenaming$} BEFORE event (handlers may rewrite
+     * `NewName`) — returns `false` when vetoed; fires {@link PageRenamed$} after. One
+     * undoable step; journals a `'replace'` op so the agent's page list stays current.
+     */
+    RenamePage(idOrName, newName, author = 'user') {
+        const target = this.resolvePage(idOrName);
+        const requested = (newName ?? '').trim();
+        if (!target || requested.length === 0) {
+            return false;
+        }
+        if (target.Name === requested) {
+            return true; // nothing to do
+        }
+        const renaming = { Page: this.pageInfo(target), NewName: requested, Author: author, Cancel: false };
+        this.pageRenaming.next(renaming);
+        if (renaming.Cancel) {
+            return false;
+        }
+        const effective = (renaming.NewName ?? '').trim();
+        if (effective.length === 0) {
+            return false; // a handler emptied the name — treat as an abort
+        }
+        this.beforeMutate();
+        const oldName = target.Name;
+        target.Name = effective;
+        this.record('replace', '', author, `renamed page "${oldName}" to "${target.Name}"`);
+        this.pageRenamed.next({ Page: this.pageInfo(target), OldName: oldName, Author: author });
+        return true;
+    }
+    /**
+     * Remove a page AND all of its items (tolerant lookup, same as {@link SwitchPage}).
+     * The LAST remaining page can never be removed (`false`, no events). Removing the
+     * ACTIVE page activates a neighbor — the next page when one exists, otherwise the
+     * previous one.
+     *
+     * Raises the cancelable {@link PageRemoving$} BEFORE event — returns `false` when
+     * vetoed or the page is unknown; fires {@link PageRemoved$} after (with the activated
+     * neighbor when the active page was removed). One undoable step; journals a
+     * `'replace'` op.
+     */
+    RemovePage(idOrName, author = 'user') {
+        const target = this.resolvePage(idOrName);
+        if (!target || this.pages.length <= 1) {
+            return false; // unknown, or the guarded last page
+        }
+        const removingInfo = this.pageInfo(target);
+        const removing = { Page: removingInfo, Author: author, Cancel: false };
+        this.pageRemoving.next(removing);
+        if (removing.Cancel) {
+            return false;
+        }
+        this.beforeMutate();
+        const index = this.pages.indexOf(target);
+        this.pages.splice(index, 1);
+        let activated = null;
+        if (UUIDsEqual(target.ID, this.activePageId)) {
+            // activate the neighbor: the page that slid into the removed slot, else the new last
+            const neighbor = this.pages[Math.min(index, this.pages.length - 1)];
+            this.activePageId = neighbor.ID;
+            activated = this.pageInfo(neighbor);
+            this.changeSelection(null);
+        }
+        this.record('replace', '', author, `removed page "${target.Name}"`);
+        this.pageRemoved.next({ Page: removingInfo, ActivatedPage: activated, Author: author });
+        return true;
+    }
+    /**
+     * Run several mutations as ONE undo step (one snapshot). Used per agent tool call and for
+     * compound user gestures, so the toast's "Undo" reverts the whole tool effect at once.
+     */
+    RunBatch(fn) {
+        if (this.batchDepth === 0) {
+            this.pushUndo();
+        }
+        this.batchDepth++;
+        try {
+            return fn();
+        }
+        finally {
+            this.batchDepth--;
+        }
+    }
+    // ────────────────────────────────────────────── undo / redo
+    /** Restore the previous snapshot. Emits a `'replace'` change. */
+    Undo() {
+        const snap = this.undoStack.pop();
+        if (!snap) {
+            return false;
+        }
+        this.redoStack.push(this.snapshot());
+        this.restore(snap);
+        this.record('replace', '', 'user', 'undid the last change');
+        return true;
+    }
+    /** Re-apply the most recently undone snapshot. Emits a `'replace'` change. */
+    Redo() {
+        const snap = this.redoStack.pop();
+        if (!snap) {
+            return false;
+        }
+        this.undoStack.push(this.snapshot());
+        this.restore(snap);
+        this.record('replace', '', 'user', 'redid the last change');
+        return true;
+    }
+    // ────────────────────────────────────────────── perception (scene deltas)
+    /**
+     * Build the coalesced scene delta of everything that changed AFTER `sinceToken`
+     * (a previously observed {@link CurrentSeq}; defaults to 0 = everything).
+     *
+     * Coalescing: per item, the NET effect wins — N moves → one `moved` entry at the current
+     * position; add+move → one `added` entry (current state); add+remove → nothing;
+     * update+move → one `updated` entry. When the window contains a `'replace'` (undo/redo/load)
+     * or the journal no longer reaches the token, the delta carries `reset: true` plus the full
+     * compact `items` array — replace-current-state semantics, never an append-only log.
+     */
+    BuildSceneDelta(sinceToken = 0) {
+        const delta = {
+            op: 'scene-delta',
+            seq: this.seq,
+            added: [],
+            moved: [],
+            updated: [],
+            removed: [],
+            pages: this.scenePages(),
+            summary: ''
+        };
+        const tokenTooOld = sinceToken < this.journalTrimmedBeforeSeq;
+        const inRange = this.journal.filter((e) => e.Seq > sinceToken);
+        const hasReplace = inRange.some((e) => e.Op === 'replace');
+        if (tokenTooOld || hasReplace) {
+            delta.reset = true;
+            delta.items = this.Items.map((i) => this.compact(i));
+            delta.summary = this.composeSummaryText({ reset: true });
+            return delta;
+        }
+        // Net-effect per item, preserving first-op semantics.
+        const firstOp = new Map();
+        const lastOp = new Map();
+        const sawUpdate = new Set();
+        for (const entry of inRange) {
+            if (!firstOp.has(entry.ItemID)) {
+                firstOp.set(entry.ItemID, entry.Op);
+            }
+            lastOp.set(entry.ItemID, entry.Op);
+            if (entry.Op === 'update') {
+                sawUpdate.add(entry.ItemID);
+            }
+        }
+        for (const [id, first] of firstOp) {
+            const last = lastOp.get(id);
+            const item = this.items.get(id);
+            if (first === 'add') {
+                if (item) {
+                    delta.added.push(this.compact(item)); // add → (move/update)* coalesces into the added entry
+                }
+                // add → … → remove: net nothing
+                continue;
+            }
+            if (last === 'remove' || !item) {
+                delta.removed.push(id);
+                continue;
+            }
+            if (sawUpdate.has(id)) {
+                delta.updated.push(this.compact(item)); // update (+ moves) → one updated entry w/ current state
+                continue;
+            }
+            // moves only → one moved entry at the current position
+            const b = this.ItemBounds(item);
+            delta.moved.push({ id, x: Math.round(b.X), y: Math.round(b.Y) });
+        }
+        delta.summary = this.composeSummaryText({
+            added: delta.added.length,
+            moved: delta.moved.length,
+            updated: delta.updated.length,
+            removed: delta.removed.length
+        });
+        return delta;
+    }
+    /** Full compact scene + counts — the popover's stats and the delta-reset payload. */
+    BuildSceneSummary() {
+        const items = this.Items;
+        const byKind = {};
+        for (const item of items) {
+            byKind[item.Kind] = (byKind[item.Kind] ?? 0) + 1;
+        }
+        return {
+            op: 'scene-summary',
+            seq: this.seq,
+            counts: {
+                total: this.ElementCount,
+                user: this.CountByAuthor('user'),
+                agent: this.CountByAuthor('agent'),
+                byKind
+            },
+            items: items.map((i) => this.compact(i)),
+            pages: this.scenePages(),
+            summary: this.composeSummaryText({})
+        };
+    }
+    /** Compact page list for deltas / summaries (model-facing). */
+    scenePages() {
+        return this.pages.map((p) => ({
+            id: p.ID,
+            name: p.Name,
+            active: UUIDsEqual(p.ID, this.activePageId),
+            items: p.Items.size
+        }));
+    }
+    // ────────────────────────────────────────────── persistence
+    /**
+     * Serialize the board (state of record — persisted as the session-channel artifact).
+     * Emits the VERSION 2 paged shape (see {@link WhiteboardStateJSON}); the legacy flat
+     * shape is still accepted on load and rehydrates as a single page "Page 1".
+     */
+    ToJSON() {
+        return JSON.stringify(this.snapshot());
+    }
+    /**
+     * Rehydrate a board from {@link ToJSON} output — BOTH shapes accepted: the current
+     * paged shape (version 2) and the legacy flat shape (version 1, `items` at the root),
+     * which migrates to one page named "Page 1". Throws on malformed input (use
+     * {@link LoadFromJSON} or `ParseBoardStateJson` for the tolerant variants).
+     */
+    static FromJSON(json) {
+        const normalized = WhiteboardState.normalizePersisted(JSON.parse(json));
+        if (!normalized) {
+            throw new Error('WhiteboardState.FromJSON: malformed payload');
+        }
+        const state = new WhiteboardState();
+        state.restore(normalized);
+        state.seq = normalized.seq;
+        state.journalTrimmedBeforeSeq = state.seq; // older tokens force reset deltas
+        return state;
+    }
+    /**
+     * Normalize a parsed persisted payload — EITHER shape — into the current
+     * {@link WhiteboardStateJSON}. Returns `null` for anything unrecognizable (the
+     * callers decide whether that throws or fails soft). Defensive throughout: page
+     * entries missing ids/names/item arrays are repaired, an empty page list gains one
+     * "Page 1", and an unknown `activePageId` falls back to the first page.
+     */
+    static normalizePersisted(parsed) {
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return null;
+        }
+        const raw = parsed;
+        const num = (value, fallback) => typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+        if (Array.isArray(raw['pages'])) {
+            // CURRENT shape (version 2, paged)
+            const pages = [];
+            for (const entry of raw['pages']) {
+                if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+                    continue;
+                }
+                const p = entry;
+                const name = typeof p['name'] === 'string' && p['name'].trim().length > 0
+                    ? p['name'] : `Page ${pages.length + 1}`;
+                pages.push({
+                    id: typeof p['id'] === 'string' && p['id'].length > 0 ? p['id'] : `page-${pages.length + 1}`,
+                    name,
+                    // additive authorship field — tolerated absent (pre-garnish payloads → 'user')
+                    author: p['author'] === 'agent' ? 'agent' : 'user',
+                    items: Array.isArray(p['items']) ? p['items'] : []
+                });
+            }
+            if (pages.length === 0) {
+                pages.push({ id: 'page-1', name: 'Page 1', items: [] });
+            }
+            const active = raw['activePageId'];
+            return {
+                version: 2,
+                seq: num(raw['seq'], 0),
+                idCounter: num(raw['idCounter'], 0),
+                zCounter: num(raw['zCounter'], 0),
+                pageCounter: Math.max(num(raw['pageCounter'], pages.length), pages.length),
+                activePageId: typeof active === 'string' && pages.some((p) => p.id === active) ? active : pages[0].id,
+                pages
+            };
+        }
+        if (Array.isArray(raw['items'])) {
+            // LEGACY shape (version 1, flat) — migrate to a single page "Page 1"
+            return {
+                version: 2,
+                seq: num(raw['seq'], 0),
+                idCounter: num(raw['idCounter'], 0),
+                zCounter: num(raw['zCounter'], 0),
+                pageCounter: 1,
+                activePageId: 'page-1',
+                pages: [{ id: 'page-1', name: 'Page 1', items: raw['items'] }]
+            };
+        }
+        return null;
+    }
+    /**
+     * Rehydrate THIS instance in place from {@link ToJSON} output — used by the channel's
+     * `RestoreState` hook so existing subscriptions (perception feed, save pipeline) and any
+     * bound surface keep pointing at the same engine. TOLERANT: malformed input returns
+     * `false` and leaves the current state untouched (never throws).
+     *
+     * On success the undo/redo stacks and journal are cleared (restored state is the new
+     * baseline), stale delta tokens force reset semantics, one `'replace'` change is
+     * emitted so consumers re-read the full scene, and {@link BoardLoaded$} fires.
+     */
+    LoadFromJSON(json) {
+        let parsed;
+        try {
+            parsed = JSON.parse(json);
+        }
+        catch {
+            return false;
+        }
+        const normalized = WhiteboardState.normalizePersisted(parsed);
+        if (!normalized) {
+            return false;
+        }
+        this.restore(normalized);
+        this.seq = normalized.seq;
+        this.journal = [];
+        this.journalTrimmedBeforeSeq = this.seq; // older tokens force reset deltas
+        this.undoStack = [];
+        this.redoStack = [];
+        this.changeSelection(null);
+        this.record('replace', '', 'user', 'restored a saved board');
+        this.boardLoaded.next({ ItemCount: this.TotalItemCount });
+        return true;
+    }
+    // ────────────────────────────────────────────── internals
+    /** Mint the next stable item ID for a kind (`sticky-3`, `shape-7`, …). */
+    nextId(kind) {
+        return `${kind}-${++this.idCounter}`;
+    }
+    /**
+     * Pre-mutation bookkeeping shared by every committed mutation: pushes the undo
+     * snapshot (unless inside a {@link RunBatch}, which snapshotted at batch start) and
+     * invalidates the redo branch. Subclasses extending the mutation paths should call
+     * this exactly once per logical change, AFTER any cancelable before-event survived.
+     */
+    beforeMutate() {
+        if (this.batchDepth === 0) {
+            this.pushUndo();
+        }
+        // Any forward mutation invalidates the redo branch (batched mutations included).
+        this.redoStack = [];
+    }
+    /** Push the current scene onto the undo stack (bounded) and drop the redo branch. */
+    pushUndo() {
+        this.undoStack.push(this.snapshot());
+        if (this.undoStack.length > WhiteboardState.UndoMax) {
+            this.undoStack.shift();
+        }
+        this.redoStack = [];
+    }
+    /**
+     * Deep-copied serializable snapshot of the WHOLE board — every page's items plus the
+     * page structure and counters (undo entries / ToJSON). Page items serialize in render
+     * order (ascending Z).
+     */
+    snapshot() {
+        return {
+            version: 2,
+            seq: this.seq,
+            idCounter: this.idCounter,
+            zCounter: this.zCounter,
+            pageCounter: this.pageCounter,
+            activePageId: this.activePageId,
+            pages: this.pages.map((p) => ({
+                id: p.ID,
+                name: p.Name,
+                author: p.Author,
+                items: JSON.parse(JSON.stringify(Array.from(p.Items.values()).sort((a, b) => a.Z - b.Z)))
+            }))
+        };
+    }
+    /**
+     * Swap the whole board to a snapshot's pages/counters (drops a now-missing selection;
+     * an unknown active-page id falls back to the first page; an empty page list gains a
+     * fresh "Page 1" so the engine never runs page-less).
+     */
+    restore(snap) {
+        this.pages = (snap.pages ?? []).map((p) => ({
+            ID: p.id,
+            Name: p.name,
+            Author: p.author === 'agent' ? 'agent' : 'user',
+            Items: new Map(JSON.parse(JSON.stringify(p.items ?? []))
+                .filter((i) => !!i && typeof i === 'object' && typeof i.ID === 'string')
+                .map((i) => [i.ID, i]))
+        }));
+        if (this.pages.length === 0) {
+            this.pages = [{ ID: 'page-1', Name: 'Page 1', Author: 'user', Items: new Map() }];
+        }
+        this.activePageId = this.pages.some((p) => UUIDsEqual(p.ID, snap.activePageId)) ? snap.activePageId : this.pages[0].ID;
+        this.idCounter = snap.idCounter ?? 0;
+        this.zCounter = snap.zCounter ?? 0;
+        this.pageCounter = Math.max(snap.pageCounter ?? this.pages.length, this.pages.length);
+        // drop selection members the restored active page no longer contains
+        const surviving = this.selectedIds.filter((id) => this.items.has(id));
+        if (surviving.length !== this.selectedIds.length) {
+            this.applySelection(surviving);
+        }
+    }
+    /**
+     * Post-mutation bookkeeping shared by every committed mutation: bumps the sequence,
+     * appends the journal entry (bounded — trimming forces reset deltas for stale tokens)
+     * and emits the {@link Changed$} notification.
+     */
+    record(op, itemId, author, summaryFragment) {
+        this.seq++;
+        this.journal.push({ Seq: this.seq, Op: op, ItemID: itemId });
+        if (this.journal.length > WhiteboardState.JournalMax) {
+            const dropped = this.journal.splice(0, this.journal.length - WhiteboardState.JournalMax);
+            this.journalTrimmedBeforeSeq = dropped[dropped.length - 1].Seq;
+        }
+        this.changed.next({ Op: op, ItemID: itemId, Author: author, SummaryFragment: summaryFragment, Seq: this.seq });
+    }
+    /** Project one item to its compact, model-facing representation (deltas / summaries). */
+    compact(item) {
+        const c = { id: item.ID, type: item.Kind, author: item.Author };
+        switch (item.Kind) {
+            case 'sticky':
+                c.x = Math.round(item.X);
+                c.y = Math.round(item.Y);
+                c.text = clip(item.Text, 120);
+                WhiteboardState.compactTextStyle(item, c);
+                break;
+            case 'shape':
+                c.x = Math.round(item.X);
+                c.y = Math.round(item.Y);
+                c.w = Math.round(item.W);
+                c.h = Math.round(item.H);
+                c.shape = item.Shape;
+                c.text = clip(item.Sub ? `${item.Label} (${item.Sub})` : item.Label, 120);
+                break;
+            case 'text':
+                c.x = Math.round(item.X);
+                c.y = Math.round(item.Y);
+                if (item.W) {
+                    c.w = Math.round(item.W);
+                }
+                c.text = clip(item.Text, 120);
+                WhiteboardState.compactTextStyle(item, c);
+                if (item.Color) {
+                    c.color = item.Color;
+                }
+                break;
+            case 'image':
+                c.x = Math.round(item.X);
+                c.y = Math.round(item.Y);
+                c.name = item.Name;
+                break;
+            case 'ink': {
+                const b = this.ItemBounds(item);
+                c.x = Math.round(b.X);
+                c.y = Math.round(b.Y);
+                c.w = Math.round(b.W);
+                c.h = Math.round(b.H);
+                c.points = item.Points.length;
+                break;
+            }
+            case 'connector':
+                c.from = item.FromItemID ?? item.FromPoint ?? null;
+                c.to = item.ToItemID ?? item.ToPoint ?? null;
+                break;
+            case 'highlight':
+                c.x = Math.round(item.X);
+                c.y = Math.round(item.Y);
+                c.w = Math.round(item.W);
+                c.h = Math.round(item.H);
+                if (item.Label) {
+                    c.text = clip(item.Label, 120);
+                }
+                break;
+            case 'markdown':
+                // the agent must SEE what's in the panel — project the clipped SOURCE, not a stub
+                c.x = Math.round(item.X);
+                c.y = Math.round(item.Y);
+                c.w = Math.round(item.W);
+                if (item.H != null) {
+                    c.h = Math.round(item.H);
+                }
+                c.text = clip(item.Markdown, 200);
+                break;
+            case 'html':
+                c.x = Math.round(item.X);
+                c.y = Math.round(item.Y);
+                c.w = Math.round(item.W);
+                c.h = Math.round(item.H);
+                if (item.Title) {
+                    c.name = clip(item.Title, 80);
+                }
+                c.text = clip(item.Html, 200);
+                break;
+        }
+        return c;
+    }
+    /** Project the optional text-style fields onto a compact item (sticky / text kinds). */
+    static compactTextStyle(item, c) {
+        if (item.FontSize != null) {
+            c.fontSize = item.FontSize;
+        }
+        if (item.FontFamily) {
+            c.fontFamily = item.FontFamily;
+        }
+        if (item.FontWeight === 700) {
+            c.bold = true;
+        }
+    }
+    /**
+     * Compose the human-readable tail line of deltas / summaries ("2 added, 1 moved. …"),
+     * including which page is active and the full page list — so the model always knows
+     * pages exist and which one its item entries describe.
+     */
+    composeSummaryText(parts) {
+        const bits = [];
+        if (parts.reset) {
+            bits.push('full scene snapshot (state replaced)');
+        }
+        else {
+            if (parts.added) {
+                bits.push(`${parts.added} added`);
+            }
+            if (parts.moved) {
+                bits.push(`${parts.moved} moved`);
+            }
+            if (parts.updated) {
+                bits.push(`${parts.updated} updated`);
+            }
+            if (parts.removed) {
+                bits.push(`${parts.removed} removed`);
+            }
+            if (bits.length === 0) {
+                bits.push('no changes');
+            }
+        }
+        return `${bits.join(', ')}. ${this.composePagesText()}`;
+    }
+    /** The page-aware scene sentence shared by every delta / summary tail line. */
+    composePagesText() {
+        const active = this.activePage;
+        const index = this.pages.indexOf(active) + 1;
+        const counts = `${this.ElementCount} elements (user ${this.CountByAuthor('user')} · agent ${this.CountByAuthor('agent')})`;
+        if (this.pages.length === 1) {
+            return `Active page "${active.Name}" (the only page) has ${counts}.`;
+        }
+        const others = this.pages
+            .filter((p) => !UUIDsEqual(p.ID, active.ID))
+            .map((p) => `"${p.Name}" (${p.Items.size})`)
+            .join(', ');
+        return `Active page "${active.Name}" (${index} of ${this.pages.length}) has ${counts}. Other pages: ${others}.`;
+    }
+    static describe(item) {
+        switch (item.Kind) {
+            case 'sticky': return `a sticky note ("${clip(item.Text)}")`;
+            case 'shape': return `a ${item.Shape} ("${clip(item.Label)}")`;
+            case 'text': return `a text label ("${clip(item.Text)}")`;
+            case 'image': return `an image (${item.Name})`;
+            case 'ink': return 'an ink stroke';
+            case 'connector': return 'a connector';
+            case 'highlight': return 'a highlight region';
+            case 'markdown': return `a markdown panel ("${clip(item.Markdown)}")`;
+            case 'html': return `an HTML widget${item.Title ? ` ("${clip(item.Title)}")` : ''}`;
+        }
+    }
+}
+//# sourceMappingURL=whiteboard-state.js.map