@jxsuite/studio 1.0.0 → 1.2.0

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()],
+      };
+    }
+  });
+}

package/src/canvas/iframe-host.ts

@@ -12,6 +12,7 @@ import { canvasBaseOrigin } from "./canvas-origin";
 import { resolveCanvasDocument } from "./canvas-live-render";
 import {
   applyInlineCommit,
+  applyInlinePropCommit,
   applyInlineInsert,
   applyInlineSplit,
 } from "../editor/inline-edit-apply";
@@ -23,7 +24,15 @@ import { clearDragGhost, moveDragGhost } from "../panels/drag-ghost";
 import { applyDropInstruction } from "../panels/dnd";
 import { rectOf } from "../utils/geometry";
 import { effect, effectScope } from "../reactivity";
-import { canvasPanels, canvasWrap, pathsEqual, renderOnly, updateCanvas, updateUi } from "../store";
+import {
+  canvasPanels,
+  canvasWrap,
+  pathsEqual,
+  projectState,
+  renderOnly,
+  updateCanvas,
+  updateUi,
+} from "../store";
 import { activeTab, workspace } from "../workspace/workspace";
 import { collabState } from "../collab/collab-state";
 import { getPlatform, hasPlatform } from "../platform";
@@ -31,6 +40,7 @@ import type {
   ApplyFormatIntent,
   CanvasMode,
   DragSrcKind,
+  EvalExprResult,
   IframeToParent,
   InsertZone,
   NodeHit,
@@ -43,13 +53,15 @@ import type { IframeChannel } from "./iframe-channel";
 import type { OverlayLayer, OverlayPlacement } from "./iframe-overlay";
 import type { SlashCommand } from "../editor/inline-edit";
 import type { Tab } from "../tabs/tab";
-import type { JxMutableNode } from "@jxsuite/schema/types";
+import type { JxExpressionNode, JxMutableNode } from "@jxsuite/schema/types";
 
 /** A rect in PARENT coordinates (overlay-local from {@link canvasRectToParent}, same field shape). */
 type ParentRect = OverlayPlacement;
 
 interface HostState {
   iframe: HTMLIFrameElement;
+  /** The `.canvas-panel-canvas` element hosting the iframe + overlay (the WeakMap key). */
+  canvasEl: HTMLElement;
   channel: IframeChannel<ParentToIframe, IframeToParent>;
   /**
    * The resolved canvasUrl this iframe was built with — so a host built early with the default URL
@@ -70,6 +82,8 @@ interface HostState {
   presenceMeta: Map<string, { color: string; label: string }>;
   /** Whether an inline-edit session is live in this host's iframe (drives the format toolbar). */
   editing: boolean;
+  /** The prop a live plain session edits (prop-bound text) — null for rich sessions/none. */
+  editingProp: string | null;
   /** The latest selection snapshot from this host's iframe (active tags + caret rect + link). */
   snapshot: SelectionSnapshot | null;
   /** Highest snapshot `seq` seen, so stale (re-ordered) snapshots are dropped. */
@@ -176,6 +190,72 @@ export function sawIframeDragOver(seq: number): boolean {
   );
 }
 
+// ─── Live expression preview (M6) ───────────────────────────────────────────────
+// The parent asks a live iframe to evaluate expression nodes against its LIVE resolved scope and
+// Correlates the `evalResult` reply by reqId (the measure/geometry precedent), gen-gating it so a
+// Reply computed against a superseded render never paints badges.
+
+/** Monotonic eval request id (shared across hosts; stale replies carry an older/unknown id). */
+let evalReqId = 0;
+
+/** Pending eval resolvers keyed by reqId; a timeout or stale reply resolves null. */
+const pendingEvals = new Map<number, (results: EvalExprResult[] | null) => void>();
+
+/** How long (ms) the parent waits for an `evalResult` before falling back to the snapshot. */
+export const EVAL_TIMEOUT_MS = 300;
+
+/**
+ * Post an `evalExpr` request to the live, ready iframe host rendering `tabId`'s document and
+ * resolve with its results. Resolves `null` when no such host exists (caller falls back to the
+ * snapshot evaluator immediately), when no reply lands within `timeoutMs`, or when the reply's gen
+ * shows it was computed against a superseded render.
+ */
+export function requestCanvasEval(
+  tabId: string | null,
+  exprs: { id: string; node: unknown }[],
+  contextPath: (string | number)[] | null,
+  timeoutMs: number = EVAL_TIMEOUT_MS,
+): Promise<EvalExprResult[] | null> {
+  let target: HostState | null = null;
+  for (const host of liveHosts) {
+    if (!host.iframe.isConnected) {
+      liveHosts.delete(host);
+      continue;
+    }
+    // Only a document host can answer (never a stylebook specimen catalog or a null-tab override
+    // Doc like git-diff), and only the one whose iframe DOM reflects this tab's document.
+    if (host.ready && !host.stylebook && tabId !== null && host.tabId === tabId) {
+      target = host;
+      break;
+    }
+  }
+  if (!target) {
+    return Promise.resolve(null);
+  }
+  evalReqId += 1;
+  const reqId = evalReqId;
+  // Expression nodes come off the reactive document — only plain values may cross postMessage.
+  // oxlint-disable-next-line unicorn/prefer-structured-clone
+  const wireExprs = JSON.parse(JSON.stringify(exprs)) as { id: string; node: JxExpressionNode }[];
+  target.channel.post({
+    contextPath: contextPath ? [...contextPath] : null,
+    exprs: wireExprs,
+    gen: target.lastRenderedGen,
+    kind: "evalExpr",
+    reqId,
+  });
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      pendingEvals.delete(reqId);
+      resolve(null);
+    }, timeoutMs);
+    pendingEvals.set(reqId, (results) => {
+      clearTimeout(timer);
+      resolve(results);
+    });
+  });
+}
+
 /** The host backing a given canvas element (or null), for the coordinator's host resolution. */
 export function hostForCanvas(canvasEl: HTMLElement): HostState | null {
   return hosts.get(canvasEl) ?? null;
@@ -263,6 +343,25 @@ export function hostDragGeometry(host: HostState): {
   return { rect, scale };
 }
 
+/**
+ * Pin the `.canvas-panel-viewport` (the white "page" surface, the canvas element's parent) to the
+ * SCALED content height when edit-mode content zoom is active. A `transform: scale()` on the canvas
+ * element rescales its painted box but never its ancestor's auto-height, so without this write the
+ * viewport background would stay sized to the UN-zoomed iframe height. The scale is read from the
+ * canvas element's own inline transform (written only by `applyEditZoom`) — NOT from
+ * {@link hostDragGeometry}, whose empirical ratio also reflects design mode's panzoom-wrap
+ * transform, where the viewport must keep its unscaled auto height.
+ */
+function syncEditZoomViewportHeight(state: HostState): void {
+  const viewport = state.canvasEl.parentElement;
+  if (!viewport) {
+    return;
+  }
+  const match = /scale\(([\d.]+)\)/.exec(state.canvasEl.style.transform);
+  const scale = match ? Number(match[1]!) : 1;
+  viewport.style.height = scale === 1 ? "" : `${state.iframe.offsetHeight * scale}px`;
+}
+
 /** Post a parent→iframe drag message to `host`'s channel (the coordinator builds it purely). */
 export function postDragMessage(host: HostState, msg: ParentToIframe): void {
   if (!host.iframe.isConnected) {
@@ -662,9 +761,11 @@ function ensureHost(canvasEl: HTMLElement): HostState {
   });
 
   const state: HostState = {
+    canvasEl,
     canvasUrl,
     channel,
     editing: false,
+    editingProp: null,
     iframe,
     insertHideTimer: null,
     insertZone: null,
@@ -875,6 +976,18 @@ function handleMessage(state: HostState, msg: IframeToParent): void {
       }
       return;
     }
+    case "evalResult": {
+      // A live expression-preview reply (M6). Resolve the pending request by reqId (unknown ids —
+      // Already timed out or from a torn-down request — are dropped), gen-gating it so values
+      // Computed against a superseded render resolve null (the caller keeps the snapshot preview).
+      const resolve = pendingEvals.get(msg.reqId);
+      if (!resolve) {
+        return;
+      }
+      pendingEvals.delete(msg.reqId);
+      resolve(msg.gen === state.lastRenderedGen ? msg.results : null);
+      return;
+    }
     case "renderComplete": {
       // Adopt the tab identity this render was mounted with. host.tabId flips ONLY here — after any
       // Edit-session commit the iframe posted ahead of this ack on the FIFO channel — so a commit
@@ -922,6 +1035,7 @@ function handleMessage(state: HostState, msg: IframeToParent): void {
       // Component leaves dead space below — pages keep the floor and stay tall via #jx-canvas-root).
       state.iframe.style.height = `${msg.height}px`;
       state.iframe.style.minHeight = msg.fragment ? "0px" : "480px";
+      syncEditZoomViewportHeight(state);
       return;
     }
     case "dragOver": {
@@ -1025,10 +1139,12 @@ function handleMessage(state: HostState, msg: IframeToParent): void {
       // Tear down any other host's editing state and make this the single active edit host.
       if (activeEditHost && activeEditHost !== state) {
         activeEditHost.editing = false;
+        activeEditHost.editingProp = null;
         activeEditHost.snapshot = null;
       }
       activeEditHost = state;
       state.editing = true;
+      state.editingProp = msg.prop ?? null;
       state.snapshot = null;
       state.lastSnapshotSeq = 0;
       toolbarRefresh?.();
@@ -1050,6 +1166,12 @@ function handleMessage(state: HostState, msg: IframeToParent): void {
       applyInlineCommit(hostTab(state), msg.path, msg.children, msg.textContent);
       return;
     }
+    case "editCommitProp": {
+      // A prop-bound plain session committed: persist into the instance's $props (same host-tab
+      // Routing as editCommit; the unchanged-value no-op lives in the apply).
+      applyInlinePropCommit(hostTab(state), msg.path, msg.prop, msg.value);
+      return;
+    }
     case "editSplit": {
       // The mutation lands now (surgical patch or escalated render); re-entry on the new paragraph
       // Is deferred until this host acks the DOM that contains it (see deferEnterEdit).
@@ -1109,6 +1231,7 @@ function handleMessage(state: HostState, msg: IframeToParent): void {
         return;
       }
       state.editing = false;
+      state.editingProp = null;
       state.snapshot = null;
       if (activeEditHost === state) {
         activeEditHost = null;
@@ -1255,6 +1378,7 @@ export async function mountIframeCanvas(
   // oxlint-disable-next-line unicorn/prefer-structured-clone
   const cloneableShadow = JSON.parse(JSON.stringify(doc)) as unknown;
   const message: ParentToIframe = {
+    colorScheme: activeSchemeWire(),
     doc: cloneableDoc,
     docBase: resolved.docBase ?? `${canvasBaseOrigin()}/`,
     gen,
@@ -1304,6 +1428,7 @@ export function mountStylebookCanvas(
   // oxlint-disable-next-line unicorn/prefer-structured-clone
   const cloneableShadow = JSON.parse(JSON.stringify(generated.doc)) as unknown;
   const message: ParentToIframe = {
+    colorScheme: activeSchemeWire(),
     doc: cloneableDoc,
     docBase: `${canvasBaseOrigin()}/`,
     gen,
@@ -1328,6 +1453,57 @@ export function mountStylebookCanvas(
   }
 }
 
+/** The active tab's forced preview scheme as wire data (auto → null). */
+function activeSchemeWire(): "light" | "dark" | null {
+  const s = activeTab.value?.session.ui.previewColorScheme;
+  return s === "light" || s === "dark" ? s : null;
+}
+
+/**
+ * Flip the color-scheme preview on every ready host (page and stylebook alike — both render
+ * scheme-aware CSS). A pure attribute write iframe-side: no render, no patch, no gen.
+ */
+export function postColorSchemeToLiveHosts(scheme: "light" | "dark" | null): void {
+  for (const host of liveHosts) {
+    if (!host.iframe.isConnected) {
+      liveHosts.delete(host);
+      continue;
+    }
+    if (host.ready) {
+      host.channel.post({ kind: "setColorScheme", scheme });
+    }
+  }
+}
+
+/**
+ * Push the project's current site style to every ready PAGE host as an in-place sheet replace (live
+ * design-token editing — stylebook hosts pre-merge site style into the specimen doc and are
+ * skipped). Render-free; the next full render carries the same style via its own siteStyle.
+ */
+export function postSiteStyleToLiveHosts(): void {
+  const config = projectState?.projectConfig;
+  if (!config) {
+    return;
+  }
+  // Site config comes off a reactive store — only plain values may cross postMessage.
+  // oxlint-disable-next-line unicorn/prefer-structured-clone
+  const siteStyle = JSON.parse(JSON.stringify(config.style ?? null)) as Record<
+    string,
+    unknown
+  > | null;
+  // oxlint-disable-next-line unicorn/prefer-structured-clone
+  const media = JSON.parse(JSON.stringify(config.$media ?? {})) as Record<string, string>;
+  for (const host of liveHosts) {
+    if (!host.iframe.isConnected) {
+      liveHosts.delete(host);
+      continue;
+    }
+    if (host.ready && !host.stylebook) {
+      host.channel.post({ kind: "siteStyleUpdate", media, siteStyle });
+    }
+  }
+}
+
 /**
  * Post a live style update to every ready stylebook host (gen-tagged per host so a stale update is
  * dropped iframe-side; the superseding render carries the same style). Returns how many hosts
@@ -1381,11 +1557,19 @@ export function getActiveEditHost(): HostState | null {
 }
 
 /** The current edit session's editing flag + latest selection snapshot, for the parent toolbar. */
-export function getEditSnapshot(): { editing: boolean; snapshot: SelectionSnapshot | null } {
+export function getEditSnapshot(): {
+  editing: boolean;
+  editingProp: string | null;
+  snapshot: SelectionSnapshot | null;
+} {
   if (!activeEditHost) {
-    return { editing: false, snapshot: null };
+    return { editing: false, editingProp: null, snapshot: null };
   }
-  return { editing: activeEditHost.editing, snapshot: activeEditHost.snapshot };
+  return {
+    editing: activeEditHost.editing,
+    editingProp: activeEditHost.editingProp,
+    snapshot: activeEditHost.snapshot,
+  };
 }
 
 /** Post an `applyFormat` intent to the active edit host's iframe (no-op when none/not ready). */
@@ -1423,7 +1607,10 @@ function hostForActivePanel(): HostState | null {
  * UNSCALED iframe-viewport px (D-2: the overlay draws them inside the scaled panzoom-wrap, so the
  * browser applies the zoom there); the fixed bar gets no such free ride, so scale by the live
  * empirical zoom ({@link hostDragGeometry}) and add the iframe's on-screen offset, whose GBCR
- * already bakes in pan + zoom + ancestor scroll. Edit mode has no transform → scale is 1.
+ * already bakes in pan + zoom + ancestor scroll. The empirical ratio covers BOTH scale sources:
+ * design mode's panzoom-wrap transform and edit mode's content-zoom counter-scale (where it
+ * evaluates to exactly `editZoom` — the iframe's layout width is `renderWidth / editZoom` while its
+ * rendered width is `renderWidth`).
  */
 export function getEditBarAnchorRect(): ParentRect | null {
   // The format toolbar follows the live caret/selection snapshot of the active edit session; the

package/src/canvas/iframe-inline-edit.ts

@@ -33,6 +33,7 @@ import { isTagActiveInSelection, toggleInlineFormat } from "../editor/inline-for
 import { applyLink, insertTemplateToken, linkStateForSelection } from "../editor/inline-link";
 import { restoreTemplateExpressions } from "../utils/edit-display";
 import { rectOfRange } from "../utils/geometry";
+import { getNodeAtPath } from "../state";
 import { parseJxPath, serializeJxPath } from "./path-mapping";
 import type { IframeChannel } from "./iframe-channel";
 import type {
@@ -43,6 +44,7 @@ import type {
   SerializableRect,
 } from "./iframe-protocol";
 import type { JxPath } from "../state";
+import type { JxMutableNode } from "@jxsuite/schema/types";
 
 /** Toolbar command → inline tag (mirrors the parent's old `cmdToTag`, now iframe-side). */
 const CMD_TO_TAG: Record<string, string> = {
@@ -74,6 +76,43 @@ function findEditableTarget(target: EventTarget | null): { el: HTMLElement; path
   return null;
 }
 
+/**
+ * Walk up from an event target to the nearest element carrying `data-jx-bound-prop` (a component-
+ * internal element whose text is an invertible prop binding — stamped by the runtime, see
+ * setStampPropBindings). Component internals are unstamped, so hitting a `data-jx-path` element
+ * first means the target sits in page-level DOM (or slotted content) — not a prop-bound target.
+ */
+function findPropBoundTarget(target: EventTarget | null): { el: HTMLElement; prop: string } | null {
+  let el = target instanceof Element ? target : null;
+  while (el) {
+    if (el instanceof HTMLElement) {
+      if (el.dataset.jxBoundProp) {
+        return { el, prop: el.dataset.jxBoundProp };
+      }
+      if (el.dataset.jxPath) {
+        return null;
+      }
+    }
+    el = el.parentElement;
+  }
+  return null;
+}
+
+/**
+ * The instance that owns a prop-bound element: its nearest custom-element ancestor (that element's
+ * connectedCallback rendered the marker with its state, so the walk can never skip the owner).
+ */
+function ownerInstanceOf(el: HTMLElement): HTMLElement | null {
+  let cur = el.parentElement;
+  while (cur) {
+    if (cur.tagName.includes("-")) {
+      return cur;
+    }
+    cur = cur.parentElement;
+  }
+  return null;
+}
+
 /** Locate the rendered element for a document path via its stamped `data-jx-path`. */
 function elementForPath(container: HTMLElement, path: JxPath): HTMLElement | null {
   const serialized = serializeJxPath(path);
@@ -95,7 +134,7 @@ function toSerializableRect(rect: DOMRect): SerializableRect {
 export function startIframeInlineEdit(
   channel: IframeChannel<IframeToParent, ParentToIframe>,
   container: HTMLElement,
-  opts?: { getMode?: () => string },
+  opts?: { getMode?: () => string; getShadowDoc?: () => JxMutableNode | null },
 ): () => void {
   const doc = container.ownerDocument;
 
@@ -251,6 +290,56 @@ export function startIframeInlineEdit(
     onSelectionChange();
   };
 
+  /**
+   * Whether the instance's RAW `$props[prop]` value (from the pre-edit-display shadow doc) is
+   * plain-text editable. Template-valued (`"${...}"`) and `$ref`-valued props render display sugar,
+   * not the value — committing typed text would silently destroy the binding, so they're blocked.
+   * An absent getShadowDoc is permissive (tests, same contract as getMode).
+   */
+  const propEditableAt = (hostPath: JxPath, prop: string): boolean => {
+    const shadowDoc = opts?.getShadowDoc?.();
+    if (!shadowDoc) {
+      return true;
+    }
+    const node = getNodeAtPath(shadowDoc, hostPath) as JxMutableNode | undefined;
+    const raw = (node?.$props as Record<string, unknown> | undefined)?.[prop];
+    if (raw == null) {
+      return true; // Unset — editing ADDS the prop, overriding the definition default.
+    }
+    if (typeof raw === "object") {
+      return false;
+    }
+    return !(typeof raw === "string" && raw.includes("${"));
+  };
+
+  /**
+   * Enter a plain (plaintext-only) session on a prop-bound component-internal element. The session
+   * path is the INSTANCE path — the marker element has no path of its own, and an external `$props`
+   * patch at the host path must disturb (commit + end) this session before detaching its element.
+   */
+  const enterPropEditAt = (el: HTMLElement, hostPath: JxPath, prop: string) => {
+    channel.post({ kind: "editStart", path: hostPath, prop });
+    suspendBlurClose();
+    startEditing(
+      el,
+      hostPath,
+      {
+        onCommit: (p, _children, textContent) =>
+          channel.post({ kind: "editCommitProp", path: p, prop, value: textContent ?? "" }),
+        onEnd: () => {
+          resumeBlurClose();
+          clearHighlight();
+          lastNonEmptyRange = null;
+          channel.post({ kind: "editEnd" });
+        },
+        // Prop values are single plain strings — no split, no slash-insert.
+        onInsert: () => {},
+        onSplit: () => {},
+      },
+      { plainText: true },
+    );
+  };
+
   /** Apply a format/link/insert intent to the iframe's cached selection range. */
   const applyFormatIntent = (intent: ApplyFormatIntent) => {
     const el = getActiveElement();
@@ -290,6 +379,23 @@ export function startIframeInlineEdit(
     if (!editingAllowed()) {
       return;
     }
+    // Prop-bound targets win: they sit in unstamped component internals, deeper than any editable
+    // Page block, and once a marker is hit the event must NOT fall through to rich editing (an
+    // Instance nested inside a page-level editable would otherwise rich-edit that whole ancestor).
+    const propHit = findPropBoundTarget(e.target);
+    if (propHit) {
+      const host = ownerInstanceOf(propHit.el);
+      const hostPathRaw = host?.dataset.jxPath;
+      if (host && hostPathRaw) {
+        const hostPath = parseJxPath(hostPathRaw);
+        if (propEditableAt(hostPath, propHit.prop)) {
+          enterPropEditAt(propHit.el, hostPath, propHit.prop);
+        }
+      }
+      // A path-less host is itself internal to another definition — its $props live in a document
+      // Not open in this tab, so there is no write-back target: blocked.
+      return;
+    }
     const hit = findEditableTarget(e.target);
     if (hit) {
       enterEditAt(hit.el, hit.path);