@jxsuite/studio 2.4.3 → 4.0.0

package/src/settings/dependencies-editor.ts

@@ -1,21 +1,32 @@
 /// <reference lib="dom" />
 /**
- * Dependencies settings section — an outdated-aware table of the project's npm dependencies. Shows
+ * Dependencies settings section — a registry-aware table of the project's npm dependencies. Shows
  * current vs latest version, with per-row update/remove, an add-package field, "update all", and
- * reinstall. @jxsuite/* rows target the version this Studio build embeds; other packages target the
- * newest published version reported by the backend.
+ * reinstall.
+ *
+ * **Every row's Latest is that package's own newest version on npm.** Two assumptions used to sit
+ * between this table and the registry, and both are gone:
+ *
+ * 1. `@jxsuite/*` rows targeted `VERSION`, the version this Studio build embeds — right only while the
+ *    whole suite released as one number. The packages release on their own cadences now, so that
+ *    proposed a version that may never have been published, for a package whose real latest the
+ *    table had not looked at. The same correction `packages/jxsuite-update.ts` already made.
+ * 2. The backend was asked for _outdated_ packages, so a package already at its latest arrived as an
+ *    absence and the column read `—` — the registry's answer was known and thrown away. It now asks
+ *    `platform.packageVersions()`, which reports every dependency's latest either way, and the
+ *    comparison that decides whether an update button appears happens here.
+ *
+ * A row shows `—` only where there is genuinely nothing to show: a `workspace:`/`file:`/git spec, a
+ * package the registry does not answer for, or a host with no registry lookup at all.
  */
 
 import { html, render as litRender } from "lit-html";
 import { getPlatform } from "../platform";
-import { VERSION } from "../version";
 import { notify } from "../services/notify";
 import { showProgressModal } from "../ui/progress-modal";
-import { isComparable, isUpgrade, stripRange } from "../packages/semver";
+import { isUpgrade, stripRange } from "../packages/semver";
 import type { PackageInfo } from "../types";
 
-const JXSUITE_PREFIX = "@jxsuite/";
-
 interface Update {
   name: string;
   version: string;
@@ -28,13 +39,21 @@ let _latest = new Map<string, string>();
 let _busy = false;
 let _addName = "";
 
-/** The version a package can be updated to, or null if it is already current. */
+/** This package's newest published version, or null when the registry did not answer for it. */
 function latestFor(p: PackageInfo): string | null {
-  if (p.name.startsWith(JXSUITE_PREFIX) && isComparable(VERSION) && isUpgrade(p.version, VERSION)) {
-    return VERSION;
-  }
-  const registry = _latest.get(p.name);
-  return registry && isUpgrade(p.version, registry) ? registry : null;
+  return _latest.get(p.name) ?? null;
+}
+
+/**
+ * The version a package can be updated TO, or null when it is current or ahead.
+ *
+ * `isUpgrade`, not "differs from latest": a project deliberately pinned ahead of the registry — a
+ * prerelease, or a range bumped before the publish landed — would otherwise be offered a downgrade
+ * with an update button.
+ */
+function upgradeFor(p: PackageInfo): string | null {
+  const latest = latestFor(p);
+  return latest && isUpgrade(p.version, latest) ? latest : null;
 }
 
 async function load() {
@@ -45,10 +64,10 @@ async function load() {
     _packages = [];
   }
   _latest = new Map();
-  if (platform.outdatedPackages) {
+  if (platform.packageVersions) {
     try {
-      for (const o of await platform.outdatedPackages()) {
-        _latest.set(o.name, o.latest);
+      for (const info of await platform.packageVersions()) {
+        _latest.set(info.name, info.latest);
       }
     } catch {
       /* Registry lookups are best-effort */
@@ -118,9 +137,9 @@ async function onUpdateAll() {
   }
   const updates = (_packages ?? [])
     .map((p): Update | null => {
-      const latest = latestFor(p);
-      return latest
-        ? { dev: Boolean(p.dev), name: p.name, version: `^${stripRange(latest)}` }
+      const target = upgradeFor(p);
+      return target
+        ? { dev: Boolean(p.dev), name: p.name, version: `^${stripRange(target)}` }
         : null;
     })
     .filter((u): u is Update => u !== null);
@@ -152,6 +171,7 @@ async function onReinstall() {
 
 function row(p: PackageInfo) {
   const latest = latestFor(p);
+  const upgrade = upgradeFor(p);
   return html`
     <sp-table-row>
       <sp-table-cell>
@@ -163,13 +183,13 @@ function row(p: PackageInfo) {
       <sp-table-cell>${latest ?? "—"}</sp-table-cell>
       <sp-table-cell>
         ${
-          latest
+          upgrade
             ? html`<sp-action-button
                 size="s"
                 quiet
                 ?disabled=${_busy}
-                title="Update to ${latest}"
-                @click=${() => onUpdate(p, latest)}
+                title="Update to ${upgrade}"
+                @click=${() => onUpdate(p, upgrade)}
               >
                 <sp-icon-refresh slot="icon"></sp-icon-refresh>
               </sp-action-button>`
@@ -194,7 +214,7 @@ function render() {
     return;
   }
   const pkgs = _packages ?? [];
-  const hasUpdates = pkgs.some((p) => latestFor(p) !== null);
+  const hasUpdates = pkgs.some((p) => upgradeFor(p) !== null);
 
   const tpl = html`
     <div class="settings-section">

package/src/settings/general-settings.ts

@@ -12,9 +12,9 @@
 import { html, render as litRender, nothing } from "lit-html";
 import { live } from "lit-html/directives/live.js";
 import { errorMessage } from "@jxsuite/schema/parse";
-import { projectState, updateUi } from "../store";
+import { projectState } from "../store";
 import { updateSiteConfig } from "../site-context";
-import { tabOfContainer } from "../canvas/canvas-surface";
+import { activeRegistry } from "../commands/active-registry";
 import { getPlatform } from "../platform";
 
 import type { JxHeadEntry, ProjectConfig } from "@jxsuite/schema/types";
@@ -165,16 +165,27 @@ export function renderGeneralSettings(container: HTMLElement) {
   };
 
   /*
-   * Project Styles is the SAME document in a different editor, so this is a mode switch rather
-   * than a navigation. The predecessor closed the settings modal and opened `project.json` in a
-   * tab — the configuration IA jumping into the document IA, plan §9.3's own example of the split
-   * P6 removes. Nothing closes now, because nothing was covering anything.
+   * Project Styles is the SAME document in a different editor, and `styles.open` is the one place
+   * that says so. This used to write `session.ui.canvasMode` here directly — a second
+   * implementation of a capability, §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.
+   * The mode is still a fact about the TAB, and there is exactly one `project.json` tab, so
+   * `revealTab`'s `focusPane` puts the keyboard on whichever pane holds it.
+   *
+   * Rendered FROM the record, so the button is disabled with its `requires` sentence rather than
+   * absent when it cannot act (§12.3), and it cannot drift from the palette row or the gear menu.
    */
-  const onEditGlobalStyles = () => {
-    // THIS pane's tab. The Project Settings editor is stage content, so a settings document
-    // Open in the side pane used to send the PRIMARY into the Stylebook.
-    updateUi(tabOfContainer(container), "canvasMode", "stylebook");
-  };
+  const registry = activeRegistry();
+  const stylesCommand = registry?.get("styles.open");
+  /* The record's TITLE, and nothing else off the registry.
+     `disabledReason` would be the §12.3 shape for a control that can be inapplicable — but this one
+     cannot be. `styles.open` is gated on `ctx.project.open`, and Overview is a section of the
+     project's own configuration document, so by the time this renders the answer is always yes.
+     Asking anyway would also be a FOCUS read inside a function that was handed a container, which
+     is what `scripts/check-pane-singletons.ts` rule 4 forbids: a pane-scoped surface must not report
+     the focused pane's state. A project-level verb happens to read the same in every pane, but the
+     way to be right about that is not to ask. The one thing that can genuinely be missing is the
+     registry itself (bootstrap order, a test), and that is an existence check, not a state read. */
 
   const currentFavicon = config.favicon;
 
@@ -266,7 +277,14 @@ export function renderGeneralSettings(container: HTMLElement) {
           Design tokens and the default element styles that apply across every page. Opens Project
           Styles over this same document.
         </p>
-        <sp-action-button size="s" @click=${onEditGlobalStyles}>
+        <sp-action-button
+          size="s"
+          ?disabled=${!stylesCommand}
+          title=${stylesCommand?.title ?? ""}
+          @click=${() => {
+            void registry?.run("styles.open");
+          }}
+        >
           Edit Global Styles
         </sp-action-button>
       </div>

package/src/settings/preferences-accounts.ts

@@ -20,15 +20,9 @@
  */
 
 import { clearGithubToken, githubTokenLocation, githubTokenStored } from "../github/github-auth";
-import { getCfAccountId, getCfToken, setCfAccountId, setCfToken } from "../services/cf-settings";
-import {
-  getBaseUrl,
-  getModel,
-  hasOpenAiKey,
-  setBaseUrl,
-  setModel,
-  setOpenAiKey,
-} from "../services/ai-settings";
+import { clearCfConnection, getCfAccountId, getCfToken } from "../services/cf-settings";
+import { clearAiProvider, getBaseUrl, hasOpenAiKey } from "../services/ai-settings";
+import { preferredModel } from "../services/ai-models";
 
 /** One stored credential, as the Accounts section renders it. */
 export interface AccountRecord {
@@ -53,7 +47,7 @@ export function listAccounts(): AccountRecord[] {
   const githubToken = githubTokenStored();
   const cfToken = getCfToken();
   const cfAccount = getCfAccountId();
-  const model = getModel();
+  const model = preferredModel();
   const endpoint = getBaseUrl();
   return [
     {
@@ -74,11 +68,7 @@ export function listAccounts(): AccountRecord[] {
         ? `Key stored. Model ${model}${endpoint ? ` via ${endpoint}` : ""}.`
         : "No key stored. The Assistant section is where one is entered.",
       connected: hasOpenAiKey(),
-      revoke: () => {
-        setOpenAiKey("");
-        setBaseUrl("");
-        setModel("");
-      },
+      revoke: clearAiProvider,
     },
     {
       id: "cloudflare",
@@ -87,10 +77,7 @@ export function listAccounts(): AccountRecord[] {
         ? `Connected${cfAccount ? ` — account ${cfAccount}` : ""}.`
         : "Not connected. Publishing will ask when it needs it.",
       connected: Boolean(cfToken),
-      revoke: () => {
-        setCfToken("");
-        setCfAccountId("");
-      },
+      revoke: clearCfConnection,
     },
   ];
 }

package/src/settings/preferences-dialog.ts

@@ -48,47 +48,24 @@ import type { ShortcutRow } from "../commands/reference";
 import type { RebindResult } from "./preferences-keymap";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 
-/** One section of the sheet. The `id` is what `app.preferences { section }` accepts. */
-export interface PreferencesSection {
-  id: string;
-  title: string;
-  /** The one-line answer to "what is in here", shown under the heading. */
-  blurb: string;
-}
-
-/**
- * The sections, in sheet order.
- *
- * §9.3 lists six for the finished surface (Editor behaviour and Updates/About are the other two).
- * Four are built; a section is added here when it has something to configure, never before — an
- * empty pane is the "declared but unbuilt" state the rail already refuses to render.
+/*
+ * The sections moved to `./preferences-sections`, a leaf with no imports, so the rail's gear menu
+ * can enumerate `app.preferences`'s own `section` argument without pulling this module's graph
+ * (ai-models, github-auth, cf-settings, the settings kernel) into the rail. Re-exported here so
+ * every existing import site is unchanged.
  */
-export const PREFERENCES_SECTIONS: readonly PreferencesSection[] = [
-  { id: "appearance", title: "Appearance", blurb: "How the Studio chrome looks." },
-  {
-    id: "assistant",
-    title: "Assistant",
-    blurb: "The AI provider the assistant talks to. Stored on this machine.",
-  },
-  {
-    id: "accounts",
-    title: "Accounts",
-    blurb: "Every credential Studio holds, and how to make it forget one.",
-  },
-  {
-    id: "keyboard",
-    title: "Keyboard",
-    blurb: "Generated from the command registry — the app's own record of every chord.",
-  },
-];
-
-/** The section the sheet opens on when none is named. */
-export const DEFAULT_PREFERENCES_SECTION = PREFERENCES_SECTIONS[0]!.id;
-
-/** Whether a string names a section. */
-export function isPreferencesSection(id: unknown): boolean {
-  return PREFERENCES_SECTIONS.some((section) => section.id === id);
-}
+import {
+  DEFAULT_PREFERENCES_SECTION,
+  isPreferencesSection,
+  PREFERENCES_SECTIONS,
+} from "./preferences-sections";
+
+export {
+  DEFAULT_PREFERENCES_SECTION,
+  isPreferencesSection,
+  PREFERENCES_SECTIONS,
+} from "./preferences-sections";
+export type { PreferencesSection } from "./preferences-sections";
 
 // ─── Open state ───────────────────────────────────────────────────────────────
 
@@ -588,7 +565,7 @@ export function preferencesCommands(): AnyCommand[] {
       id: "app.preferences",
       level: "application",
       keybinding: "mod+,",
-      menus: ["commandbar/overflow", "palette"],
+      menus: ["commandbar/overflow", "settings/menu", "palette"],
       group: "7_settings",
       run: (_ctx, args) => {
         const section = (args as { section?: unknown } | undefined)?.section;

package/src/settings/preferences-keymap.ts

@@ -34,12 +34,14 @@
  */
 
 import { normalizeChord, overlappingScopes, parseChord } from "../commands/keymap";
+import { SETTINGS } from "../services/settings/definitions";
+import { clearSettings, readStoredSetting, setSetting } from "../services/settings/kernel";
 import type { KeybindingOverrides } from "../commands/keymap";
 import type { KeyScope } from "../commands/levels";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 
 /** Where the user's layer is kept. One key, one JSON object of `id → chords`. */
-export const KEYBINDINGS_STORAGE_KEY = "jx.keybindings";
+export const KEYBINDINGS_STORAGE_KEY = SETTINGS.keybindings.key;
 
 /** Keys that type nothing, and so may be bound without a modifier. */
 const UNMODIFIED_KEYS = new Set([
@@ -114,12 +116,7 @@ export function isBindableChord(chord: string): boolean {
 }
 
 function readRaw(): string {
-  try {
-    return globalThis.localStorage?.getItem(KEYBINDINGS_STORAGE_KEY) ?? "";
-  } catch {
-    // Storage unavailable (private mode): every command keeps the chord it declared.
-    return "";
-  }
+  return readStoredSetting(SETTINGS.keybindings);
 }
 
 /** Every chord in one stored entry, canonicalised — or `null` if any of them is not a chord. */
@@ -175,18 +172,11 @@ export function loadKeybindingOverrides(): Map<string, string[]> {
 }
 
 function store(layer: KeybindingOverrides): void {
-  try {
-    if (layer.size === 0) {
-      globalThis.localStorage?.removeItem(KEYBINDINGS_STORAGE_KEY);
-      return;
-    }
-    globalThis.localStorage?.setItem(
-      KEYBINDINGS_STORAGE_KEY,
-      JSON.stringify(Object.fromEntries(layer)),
-    );
-  } catch {
-    // Storage unavailable — the rebinding is live in this window and is not remembered.
+  if (layer.size === 0) {
+    clearSettings([SETTINGS.keybindings]);
+    return;
   }
+  setSetting(SETTINGS.keybindings, JSON.stringify(Object.fromEntries(layer)));
 }
 
 /**

package/src/settings/preferences-sections.ts

@@ -0,0 +1,57 @@
+/**
+ * The Preferences sections — the values `app.preferences { section }` accepts.
+ *
+ * A LEAF: it imports nothing, and that is the whole reason it is a file. `preferences-dialog.ts`
+ * reaches `ui/layers`, `ui/ai-credentials-form`, `ui/ai-managed-connect`, `preferences-accounts` (→
+ * github-auth, cf-settings, ai-settings, ai-models) and `preferences-keymap` (→
+ * services/settings/kernel) — a graph so wide that `tests/preferences-dialog.test.ts` mocks
+ * `ai-models` merely to import the module at all. The rail's gear menu needs four labels from it
+ * and nothing else, so it takes the labels rather than the graph.
+ *
+ * Same split, and the same stated reason, as `settings/section-registry.ts`: what is contributed to
+ * is not the surface that renders it, and keeping the two apart is what lets either be replaced.
+ *
+ * `preferences-dialog.ts` re-exports every symbol here, so no existing import site moved.
+ */
+
+/** One section of the sheet. The `id` is what `app.preferences { section }` accepts. */
+export interface PreferencesSection {
+  id: string;
+  title: string;
+  /** The one-line answer to "what is in here", shown under the heading. */
+  blurb: string;
+}
+
+/**
+ * The sections, in sheet order.
+ *
+ * §9.3 lists six for the finished surface (Editor behaviour and Updates/About are the other two).
+ * Four are built; a section is added here when it has something to configure, never before — an
+ * empty pane is the "declared but unbuilt" state the rail already refuses to render.
+ */
+export const PREFERENCES_SECTIONS: readonly PreferencesSection[] = [
+  { id: "appearance", title: "Appearance", blurb: "How the Studio chrome looks." },
+  {
+    id: "assistant",
+    title: "Assistant",
+    blurb: "The AI provider the assistant talks to. Stored on this machine.",
+  },
+  {
+    id: "accounts",
+    title: "Accounts",
+    blurb: "Every credential Studio holds, and how to make it forget one.",
+  },
+  {
+    id: "keyboard",
+    title: "Keyboard",
+    blurb: "Generated from the command registry — the app's own record of every chord.",
+  },
+];
+
+/** The section the sheet opens on when none is named. */
+export const DEFAULT_PREFERENCES_SECTION = PREFERENCES_SECTIONS[0]!.id;
+
+/** Whether a string names a section. */
+export function isPreferencesSection(id: unknown): boolean {
+  return PREFERENCES_SECTIONS.some((section) => section.id === id);
+}

package/src/settings/schema-field-ui.ts

@@ -5,7 +5,7 @@
  */
 
 import { html, nothing } from "lit-html";
-import { camelToLabel } from "../utils/studio-utils";
+import { camelToLabel, isMediaFormat } from "../utils/studio-utils";
 
 export interface SchemaProperty {
   type?: string;
@@ -483,7 +483,7 @@ export function yamlDefault(type: string, format?: string) {
   if (format === "date") {
     return new Date().toISOString().split("T")[0];
   }
-  if (format === "image") {
+  if (isMediaFormat(format)) {
     return '""';
   }
   switch (type) {

package/src/settings/settings-document.ts

@@ -52,6 +52,8 @@ import { renderGeneralSettings } from "./general-settings";
 import { renderHeadEditor } from "./head-editor";
 import { renderLocalesSection } from "./locales-section";
 import { selectContributedEntry } from "./contributed-section";
+// The NAME and the wire value, kept apart by that module on purpose — see its docstring.
+import { PROJECT_STYLES_TITLE, PROJECT_STYLES_VIEW } from "../style/project-styles";
 import type { Tab } from "../tabs/tab";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 
@@ -192,28 +194,37 @@ export function settingsDocumentOpen(): boolean {
  *
  * @returns {Tab | null} The tab, or null when no project is open
  */
-export function showSettingsDocument(): Tab | null {
+export function showSettingsDocument(mode: string = SETTINGS_MODE): Tab | null {
   const state = requireProjectState();
   if (!state) {
     return null;
   }
   const existing = workspace.tabs.get(PROJECT_CONFIG_PATH);
   if (existing) {
-    for (const mode of SETTINGS_TAB_MODES) {
-      if (!existing.capabilities.modes.includes(mode)) {
-        existing.capabilities.modes.unshift(mode);
+    for (const candidate of SETTINGS_TAB_MODES) {
+      if (!existing.capabilities.modes.includes(candidate)) {
+        existing.capabilities.modes.unshift(candidate);
       }
     }
-    existing.session.ui.canvasMode = SETTINGS_MODE;
+    existing.session.ui.canvasMode = mode;
     existing.session.ui.preview = false;
     return revealTab(existing as unknown as Tab);
   }
-  return openTab({
+  const tab = openTab({
     capabilities: { modes: [...SETTINGS_TAB_MODES] },
     document: (state.projectConfig ?? {}) as unknown as Record<string, unknown>,
     documentPath: PROJECT_CONFIG_PATH,
     id: PROJECT_CONFIG_PATH,
   });
+  /* The mode is written here rather than left to the capability list, because `createTab` seeds
+     `session.ui.canvasMode` from `resolvedModes.find(m => m !== "preview")` (`tabs/tab.ts`) — i.e.
+     from `SETTINGS_TAB_MODES[0]`, which is `settings`. A second door over the same document has to
+     SAY which editor it is, or `styles.open` from a cold workspace opens the settings form. The
+     capability list stays in its declared order for the same reason it always had one: the tab's
+     Editor control offers the modes in that order. */
+  tab.session.ui.canvasMode = mode;
+  tab.session.ui.preview = false;
+  return tab;
 }
 
 /**
@@ -328,10 +339,17 @@ export function settingsCommands(): AnyCommand[] {
       // ⌘⇧, — the other half of §5.3's `⌘, / ⌘⇧,` pair. `app.preferences` shipped with its chord
       // And this one did not, so the two halves of "settings" were a keystroke and a palette search.
       keybinding: "mod+shift+,",
-      menus: ["commandbar/overflow", "palette"],
+      menus: ["commandbar/overflow", "settings/menu", "palette"],
       group: "7_settings",
       requires: "an open project",
-      when: (ctx) => ctx.project.open,
+      /* `enablement`, not `when`: with no project open this row is DRAWN, greyed, carrying the
+         sentence above — §12.3's rule that a control which cannot act explains itself rather than
+         vanishing, and the reason the palette greys unavailable commands instead of hiding them.
+         It used to be `when`, so the rail's Settings menu held one row on the welcome screen and
+         said nothing about the other two; "why can't I" had no answer anywhere. The gate itself is
+         unchanged — `enabledWith` still refuses, so `registry.run` and the assistant's tool still
+         throw `CommandUnavailableError` exactly as before. */
+      enablement: (ctx) => ctx.project.open,
       aiTool: {
         description:
           "Open the project's Settings, optionally on a named section (overview, contexts, head, " +
@@ -370,7 +388,45 @@ export function settingsCommands(): AnyCommand[] {
         }
         notifySettingsDocument();
       },
-      title: "Open Settings",
+      title: "Open Project Settings",
+    },
+    /*
+     * The SECOND door over the same document. `project.json` has three editors — the settings form,
+     * Project Styles and the raw source — and until now only one of them had a name: Project Styles
+     * was reached by the pane's Editor control (which can only re-mode a tab that is ALREADY open)
+     * and by a hand-written `canvasMode` assignment inside Overview. `canvas.setMode` cannot stand
+     * in for this: it is level `document` and requires an open one, so from a cold workspace there
+     * is nothing to re-mode.
+     *
+     * It is a peer of `settings.open` and declares the same gate, byte for byte (§12.4: two verbs
+     * over one document declare ONE availability rule). `styles.*` is the project-level plural of
+     * the selection-level `style.*` verbs in `panels/style-panel.ts`; the ids are one letter apart
+     * and the levels are the reason.
+     */
+    {
+      category: "Project",
+      id: "styles.open",
+      level: "project",
+      menus: ["settings/menu", "palette"],
+      /* A distinct ordinal inside the settings family, so the gear reads Settings → Styles.
+         §12.3's lever is `group`, never a per-menu sort; `styles.open` is not in the ⬢ menu, so
+         nothing else sees this string. */
+      group: "7_settings_styles",
+      requires: "an open project",
+      // §12.4: two verbs over ONE document declare ONE availability rule, byte-identical.
+      enablement: (ctx) => ctx.project.open,
+      aiTool: {
+        description:
+          "Open the project's configuration document in its Project Styles editor — the design " +
+          "tokens and the default element styles that apply across every page.",
+        name: "open_project_styles",
+      },
+      run: () => {
+        showSettingsDocument(PROJECT_STYLES_VIEW);
+      },
+      // Named, never spelled from the wire value: `stylebook` is shared with `dist/iframe-entry.js`
+      // And may never be renamed, so nothing a reader sees is derived from it (`style/project-styles`).
+      title: `Open ${PROJECT_STYLES_TITLE}`,
     },
   ];
 }

package/src/shell.ts

@@ -22,6 +22,8 @@
  */
 
 import { effect, effectScope, reactive } from "./reactivity";
+import { SETTINGS } from "./services/settings/definitions";
+import { readStoredSetting, setSetting } from "./services/settings/kernel";
 import { loadedMonaco } from "./services/monaco-lazy";
 import { applyStartupProfile } from "./services/profile";
 import { workspace } from "./workspace/workspace";
@@ -349,8 +351,6 @@ export interface ShellState {
 
 const DOCK_STORAGE_KEY = "jx-studio-panel-widths";
 
-const THEME_STORAGE_KEY = "jx-studio-theme";
-
 /**
  * The per-project record's key prefix — one namespaced record per project root (§4.4).
  *
@@ -378,14 +378,10 @@ function isChromeTheme(value: unknown): value is ChromeTheme {
   return typeof value === "string" && (CHROME_THEMES as readonly string[]).includes(value);
 }
 
-/** Read the persisted theme, falling back to {@link DEFAULT_THEME} on absent/corrupt storage. */
+/** Read the persisted theme, falling back to {@link DEFAULT_THEME} on an absent/unknown value. */
 function readPersistedTheme(): ChromeTheme {
-  try {
-    const stored = localStorage.getItem(THEME_STORAGE_KEY);
-    return isChromeTheme(stored) ? stored : DEFAULT_THEME;
-  } catch {
-    return DEFAULT_THEME;
-  }
+  const stored = readStoredSetting(SETTINGS.theme);
+  return isChromeTheme(stored) ? stored : DEFAULT_THEME;
 }
 
 export const DOCK_IDS: DockId[] = ["left", "right", "bottom"];
@@ -1168,11 +1164,7 @@ export function setChromeTheme(theme: ChromeTheme): void {
     return;
   }
   shell.theme = theme;
-  try {
-    localStorage.setItem(THEME_STORAGE_KEY, theme);
-  } catch {
-    // Storage full or unavailable — the theme is still applied, just not remembered.
-  }
+  setSetting(SETTINGS.theme, theme);
 }
 
 /**