@jxsuite/studio 6.1.1 → 8.0.0

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

@@ -1,29 +1,30 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioSettingsCssVars",
-  "$description": "Project Settings › CSS Variables: the project's design tokens, grouped by what they name, each editable in place and each able to carry a different value in any rendering context the project declares. The adapter (`surfaces/settings-css-vars.ts`) hands in the groups already grouped, each token already resolved — its swatch colour, the chip it wears when its value follows another token, the override rows it has and the contexts it could still be given one in — and the document draws them. Nothing here reads `project.json` and nothing here decides what a token IS: `style/project-styles.ts` owns the vocabulary and `settings/css-vars-editor.ts` owns the writes. A context is DEFINED in Contexts and only overridden here, which is why the one thing the colour group says when no scheme exists is where to go and say it.",
+  "$description": "The Styles workspace's Variables view, its editor (studio.md §7.1): the project's design tokens, grouped by what they name, each editable in place and each able to carry a different value in any rendering context the project declares. The view's own frame (`surfaces/styles-variables.json`) draws the heading and mounts this document into its `editor` island. The adapter (`surfaces/settings-css-vars.ts`) hands in the groups already grouped, each token already resolved — its swatch colour, the chip it wears when its value follows another token, the override rows it has, the contexts it could still be given one in and whether it is the token the Outline pointed at — and the document draws them. Nothing here reads `project.json` and nothing here decides what a token IS: `style/project-styles.ts` owns the vocabulary and `settings/css-vars-editor.ts` owns the writes. A context is DEFINED in Project Settings › Contexts and only overridden here, which is why the one thing the colour group says when no scheme exists is where to go and say it.",
   "tagName": "section",
   "attributes": {
     "part": "cssvars"
   },
   "style": {
-    "$description": "This section's whole look, keyed on `part`. Six of the rules it used to borrow are gone rather than moved: `.settings-section` never had a rule anywhere (it was on the orphan ledger), and `.css-var-swatch input[type=\"color\"]` plus the two chip spans are drawn here now because the lit helper that emitted them is drawn here now. Every `--spectrum-font-size-*` reference is re-pointed at the kit's scale: a document is mounted in the pane rather than inside `<sp-theme>`, so each of those would have silently taken its hard-coded fallback.",
+    "$description": "This section's whole look, keyed on `part`. Six of the rules it used to borrow are gone rather than moved: `.settings-section` never had a rule anywhere (it was on the orphan ledger), and `.css-var-swatch input[type=\"color\"]` plus the two chip spans are drawn here now because the lit helper that emitted them is drawn here now. Every `--spectrum-font-size-*` reference is re-pointed at the kit's scale: a document is mounted in the pane rather than inside `<sp-theme>`, so each of those would have silently taken its hard-coded fallback. Two part names are this document's own on purpose: the colour well is `well` and a font token's specimen is `font-preview`, because `swatch` and `preview` are parts INSIDE `jx-select` (its options' colour chip and its closed-state value), and this section draws a `jx-select` per token. The kit is light DOM, so `& [part=\"preview\"]` reached the Add override picker's own value and gave it this sheet's 108px indent, bottom padding and 13px type: a 36px control under a 20px field. The name column is a fixed width (`--name-col`) so every value field in a group starts at the same x, and the override list indents to that same column rather than to a literal that guessed it.",
+    "--name-col": "12rem",
     "display": "block",
-    "& [part=\"title\"]": {
-      "margin": "0 0 16px",
-      "fontSize": "16px",
-      "fontWeight": "600",
-      "color": "var(--fg)"
-    },
     "& [part=\"section-error\"]": {
       "$description": "A write that failed, said under the section title rather than pinned to a control. This section saves on change and the predecessor dropped every rejection on the floor, so a read-only file made each edit look as though it had been taken and then quietly forgotten. It is `section-error` rather than `error` because every text field and select in the section draws a permanent `[part=\"error\"]` of its own in this same light-DOM tree, and a rule on that name would give their refusal sentences this margin and size too.",
       "margin": "0 0 12px",
       "fontSize": "var(--jx-text-md)",
       "color": "var(--danger)"
     },
-    "& [part=\"group\"]": {
+    "& [part=\"token-group\"]": {
       "marginBottom": "24px"
     },
+    "& [part=\"token\"][aria-current=\"true\"]": {
+      "$description": "The token the Outline pointed the view at: a tinted band with the accent edge the Outline's own selected row wears, so the two say the same thing about one property.",
+      "borderRadius": "var(--radius)",
+      "background": "var(--accent-20)",
+      "boxShadow": "inset 2px 0 0 var(--accent)"
+    },
     "& [part=\"group-title\"]": {
       "margin": "0 0 8px",
       "fontSize": "13px",
@@ -39,14 +40,18 @@
       "padding": "4px 0"
     },
     "& [part=\"name\"]": {
+      "$description": "A fixed column, not a minimum: with `minWidth` the value field started wherever its name ended, so a long name pushed its field out of line with every field above it. A name longer than the column is cut with an ellipsis and carries its whole self in `title`.",
+      "flex": "0 0 var(--name-col)",
+      "overflow": "hidden",
+      "textOverflow": "ellipsis",
+      "whiteSpace": "nowrap",
       "fontSize": "var(--jx-text-md)",
-      "color": "var(--fg-dim)",
-      "minWidth": "100px"
+      "color": "var(--fg-dim)"
     },
     "& [part=\"swatch-slot\"], & [part=\"chip-slot\"]": {
       "display": "contents"
     },
-    "& [part=\"swatch\"]": {
+    "& [part=\"well\"]": {
       "$description": "The colour well. Its background is the value the token RESOLVES to, so an alias token is a colour rather than a blank square, and the native input over it is transparent — the well is what the reader sees and the input is only what they operate.",
       "position": "relative",
       "width": "24px",
@@ -66,15 +71,14 @@
       "cursor": "pointer"
     },
     "& [part=\"value\"]": {
-      "flex": "1",
+      "flex": "0 1 16rem",
       "minWidth": "0"
     },
     "& [data-group=\"color\"] [part=\"value\"]": {
-      "maxWidth": "160px"
+      "flexBasis": "10rem"
     },
     "& [data-group=\"size\"] [part=\"value\"]": {
-      "flex": "none",
-      "maxWidth": "120px"
+      "flexBasis": "8rem"
     },
     "& [part=\"chip\"]": {
       "$description": "A value that is exactly `var(--token)` is a reference, and raw text is the one rendering that hides both which token and what it currently is. The chip says both. It is a span, not a button: it states, it does not navigate. Same border, same size and same radius as the provenance chips in the Inspector, because \"this value comes from somewhere else\" is the same sentence in both places.",
@@ -103,16 +107,20 @@
       "overflow": "hidden",
       "textOverflow": "ellipsis"
     },
-    "& [part=\"preview\"]": {
-      "$description": "A font token is the one kind whose value cannot be read: `'Georgia', serif` is a name for a shape, so the shape is drawn. Indented to the value column, because it belongs to the field above it rather than to the section.",
-      "padding": "4px 0 12px 108px",
+    "& [part=\"font-preview\"]": {
+      "$description": "A font token is the one kind whose value cannot be read: `'Georgia', serif` is a name for a shape, so the shape is drawn. Indented to the value column (the name column and the gap after it), because it belongs to the field above it rather than to the section.",
+      "padding": "4px 0 12px calc(var(--name-col) + 8px)",
       "fontSize": "13px",
       "color": "var(--fg-dim)"
     },
     "& [part=\"overrides\"]": {
-      "paddingLeft": "108px",
+      "$description": "Indented to the value column: past the name column and its gap, and in the colour group past the well too, so an override value sits under the base value it overrides.",
+      "paddingLeft": "calc(var(--name-col) + 8px)",
       "marginBottom": "8px"
     },
+    "& [data-group=\"color\"] [part=\"overrides\"]": {
+      "paddingLeft": "calc(var(--name-col) + 40px)"
+    },
     "& [part=\"override\"]": {
       "display": "flex",
       "alignItems": "center",
@@ -138,6 +146,11 @@
       "alignItems": "center",
       "padding": "2px 0"
     },
+    "& [part=\"add-picker\"]": {
+      "$description": "As compact as the fields beside it: sized to its own label rather than stretched, since it is a verb on the list above it and not a value of its own.",
+      "flex": "none",
+      "width": "auto"
+    },
     "& [part=\"add\"]": {
       "display": "flex",
       "alignItems": "center",
@@ -162,13 +175,6 @@
     }
   },
   "children": [
-    {
-      "tagName": "h3",
-      "attributes": {
-        "part": "title"
-      },
-      "textContent": "CSS Variables"
-    },
     {
       "tagName": "div",
       "attributes": {
@@ -200,12 +206,12 @@
       "map": {
         "tagName": "div",
         "attributes": {
-          "part": "group",
+          "part": "token-group",
           "data-group": "${$map.item.id}"
         },
         "children": [
           {
-            "tagName": "h4",
+            "tagName": "h3",
             "attributes": {
               "part": "group-title"
             },
@@ -223,7 +229,8 @@
               "tagName": "div",
               "attributes": {
                 "part": "token",
-                "data-token": "${$map.item.name}"
+                "data-token": "${$map.item.name}",
+                "aria-current": "${$map.item.current ? 'true' : null}"
               },
               "children": [
                 {
@@ -245,7 +252,7 @@
                         "swatch": {
                           "tagName": "div",
                           "attributes": {
-                            "part": "swatch"
+                            "part": "well"
                           },
                           "style": {
                             "background": {
@@ -290,7 +297,8 @@
                     {
                       "tagName": "span",
                       "attributes": {
-                        "part": "name"
+                        "part": "name",
+                        "title": "${$map.item.label}"
                       },
                       "textContent": "${$map.item.label}"
                     },
@@ -433,7 +441,7 @@
                     "font": {
                       "tagName": "div",
                       "attributes": {
-                        "part": "preview"
+                        "part": "font-preview"
                       },
                       "style": {
                         "fontFamily": {
@@ -498,7 +506,7 @@
                                   "swatch": {
                                     "tagName": "div",
                                     "attributes": {
-                                      "part": "swatch"
+                                      "part": "well"
                                     },
                                     "style": {
                                       "background": {
@@ -788,7 +796,7 @@
                 "children": [
                   {
                     "tagName": "span",
-                    "textContent": "No colour scheme is defined yet, so these tokens have one value each."
+                    "textContent": "No color scheme is defined yet, so these tokens have one value each."
                   },
                   {
                     "tagName": "jx-action-button",
@@ -797,7 +805,7 @@
                     },
                     "$props": {
                       "size": "sm",
-                      "hint": "Define a colour scheme in Project Settings › Contexts"
+                      "hint": "Define a color scheme in Project Settings › Contexts"
                     },
                     "onclick": {
                       "$ref": "#/state/manageContexts"

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

@@ -1,6 +1,8 @@
 /// <reference lib="dom" />
 /**
- * The CSS Variables settings section, as a mounted document.
+ * The CSS Variables editor, as a mounted document: the body of the Styles workspace's Variables
+ * view (`surfaces/styles-variables.json` is its frame). The file keeps the `settings-` name it had
+ * while the editor was a Project Settings section.
  *
  * `settings/css-vars-editor.ts` is the flow — it reads the project's root style block, decides what
  * an edit writes and pushes the result at every live canvas — and this is the surface it draws
@@ -19,26 +21,19 @@
  * inventing one to be photographed is what the screenshot policy forbids. It is the one place a
  * document reaches past the kit, and it reaches for a platform element rather than a Spectrum one.
  *
- * **Keyed by host, not by module.** Project Settings is a pane document and a pane can be split, so
- * two containers may be showing this section at once; a single module-level mount would take the
+ * **Keyed by host, not by module.** The Variables view is a pane document and a pane can be split,
+ * so two containers may be showing this section at once; a single module-level mount would take the
  * first one's surface away from it the moment the second drew.
  *
- * @docs studio/projects/settings
+ * @docs studio/design/tokens
  */
 
 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 {
@@ -67,6 +62,8 @@ export interface OverrideRowView {
 export interface TokenRowView {
   /** The custom property. The row's key, and every handler's first argument. */
   name: string;
+  /** Whether this is the token the Outline pointed the view at. Drawn as `aria-current`. */
+  current: boolean;
   label: string;
   value: string;
   removeLabel: string;
@@ -91,7 +88,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 +138,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 +183,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
@@ -197,3 +194,72 @@ export function renderCssVarsSurface(
     record.handle = handle;
   });
 }
+
+/**
+ * Bring one token's row on screen and put the keyboard on its value.
+ *
+ * The adapter's half of pointing the editor at a token: the flow marks the row through the scope
+ * (`current`), and only the surface knows where the row it draws is. It waits a turn, because the
+ * mark is a scope write and the row it marks is drawn by the binding that write schedules, and it
+ * searches the mounted root as it stands then, so a section redrawn since the call is the one
+ * searched. A host with no surface, or a name with no row, moves nothing.
+ *
+ * @param {HTMLElement} host The section container the editor was rendered into.
+ * @param {string} name A custom property, `--accent`.
+ */
+export function revealCssVarsToken(host: HTMLElement, name: string): void {
+  const record = mounts.get(host);
+  if (!record) {
+    return;
+  }
+  setTimeout(() => {
+    const root = record.handle?.root;
+    if (!(root instanceof HTMLElement) || !root.isConnected) {
+      return;
+    }
+    const row = [...root.querySelectorAll<HTMLElement>('[part="token"]')].find(
+      (candidate) => candidate.dataset["token"] === name,
+    );
+    if (!row) {
+      return;
+    }
+    row.scrollIntoView({ behavior: "smooth", block: "nearest" });
+    // The NATIVE input: the kit's text field does not delegate focus from its host.
+    row.querySelector<HTMLElement>('[part="value"] input')?.focus();
+  }, 0);
+}
+
+/**
+ * Bring one group's heading on screen, and with `add` put the keyboard on its Add row's name field.
+ *
+ * The Styles panel's group headings and its "Add variable" land here. It waits a turn for the
+ * reason {@link revealCssVarsToken} does. A host with no surface, or a group the section does not
+ * draw (an empty Other), moves nothing.
+ *
+ * @param {HTMLElement} host The section container the editor was rendered into.
+ * @param {string} group A token group id: `color`, `font`, `size` or `other`.
+ * @param {boolean} add Whether to focus the group's Add row.
+ */
+export function revealCssVarsGroup(host: HTMLElement, group: string, add: boolean): void {
+  const record = mounts.get(host);
+  if (!record) {
+    return;
+  }
+  setTimeout(() => {
+    const root = record.handle?.root;
+    if (!(root instanceof HTMLElement) || !root.isConnected) {
+      return;
+    }
+    const section = [...root.querySelectorAll<HTMLElement>("[data-group]")].find(
+      (candidate) => candidate.dataset["group"] === group,
+    );
+    if (!section) {
+      return;
+    }
+    section.scrollIntoView({ behavior: "smooth", block: "start" });
+    if (add) {
+      // The NATIVE input, for the reason `revealCssVarsToken` gives.
+      section.querySelector<HTMLElement>('[part="add-name"] input')?.focus();
+    }
+  }, 0);
+}

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;
     },

package/src/surfaces/settings-deploy.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioSettingsDeploy",
-  "$description": "Project Settings › Deploy: where the site ships, and what it is built with. One row over `build.adapter`, and the sentence a failed write leaves behind. The adapter (`surfaces/settings-deploy.ts`) hands in the chosen adapter, the enumeration it is chosen from and whatever the last write had to say; the document draws them and hands the change straight back. Nothing here reads `project.json` — a section that re-read the config while drawing would be a second opinion about a file one module already owns.",
+  "$description": "Publish › Hosting's build adapter (studio.md §22.8), which was Project Settings › Deploy: one row over `build.adapter`, and the sentence a failed write leaves behind. It draws no heading of its own: Hosting's \"How it is built\" section heads it, and a second title inside that card would name the same thing twice. The adapter (`surfaces/settings-deploy.ts`) hands in the chosen adapter, the enumeration it is chosen from and whatever the last write had to say; the document draws them and hands the change straight back. Nothing here reads `project.json`: a section that re-read the config while drawing would be a second opinion about a file one module already owns.",
   "tagName": "section",
   "attributes": {
     "part": "deploy"
@@ -11,12 +11,6 @@
     "display": "block",
     "fontFamily": "var(--jx-font-sans)",
     "color": "var(--fg)",
-    "& [part=\"title\"]": {
-      "margin": "0 0 16px",
-      "fontSize": "16px",
-      "fontWeight": "600",
-      "color": "var(--fg)"
-    },
     "& [part=\"section-error\"]": {
       "$description": "A write that failed, said under the section title rather than pinned to the picker: settings save on change, so a silent rejection would read as \"my edit just vanished\", and what failed was the whole file rather than the value. Its size read `--spectrum-font-size-75` with a 12px fallback, which resolved only inside `<sp-theme>` — a document is mounted in the settings pane, where that name is not in scope and the fallback is all it would ever have taken — so the size is the kit's scale and the colour is the studio layer's. It is `section-error` rather than `error` because the adapter picker is a `jx-select`, which draws a permanent `[part=\"error\"]` of its own in this same light-DOM tree: a rule on that name would give the picker's own refusal sentence this 16px margin too.",
       "margin": "0 0 16px",
@@ -29,13 +23,6 @@
     }
   },
   "children": [
-    {
-      "tagName": "h3",
-      "attributes": {
-        "part": "title"
-      },
-      "textContent": "Deploy"
-    },
     {
       "tagName": "div",
       "attributes": {
@@ -67,7 +54,7 @@
       },
       "$props": {
         "span": true,
-        "label": "Platform Adapter",
+        "label": "Build adapter",
         "description": "What the site is built for. Static writes plain files; the others emit a server entry for that runtime."
       },
       "children": [

package/src/surfaces/settings-deploy.ts

@@ -13,29 +13,22 @@
  * the old adapter back — `live()` did this for the lit template, and a binding that never moved
  * would otherwise leave the picker claiming a platform the file does not name.
  *
- * @docs studio/projects/settings
+ * @docs studio/publish/other-hosts
  */
 
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import deployDoc from "./settings-deploy.json";
-import type { JxDocument } from "@jxsuite/schema/types";
-import type { SurfaceHandle } from "../ui/surface";
+import type { SurfaceHandle, SurfaceOption } from "../ui/surface";
 
-registerSurface("settings-deploy", deployDoc as unknown as JxDocument);
-
-/** One row of the adapter picker. */
-export interface DeployChoice {
-  value: string;
-  label: string;
-}
+registerSurface("settings-deploy", deployDoc);
 
 /** What the section says the surface should be showing right now. */
 export interface DeployValues {
   /** The adapter the project is built with. */
   adapter: string;
   /** Every adapter it may be. */
-  adapters: DeployChoice[];
+  adapters: SurfaceOption[];
   /** What the last write failed with, or `""`. */
   error: string;
 }
@@ -58,9 +51,9 @@ export interface DeploySurfaceHandle {
  * The scope the document reads. `hasError` is derived here: `$switch` is a document's only
  * conditional.
  */
-interface DeployScope extends Record<string, unknown> {
+interface DeployScope {
   adapter: string;
-  adapters: DeployChoice[];
+  adapters: SurfaceOption[];
   error: string;
   hasError: boolean;
   setAdapter: (value: string) => void;
@@ -91,13 +84,13 @@ export function mountDeploySurface(
   values: DeployValues,
   actions: DeployActions,
 ): DeploySurfaceHandle {
-  const scope = reactive<DeployScope>({
+  const scope: DeployScope = reactive<DeployScope>({
     adapter: "",
     adapters: [],
     error: "",
     hasError: false,
     setAdapter: actions.setAdapter,
-  }) as DeployScope;
+  });
   project(scope, values);
 
   container.replaceChildren();
@@ -125,7 +118,7 @@ export function mountDeploySurface(
       !disposed &&
       (mounted === null
         ? container.childNodes.length === 0
-        : (mounted.root as Node).parentNode === container),
+        : mounted.root.parentNode === container),
     dispose() {
       disposed = true;
       mounted?.dispose();

package/src/surfaces/settings-dialog.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioSettingsDialog",
+  "$description": "Project Settings (§17.1): a `jx-dialog` whose body is the settings editor's two columns, the grouped section list and the section body. The dialog owns modality, Escape and focus restoration, and its one footer answer is Close: every section writes as it is edited, so there is nothing to confirm or cancel. The body is an ISLAND: this document draws the slot and nothing in it, and `settings/settings-dialog.ts` mounts `settings-pane.json` there through `onNodeCreated` (studio-ui-guidelines.md §9.4).",
+  "tagName": "jx-dialog",
+  "$props": {
+    "headline": "Project settings",
+    "confirmLabel": "",
+    "cancelLabel": "Close",
+    "size": "xl"
+  },
+  "attributes": {
+    "part": "settings"
+  },
+  "oncancel": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/closed"
+        },
+        "value": []
+      }
+    ]
+  },
+  "onclose": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/closed"
+        },
+        "value": []
+      }
+    ]
+  },
+  "children": [
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "pane-slot"
+      },
+      "style": {
+        "$description": "The editor's box is its own (`settings-pane.json`); the slot only gives it the dialog body's width.",
+        "minWidth": "0"
+      }
+    }
+  ]
+}