@memberjunction/ng-conversations 6.2.0-edge.6 → 6.2.0-edge.7

package/dist/lib/components/realtime/whiteboard/whiteboard-channel.js

@@ -4,10 +4,11 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { RegisterClass } from '@memberjunction/global';
-import { REALTIME_CHANNEL_CONTRACT_VERSION } from '@memberjunction/ai-core-plus';
+import { CompareExposure, REALTIME_CHANNEL_CONTRACT_VERSION } from '@memberjunction/ai-core-plus';
 import { BaseRealtimeChannelClient, BuildToolBackedVerbs } from '@memberjunction/realtime-runtime';
-import { ApplyWhiteboardAgentTool, BuildWhiteboardExportSvg, RealtimeWhiteboardHostComponent, WHITEBOARD_TOOL_DEFINITIONS, WHITEBOARD_TOOL_PREFIX, WhiteboardState } from '@memberjunction/ng-whiteboard';
+import { IsPlainObject, RegisterClass } from '@memberjunction/global';
+import { ApplyWhiteboardAgentTool, BuildWhiteboardExportSvg, IsWhiteboardWidgetToolAllowed, IsWhiteboardWidgetToolName, MinWhiteboardWidgetAccess, RealtimeWhiteboardHostComponent, WHITEBOARD_TOOL_DEFINITIONS, WHITEBOARD_TOOL_NAMES, WHITEBOARD_TOOL_PREFIX, WHITEBOARD_WIDGET_TOOL_NAMES, WhiteboardState, SameWhiteboardWidgetActions } from '@memberjunction/ng-whiteboard';
+import { DEFAULT_WHITEBOARD_CHANNEL_CONFIG, ParseWhiteboardChannelConfig } from './whiteboard-channel-config';
 /**
  * Whether a whiteboard tool result reports success.
  *
@@ -104,6 +105,103 @@ export async function RasterizeSvgToJpegBase64(svg, width = 1280, height = 720)
  * collapse to one trailing-edge note instead of flooding the model's context).
  */
 export const WHITEBOARD_INTERACTION_NOTE_THROTTLE_MS = 4000;
+/** Every widget tool's result carries the widget's contents (outline, state), so it requires `'state'` exposure. */
+const WIDGET_TOOLS_RETURN_STATE = Object.fromEntries(WHITEBOARD_WIDGET_TOOL_NAMES.map(name => [name, 'state']));
+/**
+ * Per-widget throttle window for "widget offers actions" perception notes (same leading +
+ * trailing, latest-wins shape as the ambient interaction notes).
+ */
+export const WHITEBOARD_ACTIONS_NOTE_THROTTLE_MS = 4000;
+/**
+ * Minimum spacing (ms) between the save requests a widget-state change triggers. The
+ * session runtime debounces saves 3 s and RE-ARMS on every request, so a chatty widget
+ * requesting on every keystroke would never save until teardown; spacing requests further
+ * apart than the debounce guarantees each one lands.
+ */
+export const WHITEBOARD_WIDGET_STATE_SAVE_THROTTLE_MS = 5000;
+/** The JSON key the widget states ride under, beside the board's own fields, in the session save payload. */
+export const WHITEBOARD_WIDGET_STATES_SAVE_KEY = 'widgetStates';
+/** A JSON tool result for a widget command the channel refused before it reached the board. */
+function widgetToolFailure(errorCode, error) {
+    const result = { success: false, error, errorCode };
+    return JSON.stringify(result);
+}
+/** Parses tool arguments into a JSON object, or null when they are not one. */
+function parseToolArgs(argsJson) {
+    try {
+        const parsed = JSON.parse(argsJson);
+        // JSON.parse output is JSON by construction, so narrowing a plain object to JSONObject is not a type lie.
+        return IsPlainObject(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether a widget event came from the agent's own operate command (absent Author = the user). */
+function isAgentAuthored(event) {
+    return event.Author === 'agent';
+}
+/** Reads the `widgetStates` sibling key of a saved payload; anything malformed reads as none. */
+function readSavedWidgetStates(stateJson) {
+    const saved = parseToolArgs(stateJson);
+    const raw = saved ? saved[WHITEBOARD_WIDGET_STATES_SAVE_KEY] : undefined;
+    const out = {};
+    if (IsPlainObject(raw)) {
+        for (const [id, value] of Object.entries(raw)) {
+            if (typeof value === 'string') {
+                out[id] = value;
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Per-key leading + trailing throttle for background notes: outside an open window a value
+ * is sent immediately and opens a window; within the window the LATEST value is stashed and
+ * a trailing-edge timer sends it when the window closes (one note per key per window).
+ */
+class KeyedNoteThrottle {
+    windowMs;
+    send;
+    entries = new Map();
+    constructor(windowMs, send) {
+        this.windowMs = windowMs;
+        this.send = send;
+    }
+    /** Offers one value for `key`; it is sent now or at the end of the key's open window. */
+    Push(key, value) {
+        const now = Date.now();
+        const entry = this.entries.get(key);
+        if (!entry || (entry.Timer === null && now - entry.LastSentAt >= this.windowMs)) {
+            this.send(value);
+            this.entries.set(key, { LastSentAt: now, Timer: null, Pending: null });
+            return;
+        }
+        entry.Pending = value; // latest wins within the window
+        if (entry.Timer === null) {
+            const wait = Math.max(0, entry.LastSentAt + this.windowMs - now);
+            entry.Timer = setTimeout(() => this.flush(entry), wait);
+        }
+    }
+    /** Cancels every pending trailing note and resets all windows. */
+    Clear() {
+        for (const entry of this.entries.values()) {
+            if (entry.Timer !== null) {
+                clearTimeout(entry.Timer);
+            }
+        }
+        this.entries.clear();
+    }
+    flush(entry) {
+        entry.Timer = null;
+        const pending = entry.Pending;
+        entry.Pending = null;
+        if (pending !== null) {
+            entry.LastSentAt = Date.now();
+            this.send(pending);
+        }
+    }
+}
 /**
  * The LIVE WHITEBOARD as a pluggable interactive channel — the canonical
  * {@link BaseRealtimeChannelClient} implementation, resolved from the `MJ: AI Agent
@@ -144,7 +242,21 @@ let RealtimeWhiteboardChannel = class RealtimeWhiteboardChannel extends BaseReal
     /** Board-mutation subscription driving the debounced state-of-record save. */
     stateChangedSub = null;
     /** Per-widget ambient-interaction note throttles (ItemID → window state). */
-    interactionThrottles = new Map();
+    interactionThrottles = new KeyedNoteThrottle(WHITEBOARD_INTERACTION_NOTE_THROTTLE_MS, (interaction) => this.sendInteractionNote(interaction));
+    /** Per-widget "offers actions" note throttles (ItemID → window state). */
+    actionsNoteThrottles = new KeyedNoteThrottle(WHITEBOARD_ACTIONS_NOTE_THROTTLE_MS, (actions) => this.sendActionsNote(actions));
+    /** Per-widget action list of the last "offers actions" note SENT (ItemID → actions), for dedupe. */
+    lastActionsNoted = new Map();
+    /** The parsed `ChannelConfig` (defaults until {@link OnInitialize}). */
+    config = { ...DEFAULT_WHITEBOARD_CHANNEL_CONFIG };
+    /** Widget-state subscription driving the throttled save. */
+    widgetStateSub = null;
+    /** Trailing timer of the widget-state save throttle, or null when idle. */
+    widgetStateSaveTimer = null;
+    /** When the widget-state path last requested a save (epoch ms). */
+    lastWidgetStateSaveAt = Number.NEGATIVE_INFINITY;
+    /** True while {@link RestoreState} runs: saves are held so none carries a half-restored board. */
+    restoring = false;
     get ChannelName() {
         return 'Whiteboard';
     }
@@ -194,8 +306,46 @@ let RealtimeWhiteboardChannel = class RealtimeWhiteboardChannel extends BaseReal
     get SurfaceShareable() {
         return true;
     }
+    /**
+     * The board's tools. The widget tools are declared only as far as {@link MaxWidgetAccess}
+     * allows (`'inspect-only'` declares Inspect only, `'off'` none). Read before the channel is
+     * initialized, so it depends on the class alone, never on the session's config.
+     */
     GetToolDefinitions() {
-        return WHITEBOARD_TOOL_DEFINITIONS;
+        const max = this.MaxWidgetAccess;
+        if (max === 'full') {
+            return WHITEBOARD_TOOL_DEFINITIONS;
+        }
+        return WHITEBOARD_TOOL_DEFINITIONS.filter(tool => !IsWhiteboardWidgetToolName(tool.Name) || IsWhiteboardWidgetToolAllowed(max, tool.Name));
+    }
+    // ────────────────────────────────────────────── widget access policy (extension points)
+    /**
+     * The most widget access this channel class ever offers — which widget tools it DECLARES to the
+     * model (tools are collected before the channel is initialized, so this cannot depend on the
+     * session). Default `'full'`. A host app lowers it by subclassing the channel and registering the
+     * subclass under `'RealtimeWhiteboardChannel'` (or via `HostChannels[].Create`).
+     */
+    get MaxWidgetAccess() {
+        return 'full';
+    }
+    /**
+     * The widget access in force for ONE call, evaluated per call (so it may change mid-session,
+     * e.g. `'off'` while an assessment is open). Default: the lower of {@link MaxWidgetAccess} and
+     * the session's `widgetAccess` config. A call it does not allow returns `access_denied`.
+     */
+    ResolveWidgetAccess() {
+        return MinWhiteboardWidgetAccess(this.MaxWidgetAccess, this.config.WidgetAccess);
+    }
+    /**
+     * Last-moment veto of one widget command that access already allows: return the refusal text the
+     * model should see (the call returns `vetoed` with it) or `null` to let it through. Default allows all.
+     */
+    OnBeforeWidgetCommand(_command) {
+        return null;
+    }
+    /** Whether widget runtime state rides in this session's saves (config `persistWidgetState`). */
+    get PersistWidgetState() {
+        return this.config.PersistWidgetState;
     }
     GetSurfaceComponent() {
         return RealtimeWhiteboardHostComponent;
@@ -234,7 +384,8 @@ let RealtimeWhiteboardChannel = class RealtimeWhiteboardChannel extends BaseReal
                     Schema: { type: 'array', items: { type: 'object' } }
                 }
             ],
-            Verbs: BuildToolBackedVerbs(this.GetToolDefinitions(), this.ToolNamePrefix),
+            // Each widget tool returns the widget's contents, so the runtime refuses it below 'state' exposure.
+            Verbs: BuildToolBackedVerbs(this.GetToolDefinitions(), this.ToolNamePrefix, 'agent', WIDGET_TOOLS_RETURN_STATE),
             Events: [
                 { Name: 'state_changed', Description: 'The board changed (by you or the user).' },
                 { Name: 'frame_pushed', Description: 'A picture of the board was sent to you.' }
@@ -251,6 +402,7 @@ let RealtimeWhiteboardChannel = class RealtimeWhiteboardChannel extends BaseReal
      * the structured note would duplicate the deltas.
      */
     OnInitialize() {
+        this.applyChannelConfig();
         this.stateChangedSub?.unsubscribe();
         this.EnableVisualPerception(this, {
             ConfirmationNote: '[whiteboard] visual confirmation of your action (background — do NOT narrate or announce your own change; continue naturally)',
@@ -259,7 +411,9 @@ let RealtimeWhiteboardChannel = class RealtimeWhiteboardChannel extends BaseReal
             StartBridgePoller: true
         });
         this.stateChangedSub = this.State.Changed$.subscribe((change) => {
-            this.Context?.RequestSave(this.State.ToJSON());
+            if (!this.restoring) {
+                this.Context?.RequestSave(this.BuildSavePayload());
+            }
             this.RecordChange({ Author: change.Author, Perceive: false });
             // Only user edits (and scene replacements like undo) drive the settle-debounce pipeline.
             // Agent edits are confirmed with a single frame in ApplyAgentTool.
@@ -267,6 +421,80 @@ let RealtimeWhiteboardChannel = class RealtimeWhiteboardChannel extends BaseReal
                 void this.NotifyVisualChange();
             }
         });
+        // Widget state is runtime data (no Changed$): save it on its own, throttled cadence.
+        this.widgetStateSub?.unsubscribe();
+        this.widgetStateSub = this.State.WidgetStateChanged$.subscribe(() => this.scheduleWidgetStateSave());
+    }
+    /** Parses `ChannelConfig`; an invalid member falls back to its default with a console warning. */
+    applyChannelConfig() {
+        const parsed = ParseWhiteboardChannelConfig(this.Context?.ChannelConfig);
+        this.config = parsed.Config;
+        for (const problem of parsed.Problems) {
+            console.warn(`[RealtimeWhiteboardChannel] channel config: ${problem}`);
+        }
+    }
+    /**
+     * Tells the model, once the session is live, which widget tools this session's access leaves
+     * unavailable (notes sent before the session is live are dropped, so not from OnInitialize).
+     */
+    OnSessionStarted() {
+        super.OnSessionStarted();
+        const limit = this.describeWidgetAccessLimit(this.ResolveWidgetAccess());
+        if (limit) {
+            this.Context?.SendContextNote(`[whiteboard] ${limit}`);
+        }
+    }
+    /** One sentence naming the widget tools `access` leaves unavailable, or null at full access. */
+    describeWidgetAccessLimit(access) {
+        if (access === 'full') {
+            return null;
+        }
+        const unavailable = WHITEBOARD_WIDGET_TOOL_NAMES.filter(name => !IsWhiteboardWidgetToolAllowed(access, name));
+        const reason = access === 'off'
+            ? 'widget tools are turned off for this session'
+            : `widgets are inspect-only for this session — read them with ${WHITEBOARD_TOOL_NAMES.InspectWidget}, but do not try to change them`;
+        return `${unavailable.join(', ')} ${unavailable.length === 1 ? 'is' : 'are'} unavailable: ${reason}.`;
+    }
+    /**
+     * The session save payload: the board's own JSON plus, when `persistWidgetState` is on and any
+     * widget holds state, a sibling `widgetStates` key. Old readers ignore the unknown key; LiveKit
+     * sync and Save-to-artifact keep plain {@link WhiteboardState.ToJSON}.
+     */
+    BuildSavePayload() {
+        const boardJson = this.State.ToJSON();
+        if (!this.config.PersistWidgetState) {
+            return boardJson;
+        }
+        const widgetStates = this.State.WidgetStatesToJSON();
+        if (Object.keys(widgetStates).length === 0) {
+            return boardJson;
+        }
+        const payload = parseToolArgs(boardJson) ?? {};
+        payload[WHITEBOARD_WIDGET_STATES_SAVE_KEY] = widgetStates;
+        return JSON.stringify(payload);
+    }
+    /**
+     * Requests a save for a widget-state change at most once per
+     * {@link WHITEBOARD_WIDGET_STATE_SAVE_THROTTLE_MS} (leading edge, then one trailing request with
+     * the latest state). Nothing is requested when `persistWidgetState` is off.
+     */
+    scheduleWidgetStateSave() {
+        if (this.restoring || !this.config.PersistWidgetState || this.widgetStateSaveTimer !== null) {
+            return;
+        }
+        const wait = this.lastWidgetStateSaveAt + WHITEBOARD_WIDGET_STATE_SAVE_THROTTLE_MS - Date.now();
+        if (wait <= 0) {
+            this.requestWidgetStateSave();
+            return;
+        }
+        this.widgetStateSaveTimer = setTimeout(() => {
+            this.widgetStateSaveTimer = null;
+            this.requestWidgetStateSave();
+        }, wait);
+    }
+    requestWidgetStateSave() {
+        this.lastWidgetStateSaveAt = Date.now();
+        this.Context?.RequestSave(this.BuildSavePayload());
     }
     /**
      * Wires the dynamically-created board host: inputs (shared state engine + agent name)
@@ -279,6 +507,7 @@ let RealtimeWhiteboardChannel = class RealtimeWhiteboardChannel extends BaseReal
         this.host = instance;
         instance.State = this.State;
         instance.AgentName = this.Context?.AgentName ?? 'Agent';
+        instance.AgentWidgetAccess = this.ResolveWidgetAccess();
         this.surfaceSubs.push(
         // The board's coalesced scene delta — the perception feed the agent "sees".
         instance.SceneDelta.subscribe((deltaJson) => {
@@ -298,6 +527,11 @@ let RealtimeWhiteboardChannel = class RealtimeWhiteboardChannel extends BaseReal
         // event ran first). Surface it to the agent so it can react to quiz answers /
         // micro-form input it asked for.
         instance.WidgetSubmitted.subscribe((submit) => {
+            // The agent's own operate command submitted it: the tool result already carries
+            // `submitted`, so no note and no spoken reaction (it would answer itself).
+            if (isAgentAuthored(submit)) {
+                return;
+            }
             // Durable awareness first (the note persists in the model's context)…
             this.Context?.SendContextNote(`[whiteboard] the user submitted input in widget "${submit.Title || submit.ItemID}": ${submit.DataJson}`);
             // …then make the model REACT — a submission is explicit user input the user is
@@ -313,6 +547,10 @@ let RealtimeWhiteboardChannel = class RealtimeWhiteboardChannel extends BaseReal
         instance.WidgetInteraction.subscribe((interaction) => {
             this.onWidgetInteraction(interaction);
         }), 
+        // A widget registered or changed its named actions — a throttled perception note.
+        instance.WidgetActionsChanged.subscribe((actions) => {
+            this.actionsNoteThrottles.Push(actions.ItemID, actions);
+        }), 
         // The board's Focus toggle — ask the shell to collapse/restore the main call column.
         instance.FocusModeChange.subscribe((focused) => {
             this.Context?.SetFocusMode(focused);
@@ -330,29 +568,14 @@ let RealtimeWhiteboardChannel = class RealtimeWhiteboardChannel extends BaseReal
      * context note: outside an open window the note goes out immediately and opens a
      * {@link WHITEBOARD_INTERACTION_NOTE_THROTTLE_MS} window; within the window the LATEST
      * event is stashed and a trailing-edge timer sends it when the window closes (one note
-     * per widget per window, latest summary wins).
+     * per widget per window, latest summary wins). The agent's own interactions (its operate
+     * steps) are not echoed back to it.
      */
     onWidgetInteraction(interaction) {
-        const now = Date.now();
-        const entry = this.interactionThrottles.get(interaction.ItemID);
-        if (!entry || (entry.Timer === null && now - entry.LastSentAt >= WHITEBOARD_INTERACTION_NOTE_THROTTLE_MS)) {
-            this.sendInteractionNote(interaction);
-            this.interactionThrottles.set(interaction.ItemID, { LastSentAt: now, Timer: null, Pending: null });
+        if (isAgentAuthored(interaction)) {
             return;
         }
-        entry.Pending = interaction; // latest wins within the window
-        if (entry.Timer === null) {
-            const wait = Math.max(0, entry.LastSentAt + WHITEBOARD_INTERACTION_NOTE_THROTTLE_MS - now);
-            entry.Timer = setTimeout(() => {
-                entry.Timer = null;
-                const pending = entry.Pending;
-                entry.Pending = null;
-                if (pending) {
-                    entry.LastSentAt = Date.now();
-                    this.sendInteractionNote(pending);
-                }
-            }, wait);
-        }
+        this.interactionThrottles.Push(interaction.ItemID, interaction);
     }
     /** The ambient-note framing: background etiquette rides in the note itself (like scene deltas). */
     sendInteractionNote(interaction) {
@@ -360,14 +583,31 @@ let RealtimeWhiteboardChannel = class RealtimeWhiteboardChannel extends BaseReal
             '(background — do NOT respond unless it is significant or you are asked; ' +
             `explicit submissions arrive separately): ${interaction.Summary}`);
     }
-    /** Cancels all pending ambient-note timers and resets the per-widget throttle windows. */
-    clearInteractionThrottles() {
-        for (const entry of this.interactionThrottles.values()) {
-            if (entry.Timer !== null) {
-                clearTimeout(entry.Timer);
-            }
+    /**
+     * "[whiteboard] widget … offers actions: …" — sent only when the channel's exposure lets the
+     * model see board contents (`'state'` or above) and this session may call widget actions,
+     * and only when the list (names + descriptions) differs from the last note sent for that
+     * widget: a remount, a `hello` answer or the agent's own inspect re-reports the same list.
+     */
+    sendActionsNote(event) {
+        if (event.Actions.length === 0 || CompareExposure(this.Exposure, 'state') < 0) {
+            return;
         }
-        this.interactionThrottles.clear();
+        if (!IsWhiteboardWidgetToolAllowed(this.ResolveWidgetAccess(), WHITEBOARD_TOOL_NAMES.CallWidget)) {
+            return;
+        }
+        const lastSent = this.lastActionsNoted.get(event.ItemID);
+        if (lastSent && SameWhiteboardWidgetActions(lastSent, event.Actions)) {
+            return;
+        }
+        this.lastActionsNoted.set(event.ItemID, event.Actions.map(action => ({ ...action })));
+        const names = event.Actions.map(action => action.Name).join(', ');
+        this.Context?.SendContextNote(`[whiteboard] widget "${event.Title || event.ItemID}" (${event.ItemID}) offers actions: ${names}`);
+    }
+    /** Cancels all pending ambient / actions note timers and resets the per-widget throttle windows. */
+    clearInteractionThrottles() {
+        this.interactionThrottles.Clear();
+        this.actionsNoteThrottles.Clear();
     }
     /**
      * Persists the current board as a `MJ: Artifacts` snapshot via the host context
@@ -387,11 +627,23 @@ let RealtimeWhiteboardChannel = class RealtimeWhiteboardChannel extends BaseReal
         }
     }
     /**
-     * Executes one `Whiteboard_*` tool call LOCALLY. Prefers the live bound host (board
-     * mutation + UI garnish); falls back to the pure engine function when no surface is
-     * bound so the channel keeps working before the board is first shown.
+     * Executes one `Whiteboard_*` tool call LOCALLY. Board tools prefer the live bound host
+     * (board mutation + UI garnish) and fall back to the pure engine function when no surface
+     * is bound, so the channel keeps working before the board is first shown. Widget tools
+     * (inspect / operate / call) need the live board and resolve asynchronously; see
+     * {@link applyWidgetTool}.
+     *
+     * Return contract: **board tools return a plain `string` synchronously** (bound or not);
+     * **the three widget tools** ({@link IsWhiteboardWidgetToolName}) **return a
+     * `Promise<string>`** (policy refusals may also come back as a plain string). The declared
+     * type is therefore `string | Promise<string>`. An override that post-processes results
+     * should route `IsWhiteboardWidgetToolName(toolName)` calls straight to `super` and, for the
+     * rest, narrow the board result with `typeof result === 'string'`.
      */
     ApplyAgentTool(toolName, argsJson) {
+        if (IsWhiteboardWidgetToolName(toolName)) {
+            return this.applyWidgetTool(toolName, argsJson);
+        }
         let result;
         if (this.host) {
             result = this.host.ApplyAgentTool(toolName, argsJson);
@@ -410,7 +662,34 @@ let RealtimeWhiteboardChannel = class RealtimeWhiteboardChannel extends BaseReal
         }
         return result;
     }
-    /** The board's serialized state of record (persisted under {@link ChannelName}). */
+    /**
+     * One widget command: access policy (`access_denied`, with the reason), then the
+     * {@link OnBeforeWidgetCommand} veto (`vetoed`), then the live board (`surface_unavailable`
+     * when none is bound). No confirmation frame: a widget's picture is a placeholder in frames.
+     */
+    applyWidgetTool(toolName, argsJson) {
+        const access = this.ResolveWidgetAccess();
+        if (!IsWhiteboardWidgetToolAllowed(access, toolName)) {
+            return widgetToolFailure('access_denied', this.describeWidgetAccessLimit(access) ?? `${toolName} is not available.`);
+        }
+        const args = parseToolArgs(argsJson);
+        const itemId = args && typeof args['itemId'] === 'string' ? args['itemId'] : null;
+        const refusal = this.OnBeforeWidgetCommand({ ToolName: toolName, ItemID: itemId, Args: args, ArgsJson: argsJson, Access: access });
+        if (refusal !== null) {
+            return widgetToolFailure('vetoed', refusal);
+        }
+        const host = this.host;
+        if (!host) {
+            return widgetToolFailure('surface_unavailable', 'The whiteboard isn\'t open, so its widgets can\'t be reached; ask the user to open the Whiteboard panel, then try again.');
+        }
+        host.AgentWidgetAccess = access; // per-call policy may have changed since BindSurface
+        return host.ApplyAgentToolAsync(toolName, argsJson).catch((error) => widgetToolFailure('surface_unavailable', `The whiteboard could not run ${toolName}: ${error?.message ?? String(error)}`));
+    }
+    /**
+     * The board's serialized state of record — the board JSON only. It also backs the channel's
+     * `GetState()` snapshot, so widget states (learner answers) stay out of it; they ride only in
+     * the session save payload ({@link BuildSavePayload}).
+     */
     SerializeState() {
         return this.State.ToJSON();
     }
@@ -419,9 +698,31 @@ let RealtimeWhiteboardChannel = class RealtimeWhiteboardChannel extends BaseReal
      * the {@link State} instance and its subscriptions are preserved). Returns `true` on
      * success; malformed / incompatible JSON returns `false` and the board stays fresh
      * (never throws — {@link WhiteboardState.LoadFromJSON} is tolerant by contract).
+     *
+     * Saves: none are requested while the board and its widget states are being loaded (so no
+     * save can pair the restored board with stale in-memory widget states); after a successful
+     * restore, exactly one save is requested carrying both. A failed restore requests nothing.
      */
     RestoreState(stateJson) {
-        return this.State.LoadFromJSON(stateJson);
+        // A trailing widget-state save armed before the restore would fire after it as a second save.
+        if (this.widgetStateSaveTimer !== null) {
+            clearTimeout(this.widgetStateSaveTimer);
+            this.widgetStateSaveTimer = null;
+        }
+        this.restoring = true;
+        try {
+            if (!this.State.LoadFromJSON(stateJson)) {
+                return false;
+            }
+            // A legacy payload (no `widgetStates` key) simply restores no widget state. With
+            // `persistWidgetState` off nothing is restored either: state lives in memory only.
+            this.State.LoadWidgetStates(this.config.PersistWidgetState ? readSavedWidgetStates(stateJson) : {});
+        }
+        finally {
+            this.restoring = false;
+        }
+        this.Context?.RequestSave(this.BuildSavePayload());
+        return true;
     }
     /** Keeps the board's "Move to stage" / "Back to tab" button true to where the host placed it. */
     OnSurfacePlacementChange(placement) {
@@ -440,6 +741,14 @@ let RealtimeWhiteboardChannel = class RealtimeWhiteboardChannel extends BaseReal
     Dispose() {
         this.stateChangedSub?.unsubscribe();
         this.stateChangedSub = null;
+        this.widgetStateSub?.unsubscribe();
+        this.widgetStateSub = null;
+        if (this.widgetStateSaveTimer !== null) {
+            // Best effort: hand the latest widget state over before the context is released.
+            clearTimeout(this.widgetStateSaveTimer);
+            this.widgetStateSaveTimer = null;
+            this.requestWidgetStateSave();
+        }
         super.Dispose(); // releases the surface binding, the visual pump + bridge, and the context
     }
     /** Unsubscribes surface outputs, cancels pending ambient notes and drops the host reference. */