@jxsuite/studio 10.1.0 → 10.2.0

package/src/services/ai-settings.ts

@@ -19,6 +19,7 @@
  * @license MIT
  */
 
+import type { AiProviderFamily } from "@jxsuite/ai/streaming-client";
 import { SETTINGS } from "./settings/definitions";
 import type { SettingDefinition } from "./settings/definitions";
 import {
@@ -58,6 +59,29 @@ export function getBaseUrl() {
   return readStoredSetting(SETTINGS.aiBaseUrl);
 }
 
+/**
+ * The wire the stored key belongs to (specs/ai.md §2.6): `"anthropic"` for a Claude key, and the
+ * OpenAI-compatible default for anything else, including nothing stored.
+ *
+ * @returns {AiProviderFamily}
+ */
+export function getAiProvider(): AiProviderFamily {
+  return readStoredSetting(SETTINGS.aiProvider) === "anthropic" ? "anthropic" : "openai-compat";
+}
+
+/**
+ * The stored key when it is an OpenAI-compatible one, and `""` when it belongs to another family.
+ *
+ * For the paths that only speak the OpenAI-compatible wire, such as the site importer's component
+ * naming: handing them a Claude key would send it to an OpenAI endpoint, which is the one thing a
+ * key must never do.
+ *
+ * @returns {string}
+ */
+export function getOpenAiCompatKey(): string {
+  return getAiProvider() === "openai-compat" ? getOpenAiKey() : "";
+}
+
 // ─── Model selection ────────────────────────────────────────────────────────
 
 /**
@@ -84,11 +108,25 @@ export function setModel(modelId: string) {
   setSetting(SETTINGS.aiModel, modelId || "");
 }
 
-/** The provider's three values together — what a credentials form drafts and what Save stores. */
+/**
+ * The provider's values together: what a credentials form drafts and what Save stores. `provider`
+ * absent is the OpenAI-compatible default, which is what every caller before it meant.
+ */
 export interface AiProvider {
   apiKey: string;
   baseUrl: string;
   model: string;
+  provider?: AiProviderFamily;
+}
+
+/**
+ * A family as the store holds it: `"anthropic"`, or blank for the default.
+ *
+ * @param {AiProviderFamily | undefined} family
+ * @returns {string}
+ */
+function storedFamily(family: AiProviderFamily | undefined): string {
+  return family === "anthropic" ? "anthropic" : "";
 }
 
 /**
@@ -105,6 +143,7 @@ export function saveAiProvider(provider: AiProvider) {
     [SETTINGS.aiOpenAiKey, provider.apiKey],
     [SETTINGS.aiBaseUrl, provider.baseUrl],
     [SETTINGS.aiModel, provider.model],
+    [SETTINGS.aiProvider, storedFamily(provider.provider)],
   ]);
 }
 
@@ -127,13 +166,14 @@ export function saveAiProvider(provider: AiProvider) {
  * sentence above always claimed to be making.
  *
  * @param {AiProvider} provider The drafts.
- * @returns {boolean} `true` when at least one of the three would move.
+ * @returns {boolean} `true` when at least one of the values would move.
  */
 export function aiProviderDiffers(provider: AiProvider): boolean {
   return (
     !storedEquals(SETTINGS.aiOpenAiKey, provider.apiKey, getOpenAiKey()) ||
     !storedEquals(SETTINGS.aiBaseUrl, provider.baseUrl, getBaseUrl()) ||
-    !storedEquals(SETTINGS.aiModel, provider.model, storedModel())
+    !storedEquals(SETTINGS.aiModel, provider.model, storedModel()) ||
+    storedFamily(provider.provider) !== storedFamily(getAiProvider())
   );
 }
 
@@ -153,11 +193,11 @@ export function storedEquals(
 }
 
 /**
- * Forget the provider entirely — key, endpoint and model.
+ * Forget the provider entirely — key, endpoint, model and family.
  *
  * The one deletion path, and the one the Accounts list's Disconnect uses. Deliberately all three
  * together: a key with an orphaned endpoint is a state no surface knows how to describe.
  */
 export function clearAiProvider() {
-  clearSettings([SETTINGS.aiOpenAiKey, SETTINGS.aiBaseUrl, SETTINGS.aiModel]);
+  clearSettings([SETTINGS.aiOpenAiKey, SETTINGS.aiBaseUrl, SETTINGS.aiModel, SETTINGS.aiProvider]);
 }

package/src/services/document-assistant.ts

@@ -34,7 +34,7 @@ import { abortImportRun, resetImportRuns } from "./import-run";
 import { runAgentLoop } from "./tool-executor";
 import { buildSystemPrompt } from "./ai-system-prompt";
 import type { ExtensionCatalogSummary } from "./ai-system-prompt";
-import { getBaseUrl, getOpenAiKey } from "./ai-settings";
+import { getAiProvider, getBaseUrl, getOpenAiKey } from "./ai-settings";
 import { preferredModel } from "./ai-models";
 import { pruneOrphanToolMessages, trimContext } from "./context-manager";
 import { renderCheck } from "./render-critic";
@@ -329,8 +329,11 @@ export function createDocumentAssistant() {
         model: chatState.model,
         // Sent as X-Api-Key; the proxy falls back to the server's OPENAI_API_KEY when empty.
         apiKey: getOpenAiKey() || undefined,
-        // Optional OpenAI-compatible endpoint override; empty uses the proxy default.
+        // Optional endpoint override; empty uses the proxy default for the family.
         baseUrl: getBaseUrl() || undefined,
+        /* The family the key belongs to (specs/ai.md §2.6), named only when it is not the default,
+           so an OpenAI-compatible send is the one it always was. */
+        provider: getAiProvider() === "anthropic" ? "anthropic" : undefined,
         /* The persisted conversation, so the backend can keep its rounds on one warm prompt cache.
            Sent to the backend only, which hashes it before any provider sees it (specs/ai.md §2.5). */
         sessionId,

package/src/services/settings/definitions.ts

@@ -60,6 +60,15 @@ function normalizeBaseUrl(raw: string): string {
   return raw.trim().replace(/\/+$/, "");
 }
 
+/**
+ * The provider family, stored only when it is not the default: `"anthropic"`, or `""` for the
+ * OpenAI-compatible wire every install had before the setting existed. Anything else reads as the
+ * default, so a hand-edited value can never send a key to a family nobody chose.
+ */
+function normalizeProvider(raw: string): string {
+  return raw.trim().toLowerCase() === "anthropic" ? "anthropic" : "";
+}
+
 /** Trim. Credentials are pasted, and a paste carries whitespace. */
 function trimmed(raw: string): string {
   return raw.trim();
@@ -91,6 +100,16 @@ export const SETTINGS = {
     scope: "user",
     secret: true,
   },
+  /**
+   * Which wire the key belongs to (specs/ai.md §2.6). Blank is the OpenAI-compatible default, so an
+   * install that predates the setting keeps the provider it already had.
+   */
+  aiProvider: {
+    default: "",
+    key: "jx.ai.provider",
+    normalize: normalizeProvider,
+    scope: "user",
+  },
   /**
    * `"gpt-4o"` is what a sender falls back to, NOT a stored choice. A surface that writes back must
    * read through `readStoredSetting`, or it persists a model the user never picked.

package/src/settings/contributed-section.ts

@@ -49,7 +49,8 @@ import { resolveContextPointer } from "../services/context-resolver";
 import { deriveSecretEnvName } from "../services/data-service";
 import { validateProjectConfig } from "../services/jx-validate";
 import { notify } from "../services/notify";
-import { SETTINGS_DIALOG_REGION } from "../surfaces/settings-dialog";
+import { REGION_ATTR } from "../ui/regions";
+import { settingsRegion } from "./settings-workspace";
 import { mountContributedSurface } from "../surfaces/settings-contributed";
 
 import type { JsonSchema, SchemaFormContext } from "../ui/schema-form";
@@ -371,15 +372,23 @@ function sectionValue(key: string): JsonObject | null {
 // ─── Per-container mount ──────────────────────────────────────────────────────
 
 /**
- * A region under the settings dialog, which is where a contributed section is drawn (§17.1): its
- * entry rows and its entry editor are named under `overlay.dialog:settings`, so a shot can crop one
+ * A region under the Settings home, which is where a contributed section is drawn (§17.1): its
+ * entry rows and its entry editor are named under `pane.<id>/settings`, so a shot can crop one
  * without a selector.
  *
+ * The home is per pane, and a renderer is handed a container and nothing else, so the base is READ
+ * off the nearest region around the container, which is the home's own: the id is derived from what
+ * is on screen, as every region is (`ui/regions.ts`). A container not yet in a home names the
+ * primary pane's.
+ *
+ * @param {HTMLElement} container The element the section was rendered into
  * @param {string} part
  * @returns {string}
  */
-function sectionRegion(part: string): string {
-  return `${SETTINGS_DIALOG_REGION}/${part}`;
+function sectionRegion(container: HTMLElement, part: string): string {
+  const base =
+    container.closest(`[${REGION_ATTR}]`)?.getAttribute(REGION_ATTR) ?? settingsRegion("primary");
+  return `${base}/${part}`;
 }
 
 /** One mounted section: its document, its two island hosts, and what it was last asked to draw. */
@@ -455,7 +464,7 @@ function project(record: SectionMount): ContributedView {
   const sectionKey = contribution.key;
   const title = contribution.title ?? sectionKey;
   const actionsState = opts.actions ? "slot" : "none";
-  const editorRegion = sectionRegion("editor");
+  const editorRegion = sectionRegion(record.container, "editor");
   const words = entryWords(contribution.settings.entry?.noun);
 
   if ((contribution.settings.layout ?? "form") !== "map") {
@@ -483,7 +492,7 @@ function project(record: SectionMount): ContributedView {
     editorState: editing ? "editing" : "empty",
     entries: Object.keys(entries).map((name) => ({
       key: name,
-      region: sectionRegion(`entry:${name}`),
+      region: sectionRegion(record.container, `entry:${name}`),
       selected: name === selected,
     })),
     entryName: record.echo ?? (editing ? selected : ""),

package/src/settings/css-vars-editor.ts

@@ -386,9 +386,9 @@ function addOverride(container: HTMLElement, token: string, ctx: string): void {
  * per token are defined.
  *
  * Through the command rather than by writing the registry's section: the editor is hosted outside
- * Settings (the Styles workspace's Variables view), so selecting a section of a dialog that is not
- * open would change nothing the reader can see. A refusal is filed under "Styles", the workspace
- * the editor lives in, as the Variables view's own button files it.
+ * Settings (the Styles workspace's Variables view), so selecting a section of a workspace that is
+ * not on screen would change nothing the reader can see. A refusal is filed under "Styles", the
+ * workspace the editor lives in, as the Variables view's own button files it.
  */
 function openContextsSection(): void {
   void runActiveReported("settings.open", { section: "contexts" }, "Styles");
@@ -418,7 +418,7 @@ function actions(container: HTMLElement): CssVarsActions {
        * appended `'--dark': '(prefers-color-scheme: dark)'` to `$media` without ever using the word
        * breakpoint, which made this form the fourth and least discoverable definition site for a
        * map whose other three lived in the wizard, Overview and Properties › Media. It goes there
-       * through `settings.open`, so the dialog opens on Contexts however this editor is hosted.
+       * through `settings.open`, so Settings opens on Contexts however this editor is hosted.
        */
       manageContexts: () => {
         openContextsSection();

package/src/settings/general-settings.ts

@@ -22,7 +22,6 @@ import { projectState } from "../store";
 import { updateSiteConfig } from "../site-context";
 import { activeRegistry } from "../commands/active-registry";
 import { runActiveReported } from "../commands/run-reported";
-import { closeSettingsDialog } from "./settings-dialog";
 import { getPlatform } from "../platform";
 import { mountOverviewSurface } from "../surfaces/settings-overview";
 import { previewAssetSrcFor } from "../canvas/asset-refs";
@@ -265,11 +264,9 @@ function actions(container: HTMLElement): OverviewActions {
      * says how to get there. This used to write `session.ui.canvasMode` here directly — a second
      * implementation of a capability, `studio-ui-guidelines.md` §12.5's defect in miniature: the
      * button and the command could disagree about what "open Project Styles" means, and only one of
-     * them was reachable by name. Overview is drawn in the settings dialog, so the dialog closes
-     * first: left up, it would cover the workspace the reader just asked for.
+     * them was reachable by name.
      */
     openStyles: () => {
-      closeSettingsDialog();
       void runActiveReported("view.setWorkspace", { workspace: "styles" }, "Settings");
     },
     setDescription: (value: string) => {

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);
+  }
+}