@jxsuite/studio 2.2.2 → 2.3.0

package/src/panels/layers-panel.ts

@@ -742,7 +742,15 @@ export function onTreeKeydown(
  */
 export function startLayerTitleEdit(path: JxPath, rerender: () => void) {
   const key = pathKey(path);
-  const row = document.querySelector(`.layer-row[data-path="${key}"]`);
+  /* Scoped to THIS panel's tree, and escaped, through the same helper every other row lookup in
+     this file uses. The predecessor was a bare `document.querySelector` with the key interpolated
+     raw, which is wrong twice over: a second pane — or the stylebook, which draws a layer tree of
+     its own — puts more than one `.layer-row[data-path=…]` in the document, and the first match
+     wins rather than the right one; and an unescaped key containing a quote or a bracket is not a
+     selector the parser accepts, so a legitimately-named node throws instead of renaming.
+     `_outlineList` is null before the first render, which is the same "row the window does not
+     hold" case the reveal-and-repaint path below already handles. */
+  const row = _outlineList ? rowElementFor(_outlineList, key) : null;
   if (!row) {
     // Renaming through a command (⌘↵, the palette, the block bar) can name a row the window does
     // Not hold. Scroll to it and repaint; the row exists on the next pass, and the caller's own

package/src/panels/panel-registry.ts

@@ -83,7 +83,6 @@ export interface NavigatorPanelDeps {
   registerLayersDnD: () => void;
   registerElementsDnD: () => void;
   registerComponentsDnD: () => void;
-  setupTreeKeyboard: (tree: HTMLElement) => void;
   registerFileTreeDnD: (ctx: { renderLeftPanel: () => void }) => void;
   setGitDiffState: (state: GitDiffState | null) => void;
   cloneRepository?: () => void;

package/src/panels/properties-panel.ts

@@ -544,7 +544,7 @@ function renderLinkTargetField(node: JxMutableNode, path: JxPath) {
     <sp-picker
       class="link-target-kind"
       size="s"
-      value=${kind}
+      .value=${live(kind)}
       @change=${(e: Event) => {
         const nextKind = (e.target as HTMLInputElement).value as LinkKind;
         // Switching kind reinterprets the current value under the new kind.
@@ -566,7 +566,7 @@ function renderLinkTargetField(node: JxMutableNode, path: JxPath) {
       <sp-picker
         class="link-target-value"
         size="s"
-        value=${value}
+        .value=${live(value)}
         @change=${(e: Event) => commit("internal", (e.target as HTMLInputElement).value)}
       >
         ${knownValue ? html`<sp-menu-item value=${value}>${value}</sp-menu-item>` : nothing}
@@ -624,7 +624,7 @@ function renderTargetField(node: JxMutableNode, path: JxPath, entry: HtmlMetaEnt
       <sp-picker
         class="link-target-window"
         size="s"
-        value=${current}
+        .value=${live(current)}
         @change=${(e: Event) =>
           transactDoc(activeTab.value!, (t) =>
             mutateUpdateAttribute(

package/src/panels/settings-pane.ts

@@ -18,7 +18,7 @@
  * `settings/settings-document.ts`, which the app loads when it registers its commands.
  *
  * Nothing here is stamped with a region of its own. `#canvas-wrap` already carries `pane.primary`
- * (`ui/regions.ts`'s `SHELL_REGION_HOSTS`), the entry rows and the entry editor are stamped by
+ * (the frame, `shell/tree.ts`), the entry rows and the entry editor are stamped by
  * `settings/contributed-section.ts` as `pane.primary/entry:<key>` and `pane.primary/editor`, and a
  * third id for "the settings body" would be a hand-stamped region with nothing to say.
  *

package/src/panels/style-panel.ts

@@ -1215,7 +1215,7 @@ function styleSidebarTemplate(
       return html`
         <sp-accordion-item
           label=${sec.label}
-          .open=${isOpen}
+          .open=${live(isOpen)}
           @sp-accordion-item-toggle=${(e: Event) => {
             activeTab.value!.session.ui.styleSections = {
               ...activeTab.value!.session.ui.styleSections,
@@ -1235,7 +1235,7 @@ function styleSidebarTemplate(
   const customSectionT = html`
     <sp-accordion-item
       label="Custom"
-      .open=${customIsOpen}
+      .open=${live(customIsOpen)}
       @sp-accordion-item-toggle=${(e: Event) => {
         activeTab.value!.session.ui.styleSections = {
           ...activeTab.value!.session.ui.styleSections,
@@ -1319,7 +1319,7 @@ function styleSidebarTemplate(
       ? html`
           <sp-accordion-item
             label="Relative Styling"
-            .open=${nestedIsOpen}
+            .open=${live(nestedIsOpen)}
             @sp-accordion-item-toggle=${(e: Event) => {
               activeTab.value!.session.ui.styleSections = {
                 ...activeTab.value!.session.ui.styleSections,

package/src/panels/stylebook-panel.ts

@@ -14,6 +14,7 @@
  */
 
 import { html, render as litRender } from "lit-html";
+import { repeat } from "lit-html/directives/repeat.js";
 import { ref } from "lit-html/directives/ref.js";
 import { classMap } from "lit-html/directives/class-map.js";
 import { live } from "lit-html/directives/live.js";
@@ -169,7 +170,15 @@ export function renderStylebookMode(surface: CanvasSurface, ctx: StylebookCtx) {
           }
         })}
       >
-        ${panelEntries.map((e) => e.tpl)}
+        ${repeat(
+          panelEntries,
+          /* Keyed on mediaName. Each entry owns a canvas IFRAME, and the breakpoint set changes
+             with the project's media definitions — so position-based reuse hands one breakpoint's
+             iframe to another's width. That is a live document rendered at the wrong viewport,
+             not a cosmetic diff. */
+          (e) => e.panel.mediaName,
+          (e) => e.tpl,
+        )}
       </div>
     `,
     /** @type {HTMLElement} */ canvasWrap,

package/src/panels/toolbar.ts

@@ -644,7 +644,7 @@ function dockTogglesTpl(registry: CommandRegistry) {
 /**
  * Mount the Command Bar.
  *
- * @param rootEl The `#toolbar` host, stamped `commandbar` by `stampShellRegions()`.
+ * @param rootEl The `#toolbar` host, stamped `commandbar` by the frame (`shell/tree.ts`).
  * @param _ctx Ignored — see {@link ToolbarCtx}.
  */
 export function mount(rootEl: HTMLElement, _ctx: ToolbarCtx = {}) {

package/src/services/bundle-base.ts

@@ -0,0 +1,69 @@
+/**
+ * Where the studio bundle was loaded from — the one fact a shipped asset can be located against.
+ *
+ * `import.meta.url` is NOT that fact, and the difference has been shipping a silent bug. Only the
+ * two ENTRIES are guaranteed to be emitted at `dist/<name>.js` (studio.md §11.1 — four consumers
+ * address those paths literally, so they are never hashed). Every other module is subject to
+ * `splitting: true` and may be hoisted into a content-hashed chunk under `dist/chunks/` — and
+ * `services/monaco-setup` was, by the code-split in 78d85ba2. Its `new URL("workers/…",
+ * import.meta.url)` therefore resolved against `dist/chunks/`, while all three distribution paths
+ * stage the workers beside the ENTRY. Verified in the built output: the string `workers/` appears
+ * in `dist/chunks/monaco-setup-<hash>.js` and in neither `dist/studio.js` nor
+ * `dist/iframe-entry.js`, and `dist/chunks/workers/` does not exist.
+ *
+ * The failure mode is why this is worth a module rather than a comment: a Monaco worker that 404s
+ * takes the whole JSON language service with it — no schema validation, no completion, no hover —
+ * and reports nothing. Nobody sees a red anything.
+ *
+ * So the entries publish their own location and everything else reads it. The base is the entry's
+ * DIRECTORY, so `bundleUrl("workers/json.worker.js")` lands beside the entry on every host without
+ * the host being asked for anything: `/packages/studio/dist/` on the repo dev server,
+ * `views://studio/dist/` in the packaged app, `/__studio__/dist/` on the desktop loopback server,
+ * and whatever prefix a cloud host staged the tree under.
+ *
+ * **Only an entry may call {@link setBundleBase}.** `tests/entry-anchors.test.ts` enforces both
+ * halves — that both entries call it, and that no other module under `src/` so much as mentions
+ * `import.meta.url` — because the next refactor that moves a module into a chunk must not be able
+ * to reintroduce this quietly.
+ */
+
+/** The entry's directory, with a trailing slash. `undefined` until an entry sets it. */
+let base: string | undefined;
+
+/**
+ * Record the calling ENTRY's own URL. Call as `setBundleBase(import.meta.url)`, first statement
+ * after the imports, from `src/studio.ts` or `src/canvas/iframe-entry.ts` only.
+ *
+ * @param entryUrl The entry module's `import.meta.url`.
+ */
+export function setBundleBase(entryUrl: string): void {
+  // Directory, not file: `new URL("./", <file url>)` strips the last segment.
+  base = new URL("./", entryUrl).href;
+}
+
+/**
+ * Resolve a path relative to the bundle's own directory.
+ *
+ * Throws rather than guessing, because its predecessor's whole problem was failing silently: an
+ * unset base means an entry did not run, and a URL invented here would 404 somewhere the user
+ * cannot see.
+ *
+ * @param path Bundle-relative path, e.g. `workers/json.worker.js` or `../canvas.html`.
+ * @returns Absolute URL.
+ * @throws {Error} When no entry has called {@link setBundleBase}.
+ */
+export function bundleUrl(path: string): string {
+  if (base === undefined) {
+    throw new Error(
+      `bundleUrl(${JSON.stringify(path)}) before setBundleBase(). An entry module ` +
+        `(src/studio.ts or src/canvas/iframe-entry.ts) must call setBundleBase(import.meta.url) ` +
+        `first; a test needs tests/with-dom.ts, which sets one.`,
+    );
+  }
+  return new URL(path, base).href;
+}
+
+/** Test seam: forget the recorded base. Not called by application code. */
+export function resetBundleBase(): void {
+  base = undefined;
+}

package/src/services/monaco-setup.ts

@@ -80,6 +80,7 @@ import "monaco-editor/languages/definitions/javascript/register";
 import { flattenSchema } from "@jxsuite/schema/project-schemas";
 import jxSchema from "@jxsuite/schema/schema.json";
 import projectSchema from "@jxsuite/schema/project-schema.json";
+import { bundleUrl } from "./bundle-base";
 
 /* Re-exported for the modules that already imported it from here. New callers should reach for
    `./model-uri` directly — it is Monaco-free, and importing this module loads the editor. */
@@ -93,28 +94,33 @@ const WORKER_FILES: Record<string, string> = {
 };
 
 /**
- * Resolve a Monaco worker to the PRE-BUNDLED copy that ships NEXT TO this bundle — `workers/`
+ * Resolve a Monaco worker to the PRE-BUNDLED copy that ships NEXT TO THE ENTRY — `dist/workers/`
  * beside `dist/studio.js`, written by scripts/build-workers.ts.
  *
- * Self-location via `import.meta.url` (Bun emits it verbatim for browser targets) is what makes one
- * expression correct on every host, because none of them agree on a prefix and two of them cannot
- * be served by one: the repo dev server mounts the shell at `/packages/studio/index.html`, the
- * packaged desktop app at `views://studio/index.html`, the desktop loopback server under
- * `/__studio__/`, and the cloud at `/edit/:owner/:repo@:branch` — a DEEP path, so even a
- * document-relative URL would resolve into the wrong directory there. The only invariant is the
- * bundle's own location.
+ * Self-location is what makes one expression correct on every host, because none of them agree on a
+ * prefix and two of them cannot be served by one: the repo dev server mounts the shell at
+ * `/packages/studio/index.html`, the packaged desktop app at `views://studio/index.html`, the
+ * desktop loopback server under `/__studio__/`, and a cloud host under whatever prefix it staged
+ * the tree at. The only invariant is the bundle's own location.
  *
- * A root-absolute `/monaco-editor/esm/vs/...` (what this used to emit) resolved on exactly one of
- * them, the repo dev server, which serves bare specifiers out of the monorepo's `node_modules`.
- * Everywhere else it 404s — and a Monaco worker that fails to start takes the whole JSON language
- * service with it: no schema validation, no completion, no hover, and no error the user can see.
+ * **But `import.meta.url` is not that location, and this function used to think it was.** It is
+ * THIS MODULE's url, and since the code-split (78d85ba2) this module is emitted into
+ * `dist/chunks/monaco-setup-<hash>.js` — so the expression resolved to `chunks/workers/<name>`, a
+ * directory that has never existed in any distribution. Only the two entries have a contractual
+ * emitted path (studio.md §11.1), which is exactly what `services/bundle-base` records.
+ *
+ * The bug this closes is invisible by construction, which is why it survived: a Monaco worker that
+ * 404s takes the whole JSON language service with it — no schema validation, no completion, no
+ * hover — and surfaces no error at all. The same silence covered the predecessor of the
+ * `import.meta.url` form, a root-absolute `/monaco-editor/esm/vs/...` that resolved on the repo dev
+ * server alone.
  *
  * @param {string} label - Monaco worker label ("json", "typescript", …)
  * @returns {string} Absolute URL of the worker bundle
  */
 export function workerUrl(label: string): string {
   const file = WORKER_FILES[label] || WORKER_FILES.editorWorkerService!;
-  return new URL(`workers/${file}`, import.meta.url).href;
+  return bundleUrl(`workers/${file}`);
 }
 
 self.MonacoEnvironment = {

package/src/shell/tree.ts

@@ -0,0 +1,155 @@
+/**
+ * The shell's mount tree — the one definition of what the application frame IS.
+ *
+ * It was `index.html`'s body, and, in drifted copies, the body of twenty-three test files. The copy
+ * in `tests/studio-shell-fixture.ts` had lost `#resize-bottom`, `#bottom-dock` and `#layer-toast`,
+ * so every shell-boot test ran against a shell with no bottom dock and no toast host — a difference
+ * no test could report, because the fixture WAS the thing under test.
+ *
+ * Nothing here is dynamic: `mountShellTree()` renders once at boot, before `initShellRefs()` adopts
+ * the hosts, and each region then renders into its own host through its own effect (see
+ * studio-ui-guidelines.md §9.3). It is a lit template rather than a string because that makes the
+ * region attributes bindings the tree owns, and because the twenty-three test files can now ask for
+ * the real shell instead of describing one.
+ */
+
+import { html, render as litRender } from "lit-html";
+import type { TemplateResult } from "lit-html";
+
+/**
+ * Render a frame template into `host`, surviving a host that was emptied since the last mount.
+ *
+ * `textContent = ""` (or `innerHTML = ""`) removes the comment nodes lit uses as a ChildPart's
+ * markers but leaves lit's private `_$litPart$` reference behind, so the next render reuses a part
+ * whose markers are detached from the DOM and throws — or, worse, quietly renders nothing. Test
+ * fixtures clear the body between cases constantly, and the app does the same thing to a stage on
+ * every mode transition; `canvas/canvas-render.ts`'s hardClearCanvasWrap carries the same ejection
+ * for the same reason.
+ *
+ * Mounting is a one-shot, so ejecting unconditionally costs nothing and makes it idempotent.
+ */
+function mountInto(host: ParentNode, tpl: TemplateResult): void {
+  /* Both halves, in this order. Clearing alone leaves lit's private part reference pointing at
+     comment markers that are no longer in the document, so the next render throws or paints
+     nothing. Ejecting alone leaves the OLD nodes in place and lit starts a fresh part beside them,
+     so a second mount produces two frames rather than one. */
+  (host as HTMLElement).textContent = "";
+  // @ts-expect-error -- _$litPart$ is lit's private render-part marker, not in the DOM types
+  delete (host as HTMLElement)["_$litPart$"];
+  litRender(tpl, host as HTMLElement);
+}
+
+/**
+ * The four overlay layers that `ui/layers.ts` renders into, in stacking order.
+ *
+ * Exported apart from {@link shellTree} because it is the piece a unit test usually wants alone
+ * (through `mountOverlayLayers` in the test harness) — twenty fixtures were describing this set by
+ * hand, and they had already stopped agreeing: most carried three layers and one carried four, so
+ * whether a toast host existed at all depended on which test file you happened to be in.
+ */
+export function overlayLayers(): TemplateResult {
+  return html`
+    <!-- The four overlay layers, in stacking order. Their z-indices were inline style
+       attributes, which put the one piece of ordering the whole overlay system depends on
+       outside the reach of check-styles.ts's stacking rule — the check that exists because a
+       blocking progress modal once shipped above its own scrim with no reachable exit. They are
+       classes in styles/overlays.css now, and the toast host is ABOVE the dialog host because
+       an operation started from a dialog reports its outcome to the person still looking at
+       it. -->
+    <div id="layer-popover" class="jx-layer jx-layer--popover"></div>
+    <div id="layer-modal" class="jx-layer jx-layer--modal"></div>
+    <div id="layer-dialog" class="jx-layer jx-layer--dialog"></div>
+    <!-- role="status" sits on the HOST, so a stack of toasts is announced as one live region
+       rather than one region per notification. It carries its region id whether or not a toast
+       has ever been raised: a region that only exists once something has gone wrong is one a
+       screenshot cannot address and focus cannot be moved into. -->
+    <div
+      id="layer-toast"
+      class="jx-layer jx-layer--toast"
+      role="status"
+      aria-live="polite"
+      data-jx-region="overlay.toasts"
+    ></div>
+  `;
+}
+
+/**
+ * The application frame: the Spectrum theme wrapper, the app grid, and the four overlay layers.
+ *
+ * The theme's three attributes are BINDINGS rather than literals, and that is not decoration. A
+ * literal lives in the template lit clones with `importNode`, and cloning a registered custom
+ * element makes the DOM fire `attributeChangedCallback` before its constructor has run — Spectrum's
+ * Theme then reaches for `_provideSystemContext` and finds nothing. A binding is applied after the
+ * element exists. `shell.ts` overwrites `color` on the first theme effect anyway, so the literal
+ * was never the source of truth.
+ *
+ * Region ids are stamped HERE. They used to live in a selector-to-id map in `ui/regions.ts`, whose
+ * comment gave the reason plainly — these were "bare `<div id>` in index.html, so it cannot stamp
+ * itself". A template can, so the map is gone and the id sits on the element it names.
+ */
+export function shellTree(): TemplateResult {
+  return html`
+    <div id="app">
+      <div id="toolbar" data-jx-region="commandbar"></div>
+      <!-- The PANE GRID (studio.md §18.1). One cell per pane, each holding that pane's own strip,
+             jump bar, chrome layer and stage — the four surfaces that used to be flat siblings of
+             THIS grid, which is to say application rows that only ever described one pane. There is
+             nothing to see here in markup: panels/pane-grid.ts reconciles the cells against
+             workspace.panes, because how many there are is a fact about the workspace and a
+             single div can only ever be one of them. -->
+      <div id="pane-grid"></div>
+      <div id="activity-bar" data-jx-region="rail"></div>
+      <div id="left-panel" data-jx-region="navigator"></div>
+      <div id="resize-left" class="resize-handle"></div>
+      <!-- The Bottom dock (⌘J). It sits in the PANE's column, under the stage and above the
+             status bar, so opening it never narrows the Navigator or the Inspector (studio.md §12
+             region ⑪). Its handle resizes on the other axis; panels/bottom-dock.ts stamps
+             dock.bottom on this host while it is open, and nothing while it is closed. -->
+      <div id="resize-bottom" class="resize-handle resize-handle-row"></div>
+      <div id="bottom-dock"></div>
+      <div id="resize-right" class="resize-handle"></div>
+      <!-- The Inspector dock. Four tabs — Content · Style · Logic · Assistant (studio.md §12
+             region ⑨) — all inside this one host. -->
+      <div id="right-panel" data-jx-region="inspector"></div>
+      <!-- The app's only status channel: announce what lands in it (studio.md §12 region ⑫). -->
+      <div id="statusbar" role="status" aria-live="polite" data-jx-region="statusbar"></div>
+    </div>
+    ${overlayLayers()}
+  `;
+}
+
+/**
+ * Render {@link shellTree} into `host`.
+ *
+ * The entry calls this once, before `initShellRefs()`. Tests call it instead of pasting an
+ * approximation of the frame — which is the whole reason it is a function.
+ *
+ * @param host Where the frame goes. Defaults to the document body.
+ */
+export function mountShellTree(host: ParentNode = document.body): void {
+  mountInto(themeHost(host), shellTree());
+}
+
+/**
+ * The Spectrum theme wrapper, created once and reused.
+ *
+ * It is NOT part of {@link shellTree}, and the reason is a real constraint rather than taste. lit
+ * instantiates a template by cloning it with `importNode`, and cloning a registered custom element
+ * enqueues its `attributeChangedCallback` before the constructor body has run — Spectrum's Theme
+ * then reaches for a field it assigns in that body and throws. `createElement` runs the constructor
+ * first, so the attributes are safe to set afterwards.
+ *
+ * `shell.ts` rewrites `color` on the first theme effect, so the value here is only the first frame.
+ */
+function themeHost(host: ParentNode): HTMLElement {
+  const existing = host.querySelector?.("sp-theme");
+  if (existing) {
+    return existing as HTMLElement;
+  }
+  const theme = document.createElement("sp-theme");
+  theme.setAttribute("color", "dark");
+  theme.setAttribute("scale", "medium");
+  theme.setAttribute("system", "spectrum");
+  (host as HTMLElement).append(theme);
+  return theme;
+}

package/src/shell.ts

@@ -24,7 +24,6 @@
 import { effect, effectScope, reactive } from "./reactivity";
 import { loadedMonaco } from "./services/monaco-lazy";
 import { applyStartupProfile } from "./services/profile";
-import { stampShellRegions } from "./ui/regions";
 import { workspace } from "./workspace/workspace";
 import { captureSession, readSession } from "./workspace/session";
 import type { PersistedSession } from "./workspace/session";
@@ -1044,7 +1043,6 @@ export function mountShell(): void {
   }
   // The six shell hosts are bare `<div id>`s in index.html, so they cannot stamp their own region
   // The way a panel or an overlay slot does. One table, applied once the tree exists.
-  stampShellRegions();
   // The Bottom dock mounts from here rather than from the bootstrap because it is a DOCK: it is
   // Projected onto the grid by the same record and the same effect as the other two, and a second
   // Mounting site would be a second place the shell's own layout is decided. Every surface's own

package/src/studio.ts

@@ -112,7 +112,6 @@ import {
   openLastSessionOrHome,
   registerFileTreeDnD,
   reloadCleanTab,
-  setupTreeKeyboard,
 } from "./files/files";
 import { startFsSync } from "./files/fs-events";
 import { invalidateParamValues } from "./page-params";
@@ -233,6 +232,24 @@ import { convertToComponent } from "./editor/convert-to-component";
 import type { GitDiffState } from "./types";
 import type { Tab } from "./tabs/tab";
 import type { JxMutableNode, ProjectConfig } from "@jxsuite/schema/types";
+import { setBundleBase } from "./services/bundle-base";
+import { mountShellTree } from "./shell/tree";
+
+/**
+ * Anchor every shipped-asset URL to THIS module's directory.
+ *
+ * Only an ENTRY may do this, and it must be an entry: `splitting: true` may hoist any other module
+ * into a content-hashed chunk under `dist/chunks/`, where `import.meta.url` means something else
+ * entirely. That is not hypothetical — it is the bug this call fixes, in `services/monaco-setup`.
+ * `tests/entry-anchors.test.ts` holds the line in both directions.
+ *
+ * Placed before any other statement so nothing can read the base before it exists. In ESM the
+ * entry's body runs AFTER its whole static import graph, so a module that called `bundleUrl()`
+ * during evaluation would still throw — deliberately, and loudly. Nothing does today: Monaco is
+ * reached only through the dynamic `services/monaco-lazy`, and `workerUrl` runs inside
+ * `MonacoEnvironment.getWorker`.
+ */
+setBundleBase(import.meta.url);
 
 void _swc;
 
@@ -419,6 +436,10 @@ mountResizeEdges();
 
 // ─── Render loop ──────────────────────────────────────────────────────────────
 
+/* The application frame, before anything adopts a host out of it. index.html carries an empty body
+   and this is the only definition — see src/shell/tree.ts for what that fixed. */
+mountShellTree();
+
 initShellRefs();
 // One effect projects the dock record onto the shell grid — collapse classes and column widths.
 mountShell();
@@ -815,7 +836,6 @@ leftPanelMod.mount({
   setGitDiffState: (state: GitDiffState | null) => {
     shell.git.diffState = state;
   },
-  setupTreeKeyboard,
   webdata,
 });
 

package/src/types.ts

@@ -166,6 +166,21 @@ export interface StudioPlatform {
    * "desktop"`, but only chromium sets this.
    */
   canvasUrl?: string;
+  /**
+   * True when this platform resolves {@link canvasUrl} ASYNCHRONOUSLY.
+   *
+   * Electrobun does: the url is this window's loopback port, fetched over RPC inside `activate()`.
+   * Until the canvas fallback was anchored to the bundle it did not matter — the old literal
+   * `/packages/studio/canvas.html` resolved to nothing servable under `views://`, so an early frame
+   * simply failed and the host rebuilt when the real url landed. Now the fallback RESOLVES:
+   * `views://studio/canvas.html` is a document electrobun really stages. An early frame would 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
+   * cannot happen. Declaring it makes the host wait instead.
+   *
+   * Not keyed on `id`: chromium and electrobun both report `"desktop"`, and only electrobun defers.
+   */
+  canvasUrlDeferred?: boolean;
   activate: (root?: string) => Promise<void>;
   openProject: () => Promise<{
     config: ProjectConfig;

package/src/ui/regions.ts

@@ -285,54 +285,19 @@ export function focusRegionOf(el: Element | null): FocusRegion | null {
 
 // ─── Stamping ─────────────────────────────────────────────────────────────────
 
-/**
- * The shell's fixed hosts, declared once.
- *
- * These live in `index.html` as bare `<div id>`s, so they cannot stamp themselves the way a panel
- * or an overlay slot does. The table is the shell's own layout stated in region terms, and it is
- * the only place a surface id is written down by hand.
- *
- * `#tab-strip` is addressed as `pane.primary/tabs` deliberately: the region names the PANE's strip,
- * so the id survives the node. The assistant is the case that has now happened twice over:
- * `inspector.assistant` was minted while the chat was a fifth grid column, survived the column
- * being deleted, and survives the `#chat-panel` DIV being deleted too — it is stamped by
- * `panels/chat-panel.ts` on whatever container hosts the assistant, which is now the Inspector's
- * fourth tab body. That is the whole argument for naming the role rather than the div, and the
- * reason this table lost a row without any shot losing its subject.
+/*
+ * There is no SHELL_REGION_HOSTS map here any more, and no stampShellRegions().
  *
- * `pane.primary/frontmatter` left the table for the same reason. It named `#frontmatter-panel`, a
- * grid row; the Document Header card is now drawn INSIDE the stage, so
- * `panels/frontmatter-panel.ts` stamps the id on the card's own `<section>` wherever the stage puts
- * it. Two rows gone, no shot re-pointed.
+ * It existed because the shell's hosts were bare `<div id>` elements in index.html — the map's
+ * own comment said so: it "cannot stamp itself". The frame is a lit template now
+ * (`src/shell/tree.ts`), so each id sits on the element it names, and a selector-to-id map beside
+ * it would be a second definition of the same fact — which is the thing moving the frame into code
+ * was for. `tests/shell-tree.test.ts` asserts the frame's ids parse and resolve uniquely, which is
+ * what the map used to guarantee by construction.
  *
- * `pane.primary` and `pane.primary/tabs` are the third and fourth to leave, and the clearest case
- * yet: they named `#canvas-wrap` and `#tab-strip`, two flat siblings of an APPLICATION grid that
- * were only ever the primary pane's stage and strip. `panels/pane-grid.ts` builds a cell per pane
- * and stamps {@link paneRegion} on each, so the id is derived from the pane rather than from a div
- * that could only ever be one of them. Four rows gone, not one shot re-pointed.
+ * A surface that is NOT part of the frame stamps its own id from its own template, which is what
+ * the derived helpers below are for.
  */
-export const SHELL_REGION_HOSTS: Readonly<Record<string, string>> = {
-  "#activity-bar": "rail",
-  // The fourth overlay layer. It is here rather than stamped by `ui/layers.ts` for the same reason
-  // Every other row is: it is a bare `<div id>` in index.html, so it cannot stamp itself, and the
-  // Id has to resolve whether or not a toast has ever been raised — a region that only exists once
-  // Something has gone wrong is a region a shot cannot address and focus cannot be moved into.
-  "#layer-toast": "overlay.toasts",
-  "#left-panel": "navigator",
-  "#right-panel": "inspector",
-  "#statusbar": "statusbar",
-  "#toolbar": "commandbar",
-};
-
-/**
- * Stamp the shell hosts. Idempotent, and safe to call before the DOM exists (an absent host is
- * simply not stamped — the desktop shell and the tests both boot partial trees).
- */
-export function stampShellRegions(root: ParentNode = document): void {
-  for (const [selector, id] of Object.entries(SHELL_REGION_HOSTS)) {
-    root.querySelector(selector)?.setAttribute(REGION_ATTR, id);
-  }
-}
 
 /**
  * Region id for a pane, or for a part inside one — derived from the pane's own id.

package/styles/overlays.css

@@ -2702,3 +2702,38 @@
 .settings-locale-routing {
   max-width: 320px;
 }
+
+/* ─── Overlay layers ───────────────────────────────────────────────────────
+   The four full-viewport hosts `ui/layers.ts` renders into, in stacking order.
+   Their z-indices were inline `style` attributes on four divs in index.html,
+   which put the one piece of ordering the whole overlay system depends on
+   outside `check-styles.ts`'s stacking rule — the rule that exists because a
+   blocking progress modal shipped above its own scrim with no reachable exit.
+   `src/shell/tree.ts` emits these classes; the ordering is reviewable here.
+
+   Each layer is inert until something is rendered into it: `pointer-events`
+   is none on the host, and each slot `ui/layers.ts` appends turns it back on
+   for itself. */
+.jx-layer {
+  position: fixed;
+  inset: 0;
+  pointer-events: none;
+}
+
+.jx-layer--popover {
+  z-index: 1000;
+}
+
+.jx-layer--modal {
+  z-index: 2000;
+}
+
+.jx-layer--dialog {
+  z-index: 3000;
+}
+
+/* Above the dialog layer, deliberately: an operation started from a dialog
+   reports its outcome to the person who is still looking at the dialog. */
+.jx-layer--toast {
+  z-index: 4000;
+}