@jxsuite/studio 6.1.0 → 6.1.2

package/src/settings/extension-sections.ts

@@ -8,13 +8,14 @@
  * path.
  */
 
+import { isNonNullObject } from "@jxsuite/schema/guards";
 import { getFormats, loadExtensions, loadFormats } from "../format/format-host";
 import { 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";
 
 /** The `$studio.settings` block shape consumed here (nav metadata + the renderer inputs). */
 interface StudioSettingsBlock {
@@ -49,31 +50,39 @@ 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,
     },
     icon: settings.icon,
@@ -143,10 +152,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,6 +16,7 @@
  * 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";
@@ -31,6 +32,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 +51,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 +68,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). */
@@ -91,11 +94,11 @@ function headWithDescription(head: JxHeadEntry[], text: string): JxHeadEntry[] {
  * 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 };
 
 // ─── Projection ──────────────────────────────────────────────────────────────
 
@@ -121,7 +124,7 @@ function values(container: HTMLElement): OverviewValues {
   return {
     description: readDescription(cfg),
     error: errors.get(container) ?? null,
-    favicon: typeof cfg.favicon === "string" ? cfg.favicon : "",
+    favicon: isString(cfg.favicon) ? cfg.favicon : "",
     name: cfg.name ?? "",
     stylesDisabled: command === undefined,
     stylesTitle: command?.title ?? "",
@@ -145,7 +148,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 {

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

@@ -42,7 +42,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";
@@ -63,7 +63,6 @@ import {
 import { applyKeybindingOverrides, rebindCommand, resetKeybinding } from "./preferences-keymap";
 import { openPreferencesSurface } from "../surfaces/preferences";
 
-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 +87,7 @@ import {
   isPreferencesSection,
   PREFERENCES_SECTIONS,
 } from "./preferences-sections";
+import type { CommandArgValues } from "../commands/command-args";
 
 export {
   DEFAULT_PREFERENCES_SECTION,
@@ -232,7 +232,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();
 }
 
@@ -652,8 +655,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 +664,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);
 }

package/src/settings/project-sections.ts

@@ -54,7 +54,7 @@ const errors = new WeakMap<HTMLElement, string>();
 
 /** The live project configuration, or an empty one before a project is open. */
 function config(): ProjectConfig {
-  return (projectState?.projectConfig ?? {}) as ProjectConfig;
+  return projectState?.projectConfig ?? {};
 }
 
 // ─── Deploy ───────────────────────────────────────────────────────────────────

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

@@ -26,6 +26,15 @@ export const FIELD_TYPES = ["string", "number", "boolean", "array", "object", "r
 
 export const FORMAT_OPTIONS = ["", "image", "date", "color"];
 
+/** What a new field's add row starts as. Spread it: every add row edits its own copy. */
+export const BLANK_FIELD = { format: "", name: "", required: false, type: "string" };
+
+/** One object field's unsubmitted nested field. */
+export interface NestedFieldDraft {
+  name: string;
+  type: string;
+}
+
 /**
  * Detect the studio field type from a JSON Schema property definition.
  *

package/src/settings/settings-document.ts

@@ -26,7 +26,7 @@
 import { errorMessage } from "@jxsuite/schema/parse";
 import { optionalStringArg, stringProperty } from "../commands/command-args";
 import { notify } from "../services/notify";
-import { requireProjectState } from "../state";
+import { projectState } from "../state";
 import { PROJECT_CONFIG_PATH } from "../tabs/tab";
 import { lendProjectConfigLayout } from "../tabs/project-config";
 import { activeTab, focusPane, openTab, workspace } from "../workspace/workspace";
@@ -181,7 +181,7 @@ export function activeSettingsSection(): string | null {
 
 /** Whether the active tab is the configuration document in its settings editor. */
 export function settingsDocumentOpen(): boolean {
-  const tab = activeTab.value as Tab | null;
+  const tab = activeTab.value;
   return tab?.documentPath === PROJECT_CONFIG_PATH && tab.session.ui.canvasMode === SETTINGS_MODE;
 }
 
@@ -197,7 +197,7 @@ export function settingsDocumentOpen(): boolean {
  * @returns {Tab | null} The tab, or null when no project is open
  */
 export function showSettingsDocument(mode: string = SETTINGS_MODE): Tab | null {
-  const state = requireProjectState();
+  const state = projectState;
   if (!state) {
     return null;
   }
@@ -210,11 +210,11 @@ export function showSettingsDocument(mode: string = SETTINGS_MODE): Tab | null {
     }
     existing.session.ui.canvasMode = mode;
     existing.session.ui.preview = false;
-    return revealTab(existing as unknown as Tab);
+    return revealTab(existing);
   }
   const tab = openTab({
     capabilities: { modes: [...SETTINGS_TAB_MODES] },
-    document: (state.projectConfig ?? {}) as unknown as Record<string, unknown>,
+    document: state.projectConfig ?? {},
     documentPath: PROJECT_CONFIG_PATH,
     id: PROJECT_CONFIG_PATH,
   });

package/src/shell/tree.ts

@@ -13,7 +13,7 @@
  * the real shell instead of describing one.
  */
 
-import { html, render as litRender } from "lit-html";
+import { html, render } from "lit-html";
 import type { TemplateResult } from "lit-html";
 import { mountShellSurface } from "../surfaces/shell";
 import { mountBootFailureSurface } from "../surfaces/boot-failure";
@@ -82,7 +82,7 @@ export async function mountShellTree(host: ParentNode = document.body): Promise<
   await mountShellSurface(root);
   /* After the frame, so the layers are its siblings in the order they always were. lit's `render`
      manages only the range between its own markers, so appending here leaves `#app` alone. */
-  litRender(overlayLayers(), root);
+  render(overlayLayers(), root);
 }
 
 /**
@@ -128,12 +128,13 @@ export async function mountBootFailureTree(
  * containing block here would move all four of them, silently.
  */
 function shellRoot(host: ParentNode): HTMLElement {
-  const existing = host.querySelector?.("#shell-root");
+  // The only `#shell-root` is the div made below, so the element found is an HTMLElement.
+  const existing = host.querySelector<HTMLElement>("#shell-root");
   if (existing) {
-    return existing as HTMLElement;
+    return existing;
   }
   const root = document.createElement("div");
   root.id = "shell-root";
-  (host as HTMLElement).append(root);
+  host.append(root);
   return root;
 }