@jxsuite/studio 6.1.2 → 8.0.1

package/src/canvas/iframe-drop.ts

@@ -46,6 +46,93 @@ const VOID_TAGS = new Set([
   "wbr",
 ]);
 
+/**
+ * Phrasing content (HTML's content model) that is NOT also an embedded or interactive block an
+ * author drops as its own block: text-level elements. Only these may land inside a paragraph. An
+ * image, a video and a component are phrasing by the letter of HTML, but a card dragged from the
+ * Site panel onto a paragraph means "put it here", not "glue it into this sentence": in Markdown
+ * the latter serialises as an inline directive or image stuck to the text.
+ */
+const TEXT_LEVEL_TAGS = new Set([
+  "a",
+  "abbr",
+  "b",
+  "bdi",
+  "bdo",
+  "br",
+  "cite",
+  "code",
+  "data",
+  "del",
+  "dfn",
+  "em",
+  "i",
+  "ins",
+  "kbd",
+  "mark",
+  "q",
+  "s",
+  "samp",
+  "small",
+  "span",
+  "strong",
+  "sub",
+  "sup",
+  "time",
+  "u",
+  "var",
+  "wbr",
+]);
+
+/** Elements whose content model is phrasing only: a block dropped inside one breaks it. */
+const PHRASING_HOSTS = new Set([
+  ...TEXT_LEVEL_TAGS,
+  "button",
+  "dt",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "label",
+  "legend",
+  "p",
+  "pre",
+  "summary",
+]);
+
+/** A node's tag, lower-cased, `div` when it names none. */
+function tagOf(node: JxMutableNode | null | undefined): string {
+  return (displayTagName(node?.tagName) || "div").toLowerCase();
+}
+
+/** Whether the dragged thing is text-level content, which may be placed inside a paragraph. */
+function isTextLevelSource(src: DragSrcKind, shadowDoc: JxMutableNode): boolean {
+  const tag = src.type === "block" ? (src.tag ?? "") : tagOf(getNodeAtPath(shadowDoc, src.path));
+  return TEXT_LEVEL_TAGS.has(tag.toLowerCase());
+}
+
+/**
+ * The outermost phrasing host at or above `el` (the paragraph around a `<strong>`), or null when
+ * `el` is in none. A block is placed beside that host, never inside it.
+ */
+function phrasingHostOf(el: HTMLElement, shadowDoc: JxMutableNode): HTMLElement | null {
+  let host: HTMLElement | null = null;
+  let current: HTMLElement | null = el;
+  while (current) {
+    const path = parseJxPath(current.dataset.jxPath ?? "");
+    if (path.length === 0) {
+      break;
+    }
+    if (PHRASING_HOSTS.has(tagOf(getNodeAtPath(shadowDoc, path)))) {
+      host = current;
+    }
+    current = nearestPathEl(current.parentElement);
+  }
+  return host;
+}
+
 /**
  * Walk up from an element to the nearest ancestor carrying a `data-jx-path`. Refactored out of the
  * `nearestHit` walk (iframe-interaction.ts) to take an element directly so the hit-test adapter can
@@ -122,6 +209,26 @@ export function computeDropInstruction(
     return null;
   }
 
+  /* A block over a paragraph (or anything inside one) lands above or below the paragraph: a
+     component or an image nested in a `<p>` is serialised glued to its text. */
+  const host = isTextLevelSource(src, shadowDoc) ? null : phrasingHostOf(targetEl, shadowDoc);
+  if (host) {
+    const hostPath = parseJxPath(host.dataset.jxPath ?? "");
+    if (!canDrop(src, hostPath)) {
+      return null;
+    }
+    const hostRect = rectFor(host);
+    const hostRelY = hostRect.height === 0 ? 0 : (cursorY - hostRect.y) / hostRect.height;
+    return hostRelY < 0.5
+      ? { edge: "top", instruction: "reorder-above", referenceRect: hostRect, targetPath: hostPath }
+      : {
+          edge: "bottom",
+          instruction: "reorder-below",
+          referenceRect: hostRect,
+          targetPath: hostPath,
+        };
+  }
+
   const node = getNodeAtPath(shadowDoc, targetPath);
   const tag = (displayTagName(node?.tagName) || "div").toLowerCase();
   const hasElementChildren =

package/src/canvas/iframe-entry.ts

@@ -12,6 +12,8 @@ import {
   applyCanvasDialogOpen,
   applyCanvasPopoverOpen,
   applyPreviewColorScheme,
+  applyPreviewLocale,
+  captureLocaleBaseline,
   applySiteStyle,
   installCanvasImageRetry,
   renderResolvedDocument,
@@ -54,9 +56,11 @@ import {
   redefineElement,
   resetDocumentStyles,
   setCanvasAssetResolver,
+  setNpmModuleResolver,
   setResolveToken,
 } from "@jxsuite/runtime";
 import { resolveAssetRef } from "./asset-resolve";
+import { npmModuleUrl } from "./npm-modules";
 import type { AssetContext } from "./asset-resolve";
 import { KIT_LOADERS } from "@jxsuite/ui/loaders";
 import type { CanvasEnvelope, IframeChannel } from "./iframe-channel";
@@ -92,6 +96,14 @@ for (const [specifier, load] of Object.entries(KIT_LOADERS)) {
   preloadModule(specifier, load);
 }
 
+/*
+ * A document's `npm:` sidecar, from the package the project installed. The build bundles one
+ * (`compiler/src/site/bundler.ts`); this frame asks the dev server, which bundles
+ * `/node_modules/<package>/<subpath>` on demand through the package's own `exports`, the URL space
+ * `registerElements` already imports a bare `$elements` specifier from.
+ */
+setNpmModuleResolver((specifier) => npmModuleUrl(specifier, location.href));
+
 /**
  * Resolve the drop placement for a forwarded cursor: point hit-test → nearest `[data-jx-path]` →
  * pure {@link computeDropInstruction}. Returns null when the cursor resolves to no droppable target.
@@ -300,6 +312,8 @@ export function startCanvasIframe(opts: {
   // Alongside the handle so a superseded render's refs can't keep posting.
   let stopDataScopeWatch: (() => void) | null = null;
   let latestGen = -1;
+  // The root's language as the frame booted it, which a render with no language goes back to.
+  const localeBaseline = captureLocaleBaseline(container.ownerDocument);
   // The raw page doc the current DOM was rendered from — the patch source-of-truth. `renderedGen`
   // Tracks which generation it (and the DOM) reflect, so patches for an in-flight/superseded render
   // Are handled correctly rather than applied against the wrong tree.
@@ -963,17 +977,12 @@ export function startCanvasIframe(opts: {
       /* The other document-level attribute flip, and the whole visible half of an axis-3 locale:
          `dir` is what makes an RTL preview actually mirror, and `lang` is what CSS's `:lang()` and
          the font stack select on. Patch-free like the scheme above — the TEXT is whatever file is
-         open, because a translation in Jx is a different file rather than a different rendering.
-         Cleared rather than blanked when the pane goes back to the document's own language: an
-         empty `lang=""` is a document that claims to be in no language at all. */
-      const root = container.ownerDocument.documentElement;
-      if (msg.locale === null) {
-        root.removeAttribute("lang");
-        root.removeAttribute("dir");
-      } else {
-        root.setAttribute("lang", msg.locale);
-        root.setAttribute("dir", msg.dir);
-      }
+         open, because a translation in Jx is a different file rather than a different rendering. */
+      applyPreviewLocale(
+        container.ownerDocument,
+        msg.locale === null ? null : { dir: msg.dir, locale: msg.locale },
+        localeBaseline,
+      );
       return;
     }
     if (msg.kind === "siteStyleUpdate") {
@@ -985,6 +994,7 @@ export function startCanvasIframe(opts: {
       return;
     }
     applyPreviewColorScheme(container.ownerDocument, msg.colorScheme ?? null);
+    applyPreviewLocale(container.ownerDocument, msg.locale ?? null, localeBaseline);
     // A render replaces the DOM under a live edit session — COMMIT it first (never discard). The
     // Resulting editCommit/editEnd post synchronously here, so on the FIFO channel they precede
     // This render's renderComplete and the parent routes them by the host's not-yet-flipped tab
@@ -1080,6 +1090,8 @@ export function startCanvasIframe(opts: {
   channel.post({ kind: "ready" });
   return () => {
     off();
+    // Leave the root as it booted, so a frame started after this one captures the same baseline.
+    applyPreviewLocale(container.ownerDocument, null, localeBaseline);
     stopInteraction();
     stopKeyForwarding();
     stopInlineEdit();
@@ -1127,7 +1139,7 @@ export function bootCanvasIframe(win: BootWindow): () => void {
   setResolveToken(params.get("rpcToken"));
   // ParentOrigin authenticates the parent peer. The host (iframe-host.ts) passes it ONLY for an
   // Http(s) parent (dev / chromium — same-origin, the origin round-trips). It OMITS it for a
-  // Non-http(s) parent (electrobun views://), whose custom scheme may not surface as a postMessage
+  // Non-http(s) parent (a custom scheme), whose custom scheme may not surface as a postMessage
   // Origin: a missing value here means fall back to "*" — token-gated, NOT a silent omission — and
   // Log it loudly so the looser origin check is visible.
   const explicitParentOrigin = params.get("parentOrigin");

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";
@@ -67,7 +67,9 @@ import type {
   SerializableRect,
   SerializedKey,
   SyncedChord,
+  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";
@@ -136,9 +138,8 @@ export interface HostState {
   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;
@@ -154,7 +155,21 @@ export interface HostState {
   selectionPath: (string | number)[] | null;
   /** The whole selection this host last measured, so a re-measure redraws every box. */
   selectionPaths: readonly JxPath[];
-  /** Id of the most recent selection `measure` request, so stale `geometry` replies are dropped. */
+  /**
+   * 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
@@ -162,7 +177,7 @@ export 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 }>;
@@ -270,8 +285,8 @@ export 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>;
   /**
@@ -772,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);
@@ -1716,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 });
 }
 
@@ -1741,6 +1756,8 @@ function requestSelection(host: HostState, sel: readonly JxPath[]): void {
     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([]);
@@ -1753,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],
@@ -1774,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 });
 }
 
@@ -1789,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
@@ -1801,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.
  *
@@ -1852,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();
 }
 
 /**
@@ -1912,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
@@ -1922,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";
@@ -1932,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);
   }
@@ -1987,6 +1985,7 @@ function ensureHost(canvasEl: HTMLElement): HostState {
     lastHover: null,
     lastSelectionRect: null,
     lastSnapshotSeq: 0,
+    measureSeq: 0,
     overlay,
     panReqId: -1,
     pending: null,
@@ -2002,7 +2001,7 @@ function ensureHost(canvasEl: HTMLElement): HostState {
     ready: false,
     selectionPath: null,
     selectionPaths: [],
-    selReqId: 0,
+    selReqId: -1,
     snapshot: null,
     stylebook: null,
     tabId: null,
@@ -2397,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;
       }
@@ -2884,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;
@@ -3008,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. */
@@ -3237,6 +3237,8 @@ export async function mountIframeCanvas(
     colorScheme: schemeWireFor(viewTab),
     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,
@@ -3267,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;
 }
 
 /**
@@ -3304,13 +3319,15 @@ export function mountStylebookCanvas(
   // (and fake test channels pass messages by reference, so sharing one object would alias them).
   const cloneableDoc = plainCopy(generated.doc);
   const cloneableShadow = plainCopy(generated.doc);
-  const message: ParentToIframe = {
+  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,
@@ -3392,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) {
@@ -3404,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) };
     }
   }
 }
@@ -3484,23 +3522,57 @@ export function postStyleUpdateToStylebookHosts(style: JxStyle): number {
   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) ─────────────────────────────────────────

package/src/canvas/iframe-keys.ts

@@ -56,6 +56,17 @@ import type { IframeToParent, ParentToIframe, SerializedKey, SyncedChord } from
  */
 export const FRAME_KEY_SCOPES = ["caret", "canvas", "global"] as const;
 
+/**
+ * Commands whose chords the frame never forwards, though their scope is on its stack.
+ *
+ * `pane.backToHome` holds bare Escape in the global scope, and it applies only to a view opened
+ * beside a strip-less workspace's home (a media viewer, a comparison, `project.json` as Code), none
+ * of which is a canvas frame. Projected into the table, it made every frame cancel Escape in
+ * Preview and mid-sentence too, where nothing else claims it, so an author's own `<dialog>` or
+ * popover in the rendered page could no longer be dismissed with it.
+ */
+export const HOST_ONLY_COMMANDS: ReadonlySet<string> = new Set(["pane.backToHome"]);
+
 /** The scope stack a caret session is in — app chords still fire, element-level ones do not. */
 const CARET_STACK = ["caret", "global"] as const;
 /** The stack with a selection but no caret: structural verbs are live. */