@jxsuite/studio 4.0.0 → 5.0.0

package/src/canvas/iframe-interaction.ts

@@ -6,7 +6,7 @@
  * the iframe only reports what was pointed at.
  */
 
-import { parseJxPath, serializeJxPath } from "./path-mapping";
+import { jxPathSelector, parseJxPath, serializeJxPath } from "./path-mapping";
 import { rectOf } from "../utils/geometry";
 import { computeInsertZones, insertZonesKey } from "./iframe-insert";
 import { getActiveElement, isEditing } from "../editor/inline-edit";
@@ -60,25 +60,57 @@ export function nearestHit(target: EventTarget | null): NodeHit | null {
   return measureHit(el, el.dataset.jxPath as string);
 }
 
+/**
+ * Whether an element is actually rendered, as opposed to merely present in the DOM.
+ *
+ * `checkVisibility` is the platform's own answer, and it is the right one: it walks the ancestor
+ * chain, so a node inside a closed popover or a `display: none` section is reported hidden without
+ * this having to know why. happy-dom implements it faithfully (`display`, `visibility`, `opacity`,
+ * disconnection), so the guard is exercised under test rather than merely asserted.
+ *
+ * A rect test would NOT work here and was tried: happy-dom performs no layout, so every element
+ * measures 0×0 at the origin and the guard would report the whole document hidden.
+ *
+ * An engine without `checkVisibility` gets the benefit of the doubt. Withholding a selection box
+ * from a node that is on screen is a worse failure than drawing one for a node that is not.
+ */
+function isRendered(el: Element): boolean {
+  const check = (el as { checkVisibility?: (o?: object) => boolean }).checkVisibility;
+  return typeof check === "function" ? check.call(el, { checkVisibilityCSS: true }) : true;
+}
+
 /**
  * Measure the current rect of each requested document path by locating its `data-jx-path` element.
- * Paths with no matching node are omitted. The serialized path is the same string the renderer
- * stamps, so a stored selection path round-trips back to its element.
+ *
+ * Paths with no matching node are omitted. Paths that resolve to an element which is NOT RENDERED —
+ * a closed popover, a `display: none` node, a `$switch` branch that is not the live case — come
+ * back under `hidden` instead of as a rect. That distinction is the point: they used to be measured
+ * like anything else, and a zero rect is a truthy object, so the overlay drew a 0×0 box at the
+ * artboard origin and the block action bar anchored to it. Selecting a hidden node put a selection
+ * marker in the corner of the page and left the toolbar sitting there.
+ *
+ * The serialized path is the same string the renderer stamps, so a stored selection path
+ * round-trips back to its element.
  */
-export function measureHits(paths: (string | number)[][], doc: Document = document): NodeHit[] {
-  const out: NodeHit[] = [];
+export function measureHits(
+  paths: (string | number)[][],
+  doc: Document = document,
+): { hits: NodeHit[]; hidden: (string | number)[][] } {
+  const hits: NodeHit[] = [];
+  const hidden: (string | number)[][] = [];
   for (const path of paths) {
-    const serialized = serializeJxPath(path);
-    // Wrap in single quotes (the serialized JSON only ever uses double quotes) and escape the few
-    // Characters that could still break out of an attribute-value selector.
-    const esc = serialized.replaceAll("\\", String.raw`\\`).replaceAll("'", String.raw`\'`);
-    const el = doc.querySelector(`[data-jx-path='${esc}']`);
-    if (el) {
+    const el = doc.querySelector(jxPathSelector(serializeJxPath(path)));
+    if (!el) {
+      continue;
+    }
+    if (isRendered(el)) {
       const r = rectOf(el);
-      out.push({ path, rect: { height: r.height, width: r.width, x: r.x, y: r.y } });
+      hits.push({ path, rect: { height: r.height, width: r.width, x: r.x, y: r.y } });
+    } else {
+      hidden.push(path);
     }
   }
-  return out;
+  return { hidden, hits };
 }
 
 /**
@@ -87,6 +119,88 @@ export function measureHits(paths: (string | number)[][], doc: Document = docume
  * {@link file://./iframe-drop.ts}'s `startGrabDetector` receives its deps rather than reaching for
  * module state.
  */
+/** The three `popovertargetaction` keywords. Anything else falls back to the HTML default. */
+const INVOKER_ACTIONS = new Set(["toggle", "show", "hide"]);
+
+/**
+ * Report an invoker click, when the click landed on one and it names an addressable popover.
+ *
+ * Both attributes are read from their CANVAS spellings: the runtime renamed `popover` to
+ * `data-jx-popover` for the render, but `popovertarget` keeps its own name — nothing in the editor
+ * needs it renamed, since with no real popover to invoke the browser does nothing with it anyway.
+ * That is what makes this safe to post unconditionally: a trigger whose target is a component's own
+ * internal popover resolves to no addressable node, and nothing is posted.
+ *
+ * Called only after `onClick`'s preview branch has returned, so no mode gate is needed here.
+ *
+ * @param target The click's `e.target`.
+ * @param channel The frame's channel.
+ */
+function postPopoverInvoke(
+  target: EventTarget | null,
+  channel: { post: (m: IframeToParent) => void },
+): void {
+  if (!(target instanceof Element)) {
+    return;
+  }
+  const invoker = target.closest("[popovertarget]");
+  const id = invoker?.getAttribute("popovertarget");
+  if (!invoker || !id) {
+    return;
+  }
+  /* Scanned rather than selected. The id is author-controlled text, so a `[id='…']` selector would
+     need escaping — a rule this file already keeps in exactly one place (`jxPathSelector`) and
+     should not gain a second spelling of. The set scanned is the addressable POPOVERS, which is
+     also the set the answer has to come from, so the scan is the test. */
+  const panels = invoker.ownerDocument.querySelectorAll("[data-jx-popover]");
+  const panel = [...panels].find((el) => el.id === id) as HTMLElement | undefined;
+  const serialized = panel?.dataset.jxPath;
+  if (!serialized) {
+    return;
+  }
+  const raw = invoker.getAttribute("popovertargetaction") ?? "toggle";
+  const action = INVOKER_ACTIONS.has(raw) ? (raw as "toggle" | "show" | "hide") : "toggle";
+  channel.post({ action, kind: "popoverTargetClick", targetPath: parseJxPath(serialized) });
+}
+
+/**
+ * Report a click on a `<button command commandfor>` the canvas de-linked.
+ *
+ * The runtime renamed `commandfor` to `data-jx-commandfor` (so the platform's invoker never runs
+ * `showModal()` or `togglePopover()` inside an editable frame); the frame reports the target's path
+ * and the command, and the host's single writer of open state decides what it means — for a popover
+ * command exactly as `popovertarget` is answered, for a dialog command through
+ * `canvas.setDialogOpen`. A custom `--command` is reported too, and the host ignores it.
+ *
+ * @param target The click's `e.target`.
+ * @param channel The frame's channel.
+ */
+function postCommandInvoke(
+  target: EventTarget | null,
+  channel: { post: (m: IframeToParent) => void },
+): void {
+  if (!(target instanceof Element)) {
+    return;
+  }
+  const invoker = target.closest<HTMLElement>("[data-jx-commandfor]");
+  const id = invoker?.dataset["jxCommandfor"];
+  const command = invoker?.getAttribute("command")?.trim().toLowerCase() ?? "";
+  if (!invoker || !id || !command) {
+    return;
+  }
+  // Scanned, not selected, for the reason `postPopoverInvoke` gives; the addressable overlays are
+  // The de-popovered panels and the stamped dialogs.
+  const overlays = invoker.ownerDocument.querySelectorAll(
+    "[data-jx-popover], dialog[data-jx-path]",
+  );
+  const overlay = [...overlays].find((el) => el.id === id) as HTMLElement | undefined;
+  const serialized = overlay?.dataset.jxPath;
+  if (!serialized) {
+    return;
+  }
+  channel.post({ command, kind: "commandTargetClick", targetPath: parseJxPath(serialized) });
+}
+
 export interface InteractionDeps {
   /**
    * The iframe's current non-reactive shadow doc (path coordinate space), or null before the first
@@ -190,6 +304,12 @@ export function startInteraction(
         kind: "hit",
       });
     }
+    /* AFTER the hit, and the order is load-bearing. The host's reveal rule opens the overlay a
+       selection lands in, so a Close button INSIDE a dialog (the normal shape of one) selected
+       after its command would close the dialog and then reveal it again. Selected first, the
+       reveal is a no-op on an overlay that is already open, and the close lands. */
+    postPopoverInvoke(e.target, channel);
+    postCommandInvoke(e.target, channel);
   };
 
   /**

package/src/canvas/iframe-patch.ts

@@ -377,7 +377,13 @@ function editModeStyle(style: JxStyle | undefined): JxStyle | undefined {
   }
   const out: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(style)) {
-    out[k] = typeof v === "string" && v.includes("${") ? "" : v;
+    /* OMITTED, not blanked. It used to be written as `""`, which was a silent no-op while a
+       declaration went to `el.style` and is a malformed declaration now that it goes into a rule.
+       Dropping the key is what blanking always meant: the property falls back to the cascade. */
+    if (typeof v === "string" && v.includes("${")) {
+      continue;
+    }
+    out[k] = v;
   }
   return out as JxStyle;
 }

package/src/canvas/iframe-position.ts

@@ -18,7 +18,7 @@
  * @docs studio/editing/writing
  */
 
-import { parseJxPath, serializeJxPath } from "./path-mapping";
+import { jxPathSelector, parseJxPath, serializeJxPath } from "./path-mapping";
 import type { JxPath } from "../state";
 
 /** A caret/selection endpoint in document coordinates: a block path + a character offset into it. */
@@ -82,11 +82,10 @@ export function activeBlockAt(
 
 /** Locate the rendered element for a document path via its stamped `data-jx-path`. */
 export function elementForPath(container: HTMLElement, path: JxPath): HTMLElement | null {
-  const serialized = serializeJxPath(path);
-  // Wrap in single quotes (the serialized JSON only ever uses double quotes) and escape the few
-  // Characters that could still break out of an attribute-value selector.
-  const esc = serialized.replaceAll("\\", String.raw`\\`).replaceAll("'", String.raw`\'`);
-  const el = container.querySelector(`[data-jx-path='${esc}']`);
+  // The escaping lives in `jxPathSelector`, which the popover work extracted for its own lookup.
+  // This function had the only other copy of it, and two spellings of one escaping rule is how the
+  // Two come to disagree about a path containing a quote.
+  const el = container.querySelector(jxPathSelector(serializeJxPath(path)));
   return el instanceof HTMLElement ? el : null;
 }
 

package/src/canvas/iframe-protocol.ts

@@ -23,11 +23,16 @@ import type { JxExpressionNode, JxMutableNode } from "@jxsuite/schema/types";
  */
 export type WireDocOp = JxDocOp;
 
-export const CANVAS_MODES = ["preview", "design", "edit", "stylebook"] as const;
+export const CANVAS_MODES = ["preview", "design", "edit", "stylebook", "git-diff"] as const;
 
 /**
- * How the iframe renders the document: live `preview`, instrumented `design`/`edit`, or the
- * `stylebook` specimen catalog (hit/hover/measure only — no inline editing, DnD, or insert zones).
+ * How the iframe renders the document: live `preview`, instrumented `design`/`edit`, the
+ * `stylebook` specimen catalog (hit/hover/measure only — no inline editing, DnD, or insert zones),
+ * or a `git-diff` comparison artboard (a read-only render carrying {@link WireDiffMarks}).
+ *
+ * `git-diff` was reaching the frame long before it was listed here: `preparePassRender` casts the
+ * resolved mode with `as CanvasMode`, so the one mode this union did not admit crossed the wire
+ * anyway and `isCanvasMode` answered false for a mode the frame was actively rendering.
  */
 export type CanvasMode = (typeof CANVAS_MODES)[number];
 
@@ -63,6 +68,24 @@ export interface SyncedChord {
   scope: "caret" | "canvas" | "global";
 }
 
+/** One node the comparison says changed, addressed in THIS artboard's document. */
+export interface WireDiffMark {
+  path: (string | number)[];
+  /**
+   * How to draw it.
+   *
+   * A modification is ONE change with two faces, and the artboard it is drawn on decides which:
+   * `modified-before` on the committed side, `modified-after` on the working copy. The parent
+   * splits them when it hands each artboard its own marks, because the frame does not know which
+   * side it is. Marked identically on both, a modification read as "added" on the left — the green
+   * of the added colour over the text that is being replaced.
+   */
+  kind: "added" | "removed" | "modified-before" | "modified-after";
+}
+
+/** An artboard's whole mark set. Each side receives only its own; `[]` clears. */
+export type WireDiffMarks = readonly WireDiffMark[];
+
 /** Messages the editor (parent) sends into the canvas iframe. */
 export type ParentToIframe =
   | { kind: "init"; gen: number }
@@ -102,11 +125,56 @@ export type ParentToIframe =
       // Forced color-scheme preview (spec §9.5): "light"/"dark" sets data-color-scheme on the
       // Iframe root, null clears it (auto — follow the OS).
       colorScheme: "light" | "dark" | null;
+      /**
+       * Which nodes to tint on a `git-diff` artboard, in this side's own coordinates.
+       *
+       * A FIELD ON THE RENDER, not a message of its own, and the reason is ordering. A render ends
+       * in `container.replaceChildren(el)`, which destroys the DOM any earlier mark was stamped on
+       * — so a separate message would need its own generation, a queue for arriving early, and a
+       * re-apply hook after every render, three mechanisms to reproduce what carrying the data
+       * already guarantees. The transport settles it too: a host holds ONE `pending` message while
+       * its iframe boots, so a marks message posted beside a queued render would replace it.
+       */
+      diffMarks?: WireDiffMarks | null;
+      /**
+       * Which popover the artboard draws OPEN, by document path — absent or null for none.
+       *
+       * Carried on `render` as well as by the setter below for the same reason `colorScheme` is: a
+       * render replaces the DOM, and the open state is one attribute on one element, so without it
+       * every re-render would close the panel the author is editing.
+       */
+      popoverOpen?: (string | number)[] | null;
+      /** The dialog to draw open after this render, for the same reason. */
+      dialogOpen?: (string | number)[] | null;
       gen: number;
     }
   // Flip the forced color-scheme preview on the iframe root without re-rendering — a document-level
   // Idempotent attribute write, deliberately gen-less (like endEdit).
   | { kind: "setColorScheme"; scheme: "light" | "dark" | null }
+  /**
+   * Draw the popover at `path` open, and every other one closed. `null` closes them all.
+   *
+   * Render-free and gen-less, exactly like `setColorScheme` above, because it changes no content:
+   * the runtime has already renamed every addressable `popover` to `data-jx-popover` for this
+   * render (`setCanvasDelinkPopovers`), so open-ness is ONE attribute on ONE element and the whole
+   * document's layout follows from flipping it. Opening a popover must not cost a full render —
+   * §4.1 calls that expensive, and it would rebuild every binding effect under the author's caret.
+   *
+   * Refused in preview, in BOTH realms: preview is native, and a canvas-only attribute has no
+   * business in a view whose whole job is fidelity (§4.2).
+   *
+   * A frame built before this message existed ignores it and draws every popover closed, which is
+   * the compatibility story `dist/iframe-entry.js` shipping prebuilt requires.
+   */
+  | { kind: "setPopoverOpen"; path: (string | number)[] | null }
+  /** The `<dialog>` to draw open in place, or none. The dialog twin of `setPopoverOpen`. */
+  | { kind: "setDialogOpen"; path: (string | number)[] | null }
+  /**
+   * Replace a custom element's definition in the frame's realm — the canvas half of
+   * `redefineElement` (embedding.md §7). Instances already on the canvas keep the old definition
+   * until the next render replaces them, which is why the host follows it with a `render`.
+   */
+  | { kind: "redefineElement"; doc: JxMutableNode; base?: string }
   /**
    * Set the language the artboard is drawn in — `lang` and `dir` on the frame's document element.
    *
@@ -443,7 +511,18 @@ export type IframeToParent =
   | { kind: "insertZones"; zones: InsertZone[] | null }
   // Response to `measure`: the rects of whichever requested paths resolved to a node (missing paths
   // Are simply omitted). `reqId` echoes the request so the parent can drop stale responses.
-  | { kind: "geometry"; reqId: number; hits: NodeHit[] }
+  /**
+   * Measured rects for the requested paths.
+   *
+   * `hidden` names the paths that RESOLVED to an element but are not rendered — a closed popover, a
+   * `display: none` node, a `$switch` branch that is not the live case. They are reported apart
+   * from `hits` rather than as a zero rect, because a zero rect is a truthy object: the overlay
+   * drew a 0×0 box at the artboard origin and the block action bar anchored to it, so selecting a
+   * hidden node put a selection marker in the top-left corner of the page.
+   *
+   * Optional, so a prebuilt frame that predates it still answers.
+   */
+  | { kind: "geometry"; reqId: number; hits: NodeHit[]; hidden?: (string | number)[][] }
   // Response to `evalExpr`: one result per requested expression (empty when the request's gen no
   // Longer matches the live render — the iframe never evaluates against the wrong scope). `reqId`/
   // `gen` echo the request so the parent can drop stale replies (measure/geometry precedent).
@@ -541,7 +620,7 @@ export type IframeToParent =
   | { kind: "editEnd" }
   // ─── Slash-menu bridge ──────────────────────────────────────────────────────
   // The engine (in the iframe) detected "/" in a live edit session; the parent shows the real
-  // Lit/Spectrum menu. Re-posted with a new `filter` as the author keeps typing (the engine's
+  // Host-realm menu. Re-posted with a new `filter` as the author keeps typing (the engine's
   // UpdateSlashMenu drives it). `rect` is the edited element's bbox in IFRAME-VIEWPORT coords.
   /**
    * Show the parent's slash menu at this rect.
@@ -580,6 +659,28 @@ export type IframeToParent =
   //
   // Deliberately NOT in the host's preview block-list: focusing a pane is not an edit, and it is
   // The one thing preview must still report.
+  /**
+   * A `popovertarget` invoker was clicked, and it names a popover the studio can address.
+   *
+   * The canvas renames `popover` to `data-jx-popover`, so the browser's own invoker activation no
+   * longer fires — which is a gain, not a loss: there is exactly ONE writer of open state instead
+   * of a race between the platform and the editor, and the model can no longer disagree with what
+   * is on screen. The affordance is re-supplied here, and the host runs the same command the
+   * palette and the assistant run.
+   *
+   * Posted ALONGSIDE `hit`, never instead of it: clicking a trigger both selects the button and
+   * opens its panel, which is what an author expects from a control they can also style.
+   */
+  | {
+      kind: "popoverTargetClick";
+      targetPath: (string | number)[];
+      action: "toggle" | "show" | "hide";
+    }
+  /**
+   * A click on a `<button command commandfor>` the canvas de-linked: the frame reports the target
+   * and the command, and the host's single writer of open state answers for a popover or a dialog.
+   */
+  | { kind: "commandTargetClick"; targetPath: (string | number)[]; command: string }
   | { kind: "paneFocus" }
   // ─── Preview navigation ─────────────────────────────────────────────────────
   // A link was clicked in PREVIEW mode. Preview keeps anchors live (design/edit de-link them onto