@jxsuite/studio 5.2.0 → 5.4.0

package/src/studio.ts

@@ -12,6 +12,7 @@
  * registration) on first use by source mode, the function editor, or the formula workspace.
  */
 import { errorMessage } from "@jxsuite/schema/parse";
+import { installModulePreloadBatcher } from "./services/module-preloads";
 import { getPanel } from "./panels/panel-registry";
 
 import {
@@ -54,7 +55,7 @@ import {
 
 import { isEditing } from "./editor/inline-edit";
 import { applyTransform, registerCanvasViewCommands } from "./canvas/canvas-utils";
-import { diffCommands } from "./canvas/diff-toolbar";
+import { diffCommands, setDiffChromeRepaint } from "./canvas/diff-toolbar";
 import type { CanvasSurface } from "./canvas/canvas-surface";
 import {
   initCanvasRender,
@@ -106,8 +107,8 @@ import {
   setDocumentSavedListener,
 } from "./files/file-ops";
 import { serializeDocument } from "./files/serialize-document";
-import { parseJsonDocument } from "./files/json-layout";
-import type { JsonLayout } from "./files/json-layout";
+import { parseJsonDocument } from "@jxsuite/schema/json-layout";
+import type { JsonLayout } from "@jxsuite/schema/json-layout";
 import {
   formatForPath,
   loadFormats,
@@ -153,7 +154,7 @@ import { seedPublishConnected } from "./publish/publish-panel";
 
 import { getPlatform, hasPlatform, registerPlatform } from "./platform";
 import { parseMediaEntries } from "./utils/canvas-media";
-import { resolveDefaultPlatform } from "./platforms/default-platform";
+import { PlatformUnavailableError, resolveDefaultPlatform } from "./platforms/default-platform";
 import { mountResizeEdges } from "./resize-edges";
 import {
   defBadgeLabel,
@@ -265,7 +266,12 @@ import type { GitDiffState } from "./types";
 import type { Tab } from "./tabs/tab";
 import type { JxDocument, JxMutableNode, ProjectConfig } from "@jxsuite/schema/types";
 import { setBundleBase } from "./services/bundle-base";
-import { mountShellTree } from "./shell/tree";
+import { mountBootFailureTree, mountShellTree } from "./shell/tree";
+
+// The bundler's `<link rel=modulepreload>` batching is installed on the module scope: before the
+// First lazy `import()` of any surface that runs, so the palette's first open does not pay a
+// Document recalculation per chunk (see the module's header for the trace that asked for this).
+installModulePreloadBatcher();
 
 /**
  * Anchor every shipped-asset URL to THIS module's directory.
@@ -382,9 +388,9 @@ function setCanvasMode(tab: Tab | null, mode: string) {
  *
  * Four deliberate properties, three of them new and each with a failure behind it:
  *
- * 1. **To the side.** §8.2 has promised this since P3 and it never shipped — the chain ran
- *    `openFileInTab` → `openTab` → `activePane()`, so "open the layout that wraps this page" opened
- *    it ON TOP of the page it was teaching about.
+ * 1. **To the side.** §14.2 says so, the shell redesign had promised it since its chrome phase, and it
+ *    never shipped — the chain ran `openFileInTab` → `openTab` → `activePane()`, so "open the
+ *    layout that wraps this page" opened it ON TOP of the page it was teaching about.
  * 2. **The focus FOLLOWS.** The open is a gesture, not a read: the author asked to edit the component,
  *    so the pane it lands in takes the keyboard. The failure it replaces is the opposite one — an
  *    assistant pane that takes the keyboard means the author's next keystroke edits the definition
@@ -447,8 +453,24 @@ initCssData(webdata);
 // Register the default platform adapter (PAL) if none was pre-registered (desktop registers its own
 // On window.__jxPlatform). resolveDefaultPlatform picks cloud when the shell signalled it, creating
 // The cloud adapter inside THIS bundle so collab shares studio's single yjs, else the dev server.
+//
+// Unless a launcher was declared or announced and registered nothing: then there is no adapter to
+// Pick, and resolveDefaultPlatform throws rather than hand a desktop window the dev-server adapter
+// (what 5.0.0-5.1.3 did — a frame that drew, and a first click that said "Failed to fetch"). The
+// Boot-failure screen is drawn INSTEAD of the frame, and the error is rethrown because ESM has no
+// Top-level return: stopping the module is the only way to keep every line below from running
+// Against no platform, and the uncaught error is the console's copy of what the screen says.
+// Nothing above this line may call getPlatform(), or it would throw first with a message about
+// Registration order instead of this one.
 if (!hasPlatform()) {
-  registerPlatform(resolveDefaultPlatform());
+  try {
+    registerPlatform(resolveDefaultPlatform());
+  } catch (error) {
+    if (error instanceof PlatformUnavailableError) {
+      await mountBootFailureTree(error.refusal);
+    }
+    throw error;
+  }
 }
 
 mountResizeEdges();
@@ -504,6 +526,9 @@ paneContext.mount(primaryCell?.chrome ?? document.createElement("div"), {
   parseMediaEntries,
   setCanvasMode,
 });
+/* The diff's Visual/Code switch decides whether the zoom pod is drawn, and the half it writes is
+   not reactive — so the switch repaints the chrome as well as the stage. See `setDiffChromeRepaint`. */
+setDiffChromeRepaint(paneContext.render);
 
 overlaysPanel.mount({
   isEditing,
@@ -605,7 +630,7 @@ export function hasUnsavedTabs(): boolean {
 }
 
 window.addEventListener("beforeunload", (e: BeforeUnloadEvent) => {
-  // The session, so a relaunch reopens what was open (§4.4). Before the prompt, not after: the
+  // The session, so a relaunch reopens what was open (§14.8). Before the prompt, not after: the
   // Author may cancel the close, and the record is the same either way.
   flushSession();
   if (hasUnsavedTabs()) {
@@ -661,11 +686,10 @@ initWelcome({
     }
   },
   cloneRepository: () => cloneRepository({ openRecentProject }),
-  openNewProject: async (options) => {
-    const result = await openNewProjectModal(options);
-    if (result) {
-      void openRecentProject(result.root);
-    }
+  // The wizard adopts what it creates itself now (new-project-modal.ts's finishCreated) — there is
+  // Nothing left for the welcome screen to do with the result.
+  openNewProject: (options) => {
+    void openNewProjectModal(options);
   },
   openProject: () => openProject(),
   openRecentProject: (root: string) => openRecentProject(root),
@@ -886,7 +910,7 @@ registerRenderer("chatPanel", () => chatPanelMod.render());
 registerRenderer("overlays", () => overlaysPanel.render());
 renderStatusbar();
 mountStatusbar();
-// ⑥ The jump bar, in the pane's own grid cell above the context bar. It renders the whole address
+// The jump bar, in the pane's own grid cell above the context bar. It renders the whole address
 // — project › file › node › node — and it is the only breadcrumb in the shell: the pane context
 // Bar drew a second one, and it named a sub-document stack nothing could push onto.
 mountJumpBar(primaryCell?.jump ?? document.createElement("div"));
@@ -1050,7 +1074,7 @@ if (_projectParam) {
          *
          * A named document is an instruction and wins, whether it came from `?file=` or from a
          * `?project=` that pointed INTO the project. A bare `?project=<dir>` is "open this
-         * project", and what that means is the documents it was last left with (§4.4) — the
+         * project", and what that means is the documents it was last left with (§14.8) — the
          * `project.json → home page` redirect below is the answer this replaces.
          *
          * This branch opens inline and never went near `openHomePage`, so it was the one door of
@@ -1124,7 +1148,7 @@ if (_projectParam) {
           render();
           // Opening a file is stated by the tab strip and the status bar's DOCUMENT field.
         }
-        /* This window may now write its session (§4.4). The `?file=` branch above opens inline and
+        /* This window may now write its session (§14.8). The `?file=` branch above opens inline and
            never reaches `openLastSessionOrHome`, which is the other place that says this — so
            without it a window opened at a named file would restore other windows' sessions and
            never record its own. */
@@ -1471,11 +1495,11 @@ commandRegistry.registerAll(derivationCommands(derivationDeps));
 /*
  * The rest of the app's contribution points, each defined beside the state it writes.
  *
- * This block is the bootstrap's whole share of plan §13's registry work: every record below lives
- * in the module that implements it, and this is the ONE place that composes them into the registry
- * `__jxAutomation.run` projects. Nothing here decides what a command is called, when it is
- * available or what it does — that would be the second definition site the design exists to
- * prevent (plan §2, principle 1).
+ * This block is the bootstrap's whole share of the registry work (§13, §13.5): every record below
+ * lives in the module that implements it, and this is the ONE place that composes them into the
+ * registry `__jxAutomation.run` projects. Nothing here decides what a command is called, when it is
+ * available or what it does — that would be the second definition site the design exists to prevent
+ * (§13).
  */
 registerShellViewCommands(commandRegistry, {
   // The registry's own answer, so a gated-off panel cannot be persisted as a showing tab.
@@ -1562,11 +1586,11 @@ registerGridViewCommands(commandRegistry);
 registerRedirectsCommands(commandRegistry);
 registerAboutCommands(commandRegistry);
 registerCollabCommands(commandRegistry);
-/* The `Assistant:` family (§11.1) — Focus Composer, New Chat, Chat History, Attach Selection, Retry
-   and Stop. Every one existed as a button in the chat view and as nothing else, so the category held
-   zero records and none of them was in the palette, bindable, or reachable by name. The chat header
-   and the error row render these ids through the registry now, which is what makes this line the
-   definition site rather than a second copy. */
+/* The `Assistant:` family (`ai.md` §3.0) — Focus Composer, New Chat, Chat History, Attach
+   Selection, Retry and Stop. Every one existed as a button in the chat view and as nothing else, so
+   the category held zero records and none of them was in the palette, bindable, or reachable by
+   name. The chat header and the error row render these ids through the registry now, which is what
+   makes this line the definition site rather than a second copy. */
 commandRegistry.registerAll(assistantCommands());
 /*
  * The structural selection verbs — Move Up/Down/In/Out, Convert to Component, Edit Component.

package/src/style/live-preview.ts

@@ -1,14 +1,14 @@
 /**
  * Pushing a project-style edit to every live canvas — one definition site.
  *
- * Plan §9.4's promise is "tune a design token and watch the page change", and until now that was
- * true of exactly one kind of canvas. `postSiteStyleToLiveHosts` skips stylebook hosts by
- * construction ({@link file://../canvas/iframe-host.ts}: `host.ready && !host.stylebook`), because
- * a specimen canvas does not render the site sheet — it renders a GENERATED document whose root
- * carries the transposed effective style, and its live channel is `styleUpdate`, not
- * `siteStyleUpdate`. So a token edited in the token editor reached every page canvas immediately
- * and left the Project Styles canvas — the one the plan puts _beside_ the editor — showing the old
- * palette until something forced a full re-render.
+ * §7.1's promise is that tuning a token shows the page changing, and until now that was true of
+ * exactly one kind of canvas. `postSiteStyleToLiveHosts` skips stylebook hosts by construction
+ * ({@link file://../canvas/iframe-host.ts}: `host.ready && !host.stylebook`), because a specimen
+ * canvas does not render the site sheet — it renders a GENERATED document whose root carries the
+ * transposed effective style, and its live channel is `styleUpdate`, not `siteStyleUpdate`. So a
+ * token edited in the token editor reached every page canvas immediately and left the Project
+ * Styles canvas — the one §7.1 puts _beside_ the editor — showing the old palette until something
+ * forced a full re-render.
  *
  * Two hosts, two messages, one event. Every surface that writes `projectConfig.style` calls this
  * instead of picking one of the two posts, which is the only arrangement in which the pair cannot

package/src/style/project-styles.ts

@@ -3,13 +3,12 @@
  *
  * ## The name and the wire value are different things
  *
- * The surface a user reaches is called **Project Styles** (plan §9.4). The canvas view it opens is
- * the string `"stylebook"`, a member of `CANVAS_MODES` in
- * {@link file://../canvas/iframe-protocol.ts} and therefore half of a `ParentToIframe` union: the
- * studio bundle and `dist/iframe-entry.js` agree on it, and changing it means rebuilding both in
- * lockstep. So it is not a name and may never be renamed to follow one.
- * {@link PROJECT_STYLES_TITLE} is the name; {@link PROJECT_STYLES_VIEW} is the wire value; a
- * surface that needs one must not reach for the other.
+ * The surface a user reaches is called **Project Styles** (§7.1). The canvas view it opens is the
+ * string `"stylebook"`, a member of `CANVAS_MODES` in {@link file://../canvas/iframe-protocol.ts}
+ * and therefore half of a `ParentToIframe` union: the studio bundle and `dist/iframe-entry.js`
+ * agree on it, and changing it means rebuilding both in lockstep. So it is not a name and may never
+ * be renamed to follow one. {@link PROJECT_STYLES_TITLE} is the name; {@link PROJECT_STYLES_VIEW}
+ * is the wire value; a surface that needs one must not reach for the other.
  *
  * ## One vocabulary for the `@` blocks
  *
@@ -19,7 +18,7 @@
  * {@link TokenContext} list so a surface cannot grow a second override path for the second kind (a
  * per-scheme writer and a per-media writer that disagreed about pruning an emptied block is exactly
  * what this replaces). Contexts are **defined** in Project Settings › Contexts and only selected or
- * overridden here — §2 principle 5.
+ * overridden here — §6.2.
  *
  * On-disk format is unchanged by anything in this module: it reads and writes the same
  * `style["--token"]` and `style["@--ctx"]["--token"]` shapes the compiler already consumes.
@@ -55,7 +54,7 @@ export interface TokenGroup {
 
 /**
  * The groups, in order. `other` is rendered only when something lands in it — a bucket named
- * "Other" over an empty list teaches nothing (§2 principle 6).
+ * "Other" over an empty list teaches nothing (`studio-ui-guidelines.md` §11.1).
  *
  * A group is a name and a prefix and nothing else. The example values an add row hints with are a
  * property of the FORM, not of the model, and they live beside the form that shows them.

package/src/style/token-ref.ts

@@ -5,8 +5,8 @@
  * text says so only to a reader who already knows CSS: `var(--color-brand)` is eleven characters of
  * syntax around a name, and the thing the author actually wants to know — _which_ token, and what
  * it currently resolves to — is the part that is not shown. So a bound value renders as a **chip**
- * (plan §9.4), in the same vocabulary as the provenance chips shipped in P5: the token's friendly
- * name, and for a colour, its resolved swatch.
+ * in the same vocabulary as the provenance chips (§6.7): the token's friendly name, and for a
+ * colour, its resolved swatch.
  *
  * The resolver follows a chain of references, because an alias token (`--color-accent:
  * var(--color-brand)`) is the normal way a palette is built and a chip that stopped at the first

package/src/surfaces/about.json

@@ -59,9 +59,11 @@
       "color": "var(--fg-dim)"
     },
     "& [part=\"meta-value\"]": {
+      "$description": "One of the two places in the chrome that opt back in to selection (`STYLING.md` §Text selection). The root sets `user-select: none` and `styles/tokens.json` restates it on every modal `dialog`, but this dialog's body IS its message: the version, the build date, the commit and the channel exist to be pasted into a bug report, and Studio offers no copy action for them.",
       "margin": "0",
       "color": "var(--fg)",
-      "wordBreak": "break-word"
+      "wordBreak": "break-word",
+      "userSelect": "text"
     },
     "& [part=\"links\"]": {
       "display": "flex",
@@ -99,10 +101,12 @@
       "gap": "4px"
     },
     "& [part=\"package-row\"]": {
+      "$description": "Selectable for the same reason `meta-value` is, and on the ROW rather than on the version alone: what a reader pastes is the pair, `@jxsuite/ai 0.37.0`, so a drag has to be able to cross from the name to the number and on down the list.",
       "display": "flex",
       "justifyContent": "space-between",
       "gap": "12px",
-      "fontSize": "var(--jx-text-md)"
+      "fontSize": "var(--jx-text-md)",
+      "userSelect": "text"
     },
     "& [part=\"package-name\"]": {
       "color": "var(--fg-dim)"

package/src/surfaces/add-repo.json

@@ -113,10 +113,10 @@
       "color": "var(--danger)"
     },
     "& [part=\"access\"]": {
-      "$description": "The listing is bounded by what the Jx Suite GitHub App was granted, so the dialog always offers a way out of that boundary rather than only saying the list is short.",
+      "$description": "The listing is bounded by what the Jx Suite GitHub App was granted, so the dialog always offers a way out of that boundary rather than only saying the list is short. `center`, not `baseline`: the `Refresh` beside the note is a small kit button, and a small kit control is layout-contained so its outset hit area adds nothing to a scrolling ancestor's overflow, which leaves it with no baseline to export; a baseline row would synthesise one from its bottom edge and drop the note and the links onto it. surface-baseline-rows.test.ts holds the rule for every surface.",
       "display": "flex",
       "flexWrap": "wrap",
-      "alignItems": "baseline",
+      "alignItems": "center",
       "gap": "var(--jx-space-2)",
       "paddingTop": "var(--jx-space-3)",
       "borderTop": "1px solid var(--border)",

package/src/surfaces/add-repo.ts

@@ -187,8 +187,8 @@ export function openAddRepoSurface(options: AddRepoSurfaceOptions): AddRepoSurfa
     setFilter: (value: string) => {
       /* What the control holds, first and unconditionally. A binding only writes when the scope
          CHANGES, so a surface that decided a value without announcing the raw one would leave the
-         field showing text the scope does not have (§9.3). Nothing refuses a filter today; the echo
-         is what makes a refusal possible at all. */
+         field showing text the scope does not have (`studio-ui-guidelines.md` §9.3). Nothing
+         refuses a filter today; the echo is what makes a refusal possible at all. */
       scope.filter = value;
       options.onFilter(value);
     },

package/src/surfaces/ai-chat.json

@@ -97,12 +97,15 @@
       "color": "var(--fg-dim)"
     },
     "& [part=\"user-body\"]": {
+      "$description": "The transcript is content, not interface, and the panel offers no copy action, so each message body opts back in to selection against the root's `user-select: none`: this bubble, the model's `md`, the `streaming` text and the `import-log`. The header, the chips and the composer's buttons around them stay unselectable.",
       "whiteSpace": "pre-wrap",
-      "overflowWrap": "anywhere"
+      "overflowWrap": "anywhere",
+      "userSelect": "text"
     },
     "& [part=\"md\"]": {
-      "$description": "The island `panels/ai-chat/chat-markdown.ts` fills — the app's ONE injection sink, and the markup reaching it has been through `markdownToHtml` and the Trusted Types policy that asserts it did. The document renders the host node and nothing inside it (specs/studio-ui-guidelines.md §9.4).",
-      "overflowWrap": "anywhere"
+      "$description": "The island `panels/ai-chat/chat-markdown.ts` fills — the app's ONE injection sink, and the markup reaching it has been through `markdownToHtml` and the Trusted Types policy that asserts it did. The document renders the host node and nothing inside it (specs/studio-ui-guidelines.md §9.4). A reply is the text a reader most often copies out of this panel, code blocks included, so it is selectable.",
+      "overflowWrap": "anywhere",
+      "userSelect": "text"
     },
     "& [part=\"md\"] > *:first-child": {
       "marginTop": "0"
@@ -137,8 +140,10 @@
       "padding": "var(--jx-space-1) 6px"
     },
     "& [part=\"streaming\"]": {
+      "$description": "The reply while it arrives, selectable for the reason `[part=\"md\"]` is. The cursor is generated content, which no selection ever includes.",
       "whiteSpace": "pre-wrap",
       "overflowWrap": "anywhere",
+      "userSelect": "text",
       "::after": {
         "content": "\"▋\"",
         "color": "var(--accent)",
@@ -314,6 +319,8 @@
       "marginRight": "var(--jx-space-2)"
     },
     "& [part=\"import-log\"]": {
+      "$description": "A captured log, kept selectable against the root's `user-select: none`: its lines are what a reader pastes into a bug report, and nothing here offers to copy them.",
+      "userSelect": "text",
       "marginTop": "var(--jx-space-2)",
       "maxHeight": "40vh",
       "overflowY": "auto",
@@ -369,7 +376,8 @@
       "color": "var(--warning)",
       "fontStyle": "normal"
     },
-    "& [part=\"error\"]": {
+    "& [part=\"error-card\"]": {
+      "$description": "The failed turn's card. It is `error-card` rather than `error` because the model picker mounted into the composer is a `jx-select`, and every kit field draws a permanent, empty `[part=\"error\"]` of its own in this same light-DOM tree: under that name this rule, padding and wash drew an 18×12 red bar over the picker's top-left corner that took the click. Its children keep the `error-` prefix, which the kit does not use.",
       "borderLeft": "2px solid var(--danger)",
       "borderRadius": "var(--jx-radius-sm)",
       "background": "var(--hover-bg)",
@@ -552,7 +560,7 @@
       "& [part=\"tool-chip\"][data-outcome=\"failed\"]": {
         "borderLeftColor": "LinkText"
       },
-      "& [part=\"error\"]": {
+      "& [part=\"error-card\"]": {
         "borderLeftColor": "LinkText"
       }
     },
@@ -1511,7 +1519,7 @@
                     "shown": {
                       "tagName": "div",
                       "attributes": {
-                        "part": "error",
+                        "part": "error-card",
                         "role": "alert"
                       },
                       "children": [

package/src/surfaces/ai-chat.ts

@@ -48,7 +48,8 @@ const LOG_STICK_THRESHOLD = 24;
  *
  * The flow asks the registry; the document draws what it is told. A command the registry does not
  * hold, or whose `when` is false, never becomes one of these — which is what keeps the panel a
- * rendering of the registry rather than a second place its capabilities are decided (§12.5).
+ * rendering of the registry rather than a second place its capabilities are decided
+ * (`studio-ui-guidelines.md` §12.5).
  */
 export interface ChatCommandView extends Record<string, unknown> {
   /** The reconcile key. The command id, because a button is drawn once per bar. */
@@ -458,7 +459,8 @@ export function mountAiChatSurface(
   host.replaceChildren();
   /* Nothing is called on an element here, so the mount is all there is to wait for: the islands
      announce themselves through `onNodeCreated` as they are created, which is one
-     `connectedCallback` EARLIER than awaiting the element would be (§1.1, "await the element"). */
+     `connectedCallback` EARLIER than awaiting the element would be
+     (`studio-ui-guidelines.md` §1.1, "await the element"). */
   void mountSurface("ai-chat", scope, host, {
     onNodeCreated: (element, _path, def, state) => {
       const part = partOf(def);

package/src/surfaces/ai-credentials-form.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioAiCredentialsForm",
-  "$description": "The AI provider credentials form every gate embeds below the keyless offer: a key, a model, an endpoint, and the two buttons that keep or abandon them. Everything here is a projection — `ui/ai-credentials-form.ts` keeps the drafts, decides what a fetch is sent with, what Save actually persists and whether Cancel is on offer at all. This document never reads a setting and never calls the proxy.",
+  "$description": "The AI provider credentials form every gate embeds below the keyless offer: a key, a model, an endpoint, and the two buttons that keep or abandon them. Everything here is a projection — `ui/ai-credentials-form.ts` keeps the drafts, decides what a fetch is sent with, what Save actually persists and whether there is anything to Save or Cancel at all. This document never reads a setting and never calls the proxy.",
   "tagName": "div",
   "attributes": {
     "part": "ai-creds-form",
@@ -17,8 +17,7 @@
     "maxWidth": "320px",
     "textAlign": "left",
     "& [part=\"title\"]": {
-      "$description": "Centred over a left-aligned column: the form is a titled block, not a list of labelled rows.",
-      "alignSelf": "center",
+      "$description": "Weight alone, and no `align-self`. It was centred over the column on the grounds that the form is a titled block rather than a list of labelled rows, and in Preferences it is neither: the sheet's own heading, the blurb, this note, the `Model` label and all three fields start at the column's inline edge, so a centred line 102px wide in a 320px column read as a stray, not as a title. A heading belongs over the first character of the thing it names.",
       "fontWeight": "600"
     },
     "& [part=\"note\"]": {
@@ -38,17 +37,22 @@
       "width": "100%"
     },
     "& [part=\"models\"]": {
+      "$description": "A wrapping row that holds the button and, when there is one, the reason the listing did not finish — and the reason always takes a line of its own, which is what `flex-basis: 100%` on it (below) is for. Beside the button it began 96px into a 320px column, so a six-line upstream body read as a paragraph indented past the control it answers for, while the button floated at that block's vertical middle with about 40px of dead space around it. Under the button, at the column's own inline edge, the reason starts where every other line in the form starts. `flex-start` rather than `center` so that a line which does hold two boxes lines up their first lines and not their middles.",
       "display": "flex",
-      "alignItems": "center",
+      "flexWrap": "wrap",
+      "alignItems": "flex-start",
       "gap": "var(--jx-space-3)"
     },
     "& [part=\"models-error\"]": {
-      "$description": "Why the listing did not finish, beside the button that would try it again. Named `models-error` rather than `error` because the kit's own fields render a permanent `[part=\"error\"]` region of their own, and a surface that reused the name would be addressing three empty paragraphs before it reached its own.",
+      "$description": "Why the listing did not finish, said under the button that would try it again. Named `models-error` rather than `error` because the kit's own fields render a permanent `[part=\"error\"]` region of their own, and a surface that reused the name would be addressing three empty paragraphs before it reached its own. `flexBasis: 100%` is what puts it under the button rather than beside it: the row wraps, and a basis of the whole line cannot share one, so however short the reason is it always reads as a line of the form (`[part=\"models\"]`). `minWidth: 0` and `overflowWrap: anywhere` because the reason is often an upstream body passed through whole — a 401's JSON is one unbroken word — and a flex item's automatic minimum is its min-content width: one measured 853px inside the 320px column, and scrolled the whole Preferences section sideways over the buttons below it.",
       "color": "var(--danger)",
-      "fontSize": "var(--jx-text-sm)"
+      "fontSize": "var(--jx-text-sm)",
+      "flexBasis": "100%",
+      "minWidth": "0",
+      "overflowWrap": "anywhere"
     },
     "& [part=\"actions\"]": {
-      "$description": "Buttons at the end of the column, in the order a dismissal precedes a commitment.",
+      "$description": "Buttons at the end of the column, in the order a dismissal precedes a commitment. Still a flex item of the column although it is drawn inside `[part=\"actions-slot\"]`, because that slot is `display: contents` — which is what keeps `alignSelf` meaning the column's end.",
       "display": "flex",
       "alignSelf": "flex-end",
       "gap": "var(--jx-space-3)"
@@ -250,26 +254,26 @@
       }
     },
     {
+      "$description": "The commit pair exists only while there is something to commit: `dirty` is the flow's answer to whether Save would change what is stored, compared after the store's own normalisation, so a pasted key's whitespace is not an edit. At rest neither button is drawn. The rule this replaced offered Cancel whenever a key was stored and Save always, so Preferences › Assistant showed a Save that would re-store what was there and a Cancel that abandoned nothing, beside the dialog's own Close. Absent rather than disabled, against the house rule for a control that cannot act, because the pair IS the pending edit's affordance: a disabled pair at rest would still be the two buttons the reader reported seeing with nothing to save, each needing a reason to give for being there. Answering either takes away the button that was pressed, so `surfaces/ai-credentials-form.ts` lands focus on the key field rather than letting it fall out of the sheet.",
       "tagName": "div",
       "attributes": {
-        "part": "actions"
+        "part": "actions-slot",
+        "role": "none"
       },
-      "children": [
-        {
+      "style": {
+        "display": "contents"
+      },
+      "$switch": {
+        "$ref": "#/state/dirty"
+      },
+      "cases": {
+        "true": {
           "tagName": "div",
           "attributes": {
-            "part": "cancel-slot",
-            "role": "none"
-          },
-          "style": {
-            "display": "contents"
-          },
-          "$switch": {
-            "$ref": "#/state/haveKey"
+            "part": "actions"
           },
-          "cases": {
-            "true": {
-              "$description": "Only offered once a key exists: with nothing stored there is nothing to go back to, and a Cancel that abandons an empty form to an empty form is a button that does nothing.",
+          "children": [
+            {
               "tagName": "jx-button",
               "attributes": {
                 "part": "cancel"
@@ -295,38 +299,38 @@
                   "textContent": "Cancel"
                 }
               ]
-            }
-          }
-        },
-        {
-          "tagName": "jx-button",
-          "attributes": {
-            "part": "save"
-          },
-          "$props": {
-            "size": "sm",
-            "variant": "accent"
-          },
-          "onclick": {
-            "$prototype": "Function",
-            "body": [
-              {
-                "operator": "call",
-                "target": {
-                  "$ref": "#/state/save"
-                },
-                "value": []
-              }
-            ]
-          },
-          "children": [
+            },
             {
-              "tagName": "span",
-              "textContent": "Save"
+              "tagName": "jx-button",
+              "attributes": {
+                "part": "save"
+              },
+              "$props": {
+                "size": "sm",
+                "variant": "accent"
+              },
+              "onclick": {
+                "$prototype": "Function",
+                "body": [
+                  {
+                    "operator": "call",
+                    "target": {
+                      "$ref": "#/state/save"
+                    },
+                    "value": []
+                  }
+                ]
+              },
+              "children": [
+                {
+                  "tagName": "span",
+                  "textContent": "Save"
+                }
+              ]
             }
           ]
         }
-      ]
+      }
     }
   ]
 }

package/src/surfaces/ai-credentials-form.ts

@@ -3,8 +3,8 @@
  * The AI provider credentials form as a mounted document.
  *
  * `ui/ai-credentials-form.ts` is the flow — it holds the three drafts, decides which credentials a
- * listing is made with, what Save persists and re-reads, and whether Cancel is on offer — and this
- * is the surface it draws into.
+ * listing is made with, what Save persists and re-reads, and whether there is anything to commit —
+ * and this is the surface it draws into.
  *
  * **The host element belongs to this module, not to the gate.** Every credentials gate is still a
  * lit template that interpolates the form beside the keyless offer, so there is no container in the
@@ -58,8 +58,12 @@ export interface AiCredentialsView {
   fetchLabel: string;
   /** Why the last listing did not finish. Empty draws nothing. */
   modelsError: string;
-  /** A key is already stored, so abandoning the drafts means something. */
-  haveKey: boolean;
+  /**
+   * The drafts differ from what is stored — there is something to Save and something to Cancel. The
+   * flow compares them as the store would hold them, so whitespace a Save would trim is not a
+   * difference. False at rest, which is when the document draws neither button.
+   */
+  dirty: boolean;
 }
 
 /** Everything the reader can do here. */
@@ -134,7 +138,17 @@ export function createAiCredentialsSurface(
   return {
     host,
     update(next) {
+      /* Save and Cancel exist only while the form is dirty, so answering either takes away the
+         button the reader just pressed — and a removed element's focus falls to `<body>`, which in
+         a modal sheet leaves a keyboard or screen-reader user nowhere. The key field is where it
+         lands instead: the top of the form that now shows what is stored. Only when focus WAS on
+         the pair and the update actually lost it, so a repaint never takes the caret from a field. */
+      const answering =
+        !next.dirty && host.querySelector('[part="actions"]')?.contains(document.activeElement);
       Object.assign(scope, derive(next));
+      if (answering && !host.contains(document.activeElement)) {
+        host.querySelector<HTMLElement>('[part="key"] [part="input"]')?.focus();
+      }
       /* A standing mount is only ASSIGNED to: rebuilding it on every repaint of the gate around it
          would empty the field the reader is typing in. The remount below answers the one case
          assignment cannot — a host the document has been taken out of — and it cannot fire while a

package/src/surfaces/ai-managed-connect.json

@@ -22,8 +22,8 @@
       "maxWidth": "280px",
       "textAlign": "center"
     },
-    "& [part=\"error\"]": {
-      "$description": "Why the last attempt did not finish, said under the button that would try it again. Narrower than the lede: a refusal is a sentence to read once, not the thing the surface is about.",
+    "& [part=\"connect-failure\"]": {
+      "$description": "Why the last attempt did not finish, said under the button that would try it again. Narrower than the lede: a refusal is a sentence to read once, not the thing the surface is about. The name is qualified, and BOTH halves of it are load-bearing. Not `error`, because every kit field draws a permanent, empty `[part=\"error\"]` of its own and the kit is light DOM, so a rule on that name would reach any field this surface ever holds. Not the bare `failure` every panel banner uses either, because this document is MOUNTED inside another one: `new-project.json` puts it in `[part=\"managed-island\"]` and styles its own backend refusal with a descendant `[part=\"failure\"]`, which would draw this sentence with that dialog's footer border and padding. A guest surface picks a name its host does not write, and `tests/surface-part-names.test.ts` holds the two island hosts to it.",
       "margin": "0",
       "color": "var(--danger)",
       "fontSize": "var(--jx-text-sm)",
@@ -78,7 +78,7 @@
     {
       "tagName": "div",
       "attributes": {
-        "part": "error-slot",
+        "part": "connect-failure-slot",
         "role": "none"
       },
       "style": {
@@ -91,7 +91,7 @@
         "true": {
           "tagName": "p",
           "attributes": {
-            "part": "error"
+            "part": "connect-failure"
           },
           "textContent": "${state.error}"
         }