@jxsuite/studio 0.32.0 → 0.34.0

package/src/services/tool-executor.ts

@@ -0,0 +1,156 @@
+/**
+ * Tool-executor.js — Agentic loop driver for the document AI assistant
+ *
+ * Streams a chat round, executes any tool calls the model makes (via a ToolRegistry backed by
+ * `transactDoc()`), feeds the results back as `tool` messages, and re-streams — up to a capped
+ * number of rounds (spec §10.2, ADR docs/ai-assistant-decision.md §6a).
+ *
+ * @license MIT
+ */
+
+import type { createChatState } from "@jxsuite/ai/chat-state";
+import type { StreamingClient } from "@jxsuite/ai/streaming-client";
+import type { ToolRegistry } from "@jxsuite/ai/tools";
+
+import type { Tab } from "../tabs/tab";
+import { beginBatch, endBatch } from "../tabs/transact";
+
+const MAX_ROUNDS = 5;
+
+interface RunAgentLoopOptions {
+  chatState: ReturnType<typeof createChatState>;
+  streamingClient: StreamingClient;
+  toolRegistry: ToolRegistry;
+  systemPrompt: string;
+  signal?: AbortSignal;
+  getTab?: () => Tab | null;
+}
+
+/**
+ * Run one user turn through the agent loop: stream the model's response, execute any tool calls,
+ * and repeat until the model stops calling tools or the round cap is hit.
+ */
+export async function runAgentLoop({
+  chatState,
+  streamingClient,
+  toolRegistry,
+  systemPrompt,
+  signal,
+  getTab,
+}: RunAgentLoopOptions): Promise<void> {
+  const allErrors: string[] = [];
+  const appliedSummaries: string[] = [];
+
+  // Batch all tool-call mutations into a single undo step
+  if (getTab) {
+    beginBatch(getTab());
+  }
+
+  try {
+    for (let round = 1; round <= MAX_ROUNDS; round++) {
+      const messages = chatState.toMessagesArray();
+      const tools = toolRegistry.listForLLM();
+
+      const toolCalls = new Map<string, { name: string; arguments: string }>();
+      let stopReason = "stop";
+      let streamError = null;
+
+      for await (const event of streamingClient.streamChat(
+        messages,
+        tools,
+        systemPrompt,
+        signal as AbortSignal,
+      )) {
+        switch (event.type) {
+          case "delta": {
+            chatState.appendDelta(event.content);
+            break;
+          }
+          case "tool_call_start": {
+            chatState.appendToolCallStart(event.id, event.name);
+            toolCalls.set(event.id, { name: event.name, arguments: "" });
+            break;
+          }
+          case "tool_call_delta": {
+            chatState.appendToolCallDelta(event.id, event.args);
+            const tc = toolCalls.get(event.id);
+            if (tc) {
+              tc.arguments += event.args;
+            }
+            break;
+          }
+          case "tool_call_end": {
+            chatState.appendToolCallEnd(event.id);
+            break;
+          }
+          case "done": {
+            ({ stopReason } = event);
+            break;
+          }
+          case "error": {
+            streamError = event.message;
+            break;
+          }
+          default: {
+            break;
+          }
+        }
+      }
+
+      chatState.finishStream(stopReason);
+
+      if (streamError) {
+        chatState.setError(streamError);
+        return;
+      }
+
+      if (stopReason !== "tool_calls" || toolCalls.size === 0) {
+        return;
+      }
+
+      for (const [id, call] of toolCalls) {
+        let result;
+        try {
+          const args = call.arguments ? (JSON.parse(call.arguments) as object) : {};
+          result = await toolRegistry.execute(call.name, args);
+        } catch (error) {
+          result = {
+            success: false,
+            error: `Failed to parse arguments: ${(error as Error).message}`,
+          };
+        }
+        if (!result.success && result.error) {
+          allErrors.push(result.error);
+        }
+        if (result.success && result.summary) {
+          appliedSummaries.push(result.summary);
+        }
+        chatState.appendToolResult(id, result);
+        chatState.pushToolResultMessage(id, JSON.stringify(result));
+      }
+
+      if (round < MAX_ROUNDS) {
+        chatState.beginAssistantTurn();
+      }
+    }
+
+    /*
+     * Surface the actual errors so the user knows what went wrong, not just a generic
+     * "I couldn't do it" message.
+     */
+    const uniqueErrors = [...new Set(allErrors)];
+    const applied =
+      appliedSummaries.length > 0
+        ? `\n\nChanges applied so far:\n${appliedSummaries.map((s) => `- ${s}`).join("\n")}`
+        : "";
+    const errors =
+      uniqueErrors.length > 0
+        ? `\n\nErrors encountered:\n${uniqueErrors.map((e) => `- ${e}`).join("\n")}`
+        : "";
+    chatState.setError(
+      `I ran out of tool-call rounds (${MAX_ROUNDS}) before finishing.${applied}${errors}\n\nYou can continue by sending another message, or try a more specific request.`,
+    );
+  } finally {
+    endBatch();
+  }
+}

package/src/settings/css-vars-editor.ts

@@ -114,7 +114,7 @@ function renderColorSection(
             <div class="css-var-swatch" style="background:${val}">
               <input
                 type="color"
-                .value=${val && String(val).startsWith("#") ? val : "#007acc"}
+                .value=${val && String(val).startsWith("#") ? val : "#3b82f6"}
                 @input=${(e: Event) => updateVar(name, (e.target as HTMLInputElement).value)}
               />
             </div>
@@ -131,7 +131,7 @@ function renderColorSection(
           </div>
         `,
       )}
-      ${renderAddRow("--color-", "Primary Blue", "#007acc", addVar)}
+      ${renderAddRow("--color-", "Primary Blue", "#3b82f6", addVar)}
     </div>
   `;
 }

package/src/state.ts

@@ -73,6 +73,35 @@ export function getNodeAtPath(doc: JxMutableNode, path: JxPath) {
   return node;
 }
 
+/**
+ * Shallow-clone every node along `path` from root to target, leaving non-path subtrees as shared
+ * references. Returns the new root and the mutable target node at the end of the path.
+ *
+ * Used by mutation functions for structural-sharing history: the old root becomes an immutable
+ * snapshot (shared subtrees are never mutated), and the new root is the live document.
+ */
+export function cloneAlongPath(
+  doc: JxMutableNode,
+  path: JxPath,
+): { root: JxMutableNode; target: JxMutableNode } {
+  const root = Array.isArray(doc) ? [...doc] : { ...doc };
+  let node: Record<string | number, unknown> = root as Record<string | number, unknown>;
+
+  for (const key of path) {
+    const child = node[key];
+    if (child == null) {
+      return { root: root as JxMutableNode, target: node as JxMutableNode };
+    }
+    const cloned = Array.isArray(child)
+      ? [...(child as unknown[])]
+      : { ...(child as Record<string, unknown>) };
+    node[key] = cloned;
+    node = cloned as Record<string | number, unknown>;
+  }
+
+  return { root: root as JxMutableNode, target: node as JxMutableNode };
+}
+
 /**
  * The node's children when they are a static array (the edit-mode invariant); an empty array for
  * mapped-array or absent children.

package/src/store.ts

@@ -10,10 +10,9 @@
 // ─── Re-exports from state.js ────────────────────────────────────────────────
 
 import { activeTab } from "./workspace/workspace";
-import { isEventBinding } from "@jxsuite/schema/guards";
 import type { JxPath } from "./state";
 import type { JxMutableNode } from "@jxsuite/schema/types";
-import type { CanvasPanel } from "./panels/canvas-dnd.js";
+import type { CanvasPanel } from "./types";
 
 export {
   createState,
@@ -52,20 +51,6 @@ export function initShellRefs() {
 
 // ─── Shared containers (mutated in place by owner modules) ───────────────────
 
-export const elToPath = new WeakMap<Element, JxPath>();
-
-/**
- * Canvas element → the runtime scope its children render with. Captured during live renders so the
- * canvas patcher can re-render a subtree in isolation with the same prototype-chained scope.
- */
-export const elToScope = new WeakMap<Element, Record<string, unknown>>();
-
-/**
- * Subtree root element → the effect scope created for its surgical render. Stopped when the subtree
- * is replaced or removed so render-time reactive effects don't accumulate.
- */
-export const elToRenderScope = new WeakMap<Element, { stop: () => void }>();
-
 export const canvasPanels: CanvasPanel[] = [];
 
 // ─── Shared constants ────────────────────────────────────────────────────────
@@ -139,52 +124,9 @@ export function cancelStyleDebounce(prop: string) {
   _styleDebounceTimers.delete(prop);
 }
 
-/**
- * Strip all on* event handler properties from a Jx document tree (deep clone).
- *
- * @param {JxMutableNode} node
- * @returns {JxMutableNode}
- */
-export function stripEventHandlers(node: JxMutableNode): JxMutableNode {
-  if (!node || typeof node !== "object") {
-    return node;
-  }
-  if (Array.isArray(node)) {
-    // Arrays of nodes round-trip element-wise; the array itself is not a node.
-    return node.map((n: JxMutableNode) => stripEventHandlers(n)) as unknown as JxMutableNode;
-  }
-  const out: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(node)) {
-    if (k.startsWith("on") && isEventBinding(v)) {
-      continue;
-    }
-    if (k === "children") {
-      out.children = Array.isArray(v)
-        ? v.map((c: JxMutableNode) => stripEventHandlers(c))
-        : stripEventHandlers(v as JxMutableNode);
-    } else if (k === "cases" && typeof v === "object") {
-      const cases: Record<string, unknown> = {};
-      for (const [ck, cv] of Object.entries(v as Record<string, unknown>)) {
-        cases[ck] = stripEventHandlers(cv as JxMutableNode);
-      }
-      out.cases = cases;
-    } else if (k === "state" && typeof v === "object" && v !== null) {
-      const state: Record<string, unknown> = {};
-      for (const [sk, sv] of Object.entries(v as Record<string, unknown>)) {
-        if (sv && typeof sv === "object" && (sv as Record<string, unknown>).timing === "server") {
-          continue;
-        }
-        state[sk] = sv;
-      }
-      out.state = state;
-    } else if (k === "style" || k === "attributes" || k === "$media") {
-      out[k] = v;
-    } else {
-      out[k] = v;
-    }
-  }
-  return out;
-}
+// `stripEventHandlers` moved to ./utils/strip-events (dependency-light, shared with the iframe
+// Subtree renderer); re-exported here so existing `from "../store"` imports keep working.
+export { stripEventHandlers } from "./utils/strip-events";
 
 // ─── Render orchestration ────────────────────────────────────────────────────
 

package/src/studio.ts

@@ -19,6 +19,7 @@ import {
   requireProjectState,
   setProjectState,
   toolbarEl,
+  updateSession,
   updateUi,
 } from "./store";
 
@@ -28,20 +29,28 @@ import { effect } from "./reactivity";
 
 import { view } from "./view";
 
-import { isEditableBlock, isEditing } from "./editor/inline-edit";
-import { enterComponentInlineEdit, initComponentInlineEdit } from "./editor/component-inline-edit";
-import { enterInlineEdit } from "./editor/content-inline-edit";
+import { isEditing } from "./editor/inline-edit";
 import { applyTransform, initCanvasUtils, positionZoomIndicator } from "./canvas/canvas-utils";
-import { findCanvasElement, getActivePanel, initCanvasHelpers } from "./canvas/canvas-helpers";
 import {
-  applyCanvasMediaOverrides,
   initCanvasRender,
   renderCanvas,
   renderOverlays,
   scheduleCanvasRender,
 } from "./canvas/canvas-render";
 import { consumePatchedDocument, initCanvasPatcher } from "./canvas/canvas-patcher";
-import { registerSubtreeDnD } from "./panels/canvas-dnd";
+import {
+  commitActiveEditSession,
+  getEditSnapshot,
+  setCanvasContextMenuHandler,
+  setCanvasSlashHandler,
+  setIframePatchEscalation,
+  setInsertZoneClickHandler,
+  setStylebookHitHandler,
+  setToolbarRefresh,
+} from "./canvas/iframe-host";
+import { runInsertZoneAction } from "./editor/insert-zone-action";
+import { canvasSlashHandler } from "./editor/canvas-slash-bridge";
+import { makeCanvasContextMenuHandler } from "./editor/canvas-context-menu";
 import { initCanvasLiveRender } from "./canvas/canvas-live-render";
 import {
   mountStatusbar,
@@ -50,7 +59,12 @@ import {
   statusMessage,
 } from "./panels/statusbar";
 import { exportFile, parseSourceForPath, saveFile, serializeDocument } from "./files/file-ops";
-import { documentExtensions, formatForPath, loadFormats } from "./format/format-host";
+import {
+  documentExtensions,
+  formatForPath,
+  loadFormats,
+  refreshFormats,
+} from "./format/format-host";
 import {
   loadProject as _loadProject,
   openProject as _openProject,
@@ -97,14 +111,17 @@ import * as rightPanelMod from "./panels/right-panel";
 import * as leftPanelMod from "./panels/left-panel";
 import * as tabStrip from "./panels/tab-strip";
 import * as tabBar from "./panels/tab-bar";
-import { renderStylebookOverlays } from "./panels/stylebook-panel";
+import { selectStylebookTag } from "./panels/stylebook-panel";
 import { registerLayersDnD, registerComponentsDnD, registerElementsDnD } from "./panels/dnd";
+import { registerCanvasDndBridge } from "./panels/canvas-dnd-bridge";
 import { defaultDef } from "./panels/shared";
 import { registerFunctionCompletions } from "./panels/editors";
-import { renderBlockActionBar, initBlockActionBar } from "./panels/block-action-bar";
+import {
+  initBlockActionBar,
+  isEditChromeTarget,
+  renderBlockActionBar,
+} from "./panels/block-action-bar";
 import { initCssData } from "./panels/style-utils";
-import { updateForcedPseudoPreview } from "./panels/pseudo-preview";
-import { initPanelEvents } from "./panels/panel-events";
 import { initQuickSearch } from "./panels/quick-search";
 import { addRecentProject, hydrateRecentProjects, removeRecentProject } from "./recent-projects";
 import { initWelcome } from "./panels/welcome-screen";
@@ -119,8 +136,14 @@ void _swc;
 // These mutable variables are local to studio.js for now. As sections are extracted
 // Into their own modules, they will migrate to ctx in store.js.
 
+// Effective canvas mode: the per-tab preview toggle composes with an edit/design base mode and
+// Presents as "preview" to every downstream gate (doc resolution, iframe flags, interaction
+// Surfaces). Consumers needing the base mode (toolbar switcher selection, canvas host layout)
+// Read tab.session.ui.canvasMode directly.
 function getCanvasMode() {
-  return activeTab.value?.session.ui.canvasMode ?? "design";
+  const ui = activeTab.value?.session.ui;
+  const base = ui?.canvasMode ?? "design";
+  return ui?.preview && (base === "edit" || base === "design") ? "preview" : base;
 }
 
 /** @param {string} mode */
@@ -361,39 +384,58 @@ initBlockActionBar({
   getCanvasMode,
   navigateToComponent,
 });
-
-initComponentInlineEdit({ findCanvasElement });
-initCanvasHelpers({
-  getCanvasMode,
-  getZoom: () => activeTab.value?.session.ui.zoom ?? 1,
+// The iframe's re-emitted selection snapshot drives the parent format toolbar refresh (4b-2).
+setToolbarRefresh(renderBlockActionBar);
+// The cross-origin insertion "+" click runs the parent-realm slash-menu → mutateInsertNode flow.
+setInsertZoneClickHandler(runInsertZoneAction);
+// The in-iframe "/" trigger drives the parent-realm Spectrum slash menu across the bridge.
+setCanvasSlashHandler(canvasSlashHandler);
+// Canvas right-clicks show the parent-realm Jx element context menu across the bridge.
+setCanvasContextMenuHandler(makeCanvasContextMenuHandler({ navigateToComponent }));
+// Stylebook hits decode to a TAG in the host and route here (null = clicked chrome/empty space).
+setStylebookHitHandler((tag, media) => {
+  if (tag) {
+    selectStylebookTag(tag, media);
+  } else {
+    updateSession({ ui: { activeSelector: null, stylebookSelection: null } });
+  }
 });
+// Commit-on-parent-click: a pointerdown in PARENT chrome outside the edit-session chrome (format
+// Toolbar / link popover / slash menu) ends the live inline-edit session — the iframe can't observe
+// Parent-realm pointer events (layers panel, tab strip, right panel…). Pointerdowns over the canvas
+// Land inside the cross-origin iframe and never reach this listener, so it can't double-fire with
+// The iframe's own click-away commit.
+document.addEventListener(
+  "pointerdown",
+  (e) => {
+    if (getEditSnapshot().editing && !isEditChromeTarget(e.target)) {
+      commitActiveEditSession();
+    }
+  },
+  true,
+);
+
 initCanvasUtils({
   getCanvasMode,
   getZoom: () => activeTab.value?.session.ui.zoom ?? 1,
-  renderStylebookOverlays,
   setZoomDirect: (zoom) => {
     if (activeTab.value) {
       activeTab.value.session.ui.zoom = zoom;
     }
   },
 });
-initPanelEvents({
-  enterInlineEdit,
-  getCanvasMode,
-  navigateToComponent,
-});
 initCanvasLiveRender({
   getCanvasMode,
 });
 initCanvasPatcher({
-  applyCanvasMediaOverrides,
-  enterComponentInlineEdit,
   getCanvasMode,
-  registerSubtreeDnD,
   renderOverlays,
   scheduleCanvasRender,
-  updateForcedPseudoPreview,
 });
+// When the iframe canvas can't apply a posted patch surgically, fall back to a full render.
+setIframePatchEscalation(scheduleCanvasRender);
+// One global coordinator monitor drives cross-frame palette→canvas drops (Phase 4c).
+registerCanvasDndBridge();
 initCanvasRender({
   getCanvasMode,
   get gitDiffState() {
@@ -441,7 +483,10 @@ effect(() => {
     void tab.session.ui.canvasMode;
     void tab.session.ui.editingFunction;
     void tab.session.ui.featureToggles;
+    void tab.session.ui.preview;
+    void tab.session.ui.previewParams;
     void tab.session.ui.settingsTab;
+    void tab.session.ui.showLayout;
     void tab.session.ui.stylebookTab;
     void tab.session.ui.stylebookFilter;
     void tab.session.ui.stylebookCustomizedOnly;
@@ -453,7 +498,6 @@ rightPanelMod.mount({
   getCanvasMode,
   navigateToComponent,
   renderCanvas: () => renderCanvas(),
-  updateForcedPseudoPreview,
 });
 
 leftPanelMod.mount({
@@ -520,6 +564,19 @@ function ensureFsSync() {
 const _urlParams = new URLSearchParams(location.search);
 const _projectParam = _urlParams.get("project") || _urlParams.get("open");
 
+if (!_projectParam) {
+  // Electrobun (and other non-?project= hosts) load their project over RPC, so the ?project= branch
+  // Below — which is the only place that calls platform.activate() — is skipped. Kick off activate()
+  // Here UNCONDITIONALLY so this window's loopback canvasUrl is fetched on boot (the canvas iframe
+  // Needs it); a render() once it resolves lets ensureHost swap an early default iframe for the
+  // Loopback one (see iframe-host ensureHost's canvasUrl-changed rebuild).
+  const _bootPlatform = getPlatform();
+  // oxlint-disable-next-line unicorn/prefer-top-level-await -- fire-and-forget: must not block the initial render
+  void _bootPlatform.activate?.()?.then(() => {
+    render();
+  });
+}
+
 if (_projectParam) {
   // ?project= mode: skip normal loadProject, set up site context from the path
   const isAbsPath =
@@ -708,6 +765,11 @@ async function openRecentProject(root: string) {
     }
 
     platform.projectRoot = root;
+    // The format registry is cached per project — the previous root's registry (often empty on a
+    // Fresh desktop launch) must not answer for this project, or non-JSON documents fail with
+    // "No format class imported" until a reload. Mirrors openProject in files.ts.
+    refreshFormats();
+    void loadFormats();
     const content = await platform.readFile("project.json");
     const config = JSON.parse(content) as ProjectConfig;
 
@@ -779,18 +841,6 @@ function openFileFromTree(path: string) {
 initShortcuts(() => ({
   applyTransform,
   canvasMode: getCanvasMode(),
-  componentInlineEdit: view.componentInlineEdit,
-  enterEditOnPath(path) {
-    requestAnimationFrame(() => {
-      const activePanel = getActivePanel();
-      if (activePanel) {
-        const el = findCanvasElement(path, activePanel.canvas);
-        if (el && isEditableBlock(el)) {
-          enterInlineEdit(el, path);
-        }
-      }
-    });
-  },
   openProject,
   panX: view.panX,
   panY: view.panY,

package/src/tabs/doc-op-apply.ts

@@ -0,0 +1,89 @@
+/**
+ * Pure document-op applier — folds a value-carrying {@link JxDocOp} into a bare (non-reactive)
+ * document tree. Shared by two consumers that MUST stay byte-identical or undo/redo would drift
+ * from live editing: history replay in the parent ({@link file://./transact.ts}) and the iframe
+ * canvas's non-reactive shadow doc (the patch source-of-truth across the cross-origin bridge).
+ *
+ * Dependency-light on purpose: it pulls only the pure path helper from `../state` and clones values
+ * with a local JSON round-trip, so the slim canvas-iframe bundle can import it without dragging in
+ * the editor's reactive store / format host.
+ */
+
+import { getNodeAtPath } from "../state";
+import type { JxDocOp } from "./patch-ops";
+import type { JxMutableNode } from "@jxsuite/schema/types";
+
+/** JSON round-trip clone — also normalizes away reactive proxies / functions / undefined. */
+function jsonClone<T>(value: T): T {
+  // oxlint-disable-next-line unicorn/prefer-structured-clone -- structuredClone throws on reactive proxies; JSON normalization is the point
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+/** Deep-clone a recorded value (undefined/null pass through; reactive proxies are read through). */
+export function cloneValue<T>(v: T): T {
+  return v === undefined || v === null ? v : (jsonClone(v as object) as T);
+}
+
+/** The node's children array, lazily created; throws if `node` is itself a children array or mapped. */
+export function childArray(node: JxMutableNode): (JxMutableNode | string)[] {
+  // Defense-in-depth: a path that resolves to a children array (rather than a node) would
+  // Otherwise get a bogus `.children` property tacked on here, silently storing the insert where
+  // Nothing renders. Callers must pass a node; fail loudly if they don't.
+  if (Array.isArray(node)) {
+    throw new TypeError("Cannot insert into a children array; parentPath must point at a node");
+  }
+  if (!node.children) {
+    node.children = [];
+  }
+  if (!Array.isArray(node.children)) {
+    throw new TypeError("Cannot insert into mapped-array children; edit the map template instead");
+  }
+  return node.children;
+}
+
+/**
+ * Apply a replayable doc op to a bare document tree. Values/nodes are cloned in, so the tree never
+ * aliases the op object. Throws (with a machine-readable reason) when a target path is missing.
+ */
+export function applyDocOpToDoc(doc: JxMutableNode, op: JxDocOp): void {
+  switch (op.op) {
+    case "set-key": {
+      const node = getNodeAtPath(doc, op.path);
+      if (!node) {
+        throw new Error(`doc-op-node-not-found:${op.path.join("/")}`);
+      }
+      const target = node as Record<string, unknown>;
+      if (op.value === undefined) {
+        delete target[op.key];
+      } else {
+        target[op.key] = cloneValue(op.value);
+      }
+      return;
+    }
+    case "insert-child": {
+      const parent = getNodeAtPath(doc, op.parentPath);
+      childArray(parent).splice(op.index, 0, cloneValue(op.node) as JxMutableNode);
+      return;
+    }
+    case "remove-child": {
+      const parent = getNodeAtPath(doc, op.parentPath);
+      childArray(parent).splice(op.index, 1);
+      return;
+    }
+    case "set-child": {
+      const parent = getNodeAtPath(doc, op.parentPath);
+      childArray(parent).splice(op.index, 1, cloneValue(op.node) as JxMutableNode);
+      return;
+    }
+    case "move-child": {
+      const fromParent = getNodeAtPath(doc, op.fromParentPath);
+      const toParent = getNodeAtPath(doc, op.toParentPath);
+      const [node] = childArray(fromParent).splice(op.fromIndex, 1);
+      childArray(toParent).splice(op.toIndex, 0, node!);
+      return;
+    }
+    default: {
+      throw new Error(`unknown-doc-op:${(op as JxDocOp).op}`);
+    }
+  }
+}

package/src/tabs/patch-ops.ts

@@ -78,8 +78,12 @@ export interface PatchConsumer {
   classify: (tab: Tab, ops: JxPatchOp[]) => { patchable: boolean; reason: string };
   /** Mark a document root reference as surgically consumed (checked by the canvas doc-effect). */
   markConsumed: (docRef: object) => void;
-  /** Apply the batch to all ready canvas panels. Throws on any failure (caller escalates). */
-  apply: (tab: Tab, ops: JxPatchOp[]) => void;
+  /**
+   * Apply the batch to all ready canvas panels. Throws on any failure (caller escalates). `record`
+   * carries the value-carrying `docOps` the iframe consumer posts across the frame boundary; the
+   * legacy (parent-DOM) consumer ignores it and reads the post-mutation reactive doc instead.
+   */
+  apply: (tab: Tab, ops: JxPatchOp[], record?: TransactionRecord) => void;
   /** Schedule a full canvas render as the fallback path, recording the reason. */
   escalate: (reason: string) => void;
 }