@jxsuite/studio 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/studio",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Jx Studio — visual builder for Jx documents",
   "license": "MIT",
   "repository": {
@@ -39,12 +39,13 @@
     "@atlaskit/pragmatic-drag-and-drop": "^2.0.1",
     "@atlaskit/pragmatic-drag-and-drop-hitbox": "^2.0.0",
     "@jxsuite/ai": "^0.33.0",
-    "@jxsuite/collab": "^0.3.0",
-    "@jxsuite/create": "^1.0.0",
-    "@jxsuite/markup": "^0.2.0",
-    "@jxsuite/protocol": "^0.4.0",
-    "@jxsuite/runtime": "^1.0.0",
-    "@jxsuite/schema": "^1.0.0",
+    "@jxsuite/collab": "^0.4.0",
+    "@jxsuite/create": "^1.1.0",
+    "@jxsuite/formulas": "^0.0.2",
+    "@jxsuite/markup": "^0.3.0",
+    "@jxsuite/protocol": "^0.5.0",
+    "@jxsuite/runtime": "^1.1.0",
+    "@jxsuite/schema": "^1.1.0",
     "@spectrum-web-components/accordion": "^1.12.2",
     "@spectrum-web-components/action-bar": "1.12.2",
     "@spectrum-web-components/action-button": "^1.12.2",
@@ -81,12 +82,13 @@
     "@spectrum-web-components/toast": "^1.12.2",
     "@spectrum-web-components/tooltip": "^1.12.2",
     "@spectrum-web-components/underlay": "^1.12.2",
-    "@vue/reactivity": "3.5.39",
+    "@vue/reactivity": "3.5.40",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "lit": "^3.3.3",
     "lit-html": "^3.3.3",
     "monaco-editor": "^0.55.1",
+    "tabulator-tables": "^6.5",
     "y-monaco": "^0.1.6",
     "yaml": "^2.9.0"
   },
@@ -95,7 +97,7 @@
     "@types/mdast": "^4.0.4",
     "@webref/css": "^8.7.0",
     "@webref/elements": "^2.7.1",
-    "@webref/idl": "^3.81.3"
+    "@webref/idl": "^3.82.0"
   },
   "//vue-reactivity": "Exact pin required — must match @jxsuite/runtime to avoid cross-boundary proxy bugs"
 }

package/src/canvas/canvas-live-render.ts

@@ -26,6 +26,7 @@ import {
   resolveParamBoundState,
   substitutePreviewParams,
 } from "../page-params";
+import { isComponentDoc, substitutePreviewProps } from "../component-props";
 
 import type { JxElement, JxMutableNode } from "@jxsuite/schema/types";
 import type { ComponentEntry } from "../files/components.js";
@@ -182,6 +183,17 @@ export async function resolveCanvasDocument(doc: JxMutableNode): Promise<{
     }
   }
 
+  // Component definition docs (non-page): seed chosen test-prop values into the render doc's state
+  // So a non-instantiated component previews with real data — templates, dataScope snapshots, and
+  // Live/snapshot expression previews all see the values (M6, the previewParams mirror). Pure
+  // Rebuild for the same reason as substitutePreviewParams above.
+  if (!isPage && tab && isComponentDoc(renderDoc)) {
+    const { previewProps } = tab.session.ui;
+    if (previewProps && Object.keys(previewProps).length > 0) {
+      renderDoc = substitutePreviewProps(renderDoc, previewProps);
+    }
+  }
+
   const arrayPaths = new Set<string>();
   if (canvasMode === "design" || canvasMode === "edit") {
     (function findArrayPaths(node: JxMutableNode, path: (string | number)[]) {
@@ -219,9 +231,16 @@ export async function resolveCanvasDocument(doc: JxMutableNode): Promise<{
     })(doc, []);
   }
 
-  // Component auto-discovery (content mode or layout) — mirrors the legacy render path.
+  // Component auto-discovery (content mode, wrapped layout, or a layout opened on its own) —
+  // Mirrors the legacy render path. A directly-opened layout is neither a page (so it never
+  // Sets layoutWrapped) nor content mode (a plain .json file skips the mode-setting parse),
+  // So it needs its own gate; scoping to layouts/ avoids the single-component-edit path, where
+  // The doc's own root tag would otherwise inject a $ref to itself.
+  const isLayoutDoc =
+    S.documentPath != null &&
+    (S.documentPath.startsWith("layouts/") || S.documentPath.startsWith("./layouts/"));
   const effectiveElements = getEffectiveElements(renderDoc.$elements as (JxElement | string)[]);
-  if ((S.mode === "content" || layoutWrapped) && componentRegistry.length > 0) {
+  if ((S.mode === "content" || layoutWrapped || isLayoutDoc) && componentRegistry.length > 0) {
     const existingRefs = new Set(
       effectiveElements.map((e: JxElement | string) => (typeof e === "string" ? e : e?.$ref)),
     );

package/src/canvas/canvas-render.ts

@@ -15,15 +15,15 @@ import { attachCursorStyles } from "../collab/monaco-cursors";
 import type { AwarenessLike } from "../collab/monaco-cursors";
 import { view } from "../view";
 import { parseSourceForPath, serializeDocument } from "../files/file-ops";
+import { detachGridPanel, gridPanelMounted, renderGridMode } from "../grid/grid-panel";
 import { formatByName, formatForPath } from "../format/format-host";
 import { renderWelcome } from "../panels/welcome-screen";
 import { projectState } from "../state";
 import {
+  applyEditZoom,
   applyTransform,
   canvasPanelTemplate,
   observeCenterUntilStable,
-  renderZoomIndicator,
-  resetZoomIndicator,
   updateActivePanelHeaders,
 } from "./canvas-utils";
 import { parseMediaEntries } from "../utils/canvas-media";
@@ -40,6 +40,7 @@ import { dismissBlockActionBar, dismissLinkPopover } from "../panels/block-actio
 import { dismissContextMenu } from "../editor/context-menu";
 import { dismissSlashMenu } from "../editor/slash-menu";
 import { renderFunctionEditor } from "../panels/editors";
+import { renderFormulaWorkspace } from "../panels/formula-workspace";
 import { mediaDisplayName } from "../panels/shared";
 import { statusMessage } from "../panels/statusbar";
 import * as overlaysPanel from "../panels/overlays";
@@ -174,6 +175,7 @@ function resetCanvasView() {
     view.functionEditor.dispose();
     view.functionEditor = null;
   }
+  detachGridPanel();
   disposeSourceCollab();
   if (view.monacoEditor) {
     view.monacoEditor.getModel()?.dispose();
@@ -206,7 +208,6 @@ function resetCanvasView() {
   canvasWrap.style.flexDirection = "";
   canvasWrap.style.display = "";
   canvasWrap.style.overflow = "";
-  resetZoomIndicator();
   dismissBlockActionBar();
   dismissLinkPopover();
   dismissContextMenu();
@@ -266,6 +267,13 @@ export function renderCanvas() {
     view.functionEditor = null;
   }
 
+  // Formula workspace mode: full-screen structured editing of an $expression (the function editor
+  // Takes precedence when both targets are set).
+  if (S.ui.editingFormula) {
+    renderFormulaWorkspace();
+    return;
+  }
+
   // Source mode: update existing Monaco editor without recreating. Don't replace the buffer while
   // The user is actively typing in it — that would reformat under the cursor (the source view is
   // The editing surface here, mirroring the panel draft-state behaviour).
@@ -287,6 +295,12 @@ export function renderCanvas() {
     return;
   }
 
+  // Grid fast-path: the grid panel runs its own effect scope (toolbar + engine stay live), so a
+  // Same-tab re-render while the panel is mounted needs nothing from the canvas pipeline.
+  if (canvasMode === "grid" && gridPanelMounted(tab)) {
+    return;
+  }
+
   // Stylebook fast-path: a style edit re-applies IN PLACE via the bridge (the iframe re-runs the
   // Runtime's style applier on the specimen root — real @media, no re-render, no iframe reload).
   // Filter/Customized changes fall through to the full rebuild (they change which specimens exist),
@@ -344,6 +358,9 @@ export function renderCanvas() {
       view.centerObserver = null;
     }
 
+    // Destroy the grid panel if switching away from grid mode
+    detachGridPanel();
+
     // Dispose Monaco editor if switching away from source mode
     disposeSourceCollab();
     if (view.monacoEditor) {
@@ -362,9 +379,6 @@ export function renderCanvas() {
     canvasWrap.style.overflow = "";
     canvasWrap.style.overflow = "";
 
-    // Clear zoom indicator (only re-rendered by design/stylebook)
-    resetZoomIndicator();
-
     // Dismiss open popovers/toolbars that are no longer relevant
     dismissBlockActionBar();
     dismissLinkPopover();
@@ -380,12 +394,20 @@ export function renderCanvas() {
       applyTransform,
       canvasPanelTemplate,
       observeCenterUntilStable,
-      renderZoomIndicator,
       updateActivePanelHeaders,
     });
     return;
   }
 
+  // Grid mode: spreadsheet editor over the tab's grid source (mirrors the Monaco/stylebook
+  // Non-iframe-editor pattern; the panel owns its own reactivity from here).
+  if (canvasMode === "grid") {
+    canvasWrap.style.padding = "0";
+    canvasWrap.style.display = "block";
+    renderGridMode(canvasWrap, tab);
+    return;
+  }
+
   // Source mode: create Monaco editor instead of canvas
   if (canvasMode === "source") {
     canvasWrap.style.padding = "0";
@@ -599,18 +621,15 @@ export function renderCanvas() {
     if (modeChanged) {
       observeCenterUntilStable();
     }
-    renderZoomIndicator();
     return;
   }
 
-  // Edit (content) mode — centered column, no panzoom, always 100%
+  // Edit (content) mode — centered column, no panzoom; `ui.editZoom` reflows content at the zoomed
+  // Effective width while the on-screen footprint stays fixed (browser-page-zoom semantics).
   if (canvasMode === "edit") {
     if (modeChanged) {
       canvasWrap.style.padding = "0";
       canvasWrap.style.overflow = "hidden";
-
-      // Remove zoom indicator left over from design mode
-      resetZoomIndicator();
     }
 
     const { baseWidth } = parseMediaEntries(getEffectiveMedia(S.document.$media));
@@ -633,6 +652,10 @@ export function renderCanvas() {
     litRender(editTpl, canvasWrap);
     canvasPanels.push(panel as unknown as CanvasPanel);
     renderCanvasIntoPanel(panel as unknown as CanvasPanel, S.ui.featureToggles);
+    // The column must exist in the DOM before the zoom's live width measurement — so the zoom is
+    // Applied after the render rather than baked into the template (the panel mounts fluid and is
+    // Immediately re-fitted; the iframe hasn't painted yet, so nothing visibly jumps).
+    applyEditZoom();
     return;
   }
 
@@ -684,7 +707,6 @@ export function renderCanvas() {
     if (modeChanged) {
       observeCenterUntilStable();
     }
-    renderZoomIndicator();
     return;
   }
 
@@ -747,9 +769,6 @@ export function renderCanvas() {
   if (modeChanged) {
     observeCenterUntilStable();
   }
-
-  // Floating zoom indicator
-  renderZoomIndicator();
 }
 
 /**

package/src/canvas/canvas-utils.ts

@@ -4,7 +4,7 @@
  * template creation, centering, transform application, zoom indicator, and fit-to-screen.
  */
 
-import { html, render as litRender, nothing } from "lit-html";
+import { html, nothing } from "lit-html";
 import type { CanvasPanel } from "../types";
 import { ref } from "lit-html/directives/ref.js";
 import { classMap } from "lit-html/directives/class-map.js";
@@ -14,7 +14,6 @@ import { ifDefined } from "lit-html/directives/if-defined.js";
 import { canvasPanels, canvasWrap, renderOnly, updateUi } from "../store";
 import { activeTab } from "../workspace/workspace";
 import { view } from "../view";
-import { getLayerSlot } from "../ui/layers";
 import { findCanvasElement, getActivePanel, panelMediaToActiveMedia } from "./canvas-helpers";
 import { rectOf } from "../utils/geometry";
 import type { TemplateResult } from "lit-html";
@@ -25,8 +24,6 @@ let _ctx: {
   setZoomDirect: (zoom: number) => void;
 };
 
-let _zoomIndicatorEl: HTMLElement | null = null;
-
 /**
  * Initialize the canvas utils module.
  *
@@ -162,12 +159,127 @@ export function applyTransform() {
   }
   const zoom = _ctx.getZoom();
   view.panzoomWrap.style.transform = `translate(${view.panX}px, ${view.panY}px) scale(${zoom})`;
-  renderZoomIndicator();
   // Overlays live INSIDE the scaled panzoom-wrap (iframe hosts draw there), so no per-mode redraw
-  // Is needed here — the flush only re-anchors the fixed block-action-bar.
+  // Is needed here — the flush only re-anchors the fixed block-action-bar. The tab-bar zoom widget
+  // Tracks `ui.zoom` reactively, so no explicit indicator refresh is needed either.
+  renderOnly("overlays");
+}
+
+// ─── Edit-mode content zoom ──────────────────────────────────────────────────
+// Browser-page-zoom semantics: the canvas footprint stays fixed while the CONTENT reflows at the
+// Zoomed effective width — unlike design mode's panzoom, which visually scales a fixed layout.
+
+export const EDIT_ZOOM_MIN = 0.25;
+
+export const EDIT_ZOOM_MAX = 3;
+
+/** Clamp an edit-zoom value to the supported range. */
+export function clampEditZoom(zoom: number): number {
+  return Math.min(EDIT_ZOOM_MAX, Math.max(EDIT_ZOOM_MIN, zoom));
+}
+
+/**
+ * Apply the active tab's edit-mode content zoom to the single edit panel.
+ *
+ * Mechanism: a parent-side transform on the iframe never reflows the iframe's internal document (it
+ * is its own layout viewport), so genuine reflow requires resizing the iframe's REAL CSS width to
+ * `renderWidth / editZoom` — and a compensating `scale(editZoom)` on the canvas element brings the
+ * rendered footprint back to exactly `renderWidth`. The overlay layer (the iframe's DOM sibling
+ * inside the canvas element) inherits the transform, so overlay boxes stay drawn at scale 1 (D-2),
+ * and `hostDragGeometry`'s empirical `rect.width / clientWidth` evaluates to exactly `editZoom`
+ * with no bridge changes.
+ *
+ * `renderWidth` is measured live from `.content-edit-column` (already `min(baseWidth, available)`
+ * via normal block layout) — the nominal `$media["--"]` width would overflow a narrow studio
+ * window.
+ *
+ * HARD INVARIANT: never trigger a canvas re-render from here (`renderCanvas`/`mountIframeCanvas`) —
+ * a re-render rebuilds the iframe DOM and would destroy a live inline-edit session. Live zoom is
+ * bare style writes only; the iframe's own ResizeObserver re-posts `contentHeight` after the
+ * reflow, which also finalizes the viewport height.
+ */
+export function applyEditZoom() {
+  if (_ctx.getCanvasMode() !== "edit") {
+    return;
+  }
+  const [panel] = canvasPanels;
+  if (!panel?.canvas || !panel.viewport) {
+    return;
+  }
+  const canvasEl = panel.canvas;
+  const iframe = canvasEl.querySelector("iframe");
+  const editZoom = activeTab.value?.session.ui.editZoom ?? 1;
+  if (editZoom === 1) {
+    // Exactly today's fluid behavior — no inline width, no transform, auto viewport height.
+    panel._width = null;
+    canvasEl.style.width = "";
+    canvasEl.style.transform = "";
+    canvasEl.style.transformOrigin = "";
+    if (iframe) {
+      iframe.style.width = "100%";
+    }
+    panel.viewport.style.height = "";
+  } else {
+    const column = canvasWrap.querySelector<HTMLElement>(".content-edit-column");
+    if (!column) {
+      return;
+    }
+    // The column width is parent-driven (width:100%, max-width:baseWidth), so it is independent of
+    // The canvas content — measuring it mid-zoom is stable. No rounding: layoutWidth * editZoom
+    // Must equal renderWidth exactly.
+    const renderWidth = rectOf(column).width;
+    if (renderWidth <= 0) {
+      return;
+    }
+    const layoutWidth = renderWidth / editZoom;
+    panel._width = layoutWidth;
+    canvasEl.style.width = `${layoutWidth}px`;
+    canvasEl.style.transform = `scale(${editZoom})`;
+    canvasEl.style.transformOrigin = "top left";
+    if (iframe) {
+      iframe.style.width = `${layoutWidth}px`;
+      // Transforms don't affect an ancestor's auto-height, so the viewport (the white "page"
+      // Surface) needs its height pinned to the SCALED content height. offsetHeight is the
+      // Pre-measurement approximation; the next contentHeight message writes the exact value.
+      panel.viewport.style.height = `${iframe.offsetHeight * editZoom}px`;
+    }
+  }
+  // Re-anchor the fixed block-action-bar over the rescaled canvas.
   renderOnly("overlays");
 }
 
+/** Set the active tab's edit zoom (clamped) and apply it synchronously. */
+export function setEditZoom(zoom: number) {
+  const tab = activeTab.value;
+  if (!tab) {
+    return;
+  }
+  tab.session.ui.editZoom = clampEditZoom(zoom);
+  applyEditZoom();
+}
+
+let _editZoomRaf = 0;
+
+/**
+ * Wheel-rate edit-zoom setter: the reactive `editZoom` write lands immediately (the tab-bar label
+ * tracks it), but the DOM work — an iframe width resize, i.e. a real reflow — is coalesced to one
+ * `applyEditZoom()` per animation frame so a fast ctrl+scroll burst doesn't thrash layout.
+ */
+export function requestEditZoom(zoom: number) {
+  const tab = activeTab.value;
+  if (!tab) {
+    return;
+  }
+  tab.session.ui.editZoom = clampEditZoom(zoom);
+  if (_editZoomRaf) {
+    return;
+  }
+  _editZoomRaf = requestAnimationFrame(() => {
+    _editZoomRaf = 0;
+    applyEditZoom();
+  });
+}
+
 /** Calculate zoom + pan to fit all panels within the viewport. */
 export function fitToScreen() {
   if (!view.panzoomWrap) {
@@ -209,12 +321,6 @@ export function resetZoom() {
   _ctx.setZoomDirect(1);
   centerCanvas();
   applyTransform();
-  renderZoomIndicator();
-}
-
-/** Reset the zoom indicator (clear its content). Called when switching to non-panzoom modes. */
-export function resetZoomIndicator() {
-  litRender(nothing, getLayerSlot("popover", "zoom-indicator"));
 }
 
 /**
@@ -286,66 +392,6 @@ export function panToElement(path: (string | number)[]) {
   _panToEl(el, panel);
 }
 
-/**
- * Render the floating zoom indicator at the bottom center of canvas-wrap. Uses position: fixed,
- * computed from canvas-wrap bounds.
- */
-export function renderZoomIndicator() {
-  const zoom = _ctx.getZoom();
-  const host = getLayerSlot("popover", "zoom-indicator");
-  litRender(
-    html`
-      <div
-        class="zoom-indicator"
-        ${ref((el: Element | undefined) => {
-          _zoomIndicatorEl = (el as HTMLElement) || null;
-        })}
-      >
-        <span class="zoom-indicator-action" title="Reset to 100%" @click=${resetZoom}>
-          <svg
-            width="14"
-            height="14"
-            viewBox="0 0 16 16"
-            fill="none"
-            stroke="currentColor"
-            stroke-width="1.5"
-          >
-            <circle cx="8" cy="8" r="5.5" />
-            <path d="M8 5.5v5M5.5 8h5" />
-          </svg>
-        </span>
-        <span class="zoom-indicator-label">${Math.round(zoom * 100)}%</span>
-        <span class="zoom-indicator-action" title="Fit to screen" @click=${fitToScreen}>
-          <svg
-            width="14"
-            height="14"
-            viewBox="0 0 16 16"
-            fill="none"
-            stroke="currentColor"
-            stroke-width="1.5"
-          >
-            <rect x="2" y="2" width="12" height="12" rx="1" />
-            <path d="M2 6h12M6 2v12" />
-          </svg>
-        </span>
-      </div>
-    `,
-    host,
-  );
-  positionZoomIndicator();
-}
-
-/** Position the zoom indicator relative to canvas-wrap bounds. */
-export function positionZoomIndicator() {
-  if (!_zoomIndicatorEl) {
-    return;
-  }
-  const rect = rectOf(canvasWrap);
-  _zoomIndicatorEl.style.left = `${rect.left + rect.width / 2}px`;
-  _zoomIndicatorEl.style.top = `${rect.bottom - 32}px`;
-  _zoomIndicatorEl.style.transform = "translateX(-50%)";
-}
-
 /** Toggle "active" class on canvas panel headers based on activeMedia. */
 export function updateActivePanelHeaders() {
   const activeMedia = activeTab.value?.session.ui.activeMedia ?? null;

package/src/canvas/iframe-entry.ts

@@ -21,6 +21,7 @@ import { startIframeSlashBridge } from "./iframe-slash";
 import { startKeyForwarding } from "./iframe-keys";
 import { applyIframePatch } from "./iframe-patch";
 import { disposeAllSubtrees } from "./iframe-subtree";
+import { evaluateLiveExprs } from "./iframe-eval";
 import { serializeDataScope } from "./serialize-scope";
 import { getActivePath, isEditing, stopEditing } from "../editor/inline-edit";
 import { isAncestor } from "../state";
@@ -226,8 +227,11 @@ export function startCanvasIframe(opts: {
   // Document, so without this they'd be swallowed whenever focus is inside the canvas iframe.
   const stopKeyForwarding = startKeyForwarding(channel, container.ownerDocument);
   // Run inline editing (contenteditable) here, posting committed/split/insert results to the parent.
+  // The shadow-doc accessor gates prop-bound sessions on the RAW instance prop value (template/$ref
+  // Valued props render display sugar and must not be plain-text edited).
   const stopInlineEdit = startIframeInlineEdit(channel, container, {
     getMode: () => currentMode,
+    getShadowDoc: () => shadowDoc,
   });
   // Bridge the engine's slash menu to the parent's Spectrum menu (show/nav/select over the channel).
   const stopSlashBridge = startIframeSlashBridge(channel, container.ownerDocument);
@@ -365,6 +369,22 @@ export function startCanvasIframe(opts: {
       });
       return;
     }
+    if (msg.kind === "evalExpr") {
+      // Live expression preview (M6): evaluate against the LIVE render's resolved scope — but only
+      // The render the request targeted. A stale/ahead gen gets an empty reply (never values from
+      // The wrong scope); the parent additionally gen-gates the reply against its own state.
+      const results =
+        msg.gen === renderedGen && renderCtx && shadowDoc
+          ? evaluateLiveExprs(
+              msg.exprs,
+              renderCtx.defs as Record<string, unknown>,
+              shadowDoc,
+              msg.contextPath,
+            )
+          : [];
+      channel.post({ gen: msg.gen, kind: "evalResult", reqId: msg.reqId, results });
+      return;
+    }
     if (msg.kind === "patch") {
       const { gen } = msg;
       if (gen < renderedGen) {

package/src/canvas/iframe-eval.ts

@@ -0,0 +1,155 @@
+/**
+ * In-iframe live expression evaluation (M6) — answers the parent's `evalExpr` requests against the
+ * LIVE resolved scope of the current render (buildScope's `$defs`), so previews see real repeater
+ * items, real `window#/` globals, and uncapped data values instead of the parent's serialized
+ * snapshot.
+ *
+ * Safety: every expression evaluates against a fresh plain-data clone of the scope (a per-key JSON
+ * round-trip, the serialize-scope idiom — it reads through the runtime's reactive proxies), so
+ * mutating operators write into the clone and never touch the live canvas. Named-formula callables
+ * (pure `$expression` entries with parameters) are kept BY REFERENCE so `call` nodes work; every
+ * other function (side-effecting handlers, server fns) is dropped so a preview can never run one.
+ */
+
+import { evaluateExpression } from "@jxsuite/runtime/expression";
+import { resolveRef } from "@jxsuite/runtime";
+import { formatPreviewValue } from "../utils/preview-format";
+
+import type { ExpressionNode } from "@jxsuite/runtime/expression";
+import type { EvalExprResult } from "./iframe-protocol";
+
+type Scope = Record<string, unknown>;
+
+/** Whether the raw (document) state entry is a pure named-formula (`$expression` + parameters). */
+function isNamedFormulaEntry(entry: unknown): boolean {
+  return (
+    typeof entry === "object" &&
+    entry !== null &&
+    !Array.isArray(entry) &&
+    "$expression" in entry &&
+    Array.isArray((entry as { parameters?: unknown }).parameters)
+  );
+}
+
+/**
+ * Clone the live `$defs` scope into a plain object safe to evaluate (and mutate) against. Data
+ * values are JSON round-tripped per key (reads through reactive proxies, unwraps top-level refs);
+ * functions survive only when their raw state entry is a pure named formula — anything else
+ * callable (event handlers, structured-body functions, server fns) is dropped so a stray `call`
+ * can't run a side effect against the live canvas.
+ */
+export function cloneLiveScope(defs: Scope, rawState: Record<string, unknown> | null): Scope {
+  const out: Scope = {};
+  for (const key of Object.keys(defs)) {
+    try {
+      // Reading through the reactive proxy auto-unwraps a top-level ref/computed — and can throw (a
+      // Computed getter that throws), which maps the key to null instead of aborting the clone.
+      const value = defs[key];
+      if (typeof value === "function") {
+        if (isNamedFormulaEntry(rawState?.[key])) {
+          out[key] = value; // A pure formula callable — safe (and needed) for `call` nodes.
+        }
+        continue;
+      }
+      const json = JSON.stringify(value);
+      out[key] = json === undefined ? null : (JSON.parse(json) as unknown);
+    } catch {
+      out[key] = null;
+    }
+  }
+  return out;
+}
+
+/**
+ * Bind repeater `$map` contexts for a node at `contextPath`: walk the shadow doc along the path
+ * and, at every repeater crossing (a `$prototype: "Array"` node entered through its `map`
+ * template), resolve the repeater's `items` against the scope built so far and layer the FIRST
+ * item's `$map` context (item + index 0) over it — the same shape `renderMappedArrayInto` gives
+ * rendered items, so `$map/item` / `$map/index` refs preview against real data. Nested repeaters
+ * chain naturally (an inner `items` ref may read the outer `$map/item`).
+ */
+export function bindRepeaterContext(
+  scope: Scope,
+  shadowDoc: unknown,
+  contextPath: (string | number)[] | null,
+): Scope {
+  if (!contextPath || contextPath.length === 0) {
+    return scope;
+  }
+  let node: unknown = shadowDoc;
+  let bound = scope;
+  for (const seg of contextPath) {
+    if (!node || typeof node !== "object") {
+      break;
+    }
+    const rec = node as Record<string, unknown>;
+    if (rec.$prototype === "Array" && seg === "map") {
+      // Entering the repeater's template — bind the first item's context before descending.
+      const itemsDef = rec.items;
+      const items: unknown =
+        itemsDef && typeof itemsDef === "object" && "$ref" in itemsDef
+          ? resolveRef((itemsDef as { $ref: string }).$ref, bound)
+          : itemsDef;
+      if (Array.isArray(items) && items.length > 0) {
+        let item: unknown;
+        try {
+          // Items resolved from the shadow doc (a literal array) must not be mutable through the
+          // Preview scope — clone; scope-resolved items are already clone data, so this is free.
+          item = structuredClone(items[0]);
+        } catch {
+          item = null;
+        }
+        const child = Object.create(bound) as Scope;
+        child.$map = { index: 0, item };
+        child["$map/item"] = item;
+        child["$map/index"] = 0;
+        bound = child;
+      }
+    }
+    node = rec[seg as keyof typeof rec];
+  }
+  return bound;
+}
+
+/**
+ * Evaluate each requested expression against a fresh clone of the live scope (with the repeater
+ * context for `contextPath` bound), reporting every sub-node's value through the engine's trace
+ * hook as pre-formatted display strings. Exceptions are guarded per expression into `error`.
+ */
+export function evaluateLiveExprs(
+  exprs: { id: string; node: unknown }[],
+  defs: Scope,
+  shadowDoc: unknown,
+  contextPath: (string | number)[] | null,
+): EvalExprResult[] {
+  const rawState =
+    shadowDoc && typeof shadowDoc === "object"
+      ? ((shadowDoc as { state?: Record<string, unknown> }).state ?? null)
+      : null;
+  return exprs.map(({ id, node }) => {
+    const values = new Map<string, string>();
+    // A fresh scope per expression: a mutating operator writes into this clone only, and can never
+    // Leak into the next expression's evaluation (or the live canvas).
+    let scope: Scope;
+    try {
+      scope = bindRepeaterContext(cloneLiveScope(defs, rawState), shadowDoc, contextPath);
+    } catch (error) {
+      return { error: error instanceof Error ? error.message : String(error), id, values: [] };
+    }
+    try {
+      if (!node || typeof node !== "object" || !("operator" in node)) {
+        throw new Error("not an expression node");
+      }
+      evaluateExpression(node as ExpressionNode, scope, null, undefined, {
+        report: (path, value) => values.set(path.join("/"), formatPreviewValue(value)),
+      });
+      return { id, values: [...values.entries()] };
+    } catch (error) {
+      return {
+        error: error instanceof Error ? error.message : String(error),
+        id,
+        values: [...values.entries()],
+      };
+    }
+  });
+}