@jxsuite/studio 0.32.0 → 0.34.0

package/src/tabs/tab.ts

@@ -16,6 +16,12 @@ import type { JxDocOp } from "./patch-ops";
 export interface TabUi {
   rightTab: string;
   canvasMode: string;
+  /** Preview toggle — composes with an edit/design canvasMode; the effective mode becomes "preview". */
+  preview: boolean;
+  /** Show elements inherited from the page's layout (pages with an effective layout only). */
+  showLayout: boolean;
+  /** Chosen literal values for dynamic route params (e.g. { sku: "mini-trencher" }). */
+  previewParams: Record<string, string>;
   zoom: number;
   activeMedia: string | null;
   activeSelector: string | null;
@@ -79,7 +85,10 @@ export interface Tab {
     ui: TabUi;
     canvas: {
       status: string;
-      scope: { stop: () => void; [k: string]: unknown } | null;
+      // A serializable snapshot of the iframe's resolved `$defs` (data-source values), posted over
+      // The bridge as a `dataScope` message and read by the data-explorer panel. Plain data now —
+      // The old live `EffectScope` (with `.stop()`) moved into the iframe realm with buildScope.
+      scope: Record<string, unknown> | null;
       error: string | null;
       pendingInlineEdit: InlineEditDef | null;
     };
@@ -92,9 +101,10 @@ export interface Tab {
 
 /**
  * @param {string} canvasMode — initial canvas mode (the tab's first allowed mode)
+ * @param {boolean} preview — initial preview-toggle state
  * @returns {TabUi}
  */
-function createDefaultUi(canvasMode: string) {
+function createDefaultUi(canvasMode: string, preview = false) {
   return {
     activeMedia: null,
     activeSelector: null,
@@ -109,8 +119,11 @@ function createDefaultUi(canvasMode: string) {
     gitStatus: null,
     inspectorSections: {},
     pendingInlineEdit: null,
+    preview,
+    previewParams: {},
     rightTab: "properties",
     settingsTab: "stylebook",
+    showLayout: true,
     styleFilter: "",
     styleFilterActive: false,
     styleSections: {},
@@ -165,7 +178,10 @@ export function createTab({
   const resolvedModes = capabilities?.modes ?? inferModes(documentPath, sourceFormat);
   // A tab opens in its first allowed mode — never one the toolbar would disable.
   // Formats author mode order so the default comes first (edit, stylebook, etc.).
-  const initialCanvasMode = resolvedModes[0] ?? "edit";
+  // "preview" is a per-tab toggle rather than a base mode: a preview-first format opens
+  // In its first non-preview mode with the toggle already on.
+  const initialCanvasMode = resolvedModes.find((m) => m !== "preview") ?? "edit";
+  const initialPreview = resolvedModes[0] === "preview";
 
   const tab = scope.run(() => ({
     capabilities: { modes: resolvedModes },
@@ -196,7 +212,7 @@ export function createTab({
       documentStack: [],
       hover: null,
       selection: null,
-      ui: createDefaultUi(initialCanvasMode),
+      ui: createDefaultUi(initialCanvasMode, initialPreview),
     }),
   })) as unknown as Tab;
 
@@ -204,6 +220,9 @@ export function createTab({
 }
 
 /**
+ * Allowed modes for a document. "preview" in a format's mode list means the preview toggle is
+ * Available for the tab (it is not a base canvas mode the toolbar switches to).
+ *
  * @param {string | null | undefined} documentPath
  * @param {string | null} sourceFormat
  * @returns {string[]}

package/src/tabs/transact.ts

@@ -2,6 +2,7 @@
 import { toRaw } from "../reactivity";
 import { jsonClone } from "../utils/studio-utils";
 import { childIndex, getNodeAtPath, isAncestor, parentElementPath, pathsEqual } from "../state";
+import { applyDocOpToDoc, childArray, cloneValue } from "./doc-op-apply";
 import {
   beginRecording,
   endRecording,
@@ -33,11 +34,6 @@ function patchHistoryEnabled() {
   }
 }
 
-/** Deep-clone a recorded value (undefined passes through; reactive proxies are read through). */
-function cloneValue<T>(v: T): T {
-  return v === undefined || v === null ? v : (jsonClone(v as object) as T);
-}
-
 /** Forward/inverse pair for a single-key change on the node at path. */
 function setKeyPair(path: JxPath, key: string, before: unknown, after: unknown): JxDocOpPair {
   return {
@@ -81,20 +77,6 @@ export type JxNodeValue =
   | JxEventBinding
   | undefined;
 
-/**
- * The editable children array of a node, created when absent. Mapped-array children (`$prototype:
- * "Array"`) cannot be index-mutated — fail loudly instead of corrupting.
- */
-function childArray(node: JxMutableNode): (JxMutableNode | string)[] {
-  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;
-}
-
 // ─── Transactional layer ─────────────────────────────────────────────────────
 
 /**
@@ -146,7 +128,7 @@ export function transactDoc(
 
   if (verdict.patchable) {
     try {
-      consumer!.apply(tab, record.ops);
+      consumer!.apply(tab, record.ops, record);
     } catch (error) {
       consumer!.escalate(
         `patch-apply-failed: ${error instanceof Error ? error.message : String(error)}`,
@@ -154,7 +136,7 @@ export function transactDoc(
     }
   }
 
-  if (!skipHistory) {
+  if (!skipHistory && !_batchTab) {
     pushHistoryEntry(tab, raw, record, selectionBefore);
   }
 
@@ -248,54 +230,6 @@ export function transact(
 /** Document-level keys whose changes require a full scope/panel rebuild on the canvas. */
 const DOC_META_KEYS = new Set(["state", "$media", "$head", "$elements", "imports", "$layout"]);
 
-/**
- * Apply a replayable doc op to a bare document tree (history replay — no canvas recording).
- *
- * @param {JxMutableNode} doc
- * @param {JxDocOp} op
- */
-function applyDocOpToDoc(doc: JxMutableNode, op: JxDocOp) {
-  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("/")}`);
-      }
-      if (op.value === undefined) {
-        delete node[op.key];
-      } else {
-        node[op.key] = cloneValue(op.value) as JxNodeValue;
-      }
-      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}`);
-    }
-  }
-}
-
 /**
  * Apply a doc op to the live document AND record the matching canvas patch op, so undo/redo
  * transactions patch the canvas surgically like any other edit.
@@ -351,6 +285,36 @@ function applyDocOp(tab: Tab, op: JxDocOp) {
   }
 }
 
+// ─── Batch (group multiple mutations into one undo step) ────────────────────
+
+let _batchTab: Tab | null = null;
+
+export function beginBatch(tab: Tab | null) {
+  _batchTab = tab;
+}
+
+export function endBatch() {
+  if (_batchTab) {
+    const raw = toRaw(_batchTab.doc.document);
+    const snapshot = {
+      document: jsonClone(raw),
+      selection: _batchTab.session.selection ? [..._batchTab.session.selection] : null,
+    };
+    const truncated = _batchTab.history.snapshots.slice(0, _batchTab.history.index + 1);
+    truncated.push(snapshot);
+    if (truncated.length > HISTORY_LIMIT) {
+      truncated.shift();
+    }
+    _batchTab.history.snapshots = truncated;
+    _batchTab.history.index = truncated.length - 1;
+  }
+  _batchTab = null;
+}
+
+export function isBatching(): boolean {
+  return _batchTab !== null;
+}
+
 // ─── Undo / Redo ─────────────────────────────────────────────────────────────
 
 /** Restore a materialized snapshot state (full-render path). */

package/src/types.ts

@@ -126,6 +126,13 @@ export interface RenameResult {
 export interface StudioPlatform {
   id: string;
   projectRoot: string;
+  /**
+   * URL of the canvas iframe document. Optional: when set (chromium serves it from the project
+   * server under the studio namespace), the iframe host uses it; otherwise the host falls back to
+   * the default dev-server path. Not keyed on `id` — chromium and electrobun both report `id:
+   * "desktop"`, but only chromium sets this.
+   */
+  canvasUrl?: string;
   activate: (root?: string) => Promise<void>;
   openProject: () => Promise<{
     config: ProjectConfig;
@@ -190,6 +197,13 @@ export interface StudioPlatform {
   /** Invoke a format capability (parse/serialize) — { format, action, source?, doc?, options? }. */
   formatAction?: (payload: Record<string, unknown>) => Promise<unknown>;
   fetchPluginSchema: (src: string, prototype?: string, base?: string) => Promise<unknown>;
+  /**
+   * Resolve a class-prototype config through the backend's `/__jx_resolve__` pipeline (with the
+   * project's content types loaded) and return the parsed result. Used by the tab-bar's dynamic
+   * route-param picker to enumerate ContentCollection entries. Optional: platforms without a
+   * resolve backend omit it and the picker falls back to a plain fetch.
+   */
+  resolveClass?: (body: Record<string, unknown>) => Promise<unknown>;
   gitStatus: () => Promise<GitStatusResult>;
   gitBranches: () => Promise<GitBranchesResult>;
   gitLog: (limit?: number) => Promise<GitLogEntry[]>;
@@ -214,12 +228,8 @@ export interface StudioPlatform {
     adapter?: string;
     directory: string;
   }) => Promise<{ root: string; config: ProjectConfig }>;
-  aiAuthStatus: () => Promise<{ authenticated: boolean; error?: string }>;
-  aiCreateSession: (opts: { message: string; systemPrompt?: string }) => Promise<{ id: string }>;
-  aiSendMessage: (id: string, message: string) => Promise<void>;
-  aiStreamUrl: (id: string) => string | Promise<string>;
-  aiStopSession: (id: string) => Promise<void>;
-  aiDeleteSession: (id: string) => Promise<void>;
+  /** Stack B AI assistant: URL of the OpenAI-compatible SSE chat proxy (`/__studio/ai/chat`). */
+  aiChatUrl: () => string | Promise<string>;
   // ─── Multi-window (desktop only; undefined on dev-server) ───────────────────
   /** Open a project in a new window, focusing an existing window if it is already open. */
   openProjectInNewWindow?: (root: string) => Promise<void>;
@@ -256,18 +266,11 @@ export interface CanvasPanel {
   mediaName: string;
   element: HTMLElement;
   canvas: HTMLElement;
-  overlay: HTMLElement;
-  overlayClk: HTMLElement;
   viewport: HTMLElement;
   scrollContainer: HTMLElement;
-  dropLine: HTMLElement;
   _width: number | null;
   /** True when the panel's DOM reflects the current document via a successful live render. */
   ready: boolean;
-  /** Breakpoints active for this panel's width (persisted for surgical patch re-application). */
-  activeBreakpoints: Set<string> | null;
-  /** Render context captured from the last successful live render (null until then). */
-  liveCtx: PanelLiveCtx | null;
   /**
    * Effect scope owning the reactive effects created while rendering this panel's content
    * (including child scopes from surgical subtree renders). Stopped when panels are rebuilt.
@@ -275,17 +278,6 @@ export interface CanvasPanel {
   renderScope: { stop: () => void; run: <T>(fn: () => T) => T | undefined } | null;
 }
 
-/** Per-panel context persisted by a successful live render so patches can re-render subtrees. */
-export interface PanelLiveCtx {
-  scope: Record<string, unknown>;
-  canvasMode: string;
-  layoutWrapped: boolean;
-  pageContentPrefix: (string | number)[] | null;
-  pageContentOffset: number;
-  arrayPaths: Set<string>;
-  pathMapper: (created: Node, path: (string | number)[], def: unknown) => void;
-}
-
 export interface DocumentStackEntry {
   document: JxMutableNode;
   documentPath: string | null;

package/src/ui/jx-theme.ts

@@ -0,0 +1,63 @@
+/**
+ * Jx brand theme fragment.
+ *
+ * Registered as the Spectrum 'app' fragment (see spectrum.ts), so it is adopted into every
+ * <sp-theme> shadow root _after_ the system/color/scale fragments and wins the :host cascade. It
+ * rebrands the stock Spectrum dark theme by overriding only the palette `-rgb` triplets: every
+ * derived token in the published theme CSS (accent, focus ring, background layers, alpha-composed
+ * tints) resolves through `rgba(var(--spectrum-*-rgb))`, so the whole theme follows coherently.
+ *
+ * Canonical brand values: sites/jxsuite.com/project.json (accent #3b82f6, accent-hover #60a5fa,
+ * neutral surfaces #0a0a0a / #111111 / #1a1a1a / #222222). Intermediate stops interpolate along the
+ * Tailwind blue/zinc ramps the brand palette derives from.
+ *
+ * Dark-theme stop order: gray 50 (darkest) -> 900 (lightest); blue 100 (darkest) -> 1400
+ * (lightest). Semantic anchors under this ramp:
+ *
+ * - Accent button fill = accent-500 (white text ~5.2:1)
+ * - Focus ring = blue-800 (brand accent-hover)
+ * - Studio --accent = accent-700 (exact brand blue)
+ * - Accent content/visual = accent-900 (soft on-dark tint)
+ */
+
+import { css } from "@spectrum-web-components/base";
+
+export const jxTheme = css`
+  :host {
+    /* Neutral (gray) ramp — Jx near-black surfaces and zinc text tones */
+    --spectrum-gray-50-rgb: 10, 10, 10; /* #0a0a0a bg-primary / base */
+    --spectrum-gray-75-rgb: 17, 17, 17; /* #111111 bg-secondary / layer-1 */
+    --spectrum-gray-100-rgb: 26, 26, 26; /* #1a1a1a surface / layer-2 */
+    --spectrum-gray-200-rgb: 34, 34, 34; /* #222222 border / surface-hover */
+    --spectrum-gray-300-rgb: 63, 63, 70; /* #3f3f46 strong border */
+    --spectrum-gray-400-rgb: 82, 82, 91; /* #52525b component border */
+    --spectrum-gray-500-rgb: 113, 113, 122; /* #71717a text-muted */
+    --spectrum-gray-600-rgb: 161, 161, 170; /* #a1a1aa text-secondary */
+    --spectrum-gray-700-rgb: 212, 212, 216; /* #d4d4d8 subtle text */
+    --spectrum-gray-800-rgb: 228, 228, 231; /* #e4e4e7 primary text */
+    --spectrum-gray-900-rgb: 250, 250, 250; /* #fafafa ink / headings */
+
+    /* Blue ramp — drives accent, informative, and the focus indicator */
+    --spectrum-blue-100-rgb: 23, 37, 84; /* #172554 */
+    --spectrum-blue-200-rgb: 30, 58, 138; /* #1e3a8a */
+    --spectrum-blue-300-rgb: 30, 64, 175; /* #1e40af */
+    --spectrum-blue-400-rgb: 29, 78, 216; /* #1d4ed8 */
+    --spectrum-blue-500-rgb: 37, 99, 235; /* #2563eb accent button fill */
+    --spectrum-blue-600-rgb: 48, 112, 241; /* #3070f1 */
+    --spectrum-blue-700-rgb: 59, 130, 246; /* #3b82f6 brand accent */
+    --spectrum-blue-800-rgb: 96, 165, 250; /* #60a5fa accent-hover / focus */
+    --spectrum-blue-900-rgb: 147, 197, 253; /* #93c5fd soft on-dark accent */
+    --spectrum-blue-1000-rgb: 191, 219, 254; /* #bfdbfe */
+    --spectrum-blue-1100-rgb: 219, 234, 254; /* #dbeafe */
+    --spectrum-blue-1200-rgb: 239, 246, 255; /* #eff6ff */
+    --spectrum-blue-1300-rgb: 248, 250, 252; /* #f8fafc */
+    --spectrum-blue-1400-rgb: 255, 255, 255; /* #ffffff */
+
+    /* Brand font stacks. Sans drops adobe-clean so Adobe Clean never renders
+       on machines that have it installed; mono leads with the vendored
+       JetBrains Mono (see index.html @font-face). */
+    --spectrum-sans-font-family-stack: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+    --spectrum-code-font-family-stack:
+      "JetBrains Mono", "SF Mono", Consolas, "Liberation Mono", Menlo, monospace;
+  }
+`;

package/src/ui/media-picker.ts

@@ -12,6 +12,8 @@ import { ref } from "lit-html/directives/ref.js";
 import { getPlatform } from "../platform";
 import { debouncedStyleCommit, renderOnly } from "../store";
 import { getLayerSlot } from "./layers";
+import { rectOf } from "../utils/geometry";
+import { loopbackAssetSrc } from "../canvas/canvas-origin";
 
 // ─── Media file cache ────────────────────────────────────────────────────────
 
@@ -142,7 +144,7 @@ function onPopoverOutsideClick(e: MouseEvent) {
 
 function renderMediaPickerPopover() {
   const host = getLayerSlot("popover", "media-picker");
-  const rect = _popoverAnchorEl?.getBoundingClientRect();
+  const rect = _popoverAnchorEl ? rectOf(_popoverAnchorEl) : undefined;
   if (!rect) {
     return;
   }
@@ -210,7 +212,7 @@ function renderMediaPickerPopover() {
                     ${m.isImage
                       ? html`<img
                           slot="icon"
-                          src=${m.path}
+                          src=${loopbackAssetSrc(m.path)}
                           alt=""
                           style="width:24px;height:24px;object-fit:cover;border-radius:var(--spectrum-corner-radius-75, 2px)"
                         />`
@@ -232,7 +234,7 @@ function renderMediaPickerPopover() {
   // Fine-tune position after render using actual measured dimensions
   requestAnimationFrame(() => {
     if (_popoverEl) {
-      const popoverRect = _popoverEl.getBoundingClientRect();
+      const popoverRect = rectOf(_popoverEl);
       let adjLeft = popoverRect.left;
       let adjTop = popoverRect.top;
       let needsAdjust = false;
@@ -304,7 +306,7 @@ export function renderMediaPicker(prop: string, value: string, onCommit: (val: s
   return html`
     <div class="media-picker">
       ${isImage && currentValue
-        ? html`<img class="media-picker-thumb" src=${currentValue} alt="" />`
+        ? html`<img class="media-picker-thumb" src=${loopbackAssetSrc(currentValue)} alt="" />`
         : nothing}
       <sp-textfield
         size="s"

package/src/ui/spectrum.ts

@@ -11,6 +11,7 @@ import { Theme } from "@spectrum-web-components/theme/src/Theme.js";
 import themeSpectrumCSS from "@spectrum-web-components/theme/src/theme.css.js";
 import themeDarkCSS from "@spectrum-web-components/theme/src/theme-dark.css.js";
 import scaleMediumCSS from "@spectrum-web-components/theme/src/scale-medium.css.js";
+import { jxTheme } from "./jx-theme";
 import { Tabs } from "@spectrum-web-components/tabs/src/Tabs.js";
 import { Tab } from "@spectrum-web-components/tabs/src/Tab.js";
 import { TabPanel } from "@spectrum-web-components/tabs/src/TabPanel.js";
@@ -296,5 +297,9 @@ for (const [tag, ctor] of components as [string, CustomElementConstructor][]) {
 Theme.registerThemeFragment("spectrum", "system", themeSpectrumCSS);
 Theme.registerThemeFragment("dark", "color", themeDarkCSS);
 Theme.registerThemeFragment("medium", "scale", scaleMediumCSS);
+/* Jx brand overrides. The 'app' kind must be registered under the literal
+   name "app" and, registered last, is adopted after the fragments above so
+   its :host declarations win the cascade (see src/ui/jx-theme.ts). */
+Theme.registerThemeFragment("app", "app", jxTheme);
 
 export { components };

package/src/utils/canvas-media.ts

@@ -2,8 +2,6 @@
 /// <reference lib="dom.iterable" />
 /** Canvas media/breakpoint utilities — pure functions extracted for testability. */
 
-import type { JxStyle } from "@jxsuite/schema/types";
-
 /**
  * Classify $media entries into size breakpoints (get a canvas each) and feature queries (rendered
  * as toolbar toggles).
@@ -63,138 +61,3 @@ export function activeBreakpointsForWidth(
   }
   return active;
 }
-
-/**
- * Apply styles to a canvas element, including active media overrides. Base (flat) styles applied
- * first, then matching media overrides in source order.
- *
- * @param {HTMLElement} el
- * @param {JxStyle | null | undefined} styleDef
- * @param {Set<string>} activeBreakpoints
- * @param {Record<string, boolean>} featureToggles
- */
-export function applyCanvasStyle(
-  el: HTMLElement,
-  styleDef: JxStyle | null | undefined,
-  activeBreakpoints: Set<string>,
-  featureToggles: Record<string, boolean>,
-) {
-  if (!styleDef || typeof styleDef !== "object") {
-    return;
-  }
-  for (const [prop, val] of Object.entries(styleDef)) {
-    if (typeof val === "string" || typeof val === "number") {
-      try {
-        if (prop.startsWith("--")) {
-          el.style.setProperty(prop, String(val));
-        } else {
-          (el.style as unknown as Record<string, unknown>)[prop] = val;
-        }
-      } catch {}
-    }
-  }
-  for (const [key, val] of Object.entries(styleDef)) {
-    if (!key.startsWith("@") || typeof val !== "object" || val === null) {
-      continue;
-    }
-    const mediaName = key.slice(1);
-    if (mediaName === "--") {
-      continue;
-    }
-    if (activeBreakpoints.has(mediaName) || featureToggles[mediaName]) {
-      for (const [prop, v] of Object.entries(/** @type {Record<string, unknown>} */ val)) {
-        if (typeof v === "string" || typeof v === "number") {
-          try {
-            if (prop.startsWith("--")) {
-              el.style.setProperty(prop, String(v));
-            } else {
-              (el.style as unknown as Record<string, unknown>)[prop] = v;
-            }
-          } catch {}
-        }
-      }
-    }
-  }
-}
-
-/**
- * Scan stylesheets for @media rules matching active breakpoints, collecting the CSS declarations
- * that should be applied as inline overrides per data-jx element.
- *
- * Returns a Map of data-jx uid → Map of CSS property → value.
- *
- * @param {Iterable<CSSStyleSheet>} styleSheets
- * @param {Set<string>} activeBreakpoints
- * @returns {Map<string, Map<string, string>>}
- */
-export function collectMediaOverrides(
-  styleSheets: Iterable<CSSStyleSheet>,
-  activeBreakpoints: Set<string>,
-) {
-  const overrides = new Map<string, Map<string, string>>();
-  if (activeBreakpoints.size === 0) {
-    return overrides;
-  }
-
-  for (const sheet of styleSheets) {
-    /** @type {CSSRuleList | null} */
-    let rules;
-    try {
-      rules = sheet.cssRules;
-    } catch {
-      continue;
-    }
-    if (!rules) {
-      continue;
-    }
-    for (const rule of rules) {
-      if (!(rule instanceof CSSMediaRule)) {
-        continue;
-      }
-      if (!activeBreakpoints.has(rule.conditionText)) {
-        continue;
-      }
-      for (const mediaRule of rule.cssRules) {
-        if (!(mediaRule instanceof CSSStyleRule)) {
-          continue;
-        }
-        const selector = mediaRule.selectorText;
-        const jxMatch = selector.match(/\[data-jx="([^"]+)"\]/);
-        if (!jxMatch) {
-          continue;
-        }
-        const [, uid] = jxMatch;
-        if (!overrides.has(uid!)) {
-          overrides.set(uid!, new Map());
-        }
-        const props = overrides.get(uid!) as Map<string, string>;
-        for (const prop of mediaRule.style) {
-          props.set(prop, mediaRule.style.getPropertyValue(prop));
-        }
-      }
-    }
-  }
-  return overrides;
-}
-
-/**
- * Apply collected media overrides to elements within a canvas.
- *
- * @param {Element} canvasEl
- * @param {Map<string, Map<string, string>>} overrides
- */
-export function applyOverridesToCanvas(
-  canvasEl: Element,
-  overrides: Map<string, Map<string, string>>,
-) {
-  for (const [uid, props] of overrides) {
-    const els = canvasEl.querySelectorAll(`[data-jx="${uid}"]`);
-    for (const el of els) {
-      for (const [prop, val] of props) {
-        try {
-          (el as HTMLElement).style.setProperty(prop, val);
-        } catch {}
-      }
-    }
-  }
-}

package/src/utils/edit-display.ts

@@ -10,6 +10,19 @@ import type { JxMutableNode } from "@jxsuite/schema/types";
 const mediaTags = new Set(["img", "video", "source", "iframe", "audio"]);
 const TRANSPARENT_PX =
   "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";
+// A neutral, visible gray placeholder for image-like bindings in edit mode (e.g. a component `image`
+// Prop bound to ${...}). The component renders <img src={prop}> internally, so a transparent pixel
+// Would collapse to nothing — a gray SVG box reads as an intentional placeholder instead.
+const PLACEHOLDER_IMG =
+  "data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20width='32'%20height='32'%3E%3Crect%20width='32'%20height='32'%20fill='%23d0d0d0'/%3E%3C/svg%3E";
+
+// Prop/attribute names that feed an <img>/background, so a ${...} binding would otherwise render a
+// Broken image in edit mode. Matched by exact name or common camelCase suffix (featuredImage, heroBg).
+const IMAGE_KEY_RE =
+  /(src|poster|image|bg|background|icon|logo|photo|avatar|thumbnail|cover|banner)$/i;
+function isImageUrlKey(key: string): boolean {
+  return IMAGE_KEY_RE.test(key);
+}
 
 const textTags = new Set([
   "p",
@@ -197,8 +210,15 @@ export function prepareForEditMode(node: JxMutableNode): JxMutableNode {
       const propsOut: Record<string, unknown> = {};
       for (const [pk, pv] of Object.entries(v)) {
         if (typeof pv === "string" && pv.includes("${")) {
-          const isUrlAttr = pk === "src" || pk === "href" || pk === "poster" || pk === "action";
-          propsOut[pk] = isUrlAttr ? "" : templateToEditDisplay(pv);
+          // Image-like prop → neutral placeholder (the component renders it as an <img src>); link
+          // Targets → inert ""; everything else → the readable ❪ expr ❫ binding text.
+          if (isImageUrlKey(pk)) {
+            propsOut[pk] = PLACEHOLDER_IMG;
+          } else if (pk === "href" || pk === "action") {
+            propsOut[pk] = "";
+          } else {
+            propsOut[pk] = templateToEditDisplay(pv);
+          }
         } else if (pv && typeof pv === "object" && (pv as Record<string, unknown>).$ref) {
           const ref = (pv as Record<string, unknown>).$ref as string;
           const label = ref.startsWith("#/state/") ? ref.slice(8) : ref;
@@ -238,7 +258,7 @@ export function prepareForEditMode(node: JxMutableNode): JxMutableNode {
                     border: "1px dashed color-mix(in srgb, var(--danger) 40%, transparent)",
                     borderRadius: "4px",
                     color: "var(--danger)",
-                    fontFamily: "'SF Mono', 'Fira Code', monospace",
+                    fontFamily: "'JetBrains Mono', 'SF Mono', 'Fira Code', monospace",
                     fontSize: "11px",
                     fontStyle: "italic",
                     padding: "6px 10px",

package/src/utils/geometry.ts

@@ -0,0 +1,43 @@
+/// <reference lib="dom" />
+/**
+ * Geometry read funnel — the single place the studio reads element bounds and does point hit-tests.
+ *
+ * Centralizing these reads is a seam for the iframe-canvas migration: today every call delegates
+ * straight to the DOM, but routing them through one module lets later phases redirect
+ * CANVAS-element geometry to rects posted out of the iframe (which the parent can't measure
+ * directly) without touching dozens of call sites. A test (`geometry.test.ts`) asserts no raw
+ * `getBoundingClientRect`/`elementFromPoint`/`elementsFromPoint` calls exist elsewhere in `src`.
+ */
+
+/** Bounding rect of an element, in viewport coordinates. */
+export function rectOf(el: Element): DOMRect {
+  return el.getBoundingClientRect();
+}
+
+/**
+ * Bounding rect of a Range, in viewport coordinates. Lives here (the one allowlisted home for
+ * `getBoundingClientRect`) so the `geometry.test.ts` textual guard passes — the iframe-side
+ * selection snapshot funnels its caret/selection geometry through this, never calling
+ * `range.getBoundingClientRect()` directly.
+ */
+export function rectOfRange(r: Range): DOMRect {
+  return r.getBoundingClientRect();
+}
+
+/** Topmost element at a viewport point, in `root` (defaults to the global document). */
+export function elementAtPoint(
+  x: number,
+  y: number,
+  root: Document | ShadowRoot = document,
+): Element | null {
+  return root.elementFromPoint(x, y);
+}
+
+/** All elements at a viewport point, front-to-back, in `root` (defaults to the global document). */
+export function elementsAtPoint(
+  x: number,
+  y: number,
+  root: Document | ShadowRoot = document,
+): Element[] {
+  return root.elementsFromPoint(x, y);
+}