@jxsuite/studio 6.1.1 → 6.1.2

package/src/surfaces/schema-builder.ts

@@ -19,7 +19,7 @@
  * Settings › Data Shapes edits the project's `$defs` and this edits a content type's `schema`, and
  * they are the same object drawn with the same six controls per row — so the two documents are the
  * same card inside a different shell, and the views are one set of types. A second declaration of
- * {@link SchemaFieldView} would be the point at which the two cards start to drift, one field at a
+ * {@link DefsFieldView} would be the point at which the two cards start to drift, one field at a
  * time, with nothing failing.
  *
  * @docs studio/data/tables
@@ -29,28 +29,18 @@ import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import builderDoc from "./schema-builder.json";
 
-import type { JxDocument } from "@jxsuite/schema/types";
-import type { SurfaceHandle } from "../ui/surface";
-import type { DefsChoice, DefsFieldView, NestedFieldView } from "./settings-defs";
+import type { SurfaceHandle, SurfaceOption } from "../ui/surface";
+import type { DefsFieldView } from "./settings-defs";
 
-registerSurface("schema-builder", builderDoc as unknown as JxDocument);
-
-/** One row of a picker: a field type, a format, or a reference target. */
-export type SchemaFieldChoice = DefsChoice;
-
-/** One field of the object being edited, as the document draws it. */
-export type SchemaFieldView = DefsFieldView;
-
-/** One child of an `object` field. It carries its parent — a nested `$map` shadows `$map.item`. */
-export type NestedSchemaFieldView = NestedFieldView;
+registerSurface("schema-builder", builderDoc);
 
 /** Everything the document draws, as one value. */
 export interface SchemaBuilderView {
-  fields: SchemaFieldView[];
-  typeOptions: SchemaFieldChoice[];
-  formatOptions: SchemaFieldChoice[];
+  fields: DefsFieldView[];
+  typeOptions: SurfaceOption[];
+  formatOptions: SurfaceOption[];
   /** The content types a reference field can point at. Empty draws no target picker. */
-  targets: SchemaFieldChoice[];
+  targets: SurfaceOption[];
   /** Whether the foot of the list is offering the add button or the add form. */
   addState: "closed" | "open";
   addName: string;
@@ -94,7 +84,7 @@ export interface SchemaBuilderSurfaceHandle {
   dispose: () => void;
 }
 
-interface BuilderScope extends Record<string, unknown>, SchemaBuilderView, SchemaBuilderActions {}
+interface BuilderScope extends SchemaBuilderView, SchemaBuilderActions {}
 
 /** The view a freshly mounted surface starts on: no fields, and no add form. */
 function emptyView(): SchemaBuilderView {
@@ -124,7 +114,7 @@ export function mountSchemaBuilderSurface(
   actions: SchemaBuilderActions,
 ): SchemaBuilderSurfaceHandle {
   host.textContent = "";
-  const scope = reactive<BuilderScope>({ ...emptyView(), ...actions }) as BuilderScope;
+  const scope: BuilderScope = reactive<BuilderScope>({ ...emptyView(), ...actions });
 
   /** `null` while a mount is in flight — which is a standing surface, not a missing one. */
   let handle: SurfaceHandle | null = null;
@@ -133,13 +123,17 @@ export function mountSchemaBuilderSurface(
 
   const mount = (): Promise<HTMLElement> =>
     mountSurface("schema-builder", scope, host).then((mounted) => {
+      /* SAFETY: `schema-builder.json`'s root definition carries `tagName: "div"`, so the runtime
+         mounts an HTMLElement; a `Text` root only comes from a document whose root is a bare
+         string. */
+      const root = mounted.root as HTMLElement;
       mounting = false;
       if (disposed) {
         mounted.dispose();
-        return mounted.root as HTMLElement;
+        return root;
       }
       handle = mounted;
-      return mounted.root as HTMLElement;
+      return root;
     });
 
   const ready = mount();

package/src/surfaces/schema-form.ts

@@ -29,14 +29,15 @@
  * @docs extending/ui-kit
  */
 
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import schemaFormDoc from "./schema-form.json";
-import type { SurfaceHandle } from "../ui/surface";
+import type { KeyedLabel, SurfaceHandle, SurfaceOption } from "../ui/surface";
 import type { JxScope } from "@jxsuite/runtime/types";
-import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+import type { JxElement } from "@jxsuite/schema/types";
 
-registerSurface("schema-form", schemaFormDoc as unknown as JxDocument);
+registerSurface("schema-form", schemaFormDoc);
 
 /** Which of the nine controls a row draws. The flow picks it; the document switches on it. */
 export type SchemaFormFieldKind =
@@ -50,12 +51,6 @@ export type SchemaFormFieldKind =
   | "rows"
   | "control";
 
-/** A control a row offers as a closed list, in the shape the kit's select reads. */
-export interface SchemaFormOption {
-  value: string;
-  label: string;
-}
-
 /** One cell of an array-of-objects row: a single declared property of one item. */
 export interface SchemaFormCellView {
   /** `${field}/${row}/${key}` — the cell's reconcile identity, and a control host's id. */
@@ -70,7 +65,7 @@ export interface SchemaFormCellView {
   kind: "text" | "select" | "checkbox" | "number" | "control";
   value: string;
   checked: boolean;
-  options: SchemaFormOption[];
+  options: SurfaceOption[];
 }
 
 /** One item of an array-of-objects field. */
@@ -84,12 +79,6 @@ export interface SchemaFormRowView {
   cells: SchemaFormCellView[];
 }
 
-/** A read of the shape a JSON field currently holds: `title: string`. */
-export interface SchemaFormChipView {
-  key: string;
-  label: string;
-}
-
 /** One property of the schema, as the document draws it. Every field is already decided. */
 export interface SchemaFormFieldView {
   /** The schema property key: this row's reconcile identity, and what every callback names. */
@@ -106,7 +95,7 @@ export interface SchemaFormFieldView {
   checked: boolean;
   placeholder: string;
   /** Choices for `select`, suggestions for `pointer`. */
-  options: SchemaFormOption[];
+  options: SurfaceOption[];
   /** Whether the pointer rung has anything to suggest; with none it is a field alone. */
   hasOptions: boolean;
   /** Bounds off the property schema, so the control refuses out-of-range input itself. */
@@ -138,7 +127,7 @@ export interface SchemaFormFieldView {
   /** The position permits exactly one rung, so the chip states it and refuses to open. */
   sourceLocked: boolean;
   /** The chips above a JSON field, naming the shape it holds. */
-  chips: SchemaFormChipView[];
+  chips: KeyedLabel[];
   hasChips: boolean;
   rows: SchemaFormRowView[];
   /** The add button's accessible name on an array-of-objects field. */
@@ -179,7 +168,7 @@ export interface SchemaFormSurface {
 /** A control host the document drew, reported as the runtime created it. */
 export type ControlHostSink = (id: string, host: HTMLElement) => void;
 
-interface SchemaFormScope extends Record<string, unknown>, SchemaFormView, SchemaFormActions {
+interface SchemaFormScope extends SchemaFormView, SchemaFormActions {
   /** The Mixed text placeholder, held in state because the literal is itself a template. */
   templatePlaceholder: string;
 }
@@ -194,20 +183,21 @@ interface SchemaFormScope extends Record<string, unknown>, SchemaFormView, Schem
  * node that needs filling.
  */
 function controlIdOf(part: string, state: JxScope | undefined): string {
-  const item = (state?.["$map"] as { item?: Record<string, unknown> } | undefined)?.item;
+  const map = state?.["$map"];
+  const item = isJsonObject(map) && isJsonObject(map["item"]) ? map["item"] : undefined;
   const id =
     part === "control-host"
       ? item?.["key"]
       : part === "cell-control-host"
         ? item?.["id"]
         : undefined;
-  return typeof id === "string" ? id : "";
+  return isString(id) ? id : "";
 }
 
 /** A node definition's `part`, as written in the document. */
 function partOf(def: JxElement | string): string {
-  const part = typeof def === "string" ? undefined : def.attributes?.["part"];
-  return typeof part === "string" ? part : "";
+  const part = isString(def) ? undefined : def.attributes?.["part"];
+  return isString(part) ? part : "";
 }
 
 /**
@@ -226,11 +216,11 @@ export function createSchemaFormSurface(
 ): SchemaFormSurface {
   const host = document.createElement("div");
   host.style.display = "contents";
-  const scope = reactive({
+  const scope: SchemaFormScope = reactive<SchemaFormScope>({
     ...view,
     ...actions,
     templatePlaceholder: "${state.…}",
-  }) as SchemaFormScope;
+  });
 
   /** `null` while a mount is in flight — which is a standing surface, not a missing one. */
   let handle: SurfaceHandle | null = null;

package/src/surfaces/secret-field.ts

@@ -28,10 +28,9 @@ import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import secretDoc from "./secret-field.json";
 
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("secret-field", secretDoc as unknown as JxDocument);
+registerSurface("secret-field", secretDoc);
 
 /** What the field says right now. Every field is the flow's, never a state it derives. */
 export interface SecretFieldView {
@@ -65,7 +64,7 @@ export interface SecretFieldSurfaceHandle {
   dispose: () => void;
 }
 
-interface SecretScope extends Record<string, unknown>, SecretFieldView, SecretFieldActions {
+interface SecretScope extends SecretFieldView, SecretFieldActions {
   /**
    * What the field's value is bound to, and the whole of the "never render a secret back" rule.
    *
@@ -92,7 +91,7 @@ export function mountSecretFieldSurface(
   actions: SecretFieldActions,
 ): SecretFieldSurfaceHandle {
   host.textContent = "";
-  const scope = reactive<SecretScope>({ ...emptyView(), ...actions, shown: "" }) as SecretScope;
+  const scope: SecretScope = reactive<SecretScope>({ ...emptyView(), ...actions, shown: "" });
 
   /** `null` while a mount is in flight — which is a standing surface, not a missing one. */
   let handle: SurfaceHandle | null = null;
@@ -101,13 +100,17 @@ export function mountSecretFieldSurface(
 
   const mount = (): Promise<HTMLElement> =>
     mountSurface("secret-field", scope, host).then((mounted) => {
+      /* SAFETY: `secret-field.json`'s root definition carries `tagName: "div"`, so the runtime
+         mounts an HTMLElement; a `Text` root only comes from a document whose root is a bare
+         string. */
+      const root = mounted.root as HTMLElement;
       mounting = false;
       if (disposed) {
         mounted.dispose();
-        return mounted.root as HTMLElement;
+        return root;
       }
       handle = mounted;
-      return mounted.root as HTMLElement;
+      return root;
     });
 
   const ready = mount();

package/src/surfaces/seo.ts

@@ -33,13 +33,12 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import { overlayRegion, REGION_ATTR } from "../ui/regions";
-import { close as closeDialog, showModal } from "@jxsuite/ui/behaviors/dialog";
+import { close, showModal } from "@jxsuite/ui/behaviors/dialog";
 import { whenReady } from "./dialog";
 import seoDoc from "./seo.json";
 import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
 
-registerSurface("seo", seoDoc as unknown as JxDocument);
+registerSurface("seo", seoDoc);
 
 /** How a field's provenance is drawn — §6.7's vocabulary, reduced to three shapes and an absence. */
 export type SeoChipKind = "none" | "dot" | "static" | "link";
@@ -65,8 +64,9 @@ export interface SeoFieldView {
   chipTitle: string;
 }
 
-/** One named warning. A list, never a total. */
+/** A named thing that is wrong, or absent. Never summed: the list IS the report. */
 export interface SeoWarningView {
+  /** Stable id, so a test and a shot name the same warning. */
   id: string;
   /** The head key it is about, so the row can carry it as code. */
   field: string;
@@ -154,17 +154,17 @@ export interface SeoSurfaceHandle {
 type LineState = "text" | "unset";
 
 /** One field row with the flags the document branches on. */
-interface SeoFieldRow extends SeoFieldView, Record<string, unknown> {
+interface SeoFieldRow extends SeoFieldView {
   valueState: LineState;
 }
 
 /** One editable row with the flags the document branches on. */
-interface SeoEditRow extends SeoEditRowView, Record<string, unknown> {
+interface SeoEditRow extends SeoEditRowView {
   hasThumb: boolean;
 }
 
 /** One group with its rows already flagged. */
-interface SeoGroupRow extends Record<string, unknown> {
+interface SeoGroupRow {
   key: string;
   title: string;
   note: string;
@@ -196,12 +196,12 @@ interface SeoFlags {
   groups: SeoGroupRow[];
 }
 
-interface SeoScope extends Record<string, unknown>, SeoFlags {
+interface SeoScope extends SeoFlags {
   documentLabel: string;
   edit: (key: string, value: string) => void;
   commit: (key: string, value: string) => void;
   upload: (key: string) => void;
-  browse: (key: string, anchor: unknown) => void;
+  browse: (key: string, anchor: EventTarget | null) => void;
   openDonor: (key: string) => void;
   closed: () => void;
 }
@@ -268,9 +268,9 @@ export function openSeoSurface(options: SeoSurfaceOptions): SeoSurfaceHandle {
     options.onClosed();
   };
 
-  const scope = reactive({
+  const scope: SeoScope = reactive<SeoScope>({
     ...derive(options.view),
-    browse: (key: string, anchor: unknown) => {
+    browse: (key: string, anchor: EventTarget | null) => {
       if (anchor instanceof HTMLElement) {
         options.onBrowse(key, anchor);
       }
@@ -288,18 +288,24 @@ export function openSeoSurface(options: SeoSurfaceOptions): SeoSurfaceHandle {
     upload: (key: string) => {
       options.onUpload(key);
     },
-  }) as SeoScope;
+  });
 
+  /* Read through a call, not the bare binding: `close()` can run while the mount is awaiting the
+     element, and a direct `closed` test after that `await` would be narrowed to the value the test
+     before it saw. */
+  const isClosed = (): boolean => closed;
   let mounted: SurfaceHandle | null = null;
   const ready = mountSurface("seo", scope, slot).then(async (surface) => {
     mounted = surface;
+    /* SAFETY: `seo.json`'s root definition carries `tagName: "jx-dialog"`, so the runtime mounts an
+       HTMLElement; a `Text` root only comes from a document whose root is a bare string. */
     const element = surface.root as HTMLElement;
-    if (closed) {
+    if (isClosed()) {
       surface.dispose();
       return element;
     }
     await whenReady(element);
-    if (closed) {
+    if (isClosed()) {
       return element;
     }
     const box = element.querySelector<HTMLElement>('dialog[part="dialog"]') ?? element;
@@ -317,7 +323,7 @@ export function openSeoSurface(options: SeoSurfaceOptions): SeoSurfaceHandle {
       const element = mounted?.root;
       if (element instanceof HTMLElement) {
         // The platform's close first, so focus goes back where it came from; then the document.
-        closeDialog(element);
+        close(element);
       }
       // A mount that has not landed yet is disposed by `ready` when it does — `finish` tells it so.
       mounted?.dispose();

package/src/surfaces/settings-contexts.ts

@@ -22,10 +22,9 @@ import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import contextsDoc from "./settings-contexts.json";
 
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("settings-contexts", contextsDoc as unknown as JxDocument);
+registerSurface("settings-contexts", contextsDoc);
 
 /** One `$media` row, as the document draws it. */
 export interface ContextRowView {
@@ -111,7 +110,7 @@ export interface ContextsSurfaceHandle {
  * would be a second place to get it wrong. The refusal lines need none — `invalid` already says
  * which control the message belongs to.
  */
-interface ContextsScope extends Record<string, unknown>, ContextsView, ContextsActions {
+interface ContextsScope extends ContextsView, ContextsActions {
   hasSectionError: boolean;
   hasNotice: boolean;
 }
@@ -141,7 +140,7 @@ export function mountContextsSurface(
   actions: ContextsActions,
 ): ContextsSurfaceHandle {
   host.textContent = "";
-  const scope = reactive<ContextsScope>({
+  const scope: ContextsScope = reactive<ContextsScope>({
     ...emptyView(),
     add: actions.add,
     hasNotice: false,
@@ -151,17 +150,20 @@ export function mountContextsSurface(
     setBase: actions.setBase,
     setQuery: actions.setQuery,
     setScheme: actions.setScheme,
-  }) as ContextsScope;
+  });
 
   let mounted: SurfaceHandle | null = null;
   let disposed = false;
   const ready = mountSurface("settings-contexts", scope, host).then((surface) => {
+    /* SAFETY: `settings-contexts.json`'s root definition carries `tagName: "div"`, so the runtime
+       mounts an HTMLElement; a `Text` root only comes from a document whose root is a bare string. */
+    const root = surface.root as HTMLElement;
     if (disposed) {
       surface.dispose();
-      return surface.root as HTMLElement;
+      return root;
     }
     mounted = surface;
-    return surface.root as HTMLElement;
+    return root;
   });
 
   return {

package/src/surfaces/settings-contributed.ts

@@ -26,14 +26,15 @@
  * @docs studio/projects/settings
  */
 
+import { isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import contributedDoc from "./settings-contributed.json";
 
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { SurfaceHandle } from "../ui/surface";
+import type { JxElement } from "@jxsuite/schema/types";
 
-registerSurface("settings-contributed", contributedDoc as unknown as JxDocument);
+registerSurface("settings-contributed", contributedDoc);
 
 /** One entry key in a map-layout section's left column. */
 export interface ContributedEntryView {
@@ -101,7 +102,7 @@ export interface ContributedSurfaceHandle {
   dispose: () => void;
 }
 
-interface ContributedScope extends Record<string, unknown>, ContributedView, ContributedActions {}
+interface ContributedScope extends ContributedView, ContributedActions {}
 
 /** The view a freshly mounted surface starts on: a form layout with nothing in it. */
 function emptyView(): ContributedView {
@@ -119,10 +120,9 @@ function emptyView(): ContributedView {
 }
 
 /** The `part` a node was authored with, or `""` — the only thing this adapter asks about a node. */
-function partOf(def: unknown): string {
-  const attributes = (def as { attributes?: Record<string, unknown> } | null)?.attributes;
-  const part = attributes?.["part"];
-  return typeof part === "string" ? part : "";
+function partOf(def: JxElement | string): string {
+  const part = isString(def) ? undefined : def.attributes?.["part"];
+  return isString(part) ? part : "";
 }
 
 /**
@@ -139,7 +139,7 @@ export function mountContributedSurface(
   islands: ContributedIslands,
 ): ContributedSurfaceHandle {
   host.textContent = "";
-  const scope = reactive<ContributedScope>({ ...emptyView(), ...actions }) as ContributedScope;
+  const scope: ContributedScope = reactive<ContributedScope>({ ...emptyView(), ...actions });
 
   let mounted: SurfaceHandle | null = null;
   let disposed = false;
@@ -160,12 +160,16 @@ export function mountContributedSurface(
       }
     },
   }).then((surface) => {
+    /* SAFETY: `settings-contributed.json`'s root definition carries `tagName: "section"`, so the
+       runtime mounts an HTMLElement; a `Text` root only comes from a document whose root is a bare
+       string. */
+    const root = surface.root as HTMLElement;
     if (disposed) {
       surface.dispose();
-      return surface.root as HTMLElement;
+      return root;
     }
     mounted = surface;
-    return surface.root as HTMLElement;
+    return root;
   });
 
   return {

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

@@ -29,16 +29,9 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import cssVarsDoc from "./settings-css-vars.json";
-import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle, SurfaceOption } from "../ui/surface";
 
-registerSurface("settings-css-vars", cssVarsDoc as unknown as JxDocument);
-
-/** One row of the add-an-override picker. */
-export interface OverrideChoice {
-  value: string;
-  label: string;
-}
+registerSurface("settings-css-vars", cssVarsDoc);
 
 /** One of a token's per-context values. */
 export interface OverrideRowView {
@@ -91,7 +84,7 @@ export interface TokenRowView {
   overrides: OverrideRowView[];
   /** Whether the add-an-override picker is offered. */
   addState: "none" | "shown";
-  addOptions: OverrideChoice[];
+  addOptions: SurfaceOption[];
   /** What the picker currently reads. Always `""` in practice — see {@link renderCssVarsSurface}. */
   addPick: string;
   addLabel: string;
@@ -141,7 +134,7 @@ interface CssVarsFlags {
   hasError: boolean;
 }
 
-interface CssVarsScope extends Record<string, unknown>, CssVarsView, CssVarsActions, CssVarsFlags {}
+interface CssVarsScope extends CssVarsView, CssVarsActions, CssVarsFlags {}
 
 interface Mounted {
   scope: CssVarsScope;
@@ -186,7 +179,7 @@ export function renderCssVarsSurface(
   }
   existing?.handle?.dispose();
   host.textContent = "";
-  const scope = reactive({ ...derive(view), ...actions }) as CssVarsScope;
+  const scope: CssVarsScope = reactive<CssVarsScope>({ ...derive(view), ...actions });
   const record: Mounted = { handle: null, scope };
   mounts.set(host, record);
   /* No race to arbitrate: a redraw arriving while this is in flight takes the branch above — a

package/src/surfaces/settings-defs.json

@@ -158,7 +158,7 @@
             {
               "$prototype": "Array",
               "items": {
-                "$ref": "#/state/shapes"
+                "$ref": "#/state/defs"
               },
               "key": {
                 "$ref": "$map/item/name"
@@ -406,7 +406,7 @@
                           {
                             "operator": "call",
                             "target": {
-                              "$ref": "#/state/removeShape"
+                              "$ref": "#/state/removeSelected"
                             },
                             "value": []
                           }

package/src/surfaces/settings-defs.ts

@@ -26,19 +26,12 @@ import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import defsDoc from "./settings-defs.json";
 
-import type { JxDocument } from "@jxsuite/schema/types";
-import type { SurfaceHandle } from "../ui/surface";
+import type { SurfaceHandle, SurfaceOption } from "../ui/surface";
 
-registerSurface("settings-defs", defsDoc as unknown as JxDocument);
-
-/** One row of a picker: a field type, a format, or a reference target. */
-export interface DefsChoice {
-  value: string;
-  label: string;
-}
+registerSurface("settings-defs", defsDoc);
 
 /** One data shape in the left column. */
-export interface DefsShapeView {
+export interface DefsEntryView {
   name: string;
   selected: boolean;
 }
@@ -87,7 +80,7 @@ export interface DefsFieldView {
 
 /** Everything the document draws, as one value. */
 export interface DefsView {
-  shapes: DefsShapeView[];
+  defs: DefsEntryView[];
   /** Whether the left column is offering the new-shape button or the form. */
   newState: "closed" | "open";
   newName: string;
@@ -95,10 +88,10 @@ export interface DefsView {
   editorState: "empty" | "editing";
   selected: string;
   fields: DefsFieldView[];
-  typeOptions: DefsChoice[];
-  formatOptions: DefsChoice[];
+  typeOptions: SurfaceOption[];
+  formatOptions: SurfaceOption[];
   /** The content types a reference field can point at. */
-  targets: DefsChoice[];
+  targets: SurfaceOption[];
   addState: "closed" | "open";
   addName: string;
   addType: string;
@@ -114,7 +107,7 @@ export interface DefsActions {
   editNew: (value: string) => void;
   createNew: () => void;
   cancelNew: () => void;
-  removeShape: () => void;
+  removeSelected: () => void;
   renameField: (key: string, value: string) => void;
   setType: (key: string, value: string) => void;
   setFormat: (key: string, value: string) => void;
@@ -149,7 +142,7 @@ export interface DefsSurfaceHandle {
   dispose: () => void;
 }
 
-interface DefsScope extends Record<string, unknown>, DefsView, DefsActions {}
+interface DefsScope extends DefsView, DefsActions {}
 
 /** The view a freshly mounted surface starts on: no shapes, and nothing chosen. */
 function emptyView(): DefsView {
@@ -160,13 +153,13 @@ function emptyView(): DefsView {
     addRequired: false,
     addState: "closed",
     addType: "string",
+    defs: [],
     editorState: "empty",
     fields: [],
     formatOptions: [],
     newName: "",
     newState: "closed",
     selected: "",
-    shapes: [],
     targets: [],
     typeOptions: [],
   };
@@ -181,17 +174,20 @@ function emptyView(): DefsView {
  */
 export function mountDefsSurface(host: HTMLElement, actions: DefsActions): DefsSurfaceHandle {
   host.textContent = "";
-  const scope = reactive<DefsScope>({ ...emptyView(), ...actions }) as DefsScope;
+  const scope: DefsScope = reactive<DefsScope>({ ...emptyView(), ...actions });
 
   let mounted: SurfaceHandle | null = null;
   let disposed = false;
   const ready = mountSurface("settings-defs", scope, host).then((surface) => {
+    /* SAFETY: `settings-defs.json`'s root definition carries `tagName: "section"`, so the runtime
+       mounts an HTMLElement; a `Text` root only comes from a document whose root is a bare string. */
+    const root = surface.root as HTMLElement;
     if (disposed) {
       surface.dispose();
-      return surface.root as HTMLElement;
+      return root;
     }
     mounted = surface;
-    return surface.root as HTMLElement;
+    return root;
   });
 
   return {
@@ -218,13 +214,13 @@ export function mountDefsSurface(host: HTMLElement, actions: DefsActions): DefsS
       scope.addRequired = view.addRequired;
       scope.addState = view.addState;
       scope.addType = view.addType;
+      scope.defs = view.defs;
       scope.editorState = view.editorState;
       scope.fields = view.fields;
       scope.formatOptions = view.formatOptions;
       scope.newName = view.newName;
       scope.newState = view.newState;
       scope.selected = view.selected;
-      scope.shapes = view.shapes;
       scope.targets = view.targets;
       scope.typeOptions = view.typeOptions;
     },