@jxsuite/studio 2.4.0 → 2.4.1

package/src/canvas/iframe-host.ts

@@ -38,6 +38,7 @@ import {
   tabOfContainer,
 } from "./canvas-surface";
 import { cloneSelection, primarySelection, toggleSelected } from "../tabs/selection";
+import { getNodeAtPath } from "../state";
 import type { JxPath } from "../state";
 import { setLayoutSelection, shell } from "../shell";
 import { formatEditableVerdicts } from "../format/constraints";
@@ -198,7 +199,13 @@ interface HostState {
    * render acks (`renderComplete`) at a bumped one — both satisfy `gen >= minGen`. An immediate
    * `enterEdit` would race the escalated ASYNC render and silently fail to find the element.
    */
-  pendingEnterEdit: { path: (string | number)[]; minGen: number; offset?: number } | null;
+  pendingEnterEdit: {
+    path: (string | number)[];
+    minGen: number;
+    offset?: number;
+    /** Set when the deferred re-entry is a PROP host rather than a block (see deferEnterEdit). */
+    prop?: string;
+  } | null;
   /**
    * Stylebook capability (set by {@link mountStylebookCanvas}, cleared by page mounts). The specimen
    * doc's paths decode to TAGS, not tab-document paths: hits route to the injected stylebook
@@ -1246,6 +1253,66 @@ function withEchoSuppressed(host: HostState, paths: (string | number)[][], fn: (
 }
 
 /** The tab whose document `state`'s iframe currently renders (null when unknown or closed). */
+/**
+ * Serialized path of an in-place prop commit whose patch was echo-suppressed, or null.
+ *
+ * One value rather than a set: a plain session edits exactly one prop of one instance at a time,
+ * and it is cleared on the release that follows.
+ */
+let propEchoPending: string | null = null;
+
+/**
+ * Serialized instance path whose release commit just transacted, so a `$props` patch rebuilding it
+ * is in flight. Read by the very next `editStart` and cleared there — the two messages arrive back
+ * to back when the user clicks from one prop slot to another in the same component.
+ */
+let propRebuildAt: string | null = null;
+
+/**
+ * Whether a release commit has to re-render the instance itself.
+ *
+ * Exported for its own test: the posting side ({@link postPatchToHosts}) needs a resolvable stage
+ * and is covered elsewhere, but the STATE MACHINE here is the part that was wrong, and it is three
+ * conditions that have to agree — the release must have declined to transact, an in-place commit
+ * must have been suppressed, and it must have been for this same instance.
+ *
+ * @param {boolean} transacted - Whether the release commit wrote to the document.
+ * @param {string | null} pending - Serialized path of a suppressed in-place commit, if any.
+ * @param {string} path - Serialized path of the instance being released.
+ * @returns {boolean}
+ */
+export function needsReleaseReconcile(
+  transacted: boolean,
+  pending: string | null,
+  path: string,
+): boolean {
+  return !transacted && pending === path;
+}
+
+/**
+ * Re-render a component instance from the document, WITHOUT transacting.
+ *
+ * Used when a release commit legitimately no-ops but the DOM is still showing what the suppressed
+ * in-place commits rendered. The op is the same `set-key $props` the patcher would have produced,
+ * so it takes the ordinary `replaceSubtree` path — this adds no rendering mechanism, it re-sends
+ * the one that was deliberately dropped while the caret needed protecting.
+ *
+ * @param {HostState} state - The host whose tab owns the document.
+ * @param {JxPath} path - The component instance's document path.
+ * @returns {void}
+ */
+function reconcileInstance(state: HostState, path: JxPath): void {
+  const tab = hostTab(state);
+  if (!tab) {
+    return;
+  }
+  const node = getNodeAtPath(tab.doc.document, path);
+  if (!node) {
+    return;
+  }
+  postPatchToHosts([{ key: "$props", op: "set-key", path, value: node.$props }], tab.id);
+}
+
 function hostTab(state: HostState): Tab | null {
   return state.tabId ? (workspace.tabs.get(state.tabId) ?? null) : null;
 }
@@ -2251,6 +2318,13 @@ function handleMessage(state: HostState, msg: IframeToParent): void {
         activeEditHost.snapshot = null;
       }
       activeEditHost = state;
+      /* The session that just opened is inside an instance a release commit is about to rebuild —
+         defer a re-entry so it survives the patch. Only for the SAME instance: moving to a slot in
+         a different component is not disturbed by this rebuild. */
+      if (msg.prop !== undefined && propRebuildAt === serializeJxPath(msg.path)) {
+        deferEnterEdit(state, msg.path, undefined, msg.prop);
+      }
+      propRebuildAt = null;
       // Each visit to a block is one undoable edit. Bumping the run id here breaks the history
       // Coalescing run, so returning to the same paragraph later is a separate ⌘Z step.
       editRunSeq += 1;
@@ -2314,9 +2388,34 @@ function handleMessage(state: HostState, msg: IframeToParent): void {
       const applyProp = () => applyInlinePropCommit(hostTab(state), msg.path, msg.prop, msg.value);
       if (msg.inPlace) {
         withEchoSuppressed(state, [msg.path], applyProp);
-      } else {
-        applyProp();
+        propEchoPending = serializeJxPath(msg.path);
+        return;
+      }
+      const transacted = applyProp();
+      /*
+       * "The instance re-renders for real on release" was only true when the release actually
+       * transacted. After an idle tick the release posts the SAME string, the apply no-ops, and no
+       * patch is ever generated — so the suppressed in-place render was the last word and the
+       * canvas kept showing pre-edit output. Emptying a heading left it visibly empty while the
+       * document had dropped the prop entirely, and any SECOND place the component renders that
+       * value kept the old one.
+       *
+       * Reconciling here rather than lifting the no-op: that guard is load-bearing (it is what
+       * stops a commit → patch → disturb → re-commit loop, and keeps undo clean), so the fix is to
+       * re-render without transacting.
+       */
+      if (needsReleaseReconcile(transacted, propEchoPending, serializeJxPath(msg.path))) {
+        reconcileInstance(state, msg.path);
       }
+      propEchoPending = null;
+      /*
+       * A release that TRANSACTED rebuilds the whole instance — `set-key $props` at the instance
+       * path becomes a `replaceSubtree`. If the user got here by clicking a SECOND prop slot in
+       * that same instance, the frame has already adopted a marker inside the subtree about to be
+       * replaced, so the session it just opened is dead on arrival: the click did nothing and they
+       * had to click again. The next `editStart` tells us whether that is what happened.
+       */
+      propRebuildAt = transacted ? serializeJxPath(msg.path) : null;
       return;
     }
     case "editMerge": {
@@ -2434,7 +2533,7 @@ function onDomUpdated(state: HostState, gen: number): void {
   requestPresence(state);
   hideInsertZoneNow(state);
   if (state.pendingEnterEdit && gen >= state.pendingEnterEdit.minGen) {
-    const { offset, path } = state.pendingEnterEdit;
+    const { offset, path, prop } = state.pendingEnterEdit;
     state.pendingEnterEdit = null;
     /* Re-enter only when this host STILL SHOWS THE TAB IT OWES THE CARET TO — which is a question
        about this host's pane, not about the focus. A background tab's iframe renders a different
@@ -2444,7 +2543,7 @@ function onDomUpdated(state: HostState, gen: number): void {
        there is one stage. With two, the side pane could be displaying its tab, holding a caret it
        owed, and drop it because the PRIMARY had focus. */
     if (state.tabId !== null && state.tabId === tabOfContainer(state.canvasEl)?.id) {
-      reenterEdit(state, path, offset);
+      reenterEdit(state, path, offset, prop);
     }
   }
 }
@@ -2455,20 +2554,32 @@ function onDomUpdated(state: HostState, gen: number): void {
  * that same gen; an escalated full render acks at a bumped one — both satisfy `gen >= minGen`,
  * while a stale ack cannot. Latest-wins on overwrite.
  */
-function deferEnterEdit(state: HostState, path: (string | number)[], offset?: number): void {
+function deferEnterEdit(
+  state: HostState,
+  path: (string | number)[],
+  offset?: number,
+  prop?: string,
+): void {
   state.pendingEnterEdit = {
     minGen: state.lastRenderedGen,
     path: [...path],
     ...(offset === undefined ? {} : { offset }),
+    ...(prop === undefined ? {} : { prop }),
   };
 }
 
 /** Ask the host's iframe to (re-)enter inline editing on `path` (a plain copy crosses the bridge). */
-function reenterEdit(state: HostState, path: (string | number)[], offset?: number): void {
+function reenterEdit(
+  state: HostState,
+  path: (string | number)[],
+  offset?: number,
+  prop?: string,
+): void {
   state.channel.post({
     kind: "enterEdit",
     path: [...path],
     ...(offset === undefined ? {} : { offset }),
+    ...(prop === undefined ? {} : { prop }),
   });
 }
 

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

@@ -25,6 +25,7 @@ import {
   handleSlashTrigger,
   isEditableBlock,
   isEditing,
+  isPlainSession,
   isSlashActive,
   openSlashMenu,
   refreshSlashMenu,
@@ -277,14 +278,44 @@ export function startIframeInlineEdit(
       return true;
     }
     const node = getNodeAtPath(shadowDoc, hostPath) as JxMutableNode | undefined;
+    /*
+     * `$props` IS NOT THE ONLY PLACE A PROP VALUE LIVES, and "absent from $props" is therefore not
+     * the same question as "unset". Two shapes deliver one through `attributes` instead, and both
+     * were reproduced against the real runtime:
+     *
+     *   1. The JSON shorthand `attributes: { "props.text": "…" }`. `connectedCallback` collects
+     *      `props.*` attributes into state, so the marker renders that text while `$props` is
+     *      empty. This repo's own site carries 95 of them.
+     *   2. A prop whose name collides with a REFLECTED HTMLElement property — `title`, `role`,
+     *      `id`, `lang`, `dir`, `slot`, `hidden`. `setAttribute("title", …)` writes the JS property
+     *      as a side effect, and the merge `key in this && this[key] !== undefined` picks it up.
+     *      41 shipped starter components declare `title` or `role` as state.
+     *
+     * Editing either would write `$props[prop]` and leave the attribute standing — two sources for
+     * one rendered value. In case 2 the attribute WINS (applyAttributes runs after the $props
+     * assignment), so the edit is simply invisible; in case 1 clearing the prop later resurrects
+     * the old text. Refusing keeps the properties panel, which edits the attribute itself, as the
+     * one way in.
+     */
+    const attrs = node?.attributes as Record<string, unknown> | undefined;
+    if (attrs?.[`props.${prop}`] !== undefined || attrs?.[prop] !== undefined) {
+      return false;
+    }
     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") {
+    /*
+     * Only a STRING is text. A number or a boolean renders as text and reads as editable, but this
+     * session commits `textContent` — so editing `count: 3` wrote the string `"3"` and silently
+     * retyped the prop, after which `${count * 2}` is `"33"` and `${enabled ? …}` is always truthy.
+     * Objects were already excluded; the scalar cases were not, and are the ones a component
+     * actually declares. They stay editable in the properties panel, which knows their type.
+     */
+    if (typeof raw !== "string") {
       return false;
     }
-    return !(typeof raw === "string" && raw.includes("${"));
+    return !raw.includes("${");
   };
 
   /**
@@ -309,6 +340,13 @@ export function startIframeInlineEdit(
         onEnd: () => {
           clearHighlight();
           lastNonEmptyRange = null;
+          /*
+           * Enter and Escape end the session inside the engine, which knows nothing about the
+           * editing host that adopted this marker. Without this the host kept pointing at the dead
+           * session, so the very next click on the same text was swallowed by the
+           * `el !== activeEl` re-entry guard — you had to click something else and come back.
+           */
+          root.forget();
           channel.post({ kind: "editEnd" });
         },
         // Prop values are single plain strings — no split, no slash-insert.
@@ -325,6 +363,15 @@ export function startIframeInlineEdit(
     if (!el) {
       return; // Session not active → no-op.
     }
+    /*
+     * A prop value carries no formatting — "formatting is off" is the documented rule for this
+     * session. The chord is inertified inside the frame, but a caret-scoped ⌘B is ALSO forwarded to
+     * the parent, matched by the shortcut registry, and posted straight back as an intent that
+     * lands here. This is the one chokepoint both routes pass through.
+     */
+    if (isPlainSession()) {
+      return;
+    }
     // Restore the cached range ONLY if it's still usable (the DOM may have re-rendered).
     if (
       lastNonEmptyRange &&
@@ -511,6 +558,21 @@ export function startIframeInlineEdit(
     if (!editingAllowed()) {
       return;
     }
+    if (msg.prop !== undefined) {
+      /*
+       * A prop host cannot be re-entered by placing a caret: the marker has no path, and the
+       * `$props` patch that prompted this REPLACED the instance element, so the node the old
+       * session held is detached. Find the marker again inside the fresh instance and open it.
+       */
+      const instance = elementForPath(container, msg.path);
+      const marker = instance?.querySelector<HTMLElement>(
+        `[data-jx-bound-prop="${CSS.escape(msg.prop)}"]`,
+      );
+      if (marker) {
+        activateProp(marker);
+      }
+      return;
+    }
     // Follow-the-caret after a split or slash-insert: the parent re-renders and then names the path
     // The caret belongs in. Placing the caret is the whole job — activation follows from where the
     // Caret is, so there is nothing else to "enter".

package/src/canvas/iframe-protocol.ts

@@ -190,6 +190,13 @@ export type ParentToIframe =
       path: (string | number)[];
       /** Character offset for the caret; defaults to the block's start. */
       offset?: number;
+      /**
+       * Re-enter the PROP-BOUND host for this prop of the instance at `path`, rather than placing a
+       * caret in a block. A prop host is identified by (instance, prop) — the marker element
+       * carries no path of its own — and it is re-entered rather than caret-placed because a
+       * `$props` patch rebuilds the whole instance, replacing the element the session was on.
+       */
+      prop?: string;
     }
   // Commit and end the inline-edit session if one is live (a no-op otherwise). Posted by the parent
   // When focus/intent leaves the edit surface in the PARENT realm (tab switch, layers-panel click,

package/src/canvas/iframe-render.ts

@@ -480,6 +480,17 @@ export function injectHead(doc: JxDocument): void {
  * + `data-jx-layout-file` (layout-originated nodes) on rendered nodes.
  */
 export function makeStamper(ctx: PathMapCtx) {
+  /*
+   * Paths of the component instances frozen below. Nodes arrive parent-first and `onNodeCreated`
+   * fires straight after `createElement`, BEFORE the node is attached — so there is no ancestor to
+   * walk at stamp time, and the path is the only way to know a node landed inside an island.
+   */
+  const islands: (string | number)[][] = [];
+  const insideIsland = (path: (string | number)[]): boolean =>
+    islands.some(
+      (island) => path.length > island.length && island.every((seg, i) => path[i] === seg),
+    );
+
   return (created: Node, path: (string | number)[], def: unknown) => {
     if (!(created instanceof HTMLElement)) {
       return;
@@ -503,8 +514,11 @@ export function makeStamper(ctx: PathMapCtx) {
     //
     // The opened document's own root is excluded: when a component definition is the file being
     // Edited, its subtree IS the document and must stay editable.
-    if (!isDefinitionRoot && created.tagName.includes("-") && isEditableMode(ctx.canvasMode)) {
+    const isIsland =
+      !isDefinitionRoot && created.tagName.includes("-") && isEditableMode(ctx.canvasMode);
+    if (isIsland) {
       created.contentEditable = "false";
+      islands.push(path);
     }
     const classified = classifyRenderNode(path, def, ctx);
     if (classified.kind === "layout") {
@@ -530,6 +544,29 @@ export function makeStamper(ctx: PathMapCtx) {
       return;
     }
     created.dataset.jxPath = serializeJxPath(classified.path);
+    /*
+     * SLOTTED PAGE CONTENT IS NOT COMPONENT INTERNALS.
+     *
+     * The island above exists to keep the caret out of what a component renders for itself. But a
+     * component's CHILDREN are the author's own document — in jx-markdown,
+     *
+     *     :::eer-intro
+     *     If you need reliable rental equipment fast, request a quote today!
+     *     :::
+     *
+     * is a paragraph the author typed, stamped here with its own `data-jx-path`. Inheriting the
+     * island's `contenteditable="false"` made every such paragraph uneditable: on a page written
+     * this way — which is most component-using pages — the caret could not be placed anywhere at
+     * all, and the only route to the text was the properties sidebar.
+     *
+     * Re-opening on the STAMPED node alone is what keeps the distinction. Component internals are
+     * created by the component's own `connectedCallback` in another document and never pass through
+     * this stamper, so they stay frozen; prop-bound internals keep their nested-host activation
+     * (see iframe-editable-root's `onPointerDownCapture`).
+     */
+    if (!isIsland && isEditableMode(ctx.canvasMode) && insideIsland(path)) {
+      created.contentEditable = "true";
+    }
   };
 }
 

package/src/editor/inline-edit-apply.ts

@@ -107,27 +107,33 @@ export function applyInlineCommit(
  * disturb→re-commit cycle loops (and pollutes undo history). An empty value deletes the prop
  * (mutateUpdateProp), reverting the instance to the definition default — same as clearing the
  * sidebar field.
+ *
+ * @returns Whether it transacted. The caller needs to know: an in-place commit's patch is
+ *   echo-suppressed so the caret survives, and the release that follows is expected to re-render
+ *   the instance for real. When the release posts the same value it no-ops here, nothing
+ *   re-renders, and the canvas keeps showing pre-edit output — see the reconcile in iframe-host.
  */
 export function applyInlinePropCommit(
   tab: Tab | null,
   path: JxPath,
   prop: string,
   value: string,
-): void {
+): boolean {
   if (!tab) {
-    return;
+    return false;
   }
   const node = getNodeAtPath(tab.doc.document, path);
   if (!node) {
-    return;
+    return false;
   }
   const current = (node.$props as Record<string, unknown> | undefined)?.[prop];
   if (`${current ?? ""}` === value) {
-    return;
+    return false;
   }
   transactDoc(tab, (t) => {
     mutateUpdateProp(t, path, prop, value);
   });
+  return true;
 }
 
 /**

package/src/editor/inline-edit.ts

@@ -182,11 +182,19 @@ let endFn: (() => void) | null = null; // Function() called when editing stops
 /**
  * Plain (plaintext-only) session state — used for prop-bound text, where the committed value is a
  * plain string (a directive attribute), so rich formatting, Enter-split, and the slash menu are all
- * disabled: Enter commits, Escape restores `_plainOriginal` and commits unchanged (the host no-ops
- * an unchanged prop value).
+ * disabled: Enter commits, Escape restores `_plainOriginal`.
+ *
+ * Escape is a genuine cancel, and `_plainPosted` is what makes it one. Restoring the text is not
+ * enough on its own: if an idle tick already wrote during the session, the document holds the typed
+ * value and the restored text must be written back over it. Conversely a session that never posted
+ * and ends matching its original must write NOTHING — the host's "unchanged value" guard cannot be
+ * relied on for that, because it compares against the STORED prop and an unset prop's stored value
+ * is `undefined` while the marker renders the definition's default.
  */
 let _plainMode = false;
 let _plainOriginal = "";
+/** Whether this plain session has posted a commit — see the note above on Escape. */
+let _plainPosted = false;
 
 /**
  * The live document's format overrides for which tags hold a caret. Injected per render (the same
@@ -286,6 +294,7 @@ export function startEditing(
   endFn = callbacks.onEnd;
   _plainMode = opts?.plainText === true;
   _plainOriginal = _plainMode ? (el.textContent ?? "") : "";
+  _plainPosted = false;
 
   // Mark the caret's block so the empty-block slash hint can target it. The editing host itself is
   // The canvas container (see syncEditableRoot) — activating a block does NOT make it a separate
@@ -345,6 +354,7 @@ export function stopEditing(silent = false) {
   insertFn = null;
   _plainMode = false;
   _plainOriginal = "";
+  _plainPosted = false;
 
   if (silent) {
     endFn = null;
@@ -370,6 +380,19 @@ export function commitActiveBlock(): void {
   commitChanges(true);
 }
 
+/**
+ * Whether the live session is PLAIN — a prop value rather than a block of the document.
+ *
+ * Exported because the format bridge is in another module and `_plainMode` is file-local, so
+ * `applyFormatIntent` could not even ask: a ⌘B forwarded out to the parent came back as an
+ * `applyFormat` intent and ran `toggleInlineFormat` on a `plaintext-only` host, wrapping the prop's
+ * text in a `<strong>` that its next commit then flattened away — losing nothing visible, but
+ * mutating the DOM under a session whose whole contract is that it holds one plain string.
+ */
+export function isPlainSession(): boolean {
+  return _plainMode && activeEl !== null;
+}
+
 /**
  * Whether inline editing is currently active.
  *
@@ -416,7 +439,9 @@ function handleKeydown(e: KeyboardEvent) {
       e.preventDefault();
       e.stopPropagation();
       if (activeEl) {
-        // Cancel: restore the original text; the commit posts the unchanged value (host no-ops).
+        /* Cancel: restore the original text. `commitChanges` then posts it ONLY if this session had
+           already written (an idle tick), which is what makes Escape undo the tick instead of
+           leaving it standing — and what stops a bare Escape from writing anything at all. */
         activeEl.textContent = _plainOriginal;
       }
       stopEditing();
@@ -532,6 +557,7 @@ function releaseWithoutCommit(): void {
   insertFn = null;
   _plainMode = false;
   _plainOriginal = "";
+  _plainPosted = false;
 
   if (endFn) {
     const fn = endFn;
@@ -557,7 +583,26 @@ function commitChanges(inPlace: boolean) {
   if (_plainMode) {
     // A prop value is a plain single-line string (a directive attribute) — flatten any newline
     // That survived plaintext editing and skip the rich DOM→Jx serialization entirely.
-    commitFn(activePath, null, (activeEl.textContent ?? "").replaceAll("\n", " "), inPlace);
+    const text = (activeEl.textContent ?? "").replaceAll("\n", " ");
+    /*
+     * A SESSION THAT CHANGED NOTHING MUST WRITE NOTHING.
+     *
+     * This branch used to post unconditionally, and the only guard was the host's
+     * "same value, do nothing" check against the STORED prop — which does not fire when the prop is
+     * unset, because the marker renders the DEFINITION's default and the stored value is
+     * `undefined`. So merely clicking a component's text and clicking away wrote
+     * `$props.<name> = "<the default>"`: the tab went dirty, an undo entry appeared, and that
+     * instance was silently detached from its definition forever. Escape did the same thing, which
+     * made "cancel" a way to modify the document.
+     *
+     * `_plainPosted` is what keeps Escape honest AFTER an idle tick has already written: the
+     * restored text equals the original, but something WAS written, so it must be written back.
+     */
+    if (text === _plainOriginal.replaceAll("\n", " ") && !_plainPosted) {
+      return;
+    }
+    _plainPosted = true;
+    commitFn(activePath, null, text, inPlace);
     return;
   }
 
@@ -775,6 +820,19 @@ export function openSlashMenu(opts?: { anchored?: boolean }): void {
   if (!activeEl || !insertFn || !activePath) {
     return;
   }
+  /*
+   * Never in a plain session. A prop value is one string — there is nowhere to insert a block, and
+   * `enterPropEditAt` says so by passing `onInsert: () => {}`. That no-op is TRUTHY, so the
+   * precondition above let the menu open anyway, and choosing an item then ran the rich select
+   * path: it deleted the typed "/…" run and called `releaseWithoutCommit`, so the edit was
+   * discarded and no block was inserted either. The menu also captures Enter and Escape
+   * document-wide, so it took the two keys the docs promise for this session.
+   *
+   * Guarded here rather than at the trigger so a programmatic `openSlashMenu()` is covered too.
+   */
+  if (_plainMode) {
+    return;
+  }
 
   const sel = window.getSelection();
   if (!sel || !sel.rangeCount) {