@memberjunction/ng-whiteboard 0.0.1 → 5.42.0

package/dist/lib/whiteboard-state.d.ts

@@ -0,0 +1,1113 @@
+import { Observable } from 'rxjs';
+/**
+ * WHITEBOARD — typed board model + state engine.
+ *
+ * This file is intentionally Angular-free: it is the single mutation API used by BOTH the
+ * user-facing board tools (pen, stickies, shapes, …) and any programmatic co-author —
+ * typically an AI agent driving the `Whiteboard_*` tool set (`Whiteboard_AddNote`,
+ * `Whiteboard_DrawConnector`, …, see `whiteboard-tools.ts`).
+ *
+ * Pages (OneNote-style): a board is an ordered list of named PAGES, each with its own
+ * items collection; exactly one page is ACTIVE at a time and every item operation
+ * (add / update / move / remove / connectors / clear / perception) targets the active
+ * page. See {@link WhiteboardState.AddPage} / {@link WhiteboardState.SwitchPage} /
+ * {@link WhiteboardState.RenamePage} / {@link WhiteboardState.RemovePage}. A fresh
+ * board starts with one page named "Page 1"; legacy (pre-pages, flat) persisted JSON
+ * rehydrates as that single page.
+ *
+ * Perception model (how a programmatic co-author "sees" the board):
+ *  - every mutation appends to a compact change journal and emits on {@link WhiteboardState.Changed$};
+ *  - {@link WhiteboardState.BuildSceneDelta} coalesces the journal since a token into ONE delta
+ *    (multiple moves of one item → one `moved` entry) with replace-current-state semantics;
+ *  - {@link WhiteboardState.BuildSceneSummary} produces the full compact scene the
+ *    "What the agent sees" popover renders;
+ *  - {@link WhiteboardState.ToJSON} / {@link WhiteboardState.FromJSON} persist the board's
+ *    state of record (e.g. a session-channel artifact in MJ realtime sessions).
+ *
+ * Extensibility: every targeted mutation also raises a cancelable BEFORE event and a
+ * matching AFTER event (`ItemAdding$` / `ItemAdded$`, `ItemUpdating$` / `ItemUpdated$`,
+ * `ItemRemoving$` / `ItemRemoved$`) — see the {@link WhiteboardState} class docs.
+ */
+/** Who authored a board item / mutation. The violet treatment is RESERVED for `'agent'`. */
+export type WhiteboardAuthor = 'user' | 'agent';
+/** The discriminant for the {@link WhiteboardItem} union. */
+export type WhiteboardItemKind = 'sticky' | 'shape' | 'ink' | 'text' | 'image' | 'connector' | 'highlight' | 'markdown' | 'html';
+/** Shape geometry of a {@link WhiteboardShapeItem}. */
+export type WhiteboardShapeKind = 'rect' | 'ellipse' | 'diamond';
+/** Visual tint of a USER sticky (agent stickies always render violet, regardless of tint). */
+export type WhiteboardStickyTint = 'amber' | 'amber-light';
+/**
+ * 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 declare const WHITEBOARD_FONT_SIZES: readonly number[];
+/**
+ * Font family choices for text labels / stickies. The keys are mapped to token-friendly
+ * font stacks in the board CSS (`wb-font-serif`, `wb-font-mono`; sans is the default).
+ */
+export type WhiteboardFontFamily = 'sans' | 'serif' | 'mono';
+/** Font weights for text labels / stickies (regular or bold). */
+export type WhiteboardFontWeight = 400 | 700;
+/** A point in board (content) coordinates. */
+export interface WhiteboardPoint {
+    X: number;
+    Y: number;
+}
+/** Fields shared by every board item. */
+export interface WhiteboardItemBase {
+    /** Stable item id (e.g. `sticky-3`) — referenced by connectors, deltas and agent tools. */
+    ID: string;
+    /** Who placed the item. Drives the ownership chrome (chips / violet vs slate-amber). */
+    Author: WhiteboardAuthor;
+    /** Render order (higher renders on top). Assigned by the engine. */
+    Z: number;
+}
+/** A sticky note. */
+export interface WhiteboardStickyItem extends WhiteboardItemBase {
+    Kind: 'sticky';
+    X: number;
+    Y: number;
+    /** Width in px; defaults to {@link WHITEBOARD_DEFAULTS.StickyW} when omitted. */
+    W?: number;
+    Text: string;
+    /** User-palette tint; ignored for agent stickies (always violet). */
+    Tint?: WhiteboardStickyTint;
+    /** Slight playful tilt, in degrees. */
+    Rotation?: number;
+    /** Curated font size (see {@link WHITEBOARD_FONT_SIZES}); omitted = the CSS default. */
+    FontSize?: number;
+    /** Font family key (mapped to token-friendly stacks in CSS); omitted = sans. */
+    FontFamily?: WhiteboardFontFamily;
+    /** Font weight; omitted = the kind's CSS default. */
+    FontWeight?: WhiteboardFontWeight;
+}
+/** A drawn shape box (rect / ellipse / diamond) with an optional label + sub-label. */
+export interface WhiteboardShapeItem extends WhiteboardItemBase {
+    Kind: 'shape';
+    Shape: WhiteboardShapeKind;
+    X: number;
+    Y: number;
+    W: number;
+    H: number;
+    Label: string;
+    Sub?: string;
+}
+/** A free-floating text label. */
+export interface WhiteboardTextItem extends WhiteboardItemBase {
+    Kind: 'text';
+    X: number;
+    Y: number;
+    Text: string;
+    /** Wrap width in px — text wraps at this width. Omitted = wrap at the default max width. */
+    W?: number;
+    /** Curated font size (see {@link WHITEBOARD_FONT_SIZES}); omitted = the CSS default. */
+    FontSize?: number;
+    /** Font family key (mapped to token-friendly stacks in CSS); omitted = sans. */
+    FontFamily?: WhiteboardFontFamily;
+    /** Font weight; omitted = the kind's CSS default. */
+    FontWeight?: WhiteboardFontWeight;
+    /**
+     * Text color from the USER pen palette. Violet is reserved for the agent's ownership
+     * styling (enforced in the user UI — the palette never offers violet); agent text gets
+     * its violet from the Author treatment, never from this field.
+     */
+    Color?: string;
+}
+/** A pasted / inserted image card. `Url` is a runtime object URL (not persisted as pixels). */
+export interface WhiteboardImageItem extends WhiteboardItemBase {
+    Kind: 'image';
+    X: number;
+    Y: number;
+    /** Width in px; defaults to {@link WHITEBOARD_DEFAULTS.ImageW}. */
+    W?: number;
+    Name: string;
+    Url?: string | null;
+}
+/** A freehand ink stroke (polyline in board coordinates, smoothed at render time). */
+export interface WhiteboardInkItem extends WhiteboardItemBase {
+    Kind: 'ink';
+    Points: WhiteboardPoint[];
+    /** Stroke color. The user palette NEVER includes violet — violet ink is the agent's. */
+    Color: string;
+    StrokeWidth: number;
+}
+/**
+ * A connector between two endpoints. Each endpoint references an item by ID when attached;
+ * when the referenced item is removed (or was never set) the endpoint falls back to the
+ * absolute `…Point` coordinate.
+ */
+export interface WhiteboardConnectorItem extends WhiteboardItemBase {
+    Kind: 'connector';
+    FromItemID?: string | null;
+    ToItemID?: string | null;
+    FromPoint?: WhiteboardPoint | null;
+    ToPoint?: WhiteboardPoint | null;
+}
+/** A pulsing highlight region ("pointing without touching") — dismissed by clicking it. */
+export interface WhiteboardHighlightItem extends WhiteboardItemBase {
+    Kind: 'highlight';
+    X: number;
+    Y: number;
+    W: number;
+    H: number;
+    Label?: string;
+}
+/**
+ * A rendered MARKDOWN panel — a rich, formatted card (headings, lists, code, links) for
+ * illustrative content that outgrows a sticky note. Width is explicit (the panel's column
+ * width); height is content-driven, optionally capped by `H` (overflow clips).
+ */
+export interface WhiteboardMarkdownItem extends WhiteboardItemBase {
+    Kind: 'markdown';
+    X: number;
+    Y: number;
+    /** Panel width in px (required — markdown always renders in an explicit column). */
+    W: number;
+    /** Optional max height in px; content beyond it is clipped. Omitted = content-driven. */
+    H?: number;
+    /** The markdown source. Rendered SAFELY (sanitized — never raw HTML passthrough). */
+    Markdown: string;
+}
+/**
+ * An interactive HTML widget — arbitrary HTML (scripts included) rendered inside a
+ * STRICTLY SANDBOXED iframe (`sandbox="allow-scripts"` only, opaque origin — see the
+ * board component for the full security rationale). Dragged/selected by its card chrome —
+ * header bar, border ring and lazy placeholder — while pointer events inside the sandboxed
+ * frame stay with the widget, so iframe interactivity and board interactions coexist.
+ */
+export interface WhiteboardHtmlItem extends WhiteboardItemBase {
+    Kind: 'html';
+    X: number;
+    Y: number;
+    W: number;
+    H: number;
+    /** The widget's full HTML source (becomes the sandboxed iframe's `srcdoc`). */
+    Html: string;
+    /** Optional title shown on the widget's header bar. */
+    Title?: string;
+}
+/** Discriminated union of everything that can live on the board. */
+export type WhiteboardItem = WhiteboardStickyItem | WhiteboardShapeItem | WhiteboardTextItem | WhiteboardImageItem | WhiteboardInkItem | WhiteboardConnectorItem | WhiteboardHighlightItem | WhiteboardMarkdownItem | WhiteboardHtmlItem;
+/** Distributive Omit that preserves the discriminated union. */
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/** What callers pass to {@link WhiteboardState.AddItem} — the engine stamps ID / Z / Author. */
+export type WhiteboardItemInput = DistributiveOmit<WhiteboardItem, 'ID' | 'Z' | 'Author'>;
+/** Patchable fields for {@link WhiteboardState.UpdateItem} (kind/identity fields excluded). */
+export interface WhiteboardItemPatch {
+    X?: number;
+    Y?: number;
+    W?: number;
+    H?: number;
+    Text?: string;
+    Label?: string;
+    Sub?: string;
+    Name?: string;
+    Url?: string | null;
+    Color?: string;
+    StrokeWidth?: number;
+    Points?: WhiteboardPoint[];
+    Tint?: WhiteboardStickyTint;
+    Rotation?: number;
+    FontSize?: number;
+    FontFamily?: WhiteboardFontFamily;
+    FontWeight?: WhiteboardFontWeight;
+    Shape?: WhiteboardShapeKind;
+    Markdown?: string;
+    Html?: string;
+    Title?: string;
+    FromItemID?: string | null;
+    ToItemID?: string | null;
+    FromPoint?: WhiteboardPoint | null;
+    ToPoint?: WhiteboardPoint | null;
+}
+/** Mutation kinds carried on {@link WhiteboardChange} and in the journal. */
+export type WhiteboardChangeOp = 'add' | 'update' | 'move' | 'remove' | 'replace';
+/**
+ * Base shape of every cancelable BEFORE event raised by {@link WhiteboardState} (and by
+ * the components layered on top of it). Handlers run SYNCHRONOUSLY during the emit; any
+ * handler may set {@link Cancel} to `true` and the operation is aborted before it touches
+ * the board (no undo snapshot, no journal entry, no {@link WhiteboardState.Changed$}
+ * emission). The matching AFTER event then never fires.
+ */
+export interface WhiteboardCancelableEventArgs {
+    /** Set to `true` (in a synchronous handler) to veto the operation. */
+    Cancel: boolean;
+}
+/**
+ * BEFORE-event args for {@link WhiteboardState.ItemAdding$}. Raised by
+ * {@link WhiteboardState.AddItem} (and therefore also by {@link WhiteboardState.Highlight}
+ * and {@link WhiteboardState.DuplicateItem}, which add through it) before anything is
+ * stamped or stored. Handlers may mutate {@link Input} (e.g. clamp coordinates, rewrite
+ * text) — the engine adds whatever the args carry after the emit — or set `Cancel` to
+ * veto the add entirely (the caller receives `null`).
+ */
+export interface WhiteboardItemAddingEventArgs extends WhiteboardCancelableEventArgs {
+    /** The item about to be added (no ID / Z / Author yet — the engine stamps those). */
+    Input: WhiteboardItemInput;
+    /** Who is adding the item. */
+    Author: WhiteboardAuthor;
+}
+/** AFTER-event args for {@link WhiteboardState.ItemAdded$} — the item is on the board. */
+export interface WhiteboardItemAddedEventArgs {
+    /** The added item, with its engine-stamped ID / Z / Author. */
+    Item: WhiteboardItem;
+    /** Who added the item. */
+    Author: WhiteboardAuthor;
+}
+/**
+ * Which mutation family an updating/updated event describes:
+ *  - `'update'` — a field patch via {@link WhiteboardState.UpdateItem};
+ *  - `'move'` — a reposition via {@link WhiteboardState.MoveItem};
+ *  - `'reorder'` — a z-order change via {@link WhiteboardState.BringToFront} /
+ *    {@link WhiteboardState.SendToBack}.
+ */
+export type WhiteboardUpdateOperation = 'update' | 'move' | 'reorder';
+/**
+ * BEFORE-event args for {@link WhiteboardState.ItemUpdating$}. {@link Item} is the LIVE,
+ * pre-mutation item (do not mutate it directly — cancel and apply your own patch
+ * instead). For `'update'` operations handlers may adjust {@link Patch}; for `'move'`
+ * operations {@link Position} carries the requested top-left target.
+ */
+export interface WhiteboardItemUpdatingEventArgs extends WhiteboardCancelableEventArgs {
+    /** The item about to change (current, pre-mutation state). */
+    Item: WhiteboardItem;
+    /** Which mutation family is about to run. */
+    Operation: WhiteboardUpdateOperation;
+    /** The field patch (`'update'` operations only). Handlers may adjust it. */
+    Patch?: WhiteboardItemPatch;
+    /** The requested top-left position (`'move'` operations only). */
+    Position?: WhiteboardPoint;
+    /** Who is changing the item. */
+    Author: WhiteboardAuthor;
+}
+/** AFTER-event args for {@link WhiteboardState.ItemUpdated$} — the change has applied. */
+export interface WhiteboardItemUpdatedEventArgs {
+    /** The item in its post-mutation state. */
+    Item: WhiteboardItem;
+    /** Which mutation family ran. */
+    Operation: WhiteboardUpdateOperation;
+    /** Who changed the item. */
+    Author: WhiteboardAuthor;
+}
+/**
+ * BEFORE-event args for {@link WhiteboardState.ItemRemoving$} — raised before the item
+ * leaves the board (and before any connector endpoints anchored to it are frozen).
+ * Cancel to keep the item.
+ */
+export interface WhiteboardItemRemovingEventArgs extends WhiteboardCancelableEventArgs {
+    /** The item about to be removed. */
+    Item: WhiteboardItem;
+    /** Who is removing the item. */
+    Author: WhiteboardAuthor;
+}
+/** AFTER-event args for {@link WhiteboardState.ItemRemoved$} — the item is gone. */
+export interface WhiteboardItemRemovedEventArgs {
+    /** The removed item (its last state — no longer on the board). */
+    Item: WhiteboardItem;
+    /** Who removed the item. */
+    Author: WhiteboardAuthor;
+}
+/**
+ * BEFORE-event args for {@link WhiteboardState.ContentChanging$} — raised (in addition to
+ * {@link WhiteboardState.ItemUpdating$}) when an {@link WhiteboardState.UpdateItem} patch
+ * touches an item's CONTENT fields: `Text`, `Label`, `Sub`, `Markdown`, `Html` or `Title`.
+ * This is the hook for content governance (length limits, redaction, moderation) without
+ * having to inspect every geometry patch. Cancel to veto the whole update.
+ */
+export interface WhiteboardContentChangingEventArgs extends WhiteboardCancelableEventArgs {
+    /** The item whose content is about to change (current, pre-mutation state). */
+    Item: WhiteboardItem;
+    /** The full patch being applied (content fields included). Handlers may adjust it. */
+    Patch: WhiteboardItemPatch;
+    /** Who is changing the content. */
+    Author: WhiteboardAuthor;
+}
+/** AFTER-event args for {@link WhiteboardState.ContentChanged$} — the content has applied. */
+export interface WhiteboardContentChangedEventArgs {
+    /** The item in its post-mutation state. */
+    Item: WhiteboardItem;
+    /** The patch that was applied. */
+    Patch: WhiteboardItemPatch;
+    /** Who changed the content. */
+    Author: WhiteboardAuthor;
+}
+/**
+ * AFTER-event args for {@link WhiteboardState.SelectionChanged$} — the selection changed
+ * (single OR multi). Selection is UI state: it is not journaled, not undoable and not
+ * persisted, so this event is a notification only (not cancelable). Fires for explicit
+ * {@link WhiteboardState.Select} / {@link WhiteboardState.ToggleSelect} /
+ * {@link WhiteboardState.SelectMany} calls AND for implicit clears (a selected item was
+ * removed, the page switched, or a restore dropped it).
+ */
+export interface WhiteboardSelectionChangedEventArgs {
+    /** The PRIMARY selected item's ID (last added to the selection), or null when cleared. */
+    SelectedID: string | null;
+    /** The previously primary item's ID, or null when nothing was selected. */
+    PreviousID: string | null;
+    /** The full multi-selection (selection order, last = primary). Empty when cleared. */
+    SelectedIDs: string[];
+}
+/**
+ * AFTER-event args for {@link WhiteboardState.BoardCleared$} — every item was removed in
+ * one operation via {@link WhiteboardState.Clear}. The clear is a single undo step; one
+ * `'replace'` op lands in the journal so perception consumers re-read the (now empty)
+ * scene.
+ */
+export interface WhiteboardBoardClearedEventArgs {
+    /** Who cleared the board. */
+    Author: WhiteboardAuthor;
+    /** How many items were removed (highlights included). */
+    ItemCount: number;
+}
+/**
+ * AFTER-event args for {@link WhiteboardState.BoardLoaded$} — a persisted board was
+ * rehydrated IN PLACE via {@link WhiteboardState.LoadFromJSON}. Undo/redo stacks and the
+ * journal were reset (the restored state is the new baseline) and one `'replace'` op was
+ * journaled, so perception consumers re-read the full scene.
+ */
+export interface WhiteboardBoardLoadedEventArgs {
+    /** How many items the restored board contains (summed across ALL pages). */
+    ItemCount: number;
+}
+/**
+ * Public, read-only descriptor of one board page — what {@link WhiteboardState.Pages}
+ * returns and what every page before/after event carries. A snapshot, not a live view:
+ * re-read {@link WhiteboardState.Pages} after mutations.
+ */
+export interface WhiteboardPageInfo {
+    /** Stable page id (e.g. `page-2`) — accepted anywhere a page name is accepted. */
+    ID: string;
+    /** Display name (e.g. "Page 1"). Not guaranteed unique; IDs are. */
+    Name: string;
+    /** How many items live on the page (highlights included). */
+    ItemCount: number;
+    /** Whether this is the board's active page. */
+    Active: boolean;
+    /**
+     * Who CREATED the page. Drives the page strip's delegated-violet garnish for
+     * agent-created pages (mirroring the item-level agent treatment). Persisted in the
+     * v2 JSON as an additive `author` field; payloads without it rehydrate as `'user'`.
+     */
+    Author: WhiteboardAuthor;
+}
+/**
+ * BEFORE-event args for {@link WhiteboardState.PageAdding$} — raised by
+ * {@link WhiteboardState.AddPage} before the page exists. Handlers may rewrite
+ * {@link Name} (the engine trims it; an emptied name falls back to the auto-name) or set
+ * `Cancel` to veto the add (the caller receives `null`).
+ */
+export interface WhiteboardPageAddingEventArgs extends WhiteboardCancelableEventArgs {
+    /** The name the page will get (auto-named "Page N" when the caller omitted one). */
+    Name: string;
+    /** Who is adding the page. */
+    Author: WhiteboardAuthor;
+}
+/** AFTER-event args for {@link WhiteboardState.PageAdded$} — the page exists and is active. */
+export interface WhiteboardPageAddedEventArgs {
+    /** The added page (now the active page). */
+    Page: WhiteboardPageInfo;
+    /** Who added the page. */
+    Author: WhiteboardAuthor;
+}
+/**
+ * BEFORE-event args for {@link WhiteboardState.PageSwitching$} — raised by
+ * {@link WhiteboardState.SwitchPage} before the active page changes. Cancel to stay on
+ * the current page.
+ */
+export interface WhiteboardPageSwitchingEventArgs extends WhiteboardCancelableEventArgs {
+    /** The page that is currently active. */
+    FromPage: WhiteboardPageInfo;
+    /** The page about to become active. */
+    ToPage: WhiteboardPageInfo;
+    /** Who is switching. */
+    Author: WhiteboardAuthor;
+}
+/** AFTER-event args for {@link WhiteboardState.PageSwitched$} — the active page changed. */
+export interface WhiteboardPageSwitchedEventArgs {
+    /** The previously active page. */
+    FromPage: WhiteboardPageInfo;
+    /** The newly active page. */
+    ToPage: WhiteboardPageInfo;
+    /** Who switched. */
+    Author: WhiteboardAuthor;
+}
+/**
+ * BEFORE-event args for {@link WhiteboardState.PageRenaming$} — raised by
+ * {@link WhiteboardState.RenamePage}. Handlers may rewrite {@link NewName} (trimmed by
+ * the engine; an emptied rewrite aborts the rename) or set `Cancel` to veto.
+ */
+export interface WhiteboardPageRenamingEventArgs extends WhiteboardCancelableEventArgs {
+    /** The page about to be renamed (pre-rename snapshot). */
+    Page: WhiteboardPageInfo;
+    /** The requested new name. Handlers may adjust it. */
+    NewName: string;
+    /** Who is renaming. */
+    Author: WhiteboardAuthor;
+}
+/** AFTER-event args for {@link WhiteboardState.PageRenamed$} — the rename applied. */
+export interface WhiteboardPageRenamedEventArgs {
+    /** The page in its post-rename state. */
+    Page: WhiteboardPageInfo;
+    /** The name the page had before. */
+    OldName: string;
+    /** Who renamed it. */
+    Author: WhiteboardAuthor;
+}
+/**
+ * BEFORE-event args for {@link WhiteboardState.PageRemoving$} — raised by
+ * {@link WhiteboardState.RemovePage} (never for the last remaining page — that is
+ * guarded before the event). Cancel to keep the page.
+ */
+export interface WhiteboardPageRemovingEventArgs extends WhiteboardCancelableEventArgs {
+    /** The page about to be removed (with all of its items). */
+    Page: WhiteboardPageInfo;
+    /** Who is removing it. */
+    Author: WhiteboardAuthor;
+}
+/** AFTER-event args for {@link WhiteboardState.PageRemoved$} — the page is gone. */
+export interface WhiteboardPageRemovedEventArgs {
+    /** The removed page (its last state). */
+    Page: WhiteboardPageInfo;
+    /** When the REMOVED page was active: the neighbor page that became active. Else null. */
+    ActivatedPage: WhiteboardPageInfo | null;
+    /** Who removed it. */
+    Author: WhiteboardAuthor;
+}
+/** Compact page descriptor carried on scene deltas / summaries (model-facing). */
+export interface WhiteboardScenePage {
+    id: string;
+    name: string;
+    active: boolean;
+    items: number;
+}
+/**
+ * One coalesce-able change notification, emitted on {@link WhiteboardState.Changed$}
+ * after every mutation. `'replace'` means "the whole scene was swapped" (undo / redo /
+ * FromJSON) — consumers should re-read the full state.
+ */
+export interface WhiteboardChange {
+    Op: WhiteboardChangeOp;
+    /** Empty string for `'replace'` ops. */
+    ItemID: string;
+    Author: WhiteboardAuthor;
+    /** Human fragment for toasts / activity ("added a sticky note"). */
+    SummaryFragment: string;
+    /** Monotonic sequence number — also the delta token currency. */
+    Seq: number;
+}
+/** Compact, model-facing representation of one item inside deltas / summaries. */
+export interface WhiteboardCompactItem {
+    id: string;
+    type: WhiteboardItemKind;
+    author: WhiteboardAuthor;
+    x?: number;
+    y?: number;
+    w?: number;
+    h?: number;
+    /** Clipped text content (sticky/text/shape labels; markdown/html: clipped SOURCE). */
+    text?: string;
+    shape?: WhiteboardShapeKind;
+    /** Image file name, or the html widget's Title. */
+    name?: string;
+    from?: string | WhiteboardPoint | null;
+    to?: string | WhiteboardPoint | null;
+    points?: number;
+    fontSize?: number;
+    fontFamily?: WhiteboardFontFamily;
+    bold?: boolean;
+    color?: string;
+}
+/**
+ * The coalesced scene delta fed into the live agent context ("What the agent sees").
+ * Replace-current-state semantics: each entry is the item's CURRENT state, not an edit log.
+ * When `reset` is true the `items` array replaces the agent's entire view of the board
+ * (emitted after undo/redo/load, or when the journal no longer reaches the caller's token).
+ */
+export interface WhiteboardSceneDelta {
+    op: 'scene-delta';
+    seq: number;
+    added: WhiteboardCompactItem[];
+    moved: {
+        id: string;
+        x: number;
+        y: number;
+    }[];
+    updated: WhiteboardCompactItem[];
+    removed: string[];
+    reset?: boolean;
+    items?: WhiteboardCompactItem[];
+    /** The board's page list — `active: true` marks the page the item entries describe. */
+    pages: WhiteboardScenePage[];
+    summary: string;
+}
+/** Full compact scene snapshot (popover stats + delta-reset payloads). ACTIVE page only. */
+export interface WhiteboardSceneSummary {
+    op: 'scene-summary';
+    seq: number;
+    counts: {
+        total: number;
+        user: number;
+        agent: number;
+        byKind: Partial<Record<WhiteboardItemKind, number>>;
+    };
+    items: WhiteboardCompactItem[];
+    /** The board's page list — `active: true` marks the page the item entries describe. */
+    pages: WhiteboardScenePage[];
+    summary: string;
+}
+/** Axis-aligned bounds of an item, in board coordinates. */
+export interface WhiteboardBounds {
+    X: number;
+    Y: number;
+    W: number;
+    H: number;
+}
+/** Render-time default dimensions for items whose size is content-driven. */
+export declare const WHITEBOARD_DEFAULTS: {
+    readonly StickyW: 172;
+    readonly StickyH: 96;
+    readonly ImageW: 198;
+    readonly ImageH: 134;
+    readonly TextW: 132;
+    readonly TextH: 18;
+    readonly ShapeMinH: 56;
+    readonly MarkdownW: 280;
+    readonly MarkdownMinH: 96;
+    readonly HtmlW: 360;
+    readonly 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 declare function IsResizableKind(kind: WhiteboardItemKind): boolean;
+/**
+ * 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 declare function BuildResizeCommitPatch(kind: WhiteboardItemKind, bounds: WhiteboardBounds): WhiteboardItemPatch | null;
+/** Serialized shape of one page inside {@link WhiteboardStateJSON} (version 2+). */
+interface WhiteboardPageJSON {
+    id: string;
+    name: string;
+    items: WhiteboardItem[];
+    /**
+     * Who created the page (additive, v2-tolerant: absent in pre-authorship payloads and
+     * treated as `'user'` on load). Drives the agent-page chip garnish.
+     */
+    author?: WhiteboardAuthor;
+}
+/**
+ * Serialized shape produced by {@link WhiteboardState.ToJSON} — VERSION 2 (paged).
+ * Version 1 (the legacy flat shape: `{ version: 1, seq, idCounter, zCounter, items }`)
+ * is still accepted by {@link WhiteboardState.FromJSON} / {@link WhiteboardState.LoadFromJSON}
+ * and rehydrates as a single page named "Page 1".
+ */
+interface WhiteboardStateJSON {
+    version: 2;
+    seq: number;
+    idCounter: number;
+    zCounter: number;
+    /** Monotonic page-id/auto-name counter (never decremented, so names don't collide). */
+    pageCounter: number;
+    /** ID of the active page (always one of `pages`). */
+    activePageId: string;
+    /** The ordered page list (always at least one page). */
+    pages: WhiteboardPageJSON[];
+}
+/** Internal live record of one page (the active page's map backs `this.items`). */
+interface PageRecord {
+    ID: string;
+    Name: string;
+    /** Who created the page (drives the agent-page garnish; persisted). */
+    Author: WhiteboardAuthor;
+    Items: Map<string, WhiteboardItem>;
+}
+/**
+ * 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 declare class WhiteboardState {
+    private static readonly UndoMax;
+    private static readonly JournalMax;
+    /**
+     * 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.
+     */
+    private pages;
+    /** ID of the active page (always present in {@link pages}). */
+    private activePageId;
+    /** Monotonic page counter — mints page IDs and the "Page N" auto-names. */
+    private pageCounter;
+    /** The ACTIVE page's item map (accessor keeps all item mutations page-scoped). */
+    private get items();
+    private set items(value);
+    /** The active page record (defensive fallback to the first page — never undefined). */
+    private get activePage();
+    private idCounter;
+    private zCounter;
+    private seq;
+    private undoStack;
+    private redoStack;
+    private batchDepth;
+    private 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. */
+    private journalTrimmedBeforeSeq;
+    private changed;
+    /** Fires after every mutation (including undo/redo `'replace'` events). */
+    readonly Changed$: Observable<WhiteboardChange>;
+    private itemAdding;
+    /**
+     * 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.
+     */
+    readonly ItemAdding$: Observable<WhiteboardItemAddingEventArgs>;
+    private itemAdded;
+    /** AFTER event: an item was added (fires once per applied {@link AddItem}). */
+    readonly ItemAdded$: Observable<WhiteboardItemAddedEventArgs>;
+    private itemUpdating;
+    /**
+     * 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`.
+     */
+    readonly ItemUpdating$: Observable<WhiteboardItemUpdatingEventArgs>;
+    private itemUpdated;
+    /** AFTER event: an item changed (patch applied / moved / z-reordered). */
+    readonly ItemUpdated$: Observable<WhiteboardItemUpdatedEventArgs>;
+    private itemRemoving;
+    /**
+     * Cancelable BEFORE event of {@link RemoveItem}. Set `Cancel = true` synchronously to
+     * keep the item — {@link RemoveItem} then returns `false` and nothing changes.
+     */
+    readonly ItemRemoving$: Observable<WhiteboardItemRemovingEventArgs>;
+    private itemRemoved;
+    /** AFTER event: an item was removed from the board. */
+    readonly ItemRemoved$: Observable<WhiteboardItemRemovedEventArgs>;
+    private contentChanging;
+    /**
+     * 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.
+     */
+    readonly ContentChanging$: Observable<WhiteboardContentChangingEventArgs>;
+    private contentChanged;
+    /** AFTER event: an item's content fields changed (markdown / html / text edits). */
+    readonly ContentChanged$: Observable<WhiteboardContentChangedEventArgs>;
+    private selectionChanged;
+    /**
+     * 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).
+     */
+    readonly SelectionChanged$: Observable<WhiteboardSelectionChangedEventArgs>;
+    private boardCleared;
+    /** AFTER event: {@link Clear} removed everything from the board (one undo step). */
+    readonly BoardCleared$: Observable<WhiteboardBoardClearedEventArgs>;
+    private boardLoaded;
+    /** AFTER event: {@link LoadFromJSON} rehydrated a persisted board into this instance. */
+    readonly BoardLoaded$: Observable<WhiteboardBoardLoadedEventArgs>;
+    private pageAdding;
+    /**
+     * Cancelable BEFORE event of {@link AddPage}. Set `Cancel = true` synchronously to
+     * veto — {@link AddPage} then returns `null` and nothing changes.
+     */
+    readonly PageAdding$: Observable<WhiteboardPageAddingEventArgs>;
+    private pageAdded;
+    /** AFTER event: a page was added (and became the active page). */
+    readonly PageAdded$: Observable<WhiteboardPageAddedEventArgs>;
+    private pageSwitching;
+    /**
+     * Cancelable BEFORE event of {@link SwitchPage}. Set `Cancel = true` synchronously to
+     * stay on the current page — {@link SwitchPage} then returns `false`.
+     */
+    readonly PageSwitching$: Observable<WhiteboardPageSwitchingEventArgs>;
+    private pageSwitched;
+    /** AFTER event: the active page changed via {@link SwitchPage}. */
+    readonly PageSwitched$: Observable<WhiteboardPageSwitchedEventArgs>;
+    private pageRenaming;
+    /**
+     * Cancelable BEFORE event of {@link RenamePage}. Handlers may rewrite `NewName`; set
+     * `Cancel = true` synchronously to veto — {@link RenamePage} then returns `false`.
+     */
+    readonly PageRenaming$: Observable<WhiteboardPageRenamingEventArgs>;
+    private pageRenamed;
+    /** AFTER event: a page was renamed. */
+    readonly PageRenamed$: Observable<WhiteboardPageRenamedEventArgs>;
+    private pageRemoving;
+    /**
+     * Cancelable BEFORE event of {@link RemovePage} (never raised for the guarded
+     * last-page case). Set `Cancel = true` synchronously to keep the page.
+     */
+    readonly PageRemoving$: Observable<WhiteboardPageRemovingEventArgs>;
+    private pageRemoved;
+    /** AFTER event: a page (and all of its items) was removed from the board. */
+    readonly PageRemoved$: Observable<WhiteboardPageRemovedEventArgs>;
+    /**
+     * 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.
+     */
+    private selectedIds;
+    /**
+     * 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(): string | null;
+    /** All selected item IDs in selection order (last = primary). Returns a copy. */
+    get SelectedIDs(): string[];
+    /** All items on the ACTIVE page in render order (ascending Z). */
+    get Items(): WhiteboardItem[];
+    /** The ordered page list (read-only snapshots — see {@link WhiteboardPageInfo}). */
+    get Pages(): WhiteboardPageInfo[];
+    /** ID of the active page (every item operation targets this page). */
+    get ActivePageID(): string;
+    /** Display name of the active page. */
+    get ActivePageName(): string;
+    /** Total item count summed across ALL pages (the active-page count is {@link ElementCount}). */
+    get TotalItemCount(): number;
+    /**
+     * 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: string): WhiteboardPageInfo | undefined;
+    /** Current sequence number — use as the `sinceToken` for the next {@link BuildSceneDelta}. */
+    get CurrentSeq(): number;
+    /** Look up one ACTIVE-page item by ID (items on other pages are not visible here). */
+    GetItem(id: string): WhiteboardItem | undefined;
+    /** ACTIVE-page "elements" as the status footer reports them (transient highlights excluded). */
+    get ElementCount(): number;
+    /** Active-page elements by author (highlights excluded, same basis as {@link ElementCount}). */
+    CountByAuthor(author: WhiteboardAuthor): number;
+    get CanUndo(): boolean;
+    get CanRedo(): boolean;
+    /** Axis-aligned bounds for any item (estimates for content-sized kinds). */
+    ItemBounds(item: WhiteboardItem): WhiteboardBounds;
+    /** Rough rendered height of a markdown panel (line count · line height + card padding). */
+    private static markdownHeightEstimate;
+    private static pointsBounds;
+    /** Bounding box of all items (null when the board is empty). Powers fit-to-content + minimap. */
+    ContentBounds(): WhiteboardBounds | null;
+    /**
+     * 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: WhiteboardConnectorItem, end: 'from' | 'to'): WhiteboardPoint;
+    /**
+     * 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: string | null): void;
+    /**
+     * 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: string): void;
+    /**
+     * 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: string[]): void;
+    /** Whether an item is part of the current (single or multi) selection. */
+    IsItemSelected(id: string): boolean;
+    /**
+     * 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: WhiteboardBounds): WhiteboardItem[];
+    /** Apply a SINGLE-or-clear selection change (legacy internal path). */
+    protected changeSelection(next: string | null): void;
+    /** Swap the multi-selection and fire {@link SelectionChanged$} when it differs. */
+    protected applySelection(next: string[]): void;
+    /**
+     * 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: WhiteboardItemInput, author: WhiteboardAuthor): WhiteboardItem | null;
+    /**
+     * 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: string, patch: WhiteboardItemPatch, author: WhiteboardAuthor): boolean;
+    /** Whether a patch touches CONTENT fields (drives the ContentChanging/Changed pair). */
+    protected static isContentPatch(patch: WhiteboardItemPatch): boolean;
+    /**
+     * 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: string, x: number, y: number, author: WhiteboardAuthor): boolean;
+    /**
+     * 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: string, author: WhiteboardAuthor): boolean;
+    /**
+     * 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: string, author: WhiteboardAuthor): WhiteboardItem | null;
+    /**
+     * 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: string, author: WhiteboardAuthor): boolean;
+    /**
+     * 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: string, author: WhiteboardAuthor): boolean;
+    /** Raise the cancelable `'reorder'` BEFORE event; returns false when a handler vetoed. */
+    protected raiseReorder(item: WhiteboardItem, author: WhiteboardAuthor): boolean;
+    /**
+     * 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: number, y: number, w: number, h: number, label: string | undefined, author: WhiteboardAuthor): WhiteboardHighlightItem | null;
+    /**
+     * 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?: WhiteboardAuthor): boolean;
+    /**
+     * 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: number, dy: number, author: WhiteboardAuthor): number;
+    /**
+     * 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: WhiteboardAuthor): number;
+    /** Project a live page record to its public read-only descriptor. */
+    protected pageInfo(page: PageRecord): WhiteboardPageInfo;
+    /** Resolve a page by exact ID first, then case-insensitive trimmed name. */
+    private resolvePage;
+    /**
+     * 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?: string, author?: WhiteboardAuthor): WhiteboardPageInfo | null;
+    /**
+     * 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: string, author?: WhiteboardAuthor): boolean;
+    /**
+     * 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: string, newName: string, author?: WhiteboardAuthor): boolean;
+    /**
+     * 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: string, author?: WhiteboardAuthor): boolean;
+    /**
+     * 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<T>(fn: () => T): T;
+    /** Restore the previous snapshot. Emits a `'replace'` change. */
+    Undo(): boolean;
+    /** Re-apply the most recently undone snapshot. Emits a `'replace'` change. */
+    Redo(): boolean;
+    /**
+     * 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?: number): WhiteboardSceneDelta;
+    /** Full compact scene + counts — the popover's stats and the delta-reset payload. */
+    BuildSceneSummary(): WhiteboardSceneSummary;
+    /** Compact page list for deltas / summaries (model-facing). */
+    protected scenePages(): WhiteboardScenePage[];
+    /**
+     * 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(): string;
+    /**
+     * 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: string): WhiteboardState;
+    /**
+     * 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.
+     */
+    private static normalizePersisted;
+    /**
+     * 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: string): boolean;
+    /** Mint the next stable item ID for a kind (`sticky-3`, `shape-7`, …). */
+    protected nextId(kind: WhiteboardItemKind): string;
+    /**
+     * 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.
+     */
+    protected beforeMutate(): void;
+    /** Push the current scene onto the undo stack (bounded) and drop the redo branch. */
+    protected pushUndo(): void;
+    /**
+     * 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).
+     */
+    protected snapshot(): WhiteboardStateJSON;
+    /**
+     * 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).
+     */
+    protected restore(snap: WhiteboardStateJSON): void;
+    /**
+     * 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.
+     */
+    protected record(op: WhiteboardChangeOp, itemId: string, author: WhiteboardAuthor, summaryFragment: string): void;
+    /** Project one item to its compact, model-facing representation (deltas / summaries). */
+    protected compact(item: WhiteboardItem): WhiteboardCompactItem;
+    /** Project the optional text-style fields onto a compact item (sticky / text kinds). */
+    private static compactTextStyle;
+    /**
+     * 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.
+     */
+    protected composeSummaryText(parts: {
+        added?: number;
+        moved?: number;
+        updated?: number;
+        removed?: number;
+        reset?: boolean;
+    }): string;
+    /** The page-aware scene sentence shared by every delta / summary tail line. */
+    protected composePagesText(): string;
+    private static describe;
+}
+export {};
+//# sourceMappingURL=whiteboard-state.d.ts.map