@jxsuite/studio 6.1.1 → 8.0.0

package/src/settings/extension-sections.ts

@@ -8,20 +8,31 @@
  * path.
  */
 
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
 import { getFormats, loadExtensions, loadFormats } from "../format/format-host";
-import { registerSettingsSection, unregisterSettingsSection } from "./section-registry";
+import {
+  DEFAULT_SETTINGS_GROUP,
+  isSettingsGroupId,
+  registerSettingsSection,
+  unregisterSettingsSection,
+} from "./section-registry";
 import { renderContributedSection } from "./contributed-section";
 import { dataSectionActions } from "../panels/data-grid";
 import type { ExtensionContributionInfo } from "../types";
 import type { JsonSchema } from "../ui/schema-form";
-import type { SettingsContribution } from "./contributed-section";
+import type { ContributedSectionOptions, SettingsContribution } from "./contributed-section";
+import type { SettingsGroupId } from "./section-registry";
 
 /** The `$studio.settings` block shape consumed here (nav metadata + the renderer inputs). */
 interface StudioSettingsBlock {
   icon?: string;
   label?: string;
+  /** The nav group: `general`, `integrations` (the default) or `advanced`. */
+  group?: string;
   order?: number;
   layout?: "map" | "form";
+  /** The sentence the section body opens with, in place of its group's (extensions.md §9.1). */
+  intro?: string;
   entry?: SettingsContribution["settings"]["entry"];
 }
 
@@ -29,7 +40,9 @@ interface StudioSettingsBlock {
 export interface DerivedSettingsSection {
   key: string;
   label: string;
+  group: SettingsGroupId;
   icon?: string | undefined;
+  intro?: string | undefined;
   order: number;
   contribution: SettingsContribution;
 }
@@ -49,34 +62,46 @@ const DEFAULT_SECTION_ORDER = 100;
 export function deriveSettingsSection(
   info: ExtensionContributionInfo,
 ): DerivedSettingsSection | null {
-  const studio = info.studio as { settings?: StudioSettingsBlock } | null | undefined;
-  const settings = studio?.settings;
+  /* SAFETY: `$studio.settings` is the extensions.md §9.1 vocabulary, served verbatim from the
+     class descriptor; every member read below is optional and falls back through `??`, so an
+     omitted member degrades to the section defaults rather than reaching the renderer. */
+  const settings = info.studio?.settings as StudioSettingsBlock | null | undefined;
   if (!settings) {
     return null;
   }
   const { key } = info.project;
   const layout = settings.layout ?? "form";
+  /* SAFETY: the backend fills `entrySchema` with `properties[<key>]` of the extension's shipped
+     project fragment (compiler `site/format-host.ts`), which is a JSON Schema by construction. */
   const sectionSchema = (info.entrySchema ?? {}) as JsonSchema & {
     additionalProperties?: JsonSchema | boolean;
   };
   const entrySchema =
     layout === "map"
-      ? typeof sectionSchema.additionalProperties === "object"
+      ? isNonNullObject(sectionSchema.additionalProperties)
         ? sectionSchema.additionalProperties
         : {}
-      : (sectionSchema as JsonSchema);
+      : sectionSchema;
   const label = settings.label ?? info.project.title ?? key;
+  const sectionSettings: SettingsContribution["settings"] = {};
+  if (settings.entry !== undefined) {
+    sectionSettings.entry = settings.entry;
+  }
+  if (settings.layout !== undefined) {
+    sectionSettings.layout = settings.layout;
+  }
   return {
     contribution: {
       entrySchema,
       key,
-      settings: {
-        ...(settings.entry === undefined ? {} : { entry: settings.entry }),
-        ...(settings.layout === undefined ? {} : { layout: settings.layout }),
-      },
+      settings: sectionSettings,
       title: label,
     },
+    /* A group the nav does not draw falls back to the default rather than hiding the section:
+       an extension naming a group from a later vocabulary still gets its section listed. */
+    group: isSettingsGroupId(settings.group) ? settings.group : DEFAULT_SETTINGS_GROUP,
     icon: settings.icon,
+    intro: isString(settings.intro) ? settings.intro : undefined,
     key,
     label,
     order: settings.order ?? DEFAULT_SECTION_ORDER,
@@ -135,7 +160,9 @@ async function runSync(): Promise<void> {
       }
       const { contribution } = derived;
       registerSettingsSection({
+        group: derived.group,
         icon: derived.icon,
+        intro: derived.intro,
         key: derived.key,
         label: derived.label,
         order: derived.order,
@@ -143,10 +170,11 @@ async function runSync(): Promise<void> {
           // Data-domain sections get the Test/Push/Data-grid actions slot when the platform
           // Implements the protocol's data routes; every other section renders actions-free.
           const actions = dataSectionActions(derived.key);
-          renderContributedSection(container, contribution, {
-            formats: getFormats(),
-            ...(actions === null ? {} : { actions }),
-          });
+          const opts: ContributedSectionOptions = { formats: getFormats() };
+          if (actions !== null) {
+            opts.actions = actions;
+          }
+          renderContributedSection(container, contribution, opts);
         },
       });
       next.add(derived.key);

package/src/settings/extensions-section.ts

@@ -90,7 +90,10 @@ const mounted = new WeakMap<HTMLElement, ExtensionsSurfaceHandle>();
 const errors = new WeakMap<HTMLElement, string>();
 
 /** The sentence a row's state deserves, and the tone it is said in. */
-function noteFor(row: ExtensionRow): { note: string; noteTone: ExtensionRowView["noteTone"] } {
+type RowNote = Pick<ExtensionRowView, "note" | "noteTone">;
+
+/** Answer {@link RowNote} for one row. */
+function noteFor(row: ExtensionRow): RowNote {
   if (row.unavailable !== undefined) {
     return { note: row.unavailable, noteTone: "warn" };
   }

package/src/settings/general-settings.ts

@@ -16,12 +16,17 @@
  * container to a `render`, and this one mounts a document into it instead of rendering lit.
  */
 
+import { isString } from "@jxsuite/schema/guards";
 import { errorMessage } from "@jxsuite/schema/parse";
 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";
+import { PROJECT_CONFIG_PATH } from "../tabs/tab";
 
 import type {
   OverviewActions,
@@ -31,6 +36,7 @@ import type {
   OverviewValues,
 } from "../surfaces/settings-overview";
 import type { JxHeadEntry, ProjectConfig } from "@jxsuite/schema/types";
+import type { ProjectConfigPatch } from "../site-context";
 
 /**
  * The last failed write, per rendered section.
@@ -49,7 +55,7 @@ const mounted = new WeakMap<HTMLElement, OverviewSurfaceHandle>();
 
 /** The live project configuration, read at the moment it is needed rather than at render time. */
 function config(): ProjectConfig {
-  return (projectState?.projectConfig || {}) as ProjectConfig;
+  return projectState?.projectConfig || {};
 }
 
 // ─── Site description ($head meta) ───────────────────────────────────────────
@@ -66,7 +72,8 @@ function isDescriptionMeta(entry: JxHeadEntry): boolean {
  */
 function readDescription(cfg: ProjectConfig): string {
   const entry = (cfg.$head ?? []).find((e) => isDescriptionMeta(e));
-  return typeof entry?.attributes?.content === "string" ? entry.attributes.content : "";
+  const content = entry?.attributes?.content;
+  return isString(content) ? content : "";
 }
 
 /** `$head` with the description meta upserted (or dropped, when cleared). */
@@ -87,41 +94,105 @@ function headWithDescription(head: JxHeadEntry[], text: string): JxHeadEntry[] {
   );
 }
 
+// ─── Favicon ($head link) ───────────────────────────────────────────────────
+
+/**
+ * True for a `<link>` whose `rel` names the `icon` relation.
+ *
+ * `rel` is a set of space-separated, ASCII case-insensitive tokens (HTML Standard, link types), so
+ * the legacy `rel="shortcut icon"` every favicon snippet still carries is the same relation as
+ * `rel="icon"`. `apple-touch-icon` is a different token and is not the favicon.
+ */
+function isIconLink(entry: JxHeadEntry): boolean {
+  const rel = entry.attributes?.rel;
+  return (
+    entry.tagName === "link" &&
+    isString(rel) &&
+    rel
+      .toLowerCase()
+      .split(/\s+/u)
+      .some((token) => token === "icon")
+  );
+}
+
+/**
+ * The site favicon. Like the description it is not a top-level `project.json` key (the composed
+ * schema is closed, and no compiler stage reads one): it is the `<link rel="icon">` in `$head`,
+ * which is what every starter and `@jxsuite/create` write and what the browser reads
+ * (`site-architecture.md` §2).
+ */
+function readFavicon(cfg: ProjectConfig): string {
+  const href = (cfg.$head ?? []).find((e) => isIconLink(e))?.attributes?.href;
+  return isString(href) ? href : "";
+}
+
+/**
+ * `$head` with the icon link pointing at `href`.
+ *
+ * The existing link is rewritten in place, so its position among the head entries and any other
+ * attribute an author gave it (`sizes`, a media query) survive. `type` is the one attribute that is
+ * dropped: it describes the file being replaced, and a new upload may be a different format.
+ */
+function headWithFavicon(head: JxHeadEntry[], href: string): JxHeadEntry[] {
+  if (!head.some((e) => isIconLink(e))) {
+    return [...head, { attributes: { href, rel: "icon" }, tagName: "link" }];
+  }
+  return head.map((entry) => {
+    if (!isIconLink(entry)) {
+      return entry;
+    }
+    const { type: _type, ...attributes } = entry.attributes ?? {};
+    return { ...entry, attributes: { ...attributes, href } };
+  });
+}
+
+/** The file name an uploaded favicon is stored under: `favicon` plus the upload's own extension. */
+function faviconFileName(file: File): string {
+  const dot = file.name.lastIndexOf(".");
+  const ext = dot > 0 ? file.name.slice(dot + 1).toLowerCase() : "";
+  return /^[a-z0-9]+$/u.test(ext) ? `favicon.${ext}` : "favicon.ico";
+}
+
 /**
  * The patch that _removes_ `url`. `undefined` survives the object spread inside `updateSiteConfig`
  * and `JSON.stringify` then drops the key, so clearing the field clears the setting instead of
  * persisting an empty string the build would have to special-case (`site-build.ts` gates the
- * sitemap on `Boolean(url)` but still forwards `""` into the render context). The cast is the price
- * of `exactOptionalPropertyTypes` — `ProjectConfig["url"]` is `string`, never `string |
- * undefined`.
+ * sitemap on `Boolean(url)` but still forwards `""` into the render context). A
+ * {@link ProjectConfigPatch} rather than a `Partial<ProjectConfig>`, because under
+ * `exactOptionalPropertyTypes` only the patch type can carry an `undefined` member.
  */
-const CLEAR_URL = { url: undefined } as unknown as Partial<ProjectConfig>;
+const CLEAR_URL: ProjectConfigPatch = { url: undefined };
+
+/** The record the Global Styles button is drawn from: **Go to Styles**, the workspace's ⌘4. */
+const STYLES_COMMAND = "workspace.focus.styles";
 
 // ─── Projection ──────────────────────────────────────────────────────────────
 
 /**
  * What the surface should be showing, from the configuration and the registry as they stand now.
  *
- * The Project Styles button is rendered FROM the `styles.open` record, so it is disabled rather
- * than absent when it cannot act (`studio-ui-guidelines.md` §12.3) and it cannot drift from the
- * palette row or the gear menu. The record's TITLE, and nothing else off the registry:
+ * The Global Styles button is rendered FROM the `workspace.focus.styles` record (**Go to Styles**,
+ * ⌘4), whose run is `view.setWorkspace { workspace: "styles" }`, so it is disabled rather than
+ * absent when it cannot act (`studio-ui-guidelines.md` §12.3) and it cannot drift from the palette
+ * row or the switcher's tab. The record's TITLE, and nothing else off the registry:
  * `disabledReason` would be the `studio-ui-guidelines.md` §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.
+ * inapplicable, but this one cannot be — the switch is gated on `ctx.project.open` and Overview is
+ * a section of the project's own configuration, 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.
  */
 function values(container: HTMLElement): OverviewValues {
   const cfg = config();
-  const command = activeRegistry()?.get("styles.open");
+  const command = activeRegistry()?.get(STYLES_COMMAND);
   return {
     description: readDescription(cfg),
     error: errors.get(container) ?? null,
-    favicon: typeof cfg.favicon === "string" ? cfg.favicon : "",
+    favicon: readFavicon(cfg),
+    // `project.json` authored it, whatever tab is in front: the section is project-level.
+    faviconSrc: previewAssetSrcFor(readFavicon(cfg), PROJECT_CONFIG_PATH),
     name: cfg.name ?? "",
     stylesDisabled: command === undefined,
     stylesTitle: command?.title ?? "",
@@ -145,7 +216,7 @@ function actions(container: HTMLElement): OverviewActions {
 
   /** Persist a patch, surfacing the rejection instead of swallowing it. */
   const persist = async (
-    patch: Partial<ProjectConfig>,
+    patch: ProjectConfigPatch,
     field: OverviewErrorField = "section",
   ): Promise<void> => {
     try {
@@ -175,29 +246,31 @@ function actions(container: HTMLElement): OverviewActions {
       if (!file) {
         return;
       }
+      // `public/` is copied to the site root verbatim, so `public/favicon.svg` is `/favicon.svg`.
+      const name = faviconFileName(file);
       try {
-        await getPlatform().uploadFile("public/favicon.ico", file);
+        await getPlatform().uploadFile(`public/${name}`, file);
       } catch (error) {
         reject("favicon", `Could not upload the favicon — ${errorMessage(error)}`);
         return;
       }
-      await persist({ favicon: "/favicon.ico" }, "favicon");
+      await persist({ $head: headWithFavicon(config().$head ?? [], `/${name}`) }, "favicon");
     });
     input.click();
   };
 
   return {
     /*
-     * 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
+     * Global styles are the Styles workspace's, and the workspace switch is the one place that
+     * 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. 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.
+     * 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.
      */
     openStyles: () => {
-      void activeRegistry()?.run("styles.open");
+      closeSettingsDialog();
+      void runActiveReported("view.setWorkspace", { workspace: "styles" }, "Settings");
     },
     setDescription: (value: string) => {
       echo({ description: value });

package/src/settings/locales-section.ts

@@ -30,6 +30,7 @@ import { updateSiteConfig } from "../site-context";
 import type { LocalesActions, LocalesView } from "../surfaces/settings-locales";
 import type { LocaleRouting } from "@jxsuite/schema/locale";
 import type { ProjectConfig } from "@jxsuite/schema/types";
+import type { ProjectConfigPatch } from "../site-context";
 
 /**
  * The form beside the file: the tag being typed, and the last write that failed.
@@ -67,9 +68,9 @@ function form(container: HTMLElement): Form {
  * value the file still holds.
  *
  * @param {HTMLElement} container
- * @param {Partial<ProjectConfig>} patch
+ * @param {ProjectConfigPatch} patch
  */
-async function persist(container: HTMLElement, patch: Partial<ProjectConfig>): Promise<void> {
+async function persist(container: HTMLElement, patch: ProjectConfigPatch): Promise<void> {
   try {
     await updateSiteConfig(patch);
     form(container).error = "";
@@ -81,7 +82,7 @@ async function persist(container: HTMLElement, patch: Partial<ProjectConfig>): P
 
 /** The live project configuration, or an empty one before a project is open. */
 function config(): ProjectConfig {
-  return (projectState?.projectConfig ?? {}) as ProjectConfig;
+  return projectState?.projectConfig ?? {};
 }
 
 /**
@@ -90,10 +91,10 @@ function config(): ProjectConfig {
  * `undefined` survives the object spread inside `updateSiteConfig` and `JSON.stringify` then drops
  * the key, so removing the last locale leaves a project with no `i18n` at all rather than one
  * declaring an empty list — which `resolveI18n` reports as "declared with no usable locale", a
- * build error for a state the author reached by deleting things. The cast is the price of
- * `exactOptionalPropertyTypes`, the same one `general-settings.ts`'s `CLEAR_URL` pays.
+ * build error for a state the author reached by deleting things. A {@link ProjectConfigPatch}, the
+ * same as `general-settings.ts`'s `CLEAR_URL`, because only the patch type can carry `undefined`.
  */
-const CLEAR_I18N = { i18n: undefined } as unknown as Partial<ProjectConfig>;
+const CLEAR_I18N: ProjectConfigPatch = { i18n: undefined };
 
 /** The routing modes, with the sentence that says what each does to a URL. */
 export const LOCALE_ROUTINGS: readonly { value: LocaleRouting; label: string }[] = [
@@ -242,9 +243,12 @@ function remove(container: HTMLElement, tag: string): void {
   const orphaned =
     current?.defaultLocale !== undefined &&
     canonicalizeLocale(current.defaultLocale) === canonicalizeLocale(tag);
-  void persist(container, {
-    i18n: { ...current, ...(orphaned ? { defaultLocale: kept[0]! } : {}), locales: kept },
-  });
+  const i18n: NonNullable<ProjectConfig["i18n"]> = { ...current };
+  if (orphaned) {
+    i18n.defaultLocale = kept[0]!;
+  }
+  i18n.locales = kept;
+  void persist(container, { i18n });
 }
 
 /**
@@ -266,9 +270,13 @@ function actions(container: HTMLElement): LocalesActions {
         void persist(container, { i18n: { ...config().i18n, defaultLocale: value } });
       },
       chooseRouting: (value: string) => {
-        void persist(container, {
-          i18n: { ...config().i18n, routing: value as LocaleRouting },
-        });
+        /* The picker's options are LOCALE_ROUTINGS, so the lookup always finds the mode; it is what
+           turns the control's string back into the routing it was drawn from. */
+        const routing = LOCALE_ROUTINGS.find((mode) => mode.value === value)?.value;
+        if (routing === undefined) {
+          return;
+        }
+        void persist(container, { i18n: { ...config().i18n, routing } });
       },
       edit: (value: string) => {
         /* Every keystroke, with no verdict check in front of it. The lit form re-rendered only when

package/src/settings/preferences-dialog.ts

@@ -11,7 +11,8 @@
  * Four sections, and each one closes a hole the shell redesign named:
  *
  * - **Appearance** — the chrome theme. `shell.theme` and `view.setTheme` already existed; nothing
- *   rendered them, so the only way to change the theme was to run a command by hand.
+ *   rendered them, so the only way to change the theme was to run a command by hand. Beside it,
+ *   **Show developer panels**, which puts Files and Packages on the Design rail (§5.1).
  * - **Assistant** — the provider key. It used to live in `Assistant: Settings…`, a dialog reachable
  *   only from inside the assistant panel, which meant a key had to be configured from the surface
  *   that was broken for want of one. That dialog is deleted; this is where it went.
@@ -42,7 +43,7 @@
  * to paint. Preferences does not suspend the app.
  */
 
-import { CHROME_THEMES, setChromeTheme, shell } from "../shell";
+import { CHROME_THEMES, isChromeTheme, setChromeTheme, shell } from "../shell";
 import { layerHost } from "../ui/layers";
 import { hydrateAccountStatus } from "../account-status";
 import { getPlatform, hasPlatform } from "../platform";
@@ -62,8 +63,8 @@ import {
 } from "./preferences-accounts";
 import { applyKeybindingOverrides, rebindCommand, resetKeybinding } from "./preferences-keymap";
 import { openPreferencesSurface } from "../surfaces/preferences";
+import { developerPanelsShown, setDeveloperPanelsShown } from "./developer-panels";
 
-import type { ChromeTheme } from "../shell";
 import type { ShortcutRow } from "../commands/reference";
 import type { RebindResult } from "./preferences-keymap";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
@@ -88,6 +89,7 @@ import {
   isPreferencesSection,
   PREFERENCES_SECTIONS,
 } from "./preferences-sections";
+import type { CommandArgValues } from "../commands/command-args";
 
 export {
   DEFAULT_PREFERENCES_SECTION,
@@ -232,7 +234,10 @@ function selectSection(id: string): void {
 }
 
 function setTheme(value: string): void {
-  setChromeTheme(value as ChromeTheme);
+  // The theme rows are drawn from CHROME_THEMES, so a picked value is always one of them.
+  if (isChromeTheme(value)) {
+    setChromeTheme(value);
+  }
   repaint();
 }
 
@@ -547,6 +552,7 @@ function view(): PreferencesView {
     sectionTitle: active?.title ?? "",
     sections: sectionsView(),
     themes: themesView(),
+    developerPanels: developerPanelsShown(),
     ...(_section === "keyboard" ? keyboardView() : KEYBOARD_IDLE),
   };
 }
@@ -609,6 +615,10 @@ export function openPreferences(section?: string): Promise<null> {
       onResetBinding: resetBinding,
       onSelectSection: selectSection,
       onSetTheme: setTheme,
+      onSetDeveloperPanels: (show: boolean) => {
+        setDeveloperPanelsShown(show);
+        repaint();
+      },
       onShowConflict: showConflict,
       onToggleKeystroke: toggleKeystroke,
       onToggleRebind: toggleRebind,
@@ -652,8 +662,8 @@ export function preferencesCommands(): AnyCommand[] {
       keybinding: "mod+,",
       menus: ["commandbar/overflow", "settings/menu", "palette"],
       group: "7_settings",
-      run: (_ctx, args) => {
-        const section = (args as { section?: unknown } | undefined)?.section;
+      run: (_ctx, args?: CommandArgValues) => {
+        const section = args?.section;
         if (section !== undefined && !isPreferencesSection(section)) {
           throw new RangeError(
             `command "app.preferences" argument "section": "${String(section)}" is not a ` +
@@ -661,7 +671,7 @@ export function preferencesCommands(): AnyCommand[] {
               `${PREFERENCES_SECTIONS.map((candidate) => candidate.id).join(", ")}`,
           );
         }
-        void openPreferences(section as string | undefined);
+        void openPreferences(section);
       },
       title: "Preferences…",
     },

package/src/settings/preferences-keymap.ts

@@ -33,9 +33,11 @@
  * during boot.
  */
 
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { normalizeChord, overlappingScopes, parseChord } from "../commands/keymap";
 import { SETTINGS } from "../services/settings/definitions";
 import { clearSettings, readStoredSetting, setSetting } from "../services/settings/kernel";
+import type { JsonValue } from "@jxsuite/schema/types";
 import type { KeybindingOverrides } from "../commands/keymap";
 import type { KeyScope } from "../commands/levels";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
@@ -120,13 +122,13 @@ function readRaw(): string {
 }
 
 /** Every chord in one stored entry, canonicalised — or `null` if any of them is not a chord. */
-function canonicalise(chords: unknown): string[] | null {
+function canonicalise(chords: JsonValue): string[] | null {
   if (!Array.isArray(chords)) {
     return null;
   }
   const canonical: string[] = [];
-  for (const chord of chords as unknown[]) {
-    if (typeof chord !== "string") {
+  for (const chord of chords) {
+    if (!isString(chord)) {
       return null;
     }
     try {
@@ -159,10 +161,10 @@ export function loadKeybindingOverrides(): Map<string, string[]> {
     // Corrupt store: the defaults are the whole keymap.
     return layer;
   }
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+  if (!isJsonObject(parsed)) {
     return layer;
   }
-  for (const [id, chords] of Object.entries(parsed as Record<string, unknown>)) {
+  for (const [id, chords] of Object.entries(parsed)) {
     const canonical = canonicalise(chords);
     if (canonical) {
       layer.set(id, canonical);

package/src/settings/preferences-sections.ts

@@ -29,7 +29,7 @@ export interface PreferencesSection {
  * 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[] = [
+const SECTIONS = [
   { id: "appearance", title: "Appearance", blurb: "How the Studio chrome looks." },
   {
     id: "assistant",
@@ -46,12 +46,18 @@ export const PREFERENCES_SECTIONS: readonly PreferencesSection[] = [
     title: "Keyboard",
     blurb: "Generated from the command registry — the app's own record of every chord.",
   },
-];
+] as const satisfies readonly PreferencesSection[];
+
+/** The id of one built section: the literal set `app.preferences { section }` accepts. */
+export type PreferencesSectionId = (typeof SECTIONS)[number]["id"];
+
+/** {@link SECTIONS}, as the sheet and the rail read it. */
+export const PREFERENCES_SECTIONS: readonly PreferencesSection[] = SECTIONS;
 
 /** 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);
+/** Whether a value names a section. */
+export function isPreferencesSection(id: unknown): id is PreferencesSectionId {
+  return SECTIONS.some((section) => section.id === id);
 }