@jxsuite/studio 6.1.1 → 8.0.0

package/src/canvas/iframe-host.ts

@@ -23,7 +23,7 @@ import {
 import { canvasRectToParent, createOverlayLayer } from "./iframe-overlay";
 import { serializeJxPath } from "./path-mapping";
 import { getActivePanel, panelMediaToActiveMedia } from "./canvas-helpers";
-import { panToParentRect } from "./canvas-utils";
+import { panToParentRect, revealParentRect } from "./canvas-utils";
 import { clearDragGhost, moveDragGhost } from "../panels/drag-ghost";
 import { applyDropInstruction } from "../panels/dnd";
 import { rectOf } from "../utils/geometry";
@@ -46,6 +46,7 @@ import { formatEditableVerdicts } from "../format/constraints";
 import { formatByName } from "../format/format-host";
 import { collabState } from "../collab/collab-state";
 import { DIALOG_COMMANDS, isDialog, POPOVER_COMMANDS } from "@jxsuite/schema/dialogs";
+import { isNodeObject } from "@jxsuite/schema/guards";
 import { isPopover } from "@jxsuite/schema/overlays";
 import { localeDirection } from "@jxsuite/schema/locale";
 import { getPlatform, hasPlatform } from "../platform";
@@ -66,27 +67,79 @@ import type {
   SerializableRect,
   SerializedKey,
   SyncedChord,
-  WireDocOp,
+  WireLocale,
 } from "./iframe-protocol";
+import { getEffectiveRenderLocale } from "../site-context";
+import type { JxDocOp } from "../tabs/patch-ops";
 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 { JxExpressionNode, JxMutableNode } from "@jxsuite/schema/types";
+import type { JxExpressionNode, JxMutableNode, JxStyle } from "@jxsuite/schema/types";
 import { bundleUrl } from "../services/bundle-base";
 
-/** A rect in PARENT coordinates (overlay-local from {@link canvasRectToParent}, same field shape). */
-type ParentRect = OverlayPlacement;
+/**
+ * A plain-data copy of a value bound for `postMessage`.
+ *
+ * A JSON round trip rather than `structuredClone`, which throws on exactly what this exists to
+ * drop: reactive-proxy internals and stray functions riding on a value read off a live store.
+ */
+function plainCopy<T>(value: T): T {
+  /* SAFETY: Every value posted through here is document or config data, which is JSON by contract,
+     so the round trip returns the same shape minus only what the realm boundary cannot carry. */
+  // oxlint-disable-next-line unicorn/prefer-structured-clone
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+/** A deferred re-entry into inline editing, waiting for the host's DOM to reflect a split/insert. */
+interface 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;
+}
+
+/** The `enterEdit` message a host posts to re-enter inline editing. */
+type EnterEditMsg = Extract<ParentToIframe, { kind: "enterEdit" }>;
+
+/** A full-render message, as one host receives it. */
+type RenderMsg = Extract<ParentToIframe, { kind: "render" }>;
+
+/**
+ * The source data a drag session retains for its drop, exactly what {@link applyDropInstruction}
+ * consumes.
+ */
+type RetainedDragData = Parameters<typeof applyDropInstruction>[2];
+
+/** The empirical zoom of a host's iframe and the iframe's parent-viewport offset. */
+export interface DragGeometry {
+  scale: number;
+  rect: { left: number; top: number };
+}
 
-interface HostState {
+/** The current edit session's editing flag + latest selection snapshot, for the parent toolbar. */
+export interface EditSnapshotState {
+  editing: boolean;
+  editingProp: string | null;
+  snapshot: SelectionSnapshot | null;
+}
+
+/**
+ * One artboard's iframe, overlay, selection and edit session.
+ *
+ * Exported for the drag coordinator, which holds one as an opaque handle and passes it back to the
+ * session API ({@link beginDragSession}/{@link hostDragGeometry}/{@link postDragMessage}) without
+ * reading its fields.
+ */
+export 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
-   * is rebuilt once the platform's loopback canvasUrl becomes available (electrobun resolves it
-   * async).
+   * The resolved canvasUrl this iframe was built with — so a host built with one URL is rebuilt if
+   * the platform later reports a different one.
    */
   canvasUrl: string;
   ready: boolean;
@@ -101,8 +154,22 @@ interface HostState {
   /** Primary selected path (mirrors `session.selection`'s last entry), for hover de-dupe. */
   selectionPath: (string | number)[] | null;
   /** The whole selection this host last measured, so a re-measure redraws every box. */
-  selectionPaths: JxPath[];
-  /** Id of the most recent selection `measure` request, so stale `geometry` replies are dropped. */
+  selectionPaths: readonly JxPath[];
+  /**
+   * The allocator every `measure` request this host posts draws its id from: selection, presence,
+   * pan-to-card and {@link measureCanvasPath}. One counter keeps the ids disjoint, so the `geometry`
+   * handler can dispatch on the id alone.
+   */
+  measureSeq: number;
+  /**
+   * Id of the most recent SELECTION `measure` request, so a stale selection reply is dropped.
+   *
+   * It names the request, not the counter. It used to be both, so any other measure posted while a
+   * selection measure was in flight superseded it: picking a tag in the Styles Outline posts the
+   * selection measure and then a pan-to-card measure in the same tick, the pan took the newer id,
+   * and the selection reply arrived to find itself stale. The specimen was centred and never
+   * outlined. A live peer's presence measure did the same to the page selection.
+   */
   selReqId: number;
   /**
    * The NON-primary selected paths the in-flight selection `measure` covers, serialized. The
@@ -110,7 +177,7 @@ interface HostState {
    * selected node leaves it empty, so nothing but the selection box is ever drawn.
    */
   coSelectionKeys: Set<string>;
-  /** Id of the most recent presence `measure` request (allocated from the selReqId counter). */
+  /** Id of the most recent presence `measure` request (allocated from {@link HostState.measureSeq}). */
   presenceReqId: number;
   /** Serialized peer path → presence box meta for the in-flight presence measure. */
   presenceMeta: Map<string, { color: string; label: string }>;
@@ -157,7 +224,7 @@ interface HostState {
   /** Highest snapshot `seq` seen, so stale (re-ordered) snapshots are dropped. */
   lastSnapshotSeq: number;
   /** The last non-null selection rect drawn (parent/overlay coords) — toolbar position fallback. */
-  lastSelectionRect: ParentRect | null;
+  lastSelectionRect: OverlayPlacement | null;
   /** The node the pointer last hovered (iframe-viewport rect), so a zoom can hold it still. */
   lastHover: NodeHit | null;
   /**
@@ -218,8 +285,8 @@ interface HostState {
   /**
    * Resolvers for {@link measureCanvasPath} requests, keyed by the `measure` reqId.
    *
-   * Allocated from the same `selReqId` counter as the selection and presence measures, so the three
-   * can never collide and the `geometry` handler can dispatch on the id alone.
+   * Allocated from the same `measureSeq` counter as the selection and presence measures, so the
+   * three can never collide and the `geometry` handler can dispatch on the id alone.
    */
   pendingMeasures: Map<number, (hits: NodeHit[]) => void>;
   /**
@@ -228,13 +295,7 @@ 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;
-    /** Set when the deferred re-entry is a PROP host rather than a block (see deferEnterEdit). */
-    prop?: string;
-  } | null;
+  pendingEnterEdit: PendingEnterEdit | 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
@@ -250,13 +311,6 @@ interface HostState {
   panReqId: number;
 }
 
-/**
- * Opaque drag-target host handle for the coordinator bridge. The bridge passes it back to the
- * session API ({@link beginDragSession}/{@link hostDragGeometry}/{@link postDragMessage}) without
- * reading its fields.
- */
-export type DragHost = HostState;
-
 const hosts = new WeakMap<HTMLElement, HostState>();
 
 /** Every live host, so the selection watcher can re-measure each one when selection changes. */
@@ -271,7 +325,7 @@ const liveHosts = new Set<HostState>();
 let currentDragSeq = 0;
 
 /** Parent-retained source data keyed by `dragSeq` (the block fragment never crosses the boundary). */
-const retainedSrcData = new Map<number, Record<string, unknown>>();
+const retainedSrcData = new Map<number, RetainedDragData>();
 
 /**
  * The last session whose cursor-carrying `dragOver` arrived FROM an iframe, and when. While a
@@ -421,9 +475,10 @@ export function requestCanvasEval(
   }
   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 }[];
+  /* Expression nodes come off the reactive document — only plain values may cross postMessage.
+     SAFETY: A request's nodes are expression nodes by the caller's contract, and the frame re-checks
+     `operator` before evaluating one (`iframe-eval.ts`), reporting anything else per expression. */
+  const wireExprs = plainCopy(exprs) as { id: string; node: JxExpressionNode }[];
   target.channel.post({
     contextPath: contextPath ? [...contextPath] : null,
     exprs: wireExprs,
@@ -541,7 +596,7 @@ export function liveDragHostAt(cursor: { x: number; y: number }): HostState | nu
 export function beginDragSession(
   host: HostState,
   src: DragSrcKind,
-  srcData: Record<string, unknown>,
+  srcData: RetainedDragData,
 ): number {
   currentDragSeq += 1;
   retainedSrcData.set(currentDragSeq, srcData);
@@ -569,7 +624,7 @@ export function beginDragSession(
 export function adoptDragSession(
   _host: HostState,
   _src: DragSrcKind,
-  srcData: Record<string, unknown>,
+  srcData: RetainedDragData,
   seq: number,
 ): number {
   currentDragSeq = seq;
@@ -587,10 +642,7 @@ export function currentDragSession(): number {
  * read FRESH so a pan/zoom mid-drag is reflected. NOT `effectiveZoom()` (a separate path that can
  * desync). The matching iframe parent-viewport rect is returned so the cursor map cancels the pan.
  */
-export function hostDragGeometry(host: HostState): {
-  scale: number;
-  rect: { left: number; top: number };
-} {
+export function hostDragGeometry(host: HostState): DragGeometry {
   const rect = rectOf(host.iframe);
   const scale = host.iframe.clientWidth > 0 ? rect.width / host.iframe.clientWidth : 1;
   return { rect, scale };
@@ -735,8 +787,8 @@ function measureIn(
   path: readonly (string | number)[],
 ): Promise<CanvasPoint | null> {
   return new Promise((resolve) => {
-    host.selReqId += 1;
-    const reqId = host.selReqId;
+    host.measureSeq += 1;
+    const reqId = host.measureSeq;
     const timer = setTimeout(() => {
       host.pendingMeasures.delete(reqId);
       resolve(null);
@@ -1317,7 +1369,7 @@ export function postDialogOpen(tab: { id: string }, path: JxPath | null): void {
  * `host` is deliberately not a pane-scoped parameter name (see `PANE_PARAM_NAMES`), and the body
  * reads no focus: `panelHostingCanvas` resolves the stage from the host's own element.
  */
-export function postPatchToHosts(forwardOps: WireDocOp[], tabId: string | null): number {
+export function postPatchToHosts(forwardOps: JxDocOp[], tabId: string | null): number {
   let posted = 0;
   for (const host of liveHosts) {
     if (!host.iframe.isConnected) {
@@ -1457,14 +1509,14 @@ function hostTab(state: HostState): Tab | null {
 }
 
 /**
- * The tab a drag TARGET is showing — the one public reader on the opaque {@link DragHost} handle.
+ * The tab a drag TARGET is showing — the one public reader on the opaque {@link HostState} handle.
  *
  * `panels/canvas-dnd-bridge.ts` binds a session to the host under the cursor and then had nothing
  * to ask it, so the one fact it needed about the drag — what the dragged node is CALLED — came from
  * `activeTab`. The bridge is not supposed to read the handle's fields (that is what "opaque"
  * means), so the answer is a function rather than a widened type.
  */
-export function dragHostTab(host: DragHost): Tab | null {
+export function dragHostTab(host: HostState): Tab | null {
   return hostTab(host);
 }
 
@@ -1499,7 +1551,7 @@ function shownSelections(): Map<string, readonly JxPath[]> {
     if (!tab) {
       continue;
     }
-    const sel = (tab.session.selection ?? []) as readonly JxPath[];
+    const sel: readonly JxPath[] = tab.session.selection;
     // Track the selection deeply enough that a change WITHIN the set re-measures: the effect
     // Reads every path, not just the array reference.
     void sel.map((path) => path.join("/")).join("|");
@@ -1679,8 +1731,8 @@ function requestPresence(host: HostState): void {
     host.overlay.setPresence([]);
     return;
   }
-  host.selReqId += 1;
-  host.presenceReqId = host.selReqId;
+  host.measureSeq += 1;
+  host.presenceReqId = host.measureSeq;
   host.channel.post({ kind: "measure", paths, reqId: host.presenceReqId });
 }
 
@@ -1698,12 +1750,14 @@ function requestSelection(host: HostState, sel: readonly JxPath[]): void {
   }
   const primary = primarySelection(sel);
   host.selectionPath = primary;
-  host.selectionPaths = sel as JxPath[];
+  host.selectionPaths = sel;
   if (!host.iframe.isConnected) {
     liveHosts.delete(host);
     return;
   }
   if (!primary) {
+    // Nothing selected, so a reply still in flight answers a question nobody is asking any more.
+    host.selReqId = -1;
     host.coSelectionKeys.clear();
     host.overlay.setSelection(null);
     host.overlay.setCoSelection([]);
@@ -1716,7 +1770,8 @@ function requestSelection(host: HostState, sel: readonly JxPath[]): void {
   // Cross the postMessage boundary.
   const others = cloneSelection(sel.slice(0, -1));
   host.coSelectionKeys = new Set(others.map((path) => JSON.stringify(path)));
-  host.selReqId += 1;
+  host.measureSeq += 1;
+  host.selReqId = host.measureSeq;
   host.channel.post({
     kind: "measure",
     paths: [[...primary], ...others],
@@ -1737,13 +1792,15 @@ function requestStylebookSelection(host: HostState): void {
   const tag = shell.stylebook.selection;
   const cardPath = tag ? host.stylebook?.tagToCardPath.get(tag) : undefined;
   if (!tag || !cardPath) {
+    host.selReqId = -1;
     host.overlay.setSelection(null);
     return;
   }
   if (!host.ready) {
     return;
   }
-  host.selReqId += 1;
+  host.measureSeq += 1;
+  host.selReqId = host.measureSeq;
   host.channel.post({ kind: "measure", paths: [[...cardPath]], reqId: host.selReqId });
 }
 
@@ -1752,9 +1809,9 @@ function requestStylebookSelection(host: HostState): void {
  *
  * This was the literal `/packages/studio/canvas.html` — a repo dev-server path baked into a browser
  * bundle, correct on exactly one host out of four. It happened to work because every other host
- * overrides `canvasUrl`: the chromium launcher builds one from its token, electrobun fetches one
- * over RPC, and the cloud adapter hard-codes its own. So the default was never the default; it was
- * the dev server's URL with nothing saying so.
+ * overrides `canvasUrl`: the chromium launcher builds one from its token and the cloud adapter
+ * hard-codes its own. So the default was never the default; it was the dev server's URL with
+ * nothing saying so.
  *
  * `bundleUrl` resolves it against the ENTRY's directory, which is the one fact every host agrees on
  * (see services/bundle-base.ts), so the fallback is now correct everywhere rather than accidentally
@@ -1764,12 +1821,6 @@ function defaultCanvasUrl(): string {
   return bundleUrl("../canvas.html");
 }
 
-/**
- * Loads nothing, deliberately: what a platform that resolves its canvasUrl LATER gets in the
- * meantime. See {@link StudioPlatform.canvasUrlDeferred}.
- */
-const DEFERRED_CANVAS_URL = "about:blank";
-
 /**
  * Release one host: its channel, its overlay, its frame, and everything awaiting a reply from it.
  *
@@ -1815,27 +1866,12 @@ function releaseHost(host: HostState): void {
   liveHosts.delete(host);
 }
 
-/**
- * Which document this pane's canvas iframe should load.
- *
- * The `canvasUrlDeferred` branch is the one that needs saying. Electrobun resolves its canvasUrl
- * asynchronously — it is this window's loopback port, fetched over RPC inside `activate()` — and
- * until the fix above, the bundle-relative default resolved to nothing servable under `views://`,
- * so an early frame simply failed and `ensureHost` rebuilt against the real URL when it landed. Now
- * that default RESOLVES: `views://studio/canvas.html` is a document electrobun really does stage.
- * An early frame would therefore boot the whole canvas bundle inside the SHELL's app-privileged
- * origin, in a CEF instance running `disable-site-isolation-trials` — and the cross-origin loopback
- * canvas exists precisely so that never happens.
- */
+/** Which document this pane's canvas iframe should load. */
 function resolveCanvasUrl(): string {
   if (!hasPlatform()) {
     return defaultCanvasUrl();
   }
-  const platform = getPlatform();
-  if (platform.canvasUrl) {
-    return platform.canvasUrl;
-  }
-  return platform.canvasUrlDeferred ? DEFERRED_CANVAS_URL : defaultCanvasUrl();
+  return getPlatform().canvasUrl || defaultCanvasUrl();
 }
 
 /**
@@ -1875,9 +1911,8 @@ function ensureHost(canvasEl: HTMLElement): HostState {
     if (existing.canvasUrl === canvasUrl) {
       return existing;
     }
-    // The platform's loopback canvasUrl arrived after this host was built with the default URL
-    // (electrobun resolves it async over RPC) — tear the early iframe down and rebuild against the
-    // Right cross-origin origin.
+    // The platform now reports a different canvasUrl than this host was built with — tear the
+    // Iframe down and rebuild against the right origin.
     releaseHost(existing);
   }
   // ParentOrigin is the parent's real origin, passed into the iframe URL so the cross-origin iframe
@@ -1885,8 +1920,8 @@ function ensureHost(canvasEl: HTMLElement): HostState {
   const parentOrigin = location.origin;
   const token = crypto.randomUUID();
   // IframeOrigin is the iframe's own origin. For a RELATIVE canvasUrl (dev / chromium) it resolves to
-  // The parent's location.origin (same-origin). For an absolute loopback canvasUrl (electrobun) it is
-  // The loopback origin, so the channel accepts/targets the right cross-origin peer.
+  // The parent's location.origin (same-origin). For an absolute canvasUrl it is
+  // That URL's origin, so the channel accepts/targets the right cross-origin peer.
   const iframeOrigin = new URL(canvasUrl, location.href).origin;
   const iframe = document.createElement("iframe");
   iframe.className = "jx-canvas-iframe";
@@ -1895,16 +1930,16 @@ function ensureHost(canvasEl: HTMLElement): HostState {
   iframe.title = "Canvas — live page render";
   iframe.style.cssText =
     "width:100%;min-height:480px;height:100%;border:0;display:block;background:#fff";
-  // Preserve any query already on canvasUrl (e.g. electrobun's ?win=7) and append the token (always)
+  // Preserve any query already on canvasUrl (e.g. a per-window `?win=7`) and append the token (always)
   // Plus parentOrigin (conditionally — see below).
   const srcUrl = new URL(canvasUrl, location.href);
   srcUrl.searchParams.set("token", token);
   // Pass parentOrigin into the iframe src ONLY when the PARENT is served over http(s) (dev / chromium
   // — same-origin, so the origin round-trips and the iframe can keep its acceptOrigin STRICT). For a
-  // Non-http(s) parent (electrobun views://) OMIT it: a custom scheme may not surface as a postMessage
+  // Non-http(s) parent (a custom scheme) OMIT it: a custom scheme may not surface as a postMessage
   // Origin (event.origin), so the iframe falls back to acceptOrigin '*' + the shared token (it logs
   // The warn) rather than silently stalling. The PARENT side here stays STRICT — acceptOrigin /
-  // TargetOrigin are the real (loopback) iframeOrigin below, a gateable origin.
+  // TargetOrigin are the real iframeOrigin below, a gateable origin.
   if (location.protocol === "http:" || location.protocol === "https:") {
     srcUrl.searchParams.set("parentOrigin", parentOrigin);
   }
@@ -1950,6 +1985,7 @@ function ensureHost(canvasEl: HTMLElement): HostState {
     lastHover: null,
     lastSelectionRect: null,
     lastSnapshotSeq: 0,
+    measureSeq: 0,
     overlay,
     panReqId: -1,
     pending: null,
@@ -1965,7 +2001,7 @@ function ensureHost(canvasEl: HTMLElement): HostState {
     ready: false,
     selectionPath: null,
     selectionPaths: [],
-    selReqId: 0,
+    selReqId: -1,
     snapshot: null,
     stylebook: null,
     tabId: null,
@@ -2017,7 +2053,7 @@ function hideInsertZoneNow(state: HostState): void {
  */
 function insertButtonHovered(state: HostState): boolean {
   const btn = state.overlay.insertButton;
-  return state.insertHover || (typeof btn.matches === "function" && btn.matches(":hover"));
+  return state.insertHover || btn.matches(":hover");
 }
 
 /**
@@ -2173,7 +2209,8 @@ function handleMessage(state: HostState, msg: IframeToParent): void {
          behind that message with it. The null check is the same guard for a `targetPath` an edit
          has since invalidated, which threw for the same reason. */
       const target = getNodeAtPath(tab.doc.document, msg.targetPath);
-      if (!target || typeof target !== "object") {
+      // A path can resolve to a string child or to nothing at all, whatever the declared type says.
+      if (!isNodeObject(target)) {
         return;
       }
       if (POPOVER_COMMANDS.has(msg.command)) {
@@ -2359,7 +2396,7 @@ function handleMessage(state: HostState, msg: IframeToParent): void {
         const [hit] = msg.hits;
         if (hit) {
           const { rect: ifr, scale } = hostDragGeometry(state);
-          panToParentRect({ height: hit.rect.height * scale, top: hit.rect.y * scale + ifr.top });
+          revealParentRect({ height: hit.rect.height * scale, top: hit.rect.y * scale + ifr.top });
         }
         return;
       }
@@ -2370,7 +2407,7 @@ function handleMessage(state: HostState, msg: IframeToParent): void {
         // The iframe could not resolve is simply absent from `hits`.
         const primaryKey = JSON.stringify(state.selectionPath);
         const co: OverlayPlacement[] = [];
-        let rect: ParentRect | null = null;
+        let rect: OverlayPlacement | null = null;
         if (state.stylebook) {
           const [hit] = msg.hits;
           rect = hit ? canvasRectToParent(hit.rect) : null;
@@ -2762,9 +2799,8 @@ function handleMessage(state: HostState, msg: IframeToParent): void {
       const { rect: ifr, scale } = hostDragGeometry(state);
       const left = msg.rect.x * scale + ifr.left;
       const top = msg.rect.y * scale + ifr.top;
-      canvasSlashHandler?.show({
+      const request: CanvasSlashRequest = {
         filter: msg.filter,
-        ...(msg.showFilter === true ? { showFilter: true } : {}),
         onDismiss: () => state.channel.post({ kind: "slashDismissed" }),
         onSelect: (cmd) => state.channel.post({ cmd: { ...cmd }, kind: "slashSelect" }),
         rect: {
@@ -2774,7 +2810,11 @@ function handleMessage(state: HostState, msg: IframeToParent): void {
           top,
           width: msg.rect.width * scale,
         },
-      });
+      };
+      if (msg.showFilter === true) {
+        request.showFilter = true;
+      }
+      canvasSlashHandler?.show(request);
       return;
     }
     case "slashNav": {
@@ -2843,6 +2883,7 @@ function onDomUpdated(state: HostState, gen: number): void {
   requestSelection(state, state.selectionPaths);
   requestPresence(state);
   hideInsertZoneNow(state);
+  servePendingStylebookPan(state);
   if (state.pendingEnterEdit && gen >= state.pendingEnterEdit.minGen) {
     const { offset, path, prop } = state.pendingEnterEdit;
     state.pendingEnterEdit = null;
@@ -2871,12 +2912,14 @@ function deferEnterEdit(
   offset?: number,
   prop?: string,
 ): void {
-  state.pendingEnterEdit = {
-    minGen: state.lastRenderedGen,
-    path: [...path],
-    ...(offset === undefined ? {} : { offset }),
-    ...(prop === undefined ? {} : { prop }),
-  };
+  const pending: PendingEnterEdit = { minGen: state.lastRenderedGen, path: [...path] };
+  if (offset !== undefined) {
+    pending.offset = offset;
+  }
+  if (prop !== undefined) {
+    pending.prop = prop;
+  }
+  state.pendingEnterEdit = pending;
 }
 
 /** Ask the host's iframe to (re-)enter inline editing on `path` (a plain copy crosses the bridge). */
@@ -2886,12 +2929,14 @@ function reenterEdit(
   offset?: number,
   prop?: string,
 ): void {
-  state.channel.post({
-    kind: "enterEdit",
-    path: [...path],
-    ...(offset === undefined ? {} : { offset }),
-    ...(prop === undefined ? {} : { prop }),
-  });
+  const enter: EnterEditMsg = { kind: "enterEdit", path: [...path] };
+  if (offset !== undefined) {
+    enter.offset = offset;
+  }
+  if (prop !== undefined) {
+    enter.prop = prop;
+  }
+  state.channel.post(enter);
 }
 
 /**
@@ -2963,7 +3008,7 @@ function drawHover(state: HostState, hit: NodeHit | null): void {
  */
 type PreparedRender = Omit<
   Extract<ParentToIframe, { kind: "render" }>,
-  "colorScheme" | "gen" | "kind"
+  "colorScheme" | "gen" | "kind" | "locale"
 >;
 
 /** One render pass's prepared payloads, by document IDENTITY. */
@@ -3087,11 +3132,9 @@ function preparePassRender(
     // So a JSON round-trip (NOT structuredClone, which would throw) drops residual functions /
     // Reactive proxy artifacts that would otherwise raise DataCloneError and silently drop the
     // Entire message.
-    // oxlint-disable-next-line unicorn/prefer-structured-clone
-    const cloneableDoc = JSON.parse(JSON.stringify(resolved.renderDoc)) as unknown;
+    const cloneableDoc = plainCopy(resolved.renderDoc);
     // The RAW page doc (forward-op + data-jx-path coordinate space) crosses as the shadow doc.
-    // oxlint-disable-next-line unicorn/prefer-structured-clone
-    const cloneableShadow = JSON.parse(JSON.stringify(doc)) as unknown;
+    const cloneableShadow = plainCopy(doc);
     // Which tags can hold a caret depends on the document's vocabulary, so the format's verdicts
     // Ride with the render rather than being baked into the frame. Absent for a native document,
     // Where the studio's own element metadata answers on its own.
@@ -3101,21 +3144,27 @@ function preparePassRender(
     const renderTab = tabId ? (workspace.tabs.get(tabId) ?? null) : null;
     const formatElements = formatByName(renderTab?.doc.sourceFormat)?.studio?.elements;
     const editableTags = formatElements ? formatEditableVerdicts(formatElements) : undefined;
-    return {
+    const prepared: PreparedRender = {
       assets: resolved.assets,
       doc: cloneableDoc,
       docBase: resolved.docBase ?? `${canvasBaseOrigin()}/`,
       mapperCtx: resolved.mapperCtx,
-      /* Still a cast, but no longer a lie: `WireMapperCtx.canvasMode` is typed `string` (it mirrors
-         `PathMapCtx`, which carries the mode for `isEditableMode` and takes `CanvasMode | string`),
-         so this narrows a string to the union. It used to narrow it to a union that did not list
-         `git-diff` while git-diff renders went through here every day. */
+      /* SAFETY: `WireMapperCtx.canvasMode` is typed `string` only because it mirrors `PathMapCtx`,
+         which takes `CanvasMode | string`; `resolveCanvasDocument` fills it with the mode this host
+         was asked to render (`modeOverride ?? canvasModeOfTab(tab)`), and only a canvas mode ever
+         mounts a host. It used to narrow to a union that did not list `git-diff` while git-diff
+         renders went through here every day. */
       mode: resolved.mapperCtx.canvasMode as CanvasMode,
       shadowDoc: cloneableShadow,
       siteStyle: resolved.siteStyle,
-      ...(editableTags ? { editableTags } : {}),
-      ...(allowAutoRequests ? { allowAutoRequests: true } : {}),
     };
+    if (editableTags) {
+      prepared.editableTags = editableTags;
+    }
+    if (allowAutoRequests) {
+      prepared.allowAutoRequests = true;
+    }
+    return prepared;
   });
   byDoc.set(doc, { mode: modeOverride, payload, tabId, viewTabId });
   return payload;
@@ -3180,25 +3229,30 @@ export async function mountIframeCanvas(
     paneOfContainer(canvasEl),
     modeOverride,
   );
-  const message: ParentToIframe = {
+  const message: RenderMsg = {
     ...prepared,
     // Per-TAB, and read at POST time so a scheme flip that raced the shared resolution is not
     // Baked into the payload every host shares. `viewTab` is this artboard's tab — defaulted from
     // `tabOfContainer(canvasEl)`, the same route the rest of this mount takes.
     colorScheme: schemeWireFor(viewTab),
-    /* Per-ARTBOARD, and post-time for a sharper version of the same reason. `preparePassRender`
-       memoizes on the document and hands the SAME payload object to every host in the pass, and a
-       git-diff pass has two hosts holding two documents — but marks are a function of BOTH sides,
-       not of the document this host draws, so they are not derivable from that cache key at all.
-       Baking them in would make the two artboards race for whose marks the pass kept. */
-    ...(diffMarks ? { diffMarks } : {}),
     gen,
     kind: "render",
+    // The language this artboard draws in, per tab and at post time like the scheme.
+    locale: localeWireFor(viewTab),
     // Read at POST time for the same reason `colorScheme` is: a render replaces the DOM, so a panel
     // The author opened before this pass would close under them without it.
     popoverOpen: viewTab?.session.ui.openPopover ?? null,
     dialogOpen: viewTab?.session.ui.openDialog ?? null,
   };
+  /* Diff marks are per-ARTBOARD, and post-time for a sharper version of the colour scheme's
+     reason. `preparePassRender` memoizes on the document and hands the SAME payload object to every
+     host in the pass, and a git-diff pass has two hosts holding two documents — but marks are a
+     function of BOTH sides, not of the document this host draws, so they are not derivable from
+     that cache key at all. Baking them in would make the two artboards race for whose marks the
+     pass kept. */
+  if (diffMarks) {
+    message.diffMarks = diffMarks;
+  }
   state.popoverOpen = message.popoverOpen ?? null;
   state.dialogOpen = message.dialogOpen ?? null;
   // Preview is the fidelity view: no editing messages are honoured from it, no overlay is painted
@@ -3215,14 +3269,27 @@ export async function mountIframeCanvas(
  * until it says `ready`. Counted either way: the message is this pass's work for this host whether
  * or not the frame has finished loading.
  */
-function deliverRender(state: HostState, message: ParentToIframe): void {
+function deliverRender(state: HostState, message: RenderMsg): void {
   canvasPerf.hostRenderPosts += 1;
   if (state.ready) {
     syncAssetVersions(state);
     state.channel.post(message);
-  } else {
-    state.pending = message;
+    return;
+  }
+  /* The queue holds ONE render, and it must be the NEWEST, not the last to arrive. A page render
+     awaits its own resolution, so two renders started in order can finish out of order: on a
+     reload that restores two tabs, the frame is still booting, the first-opened tab's render (an
+     older gen) can resolve after the active tab's, and overwriting the slot posted the stale one
+     on `ready`. The frame drew the other tab's document, the ack adopted that tab's identity, and
+     the active tab's render was lost. A ready frame drops a stale gen itself (`latestGen`); the
+     queue has to make the same call. */
+  const queued = state.pending;
+  if (queued?.kind === "render" && queued.gen > message.gen) {
+    // Never posted, so never acked: its identity must not wait for an ack that cannot come.
+    state.pendingTabIds.delete(message.gen);
+    return;
   }
+  state.pending = message;
 }
 
 /**
@@ -3250,17 +3317,17 @@ export function mountStylebookCanvas(
   state.iframe.style.width = widthPx ? `${widthPx}px` : "100%";
   // Two independent plain clones: the iframe renders `doc` and folds styleUpdates into `shadowDoc`
   // (and fake test channels pass messages by reference, so sharing one object would alias them).
-  // oxlint-disable-next-line unicorn/prefer-structured-clone
-  const cloneableDoc = JSON.parse(JSON.stringify(generated.doc)) as unknown;
-  // oxlint-disable-next-line unicorn/prefer-structured-clone
-  const cloneableShadow = JSON.parse(JSON.stringify(generated.doc)) as unknown;
-  const message: ParentToIframe = {
+  const cloneableDoc = plainCopy(generated.doc);
+  const cloneableShadow = plainCopy(generated.doc);
+  const message: RenderMsg = {
     // The specimen carries no tab identity, but the STAGE it is mounted into does: a stylebook is
     // Opened as a tab like anything else, and its `previewColorScheme` is that tab's.
     /* A stylebook specimen is generated, not a project document, so it references no project
        media and needs no resolution. */
     assets: null,
     colorScheme: schemeWireFor(tabOfContainer(canvasEl)),
+    // And its language, for the same reason: a stylebook draws `:lang()` rules and `dir` too.
+    locale: localeWireFor(tabOfContainer(canvasEl)),
     doc: cloneableDoc,
     docBase: `${canvasBaseOrigin()}/`,
     gen,
@@ -3342,6 +3409,21 @@ export function postColorSchemeToLiveHosts(
  * `dir` is computed here and sent with the tag: `localeDirection` is CLDR's answer through
  * `Intl.Locale`, and a frame deriving it again is a second copy of the RTL script list to keep.
  */
+/** A locale tag as the frame applies it, with its direction; null stays null. */
+function localeWire(locale: string | null): WireLocale | null {
+  return locale === null ? null : { dir: localeDirection(locale), locale };
+}
+
+/**
+ * The language a TAB's artboard draws in, as wire data (studio.md §20.2): the one rule
+ * `getEffectiveRenderLocale` answers, read at post time for `schemeWireFor`'s reason.
+ */
+function localeWireFor(tab: Tab | null): WireLocale | null {
+  return localeWire(
+    tab ? getEffectiveRenderLocale(tab.session.ui.previewLocale, tab.documentPath) : null,
+  );
+}
+
 export function postLocaleToLiveHosts(locale: string | null, root?: HTMLElement | null): void {
   const dir = localeDirection(locale);
   for (const host of liveHosts) {
@@ -3354,6 +3436,12 @@ export function postLocaleToLiveHosts(locale: string | null, root?: HTMLElement
     }
     if (host.ready) {
       host.channel.post({ dir, kind: "setLocale", locale });
+    } else if (host.pending?.kind === "render") {
+      /* A host still booting draws the render it is waiting for, so THAT is what learns the
+         language: a restored session writes `previewLocale` after its files have opened, by which
+         time a pane's render may already be pending with the old value, and no render follows. A
+         host with nothing pending is skipped; its render reads the value when it is posted. */
+      host.pending = { ...host.pending, locale: localeWire(locale) };
     }
   }
 }
@@ -3371,8 +3459,7 @@ export function postLocaleToLiveHosts(locale: string | null, root?: HTMLElement
  * off a tab's reactive record is a proxy, and a proxy cannot be structured-cloned.
  */
 export function postRedefineElementToLiveHosts(doc: JxMutableNode, base: string): number {
-  // oxlint-disable-next-line unicorn/prefer-structured-clone
-  const plain = JSON.parse(JSON.stringify(doc)) as JxMutableNode;
+  const plain = plainCopy(doc);
   let posted = 0;
   for (const host of liveHosts) {
     if (!host.iframe.isConnected) {
@@ -3398,13 +3485,8 @@ export function postSiteStyleToLiveHosts(): void {
     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>;
+  const siteStyle = plainCopy(config.style ?? null);
+  const media = plainCopy(config.$media ?? {});
   for (const host of liveHosts) {
     if (!host.iframe.isConnected) {
       liveHosts.delete(host);
@@ -3422,11 +3504,10 @@ export function postSiteStyleToLiveHosts(): void {
  * received it — zero means no stylebook iframe is live yet and the caller should fall through to a
  * full render. Each post is followed by a selection re-measure so the box tracks the reflow.
  */
-export function postStyleUpdateToStylebookHosts(style: Record<string, unknown>): number {
+export function postStyleUpdateToStylebookHosts(style: JxStyle): number {
   let posted = 0;
   // Style objects come off the reactive doc — only plain values may cross postMessage.
-  // oxlint-disable-next-line unicorn/prefer-structured-clone
-  const cloneable = JSON.parse(JSON.stringify(style)) as Record<string, unknown>;
+  const cloneable = plainCopy(style);
   for (const host of liveHosts) {
     if (!host.iframe.isConnected) {
       liveHosts.delete(host);
@@ -3441,33 +3522,63 @@ export function postStyleUpdateToStylebookHosts(style: Record<string, unknown>):
   return posted;
 }
 
+/**
+ * A pan asked for before any stylebook canvas could serve it: the tag, served by the next stylebook
+ * render that draws its card while it is still the selection ({@link servePendingStylebookPan}).
+ */
+let pendingStylebookPan: string | null = null;
+
+/** Post the measure that pans `host` to `tag`'s card. `false` when the host cannot serve it yet. */
+function postStylebookPan(host: HostState | null, tag: string): boolean {
+  if (!host?.stylebook || !host.ready) {
+    return false;
+  }
+  const cardPath = host.stylebook.tagToCardPath.get(tag);
+  if (!cardPath) {
+    return false;
+  }
+  host.measureSeq += 1;
+  host.panReqId = host.measureSeq;
+  host.channel.post({ kind: "measure", paths: [[...cardPath]], reqId: host.panReqId });
+  return true;
+}
+
 /**
  * Pan the canvas so the selected tag's card is centered (layers-panel "locate" affordance). The
  * card lives inside the iframe, so it is measured over the bridge and the reply pans by the
  * converted parent-viewport rect (see the `geometry` handler's panReqId branch).
+ *
+ * A pan the canvas cannot serve yet is KEPT, not dropped. The Styles panel switches the pane to the
+ * Elements view and selects a tag in one tick, from the Variables view, where no stylebook frame
+ * exists: the frame that will draw the card has not been mounted. The request waits for it.
  */
 export function panToStylebookTag(tag: string): void {
-  const host = hostForActivePanel();
-  if (!host?.stylebook || !host.ready) {
+  pendingStylebookPan = postStylebookPan(hostForActivePanel(), tag) ? null : tag;
+}
+
+/**
+ * Serve a kept pan on a stylebook render that has just landed: on the canvas the author is in, and
+ * only while its tag is still the selection, so a request the author has since moved past is
+ * forgotten rather than served late.
+ */
+function servePendingStylebookPan(state: HostState): void {
+  const tag = pendingStylebookPan;
+  if (tag === null || !state.stylebook) {
     return;
   }
-  const cardPath = host.stylebook.tagToCardPath.get(tag);
-  if (!cardPath) {
+  if (shell.stylebook.selection !== tag) {
+    pendingStylebookPan = null;
     return;
   }
-  host.selReqId += 1;
-  host.panReqId = host.selReqId;
-  host.channel.post({ kind: "measure", paths: [[...cardPath]], reqId: host.selReqId });
+  if (state === hostForActivePanel() && postStylebookPan(state, tag)) {
+    pendingStylebookPan = null;
+  }
 }
 
 // ─── Format-toolbar bridge (Phase 4b-2) ─────────────────────────────────────────
 
-/** The current edit session's editing flag + latest selection snapshot, for the parent toolbar. */
-export function getEditSnapshot(): {
-  editing: boolean;
-  editingProp: string | null;
-  snapshot: SelectionSnapshot | null;
-} {
+/** The current edit session's state, for the parent toolbar. */
+export function getEditSnapshot(): EditSnapshotState {
   /* The same connectivity guard {@link isCaretActive} has, and for the same reason: a session
      belongs to a frame, and a frame that has left the document has no caret in it. `releaseHost`
      clears `activeEditHost`, so this is the second line rather than the first — it covers the frame
@@ -3578,7 +3689,7 @@ export function commitActiveEditSession(): void {
 /** The live host backing the active panel's canvas (for non-edit selection-bar positioning). */
 function hostForActivePanel(): HostState | null {
   const panel = getActivePanel();
-  return panel ? hostForCanvas(panel.canvas as HTMLElement) : null;
+  return panel ? hostForCanvas(panel.canvas) : null;
 }
 
 /**
@@ -3592,7 +3703,7 @@ function hostForActivePanel(): HostState | null {
  * (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 {
+export function getEditBarAnchorRect(): OverlayPlacement | null {
   // The bar rests on the SELECTED ELEMENT's box, edit session or not. It used to prefer the caret's
   // Snapshot rect while editing, so it hopped line to line with the caret and sat over the text the
   // Author was typing; the snapshot still feeds the format state, never the position. Only an edit