@jxsuite/studio 10.0.0 → 10.2.0

package/src/settings/preferences-accounts.ts

@@ -27,7 +27,7 @@
 
 import { clearGithubToken, githubTokenLocation, githubTokenStored } from "../github/github-auth";
 import { clearCfConnection, getCfAccountId, getCfToken } from "../services/cf-settings";
-import { clearAiProvider, getBaseUrl, hasOpenAiKey } from "../services/ai-settings";
+import { clearAiProvider, getAiProvider, getBaseUrl, hasOpenAiKey } from "../services/ai-settings";
 import { preferredModel, resetModelCache } from "../services/ai-models";
 import { getPlatform, hasPlatform } from "../platform";
 import { getAccountEntries } from "../account-status";
@@ -292,7 +292,7 @@ export function listAccounts(): AccountRecord[] {
       id: "ai",
       label: "AI provider",
       detail: hasOpenAiKey()
-        ? `Key stored. Model ${model}${endpoint ? ` via ${endpoint}` : ""}.`
+        ? `${getAiProvider() === "anthropic" ? "Anthropic key" : "Key"} stored. Model ${model}${endpoint ? ` via ${endpoint}` : ""}.`
         : "No key stored. The Assistant section is where one is entered.",
       connected: hasOpenAiKey(),
       revoke: clearAiProvider,

package/src/settings/preferences-dialog.ts

@@ -143,8 +143,10 @@ function sectionShown(): void {
 const credsForm = createAiCredentialsForm({
   /* A sentence rather than a template: the form is a document now, and a document renders text
      rather than another module's markup. */
-  intro:
-    "Any OpenAI-compatible key works. Stored locally on this machine; sent only to the Studio proxy (never to a third party except your chosen endpoint).",
+  intro: (offersProviders) =>
+    offersProviders
+      ? "An Anthropic key for Claude, or any OpenAI-compatible key. Stored locally on this machine; sent only to the Studio proxy (never to a third party except your chosen provider)."
+      : "Any OpenAI-compatible key works. Stored locally on this machine; sent only to the Studio proxy (never to a third party except your chosen endpoint).",
   // Both buttons keep the sheet open: Preferences is a place, not a wizard step, and the previous
   // Dialog's habit of vanishing on Save is what made "did that take?" unanswerable.
   onCancel: repaint,

package/src/settings/project-sections.ts

@@ -13,7 +13,7 @@
  *
  * **Raw JSON does not open a second editor.** It shows what is on disk and hands the author to the
  * Code editor over the `project.json` tab (§17.1): the host says how, through `editAsCode`, because
- * the section sits in the settings dialog and the tab it opens is the Styles workspace's.
+ * the section sits in the Settings workspace and the tab it opens is the Styles workspace's.
  *
  * **Deploy is no longer a Project Settings section.** Hosting moved to the Publish workspace
  * (§17.1's Moved footnote), which hosts `renderDeploySection`; the renderer is unchanged.

package/src/settings/section-registry.ts

@@ -3,10 +3,11 @@
  *
  * `registerSettingsSection` is a **preserved public contract** (specs/extensions.md §9.1): an
  * extension's `project` class declares a `$studio.settings` block and `settings/extension-sections`
- * turns it into one of these records. Project Settings has moved host twice — a modal, then a
- * document in the pane, and now a dialog again (§17.1) — and the registry moved with neither,
- * because a section is a contribution to CONFIGURATION, not to whatever draws it. Splitting it out
- * is what lets the host be replaced without the contribution point being touched.
+ * turns it into one of these records. Project Settings has moved host three times — a modal, then a
+ * document in the pane, then a dialog again, and now a workspace of its own (§17.1, §22.9) — and
+ * the registry moved with none of them, because a section is a contribution to CONFIGURATION, not
+ * to whatever draws it. Splitting it out is what lets the host be replaced without the contribution
+ * point being touched.
  *
  * **This module holds no renderer and imports nothing.** That is load-bearing rather than tidy: the
  * gear menu (`panels/settings-menu.ts`) enumerates these sections from the top bar, so anything

package/src/settings/settings-document.ts

@@ -3,18 +3,18 @@
  * Project Settings: the built-in sections, the `project.json` tab's editors, and the two commands
  * that reach them.
  *
- * **Settings is a dialog; the configuration DOCUMENT is still a tab.** `project.json` is a real Tab
- * under the transaction log with one write chokepoint (`tabs/project-config.ts`, §17.1), and it has
- * three editors, the Styles workspace's three views: Elements (`stylebook`), Variables (`tokens`,
- * `style/variables-view.ts`) and Code (`source`). Project Settings is neither of them: it is a
- * dialog in the dialog layer (`./settings-dialog.ts`) hosting the section list, reachable from
- * every workspace, and every section in it writes through the same chokepoint the tab's editors do,
- * so the file has one history whichever door changed it.
+ * **Settings is a workspace; the configuration DOCUMENT is still a tab.** `project.json` is a real
+ * Tab under the transaction log with one write chokepoint (`tabs/project-config.ts`, §17.1), and it
+ * has three editors, the Styles workspace's three views: Elements (`stylebook`), Variables
+ * (`tokens`, `style/variables-view.ts`) and Code (`source`). Project Settings is neither of them:
+ * it is the Settings workspace, whose home hosts the section list (`./settings-workspace.ts`),
+ * reached from every workspace, and every section in it writes through the same chokepoint the
+ * tab's editors do, so the file has one history whichever door changed it.
  *
  * **`settings.open` did not change what it means.** It still means "reach project settings,
  * optionally at a named section and entry", its args schema still declares `section` and `entry`,
- * and a key nobody registered still fails the call. What changed is the `run`: a dialog instead of
- * a tab mode.
+ * and a key nobody registered still fails the call. What changed is the `run`: a workspace switch
+ * instead of a dialog.
  *
  * @docs studio/projects/settings
  */
@@ -31,7 +31,8 @@ import { notify } from "../services/notify";
 import { projectState } from "../state";
 import { PROJECT_CONFIG_PATH } from "../tabs/tab";
 import { lendProjectConfigLayout } from "../tabs/project-config";
-import { focusPane, openTab, workspace } from "../workspace/workspace";
+import { focusPane, openTab, paneOfTab, workspace } from "../workspace/workspace";
+import { workspaceHomeTabId } from "../workspace/workspace-ids";
 import {
   notifySettingsDocument,
   registerSettingsSection,
@@ -47,7 +48,7 @@ import { renderGeneralSettings } from "./general-settings";
 import { renderHeadEditor } from "./head-editor";
 import { renderLocalesSection } from "./locales-section";
 import { selectContributedEntry } from "./contributed-section";
-import { closeSettingsDialog, openSettingsDialog } from "./settings-dialog";
+import { focusSettingsHome } from "./settings-workspace";
 // The NAME and the wire value, kept apart by that module on purpose — see its docstring.
 import {
   PROJECT_STYLES_TITLE,
@@ -79,7 +80,7 @@ const PROJECT_TAB_MODES = STYLES_TAB_MODES;
 
    Two sections that used to be here are not, and their renderers are not deleted: CSS Variables
    (`./css-vars-editor.ts`) belongs to the Styles workspace, and Deploy (`renderDeploySection`) to
-   the Publish workspace. The dialog's Moved footnote says where each went.
+   the Publish workspace. Settings' Moved footnote says where each went.
 
    `icon` is a KEY into the kit's glyph manifest (`@jxsuite/ui/icons`), not a tag: `studio.md`
    §13.5 is about exactly this distinction, and a key with no row draws nothing and says nothing.
@@ -156,9 +157,9 @@ registerSettingsSection({
   render: renderDependenciesEditor,
 });
 /*
- * Raw JSON's "Edit as code" leaves the dialog: the Code editor is the `project.json` tab's, which is
- * the Styles workspace's, so the dialog closes and the tab opens in its source editor. Activating
- * it is what switches the workspace (`workspace/tab-workspace.ts`).
+ * Raw JSON's "Edit as code" leaves Settings: the Code editor is the `project.json` tab's, which is
+ * the Styles workspace's, so the tab opens in its source editor, and activating it is what switches
+ * the workspace (`workspace/tab-workspace.ts`).
  */
 registerSettingsSection({
   group: "advanced",
@@ -169,7 +170,6 @@ registerSettingsSection({
   render: (container) => {
     renderRawJsonSection(container, {
       editAsCode: () => {
-        closeSettingsDialog();
         showSettingsDocument(SOURCE_MODE);
       },
     });
@@ -271,12 +271,13 @@ function revealTab(tab: Tab): Tab {
 /**
  * Reach Project Settings, optionally at a named section.
  *
- * Opens the dialog on the requested section (or on the one it last showed, which the registry
- * remembers for the session), then awaits the contributed-section sync before returning, so a
- * caller that then asks whether a section exists is asking the complete registry. The sync is
- * COALESCED (`extension-sections.ts`): `refreshExtensionUi` fires the same function on project
- * activation and after every `project.json` write, and a second, interleaved run could otherwise
- * take the caller's section down between the promise resolving and the frame being drawn.
+ * Switches to the Settings workspace on the requested section (or on the one it last showed, which
+ * the registry remembers for the session), puts the keyboard on that section's row, then awaits the
+ * contributed-section sync before returning, so a caller that then asks whether a section exists is
+ * asking the complete registry. The sync is COALESCED (`extension-sections.ts`):
+ * `refreshExtensionUi` fires the same function on project activation and after every `project.json`
+ * write, and a second, interleaved run could otherwise take the caller's section down between the
+ * promise resolving and the frame being drawn.
  *
  * @param {string} [section]
  */
@@ -284,7 +285,15 @@ export async function openProjectSettings(section?: string): Promise<void> {
   if (section !== undefined) {
     setSettingsSection(section);
   }
-  void openSettingsDialog();
+  const registry = activeRegistry();
+  if (!registry) {
+    throw new Error('command "settings.open" needs the window\'s command registry');
+  }
+  await registry.run("view.setWorkspace", { workspace: "settings" });
+  const paneId = paneOfTab(workspaceHomeTabId("settings"))?.id;
+  if (paneId !== undefined) {
+    void focusSettingsHome(paneId);
+  }
   try {
     const { syncExtensionSettingsSections } = await import("./extension-sections");
     await syncExtensionSettingsSections();
@@ -318,7 +327,7 @@ export async function settingsSectionsReady(): Promise<void> {
  * step are the same call.
  *
  * The validation is deliberately asynchronous. Extension-contributed sections (`connections`,
- * `data`, `content`) register a tick after the dialog opens, so refusing synchronously would reject
+ * `data`, `content`) register a tick after Settings opens, so refusing synchronously would reject
  * three legitimate section ids; the command opens, awaits the sync, and only then decides whether
  * the caller named something real. A wrong key therefore fails the call instead of rendering an
  * empty body.

package/src/settings/settings-workspace.ts

@@ -0,0 +1,205 @@
+/// <reference lib="dom" />
+/**
+ * Project Settings as a workspace (§17.1, §22.9): the home that hosts the settings editor, mounted
+ * into a pane's stage, and the two ways out of it.
+ *
+ * Project Settings was a dialog, and before that the `project.json` tab under a `settings` editor
+ * mode. The dialog was reachable from every workspace, but a dialog is a box of fixed size over a
+ * window that has a whole stage to spare, and the map-layout sections (Content types, Data tables,
+ * Connections) are two columns of their own inside the editor's two columns: four columns in 900px.
+ * A workspace gives the editor the stage, and keeps what the dialog was for: Settings is reached
+ * from every workspace through its links (the gear menu, ⌘⇧, and every `settings.open` deep link),
+ * and **Back** returns to the workspace it was opened from, which the top bar cannot say because it
+ * draws no tab for Settings.
+ *
+ * **Per pane**, for the reason `publish/publish-workspace.ts` gives: the home is a tab, so two
+ * panes can each show it. Each mount is the editor, built when the home is drawn and taken down
+ * when the pane's stage moves on (a switch to another workspace, a project closing). A visit is
+ * therefore a fresh editor: a half-typed entry or a failed save's error from the last visit, or
+ * from another project's, does not come back. **Which section shows is the registry's**, not this
+ * module's (`settings/section-registry.ts`), and the registry outlives every mount, which is what
+ * makes Settings reopen where the author left it for the rest of the session.
+ *
+ * @docs studio/projects/settings
+ */
+
+import { activeRegistry } from "../commands/active-registry";
+import { runActiveReported } from "../commands/run-reported";
+import { mountSettingsPane } from "../panels/settings-pane";
+import { previousWorkspace } from "../shell";
+import { paneRegion } from "../ui/regions";
+import { DEFAULT_WORKSPACE, workspaceInfo } from "../workspace/workspace-ids";
+import type { CanvasSurface } from "../canvas/canvas-surface";
+import type { SettingsPaneMount, SettingsPaneOptions } from "../panels/settings-pane";
+import type { PublishTab } from "../publish/publish-ids";
+import type { InspectorTabId } from "../shell";
+import type { StylesView } from "../style/project-styles";
+import type { Tab } from "../tabs/tab";
+import type { WorkspaceId } from "../workspace/workspace-ids";
+
+/** The region part the home is stamped with, under its pane: `pane.<id>/settings`. */
+export const SETTINGS_REGION_PART = "settings";
+
+/** The region of the Settings home in `paneId`. */
+export function settingsRegion(paneId: string): string {
+  return paneRegion(paneId, SETTINGS_REGION_PART);
+}
+
+/** One pane's mount: the editor, and which tab and stage it was drawn for. */
+interface PaneMount {
+  pane: SettingsPaneMount;
+  tabId: string;
+  wrap: HTMLElement;
+}
+
+const _panes = new Map<string, PaneMount>();
+
+/** Panes whose next mount takes the keyboard: Settings was asked for before its home was drawn. */
+const _focusOnMount = new Set<string>();
+
+/**
+ * Where Back goes: the workspace entered before Settings, or Design when there was none (a session
+ * that was restored into Settings).
+ */
+export function returnWorkspace(): WorkspaceId {
+  const previous = previousWorkspace();
+  return previous === null || previous === "settings" ? DEFAULT_WORKSPACE : previous;
+}
+
+/**
+ * Leave Settings for the workspace it was opened from.
+ *
+ * A refusal (the switch is gated on an open project) is filed in Problems under this surface's name
+ * instead of being dropped.
+ */
+export async function leaveSettings(): Promise<void> {
+  await runActiveReported("view.setWorkspace", { workspace: returnWorkspace() }, "Settings");
+}
+
+/**
+ * Leave Settings for the workspace something moved to: the Moved footnote's buttons.
+ *
+ * A row that names an Inspector tab ("Head and SEO defaults → Page tab") also shows the Inspector
+ * on that tab, AFTER the switch, because entering a workspace applies its frame preset and would
+ * otherwise put the dock back as the preset has it. The tab is a document-level view, so with no
+ * document open there is no tab to show and asking would only file a refusal; the dock is still
+ * opened, which is where the tab appears once one is.
+ *
+ * A row that names a Styles view ("Colors and fonts → Styles › Variables") runs `styles.open` with
+ * that view instead, which is the same workspace switch followed by the view, and a row that names
+ * a Publish sub-tab runs `publish.open` on it.
+ *
+ * @param {WorkspaceId} workspace
+ * @param {InspectorTabId} [inspector]
+ * @param {StylesView} [view]
+ * @param {PublishTab} [publishTab]
+ * @returns {Promise<void>} Settles once every command the row runs has settled
+ */
+export async function openMoved(
+  workspace: WorkspaceId,
+  inspector?: InspectorTabId,
+  view?: StylesView,
+  publishTab?: PublishTab,
+): Promise<void> {
+  if (view !== undefined) {
+    await runActiveReported("styles.open", { view }, "Settings");
+    return;
+  }
+  // Hosting is a Publish sub-tab, not the workspace's first: the button says where it lands.
+  if (publishTab !== undefined) {
+    await runActiveReported("publish.open", { tab: publishTab }, "Settings");
+    return;
+  }
+  await runActiveReported("view.setWorkspace", { workspace }, "Settings");
+  if (inspector === undefined) {
+    return;
+  }
+  await runActiveReported("view.setRightPanel", { open: true }, "Settings");
+  if (activeRegistry()?.isEnabled("view.setRightTab") === true) {
+    await runActiveReported("view.setRightTab", { tab: inspector }, "Settings");
+  }
+}
+
+/** Whether this tab's home is already mounted in this pane and still in the document. */
+export function settingsWorkspaceMounted(paneId: string, tab: Tab): boolean {
+  const mount = _panes.get(paneId);
+  return (
+    mount !== undefined && mount.tabId === tab.id && mount.wrap.isConnected && mount.pane.attached()
+  );
+}
+
+/** Tear one pane's home down (mode change, tab switch, project close). Idempotent. */
+export function detachSettingsWorkspace(paneId: string): void {
+  const mount = _panes.get(paneId);
+  if (!mount) {
+    return;
+  }
+  _panes.delete(paneId);
+  mount.pane.dispose();
+}
+
+/** Put the keyboard on the current section's row once the editor has drawn it. */
+async function focusWhenReady(paneId: string, mount: PaneMount): Promise<void> {
+  await mount.pane.ready;
+  if (_panes.get(paneId) === mount) {
+    await mount.pane.focusActive();
+  }
+}
+
+/**
+ * Give the keyboard to the Settings home in `paneId`, on the current section's row: what opening
+ * Settings does, so an author who asked for Advanced › Raw JSON is on Raw JSON rather than on the
+ * first group's tab stop. Served now when the home is standing in the pane, or by its next mount
+ * there.
+ *
+ * @param {string} paneId
+ * @returns {Promise<void>} Settles once the keyboard has moved, or once the request is queued
+ */
+export async function focusSettingsHome(paneId: string): Promise<void> {
+  const mount = _panes.get(paneId);
+  if (mount?.wrap.isConnected === true && mount.pane.attached()) {
+    await focusWhenReady(paneId, mount);
+    return;
+  }
+  _focusOnMount.add(paneId);
+}
+
+/**
+ * What the home's controls do, the same in every pane: Back and the Moved buttons are workspace
+ * switches, window-level commands that act wherever the author is, and no fact about the pane the
+ * home is drawn in goes into them. Declared here rather than in {@link renderSettingsWorkspace} so
+ * nothing that consults the window's state is reached from a function holding a pane.
+ */
+const HOME_ACTIONS: Omit<SettingsPaneOptions, "region"> = {
+  back: () => {
+    void leaveSettings();
+  },
+  backLabel: () => `Back to ${workspaceInfo(returnWorkspace()).title}`,
+  openMoved: (workspace, inspector, view, publishTab) => {
+    void openMoved(workspace, inspector, view, publishTab);
+  },
+};
+
+/**
+ * Draw the Settings home into a pane's stage. It reads the pane's id and its stage, and nothing
+ * else of the canvas surface.
+ *
+ * @param {Pick<CanvasSurface, "paneId" | "wrap">} surface
+ * @param {Tab} tab
+ */
+export function renderSettingsWorkspace(
+  surface: Pick<CanvasSurface, "paneId" | "wrap">,
+  tab: Tab,
+): void {
+  const { paneId, wrap } = surface;
+  if (settingsWorkspaceMounted(paneId, tab)) {
+    return;
+  }
+  detachSettingsWorkspace(paneId);
+  const pane = mountSettingsPane(wrap, { ...HOME_ACTIONS, region: settingsRegion(paneId) });
+  const mount: PaneMount = { pane, tabId: tab.id, wrap };
+  _panes.set(paneId, mount);
+  if (_focusOnMount.delete(paneId)) {
+    void focusWhenReady(paneId, mount);
+  }
+}

package/src/shell.ts

@@ -45,8 +45,8 @@ import type { AnyCommand, CommandRegistry } from "./commands/registry";
 import {
   DEFAULT_WORKSPACE,
   isWorkspaceId,
+  SWITCHER_WORKSPACES,
   WORKSPACE_IDS,
-  WORKSPACES,
 } from "./workspace/workspace-ids";
 import type { WorkspaceId } from "./workspace/workspace-ids";
 import { DEFAULT_PUBLISH_DESTINATION, DEFAULT_PUBLISH_TAB } from "./publish/publish-ids";
@@ -416,7 +416,7 @@ export interface WorkspacePreset {
 }
 
 /**
- * The five presets.
+ * The six presets.
  *
  * - **Design** draws the rail and both side docks: the canvas, its outline and its inspector.
  * - **Content** opens the Navigator on the Collections panel and collapses the Inspector, drawing it
@@ -427,8 +427,10 @@ export interface WorkspacePreset {
  *   schemes), and the Inspector on its Style tab only while the Elements view is on screen: that
  *   view selects an element default on a canvas, and the Inspector is where it is styled. Variables
  *   is edited in the view itself, and Code has no canvas, so both leave the pane its width.
+ * - **Settings** collapses both side docks, as Media and Publish do: its home is the settings editor,
+ *   whose section list is its own navigator.
  *
- * Only Design and Content draw a tab strip; the other three draw their home surface alone.
+ * Only Design and Content draw a tab strip; the other four draw their home surface alone.
  */
 export const WORKSPACE_PRESETS: Readonly<Record<WorkspaceId, WorkspacePreset>> = {
   content: {
@@ -459,6 +461,13 @@ export const WORKSPACE_PRESETS: Readonly<Record<WorkspaceId, WorkspacePreset>> =
     rail: false,
     tabStrip: false,
   },
+  settings: {
+    id: "settings",
+    inspector: { open: false },
+    navigator: { open: false },
+    rail: false,
+    tabStrip: false,
+  },
   styles: {
     id: "styles",
     inspector: { open: false, tab: "style", whileWriting: true },
@@ -833,6 +842,19 @@ let _workspaceRoot: string | null | undefined;
  */
 let _panels: Partial<Record<WorkspaceId, string>> = {};
 
+/**
+ * The workspace on screen before the one that is, in this window, or `null` before the first
+ * switch. Not persisted, for the reason {@link _panels} is not. Project Settings' **Close** returns
+ * here (`settings/settings-workspace.ts`), because Settings is visited from somewhere rather than
+ * worked in, and the top bar has no tab to say where that was.
+ */
+let _previous: WorkspaceId | null = null;
+
+/** The workspace entered before the one on screen, or `null` when there was none this session. */
+export function previousWorkspace(): WorkspaceId | null {
+  return _previous;
+}
+
 /** The raw record for `root`, or `{}` for absent, corrupt or hand-edited storage. */
 function rawPersistedProject(root: string | null): JsonObject {
   if (!root) {
@@ -949,6 +971,7 @@ export function syncProjectWorkspace(root: string | null): void {
   }
   _workspaceRoot = root;
   _panels = {};
+  _previous = null;
   shell.workspace = persistedWorkspace(root);
   if (root === null) {
     /* No frame to apply, but the Navigator is still on screen beside the rail: a panel only the
@@ -1020,6 +1043,7 @@ export function enterWorkspace(id: WorkspaceId, deps?: WorkspaceDeps): boolean {
   if (!WORKSPACE_PRESETS[shell.workspace].navigator.panel) {
     _panels[shell.workspace] = shell.leftTab;
   }
+  _previous = shell.workspace;
   shell.workspace = id;
   applyFrame(id, deps);
   persistDocks();
@@ -1580,8 +1604,9 @@ export function shellViewCommands(deps: ShellCommandDeps): AnyCommand[] {
       title: "Show Assistant",
     },
     // ── Workspaces ───────────────────────────────────────────────────────────
-    // One SETTER, and one chord record per workspace. A chord cannot carry an argument, so ⌘1–5
-    // Are five records that each run the setter's own path rather than five implementations of it.
+    /* One SETTER, and one chord record per switcher workspace. A chord cannot carry an argument, so
+       ⌘1–5 are five records that each run the setter's own path rather than five implementations
+       of it. Settings has none: `settings.open` is its record, with its own chord (⌘⇧,). */
     {
       args: argsSchema({
         workspace: enumProperty(WORKSPACE_IDS, "Which workspace to show."),
@@ -1603,7 +1628,7 @@ export function shellViewCommands(deps: ShellCommandDeps): AnyCommand[] {
       },
       title: "Switch Workspace",
     },
-    ...WORKSPACES.map((entry, index): AnyCommand => ({
+    ...SWITCHER_WORKSPACES.map((entry, index): AnyCommand => ({
       category: "View",
       id: `workspace.focus.${entry.id}`,
       keybinding: `mod+${index + 1}`,

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 there is anything to Save or Cancel 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 provider family (only where the backend reaches more than one), 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",
@@ -32,7 +32,7 @@
       "fontWeight": "500",
       "fontSize": "var(--jx-text-sm)"
     },
-    "& [part=\"key\"], & [part=\"model\"], & [part=\"endpoint\"]": {
+    "& [part=\"provider\"], & [part=\"key\"], & [part=\"model\"], & [part=\"endpoint\"]": {
       "$description": "Every control takes the column's width; the kit's fields are inline-flex by default.",
       "width": "100%"
     },
@@ -73,6 +73,54 @@
       },
       "textContent": "${state.intro}"
     },
+    {
+      "$description": "The family the key belongs to (specs/ai.md §2.6), drawn only where it is a choice: the backend's models route lists more than the OpenAI-compatible family, or the stored or drafted family is already another one, so a reader can always switch back. A backend that lists nothing reaches the OpenAI-compatible family alone and forwards every key there, so offering Claude to it would send a Claude key to OpenAI. Above the key because it decides what the key is.",
+      "tagName": "div",
+      "attributes": {
+        "part": "provider-slot",
+        "role": "none"
+      },
+      "style": {
+        "display": "contents"
+      },
+      "$switch": {
+        "$ref": "#/state/showProvider"
+      },
+      "cases": {
+        "true": {
+          "tagName": "jx-select",
+          "attributes": {
+            "part": "provider"
+          },
+          "$props": {
+            "label": "Provider",
+            "size": "sm",
+            "options": {
+              "$ref": "#/state/providerOptions"
+            },
+            "value": {
+              "$ref": "#/state/providerDraft"
+            }
+          },
+          "onchange": {
+            "$prototype": "Function",
+            "body": [
+              {
+                "operator": "call",
+                "target": {
+                  "$ref": "#/state/setProvider"
+                },
+                "value": [
+                  {
+                    "$ref": "event#/target/value"
+                  }
+                ]
+              }
+            ]
+          }
+        }
+      }
+    },
     {
       "tagName": "jx-textfield",
       "attributes": {
@@ -82,7 +130,9 @@
         "label": "AI provider key",
         "type": "password",
         "size": "sm",
-        "placeholder": "sk-… or any compatible key",
+        "placeholder": {
+          "$ref": "#/state/keyPlaceholder"
+        },
         "value": {
           "$ref": "#/state/keyDraft"
         }
@@ -120,7 +170,9 @@
       "$props": {
         "label": "Model ID",
         "size": "sm",
-        "placeholder": "Model ID (e.g. gpt-4o, claude-sonnet-4-20250514, etc.)",
+        "placeholder": {
+          "$ref": "#/state/modelPlaceholder"
+        },
         "allowsCustomValue": true,
         "value": {
           "$ref": "#/state/modelDraft"
@@ -231,7 +283,9 @@
       "$props": {
         "label": "Endpoint",
         "size": "sm",
-        "placeholder": "Endpoint (optional, e.g. http://localhost:11434/v1)",
+        "placeholder": {
+          "$ref": "#/state/endpointPlaceholder"
+        },
         "value": {
           "$ref": "#/state/baseUrlDraft"
         }

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

@@ -2,7 +2,7 @@
 /**
  * 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
+ * `ui/ai-credentials-form.ts` is the flow — it holds the drafts, decides which credentials a
  * 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.
  *
@@ -37,10 +37,22 @@ registerSurface("ai-credentials-form", credentialsDoc);
 export interface AiCredentialsView {
   /** The line under the title: where the key goes, and where it does not. */
   intro: string;
-  /** The three drafts, exactly as the flow holds them. */
+  /** The drafts, exactly as the flow holds them. */
+  providerDraft: string;
   keyDraft: string;
   modelDraft: string;
   baseUrlDraft: string;
+  /**
+   * Whether the provider picker is drawn: the backend reaches another family, or the drafted or
+   * stored family already is one (specs/ai.md §2.6).
+   */
+  showProvider: boolean;
+  /** The families the picker offers. */
+  providerOptions: SurfaceOption[];
+  /** What each field says while it is empty; they follow the drafted family. */
+  keyPlaceholder: string;
+  modelPlaceholder: string;
+  endpointPlaceholder: string;
   /** The catalogue the last successful listing returned; empty draws no chevron on the field. */
   models: SurfaceOption[];
   /** A listing is in flight: the button says so and refuses a second one. */
@@ -59,6 +71,7 @@ export interface AiCredentialsView {
 
 /** Everything the reader can do here. */
 export interface AiCredentialsActions {
+  setProvider: (value: string) => void;
   setKey: (value: string) => void;
   setModel: (value: string) => void;
   setBaseUrl: (value: string) => void;

package/src/surfaces/commandbar.ts

@@ -57,7 +57,7 @@ import {
   openSettingsMenu,
   SETTINGS_MENU_PLACEMENT,
 } from "../panels/settings-menu";
-import { WORKSPACES } from "../workspace/workspace-ids";
+import { SWITCHER_WORKSPACES } from "../workspace/workspace-ids";
 import type { WorkspaceId } from "../workspace/workspace-ids";
 import commandbarDoc from "./commandbar.json";
 import type { PresenceProjection } from "../collab/presence-chips";
@@ -584,7 +584,11 @@ function projectSegments(tab: Tab | null): SegmentProjection[] {
 }
 
 /**
- * `Design · Content · Media · Styles · Publish`: the five workspaces, as a tablist.
+ * `Design · Content · Media · Styles · Publish`: the five switcher workspaces, as a tablist.
+ *
+ * Project Settings is a workspace too, and is not here: it is reached from its links (the gear
+ * menu's row, ⌘⇧, and every `settings.open` deep link), so while it is on screen no tab is selected
+ * and any of these five leaves it (studio.md §22.2).
  *
  * Each tab RUNS `view.setWorkspace`, so the click, ⌘1–5, the palette row and a script all take the
  * same path, and the selected tab is `shell.workspace` rather than a second record of it. Publish
@@ -598,7 +602,7 @@ function projectWorkspaces(registry: CommandRegistry | null): WorkspaceTabProjec
     return [];
   }
   const dirty = shell.git.status?.files.length ?? 0;
-  return WORKSPACES.map((entry) => {
+  return SWITCHER_WORKSPACES.map((entry) => {
     const badge = entry.id === "publish" && dirty > 0 ? String(dirty) : "";
     const chord = registry.keymap.formatBinding(`workspace.focus.${entry.id}`);
     const named = chord ? `${entry.title} (${chord})` : entry.title;