@jxsuite/studio 2.2.2 → 2.4.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/platforms/cloud.ts

@@ -223,6 +223,15 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
     id: "cloud",
     projectRoot: root,
     canvasUrl: "/canvas.html",
+    /* The projectRoot here is the IDENTIFIER "owner/repo@branch", not a served path, so the canvas's
+       default base — <origin>/<projectRoot>/ — addressed nothing. Every component $ref fetch landed
+       on the SPA fallback, which answers the marketing page at HTTP 200, so res.ok passed and the
+       runtime's res.json() died on "Unexpected token '<'". Images failed the same way, silently.
+       The session serves the project tree at /raw.
+
+       Conditional because `base` is "" until a project is bound, and "/raw/" would be a confident
+       wrong answer — worse than the default, which at least fails visibly. */
+    ...(base ? { documentBaseUrl: `${base}/raw/` } : {}),
     /* Open Project routes through Studio's repo picker (write-access repos via listRepos +
        importProject) — sessions are URL-bound, so openProject() below never opens a dialog. */
     openProjectPicker: "repo-list",

package/src/services/ai-models.ts

@@ -24,6 +24,7 @@ let cache: AiModel[] | null = null;
 let proxyConfigured = false;
 let proxyManaged = false;
 let proxyDefaultModel = "";
+let proxyCode: AiModelsResponse["code"];
 
 /**
  * One-shot capability probe shared by every credentials gate, plus the hosts to repaint when it
@@ -39,7 +40,8 @@ export function invalidateModelCache() {
   proxyConfigured = false;
   proxyManaged = false;
   proxyDefaultModel = "";
-  /* The probe's result IS the three flags above. Clearing them while keeping the settled promise
+  proxyCode = undefined;
+  /* The probe's result IS the flags above. Clearing them while keeping the settled promise
      would strand every gate on a permanent "unconfigured, unmanaged" reading — ensureProxyProbe
      would no-op forever and the managed option would vanish until a full reload. */
   proxyProbe = null;
@@ -91,6 +93,16 @@ export function isManagedProxy(): boolean {
   return proxyManaged;
 }
 
+/**
+ * Why the proxy reported itself unconfigured, when it said so.
+ *
+ * Undefined on any backend that does not send one — every gate must treat that as "no reason given"
+ * and fall back to the plain connect wording.
+ */
+export function proxyStateCode(): AiModelsResponse["code"] {
+  return proxyCode;
+}
+
 /** The proxy's preferred model id ("" when it does not declare one). */
 export function getProxyDefaultModel(): string {
   return proxyDefaultModel;
@@ -161,6 +173,7 @@ export async function fetchAvailableModels(
   proxyConfigured = data.configured === true;
   proxyManaged = data.managed === true;
   proxyDefaultModel = data.defaultModel ?? "";
+  proxyCode = data.code;
   cache = (data.models || []).map((m) => ({ id: m.id, name: m.name || m.id }));
   return cache;
 }

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,38 @@ 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;
+  /**
+   * Base URL the canvas fetches PROJECT FILES from — component `$ref`s, `$src` modules, images.
+   *
+   * The renderer resolves a `$ref` with `fetch(url).then(r => r.json())` from inside the iframe, so
+   * project files have to exist at a URL, not merely behind {@link readFile}. Hosts that serve the
+   * project tree from their web root need no value here: the default is `<canvas
+   * origin>/<projectRoot>/`, which is what the dev server and the desktop loopback both already
+   * answer.
+   *
+   * A host whose project files are NOT at a URL-shaped `projectRoot` must set this. Jx Cloud is
+   * one: its `projectRoot` is the identifier `owner/repo@branch`, nothing served the tree, and
+   * every `$ref` fetch landed on the SPA fallback — which answers HTML at **200**, so `res.ok`
+   * passed and the parse died on `Unexpected token '<'`. Images failed the same way in silence.
+   *
+   * Must end in `/`; a project-relative path is appended to it verbatim.
+   */
+  documentBaseUrl?: string;
   activate: (root?: string) => Promise<void>;
   openProject: () => Promise<{
     config: ProjectConfig;

package/src/ui/ai-managed-connect.ts

@@ -24,6 +24,7 @@ import {
   fetchAvailableModels,
   isManagedProxy,
   isProxyConfigured,
+  proxyStateCode,
 } from "../services/ai-models";
 
 export interface ManagedConnectOptions {
@@ -91,17 +92,31 @@ export function createManagedConnect(opts: ManagedConnectOptions): ManagedConnec
     if (!canOffer()) {
       return nothing;
     }
+    /*
+     * A lapsed grant and a fresh one get different words. The backend distinguishes them because
+     * "connect" is an invitation and "reconnect" is an explanation — and on a managed platform the
+     * lapsed case is the common one: a Cloudflare access token lives an hour.
+     */
+    const lapsed = proxyStateCode() === "cf_reconnect_required";
+    const busyLabel = lapsed ? "Reconnecting…" : "Connecting…";
     return html`
-      <div class="ai-managed-connect">
-        <div>Use Workers AI on your own Cloudflare account — no API key needed.</div>
+      <div class="ai-managed-connect" data-jx-recommended="cloudflare">
+        <div class="ai-managed-connect-lede">
+          ${
+            lapsed
+              ? "Your Cloudflare connection has expired. Reconnect to keep using the assistant."
+              : "Recommended — run the assistant on Workers AI in your own Cloudflare account. No API key to create, copy or rotate."
+          }
+        </div>
         <sp-button
           size="s"
+          variant="accent"
           ?disabled=${busy}
           @click=${() => {
             void connect();
           }}
         >
-          ${busy ? "Connecting…" : "Connect Cloudflare"}
+          ${busy ? busyLabel : lapsed ? "Reconnect Cloudflare" : "Connect Cloudflare"}
         </sp-button>
         ${connectError ? html`<div class="ai-managed-connect-error">${connectError}</div>` : nothing}
         <div class="ai-managed-connect-divider">— or bring your own key —</div>