@jxsuite/studio 4.1.0 → 5.0.0

package/src/surfaces/settings-packages.ts

@@ -0,0 +1,158 @@
+/// <reference lib="dom" />
+/**
+ * The Packages settings section, as a mounted document.
+ *
+ * `settings/dependencies-editor.ts` is the flow — it asks the platform what the project depends on,
+ * asks the registry what each of those is at now, decides which of the two is newer and runs the
+ * four `bun` verbs — and this is the surface it draws into: the reactive scope the document reads,
+ * the flags it discriminates on, and the mount that stays put while the section is redrawn around
+ * it.
+ *
+ * **The flow tells the surface what a row says, never what it means.** `latest` arrives as the
+ * string to print, `—` included, and `upgrade` as the version an update would install or `""` —
+ * because "the registry did not answer" and "this package is already current" are two different
+ * absences that a document with one conditional could not tell apart, and only the flow knows which
+ * one it is looking at.
+ *
+ * **The add field is an ECHO, and that is load-bearing.** The lit template bound `.value` through
+ * `live()`, so a field the reader had typed into was pushed back to the module's `_addName` on
+ * every render. A document binding writes only when the SCOPE moves, so the flow states what the
+ * control now holds before it decides anything — otherwise clearing the field after a successful
+ * add would be a write of `""` over a scope that still said `""`, and the installed package's name
+ * would sit in the field as though nothing had happened.
+ *
+ * **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
+ * first one's surface away from it the moment the second drew.
+ *
+ * @docs studio/projects/settings
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import packagesDoc from "./settings-packages.json";
+import type { SurfaceHandle } from "../ui/surface";
+import type { JxDocument } from "@jxsuite/schema/types";
+
+registerSurface("settings-packages", packagesDoc as unknown as JxDocument);
+
+/** One dependency, as the table draws it. Every field is already a string the row can print. */
+export interface PackageRow {
+  name: string;
+  /** The range in `package.json`, as it is written there. */
+  version: string;
+  /** The newest published version, or `—` where there is genuinely nothing to show. */
+  latest: string;
+  /**
+   * The version an update would install, or `""` when this row is not behind one. The flow decides
+   * it: a project pinned ahead of the registry has a `latest` to show and no upgrade to offer.
+   */
+  upgrade: string;
+  /** Whether the package is a devDependency, said beside its name. */
+  dev: boolean;
+}
+
+/** What the section shows — the flow's projection of the project's dependencies. */
+export interface PackagesView {
+  rows: PackageRow[];
+  /** The list has not come back yet. Distinct from a project that has no dependencies. */
+  loading: boolean;
+  /** A `bun` run is in flight; every control on the surface is refused until it settles. */
+  busy: boolean;
+  /** The package name being typed, kept so an outside redraw does not take it away. */
+  addName: string;
+}
+
+/** Everything the reader can do here. Each one is a decision the flow makes. */
+export interface PackagesActions {
+  /** Install the typed name. */
+  add: () => void;
+  /** State what the add field now holds — the echo, before anything is decided about it. */
+  edit: (value: string) => void;
+  /** Move one package to its newest published version. */
+  update: (name: string) => void;
+  /** Move every package that is behind one. */
+  updateAll: () => void;
+  remove: (name: string) => void;
+  /** Run `bun install` over the project as it stands. */
+  reinstall: () => void;
+}
+
+/** One row plus the flag its buttons switch on. */
+interface RowScope extends Record<string, unknown>, PackageRow {
+  /** Whether to draw the update button — `upgrade` said as something a `$switch` can read. */
+  canUpdate: boolean;
+}
+
+/** What the document discriminates on. Derived here, so the flow never has to spell it. */
+interface PackagesFlags {
+  /**
+   * Which of the three bodies to draw. "Loading…" and "No dependencies." are not the same sentence:
+   * a project with no dependencies is an ordinary project, and drawing its empty table while the
+   * answer is still in flight would say so before anybody knows.
+   */
+  listState: "loading" | "empty" | "listed";
+  /** Whether anything is behind, which is the whole of the Update all button's existence. */
+  hasUpdates: boolean;
+}
+
+interface PackagesScope
+  extends Record<string, unknown>, Omit<PackagesView, "rows">, PackagesActions, PackagesFlags {
+  rows: RowScope[];
+}
+
+interface Mounted {
+  scope: PackagesScope;
+  /** `null` while the mount is still in flight — which is a standing surface, not a missing one. */
+  handle: SurfaceHandle | null;
+}
+
+const mounts = new WeakMap<HTMLElement, Mounted>();
+
+/** The view plus the flags the document switches on. */
+function derive(view: PackagesView): Omit<PackagesScope, keyof PackagesActions> {
+  const rows = view.rows.map((row): RowScope => ({ ...row, canUpdate: row.upgrade !== "" }));
+  return {
+    addName: view.addName,
+    busy: view.busy,
+    hasUpdates: rows.some((row) => row.canUpdate),
+    listState: view.loading ? "loading" : rows.length === 0 ? "empty" : "listed",
+    loading: view.loading,
+    rows,
+  };
+}
+
+/**
+ * Draw the section into `host`, or bring the one already there up to date.
+ *
+ * A mount whose root has left the document is remade; one still standing is only assigned to, which
+ * is what keeps a `bun` run from rebuilding the table under the reader — and what keeps the add
+ * field's caret where it is while they type into it.
+ *
+ * @param {HTMLElement} host The section container the registry handed the renderer.
+ * @param {PackagesView} view What to show.
+ * @param {PackagesActions} actions What the reader may do — read once, when the surface is mounted.
+ */
+export function renderPackagesSurface(
+  host: HTMLElement,
+  view: PackagesView,
+  actions: PackagesActions,
+): void {
+  const existing = mounts.get(host);
+  if (existing && (existing.handle === null || existing.handle.root.isConnected)) {
+    Object.assign(existing.scope, derive(view));
+    return;
+  }
+  existing?.handle?.dispose();
+  host.textContent = "";
+  const scope = reactive({ ...derive(view), ...actions }) as PackagesScope;
+  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
+     record with no handle yet IS the standing one — so a second mount into the same host cannot
+     start before this settles. The previous handle, when there was one, was disposed a few lines
+     up; that is the only mount this surface ever has to take down. */
+  void mountSurface("settings-packages", scope, host).then((handle) => {
+    record.handle = handle;
+  });
+}

package/src/surfaces/settings-pane.json

@@ -0,0 +1,147 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioSettingsPane",
+  "$description": "The Project Settings editor's two columns, drawn inside the pane: the section list and the section body. It draws no section — `panels/settings-pane.ts` keeps the registry, decides which section is current, and renders whichever one that is into the one empty `[part=\"body\"]` island this document leaves for it (studio-ui-guidelines.md §9.4), because a section renderer may be a lit template or a mounted document and neither can share a container with this one. The list is a real vertical `tablist` rather than the column of `<button aria-current=\"page\">` it replaces: a settings section is not a page and choosing one moves no location, so what the reader was owed was one tab stop, arrow keys down the column, and a body named by the entry that selected it.",
+  "tagName": "div",
+  "attributes": {
+    "part": "doc"
+  },
+  "style": {
+    "$description": "`.settings-doc`, `.settings-doc-nav`, `.settings-doc-content` (styles/panels.css) and `.settings-nav-item`, `.settings-nav-item:hover`, `.settings-nav-item.active`, `.settings-empty-state` (styles/overlays.css) — all seven go dead with this conversion and none is shared with a surface that is still lit. Four of them are DELETED rather than moved: the nav's own right rule and each row's hover fill, selected fill and weight are `jx-tabs[aria-orientation=\"vertical\"]` and `jx-tab` respectively, and the two Spectrum greys they reached for (`--spectrum-gray-200`, `--spectrum-gray-300`) resolved only inside an `<sp-theme>` this pane never had — so both rows had been taking their hard-coded fallback since the editor moved out of the modal.",
+    "display": "flex",
+    "height": "100%",
+    "minHeight": "0",
+    "background": "var(--bg)",
+    "color": "var(--fg)",
+    "fontFamily": "var(--jx-font-sans)",
+    "textAlign": "initial",
+    "& [part=\"nav\"]": {
+      "width": "180px",
+      "minWidth": "180px",
+      "flexShrink": "0",
+      "padding": "var(--jx-space-2) 0",
+      "overflowY": "auto",
+      "fontSize": "13px"
+    },
+    "& [part=\"nav-item\"]": {
+      "$description": "Full-bleed rows, which a tab is not by default: `jx-tab` centres its label and caps itself at 220px because a horizontal strip is a row of chips. In a 180px column the row IS the target, so the label goes to the leading edge and the cap comes off.",
+      "maxWidth": "none",
+      "justifyContent": "flex-start",
+      "padding": "var(--jx-space-2) var(--jx-space-4)"
+    },
+    "& [part=\"content\"]": {
+      "flex": "1",
+      "minWidth": "0",
+      "overflowY": "auto",
+      "padding": "24px"
+    },
+    "& [part=\"body\"]": {
+      "display": "block",
+      "minWidth": "0"
+    },
+    "& [part=\"empty\"]": {
+      "$description": "What the body says when the active section is registered by nobody — every section unregistering at once, which is a project closing while the editor is open. A blank column beside a list reads as a broken pane, so it says which it is.",
+      "display": "flex",
+      "alignItems": "center",
+      "justifyContent": "center",
+      "minHeight": "120px",
+      "margin": "0",
+      "color": "var(--fg-dim)",
+      "fontSize": "13px"
+    }
+  },
+  "children": [
+    {
+      "tagName": "jx-tabs",
+      "attributes": {
+        "part": "nav",
+        "selected": "${state.active}",
+        "orientation": "vertical"
+      },
+      "$props": {
+        "label": {
+          "$ref": "#/state/navLabel"
+        }
+      },
+      "onchange": {
+        "$prototype": "Function",
+        "body": [
+          {
+            "operator": "call",
+            "target": {
+              "$ref": "#/state/selectSection"
+            },
+            "value": [
+              {
+                "$ref": "event#/detail"
+              }
+            ]
+          }
+        ]
+      },
+      "children": [
+        {
+          "$prototype": "Array",
+          "items": {
+            "$ref": "#/state/sections"
+          },
+          "key": {
+            "$ref": "$map/item/key"
+          },
+          "map": {
+            "tagName": "jx-tab",
+            "attributes": {
+              "part": "nav-item",
+              "id": "${$map.item.tabId}",
+              "data-section": "${$map.item.key}",
+              "value": "${$map.item.key}",
+              "label": "${$map.item.label}",
+              "panel": "settings-pane-panel"
+            }
+          }
+        }
+      ]
+    },
+    {
+      "tagName": "jx-tab-panel",
+      "attributes": {
+        "part": "content",
+        "id": "settings-pane-panel"
+      },
+      "$props": {
+        "active": true,
+        "labelledby": {
+          "$ref": "#/state/activeTabId"
+        }
+      },
+      "children": [
+        {
+          "$description": "The island, and it stays empty: a settings section renders itself, into a host this document never writes into and never reads back (studio-ui-guidelines.md §9.4).",
+          "tagName": "div",
+          "attributes": {
+            "part": "body"
+          }
+        },
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "empty-slot",
+            "role": "none"
+          },
+          "$switch": {
+            "$ref": "#/state/hasSection"
+          },
+          "cases": {
+            "false": {
+              "tagName": "p",
+              "attributes": {
+                "part": "empty"
+              },
+              "textContent": "${state.empty}"
+            }
+          }
+        }
+      ]
+    }
+  ]
+}

package/src/surfaces/settings-pane.ts

@@ -0,0 +1,150 @@
+/// <reference lib="dom" />
+/**
+ * The Project Settings editor's chrome as a mounted document — the mount seam, and nothing else.
+ *
+ * `panels/settings-pane.ts` is the flow: which sections are registered, which of them is current,
+ * what a nav click does, and which renderer draws the body. This is the surface it draws into.
+ *
+ * **One island, and the sections are why.** A settings section is handed a container and renders
+ * into it — some of them still with lit, some by mounting a document of their own — so the body
+ * cannot be part of this document's subtree. It draws an empty `[part="body"]`, announces it
+ * through `onNodeCreated` as it is created, and the flow renders into it (studio-ui-guidelines.md
+ * §9.4). Nothing here queries for it by a selector this package also renders.
+ *
+ * @docs studio/projects/settings
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import settingsPaneDoc from "./settings-pane.json";
+import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("settings-pane", settingsPaneDoc as unknown as JxDocument);
+
+/** One row of the section list, as the document draws it. */
+export interface SettingsNavView {
+  /** The section key — the row's identity, its `value`, and what the strip compares `selected` to. */
+  key: string;
+  label: string;
+  /** The row's own element id, which the one panel names as its `aria-labelledby`. */
+  tabId: string;
+}
+
+/** What the editor says right now. */
+export interface SettingsPaneValues {
+  /** The list's accessible name. A tablist takes no name from its tabs. */
+  navLabel: string;
+  /** The current section's key. */
+  active: string;
+  /** The current section's row id, so the body is named by the row that chose it. */
+  activeTabId: string;
+  sections: SettingsNavView[];
+  /**
+   * Whether a renderer will draw into the island.
+   *
+   * The flow's own question — `settingsSection(active)` — rather than "are there any sections": the
+   * body is empty exactly when the ACTIVE key is registered by nobody, and a second spelling of
+   * that would be a second thing to get wrong.
+   */
+  hasSection: boolean;
+  /** What the body says instead, when it will not be drawn into. */
+  empty: string;
+}
+
+export interface SettingsPaneActions {
+  /** A row was activated. */
+  selectSection: (key: string) => void;
+}
+
+export interface SettingsPaneHandle {
+  /** Bring the standing document up to date. An assignment; the mount is never rebuilt. */
+  update: (values: SettingsPaneValues) => void;
+  /**
+   * The empty `[part="body"]` island, once it exists — the one element a section renderer needs.
+   *
+   * It is HELD rather than re-found, exactly as `surfaces/tab-strip.ts` holds its `jx-tabs`: it
+   * arrives through `onNodeCreated` as the node is created, so nothing in this package queries for
+   * a node this package renders (studio-ui-guidelines.md §9.4).
+   */
+  body: () => HTMLElement | null;
+  /** Settles once the document is mounted, or the surface was disposed first. */
+  ready: Promise<void>;
+  /** Take the document down. Idempotent. */
+  dispose: () => void;
+}
+
+interface SettingsPaneScope
+  extends Record<string, unknown>, SettingsPaneValues, SettingsPaneActions {}
+
+/** The `part` a node was declared with, or the empty string. */
+function partOf(def: JxElement | string): string {
+  const part = typeof def === "string" ? undefined : def.attributes?.["part"];
+  return typeof part === "string" ? part : "";
+}
+
+/**
+ * Mount the editor's chrome into `container`, which is the pane's stage.
+ *
+ * The container is cleared first, lit's render marker included: the stage is shared with every
+ * other canvas mode, and a marker left behind by whatever drew there last would make the next lit
+ * render throw on a part whose nodes have gone.
+ *
+ * @param {HTMLElement} container The pane's `#canvas-wrap`
+ * @param {SettingsPaneValues} values What to say on the first paint
+ * @param {SettingsPaneActions} actions What a nav row does. Read once, when the scope is made.
+ * @returns {SettingsPaneHandle}
+ */
+export function mountSettingsPaneSurface(
+  container: HTMLElement,
+  values: SettingsPaneValues,
+  actions: SettingsPaneActions,
+): SettingsPaneHandle {
+  const scope = reactive<SettingsPaneScope>({ ...values, ...actions }) as SettingsPaneScope;
+
+  container.textContent = "";
+  // @ts-expect-error -- _$litPart$ is lit's private render-part marker, not in the DOM types
+  delete container["_$litPart$"];
+
+  let mounted: SurfaceHandle | null = null;
+  let disposed = false;
+  let body: HTMLElement | null = null;
+  const ready = mountSurface("settings-pane", scope, container, {
+    onNodeCreated: (element, _path, def) => {
+      /* `disposed` and not just the part: a mount that is still in flight goes on building its
+         nodes after the handle has let go, and holding one of them would answer `body()` with an
+         element belonging to a document nobody is standing behind any more. */
+      if (!disposed && element instanceof HTMLElement && partOf(def) === "body") {
+        body = element;
+      }
+    },
+  }).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+      return;
+    }
+    mounted = surface;
+  });
+
+  return {
+    body: () => body,
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+      body = null;
+    },
+    ready,
+    update(next) {
+      /* Field by field, so an unchanged one is inert — and `active` LAST, because it is what the
+         strip's selection is compared against: writing it before the rows it names have arrived
+         would make `jx-tabs` sync a selection onto a column that does not hold that tab yet. */
+      scope.navLabel = next.navLabel;
+      scope.sections = next.sections;
+      scope.activeTabId = next.activeTabId;
+      scope.empty = next.empty;
+      scope.hasSection = next.hasSection;
+      scope.active = next.active;
+    },
+  };
+}

package/src/surfaces/settings-rawjson.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioSettingsRawJson",
+  "$description": "Project Settings › Raw JSON: `project.json` as it is written, and the way through to editing it as text. The adapter (`surfaces/settings-rawjson.ts`) hands in the serialisation the save chokepoint itself produced, so what is drawn is what a save writes rather than a second pretty-printer that would disagree with the file by an indent. The button opens the SAME tab in the Code editor — one document, three editors (`studio.md` §9.3) — so switching to the text and back keeps one undo stack instead of forking two.",
+  "tagName": "section",
+  "attributes": {
+    "part": "rawjson"
+  },
+  "style": {
+    "$description": "Two of the rules this section borrowed are gone rather than moved. `.settings-field-desc` styled the sentence under the title, and it is kept here because there is no `jx-field` in this section to draw it — a `<pre>` is not a control and wrapping one in a row would give the file a label it does not need. `.settings-edit-as-code` set `align-self: flex-start` on the button, which did nothing: its parent carried `.settings-section`, a class no stylesheet defines, so there was no flex container for the declaration to be about — and `jx-button` is `inline-flex`, so it already sits at the left of a block.",
+    "display": "block",
+    "fontFamily": "var(--jx-font-sans)",
+    "color": "var(--fg)",
+    "& [part=\"title\"]": {
+      "margin": "0 0 16px",
+      "fontSize": "16px",
+      "fontWeight": "600",
+      "color": "var(--fg)"
+    },
+    "& [part=\"intro\"]": {
+      "$description": "The sentence under the title. Its size read `--spectrum-font-size-75` with a 12px fallback, a name that resolves only inside `<sp-theme>`; a document is mounted in the settings pane, so the fallback is all it could ever have taken and the size is the kit's scale now.",
+      "margin": "0 0 6px",
+      "fontSize": "var(--jx-text-md)",
+      "color": "var(--fg-dim)"
+    },
+    "& [part=\"file\"]": {
+      "$description": "The file's name, said in the prose as the file it is. It borrowed a bare `<code>` element and whatever the page happened to give one; a document's styling is its own, so the face is stated here.",
+      "fontFamily": "var(--font-mono)"
+    },
+    "& [part=\"json\"]": {
+      "$description": "`project.json` as it is saved. It scrolls in its own box: a 250-line file must not push the \"Edit as code\" action off the bottom of the section. Its background read `var(--bg-dim, var(--bg))` and `--bg-dim` is declared nowhere in the token layer, so the fallback is what has always painted it — written as what it resolves to rather than as a name that never resolved.",
+      "margin": "0 0 12px",
+      "padding": "12px",
+      "maxHeight": "420px",
+      "overflow": "auto",
+      "border": "1px solid var(--border)",
+      "borderRadius": "var(--radius)",
+      "background": "var(--bg)",
+      "fontFamily": "var(--font-mono)",
+      "fontSize": "var(--jx-text-md)",
+      "color": "var(--fg)",
+      "whiteSpace": "pre"
+    }
+  },
+  "children": [
+    {
+      "tagName": "h3",
+      "attributes": {
+        "part": "title"
+      },
+      "textContent": "Raw JSON"
+    },
+    {
+      "tagName": "p",
+      "attributes": {
+        "part": "intro"
+      },
+      "children": [
+        "The whole of ",
+        {
+          "tagName": "code",
+          "attributes": {
+            "part": "file"
+          },
+          "textContent": "project.json"
+        },
+        ", as it is saved. Editing it as code opens the same document in the Code editor — one undo stack, one dirty flag."
+      ]
+    },
+    {
+      "tagName": "pre",
+      "attributes": {
+        "part": "json"
+      },
+      "textContent": "${state.json}"
+    },
+    {
+      "tagName": "jx-button",
+      "attributes": {
+        "part": "edit"
+      },
+      "$props": {
+        "size": "sm"
+      },
+      "onclick": {
+        "$prototype": "Function",
+        "body": [
+          {
+            "operator": "call",
+            "target": {
+              "$ref": "#/state/editAsCode"
+            }
+          }
+        ]
+      },
+      "children": [
+        {
+          "tagName": "span",
+          "textContent": "Edit as code"
+        }
+      ]
+    }
+  ]
+}

package/src/surfaces/settings-rawjson.ts

@@ -0,0 +1,107 @@
+/// <reference lib="dom" />
+/**
+ * The Raw JSON surface: `project.json` as it is written, and the way through to editing it as text.
+ *
+ * This is the adapter. `settings/project-sections.ts` keeps the section — it asks the save
+ * chokepoint to serialise the configuration, so what is drawn is what a save writes, and it owns
+ * what "Edit as code" does to the tab. The document renders one string and one button.
+ *
+ * There is nothing to echo here, which is the whole difference from the sibling surfaces: this
+ * section holds no value the reader can move, so the scope can only ever be behind the file rather
+ * than ahead of it, and a redraw is the only thing that changes what it says.
+ *
+ * @docs studio/projects/settings
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import rawJsonDoc from "./settings-rawjson.json";
+import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("settings-rawjson", rawJsonDoc as unknown as JxDocument);
+
+/** What the section says the surface should be showing right now. */
+export interface RawJsonValues {
+  /** The whole file, serialised by the chokepoint that writes it. */
+  json: string;
+}
+
+/** What the reader can do here. */
+export interface RawJsonActions {
+  /** Open the same document in the Code editor, over the same tab. */
+  editAsCode: () => void;
+}
+
+export interface RawJsonSurfaceHandle {
+  /** Bring the mounted document up to date. A key left out is left alone. */
+  update: (patch: Partial<RawJsonValues>) => void;
+  /** Whether the document this mounted is still standing in the container it was given. */
+  connected: () => boolean;
+  /** Take the document down. Idempotent. */
+  dispose: () => void;
+}
+
+/** The scope the document reads. */
+interface RawJsonScope extends Record<string, unknown> {
+  json: string;
+  editAsCode: () => void;
+}
+
+/** Write a patch into the scope. */
+function project(scope: RawJsonScope, patch: Partial<RawJsonValues>): void {
+  if (patch.json !== undefined) {
+    scope.json = patch.json;
+  }
+}
+
+/**
+ * Mount the Raw JSON document into `container`.
+ *
+ * The container is cleared first: a settings section is handed the pane's content area, and
+ * whatever the last section drew into it is not this one's to keep.
+ */
+export function mountRawJsonSurface(
+  container: HTMLElement,
+  values: RawJsonValues,
+  actions: RawJsonActions,
+): RawJsonSurfaceHandle {
+  const scope = reactive<RawJsonScope>({
+    editAsCode: actions.editAsCode,
+    json: "",
+  }) as RawJsonScope;
+  project(scope, values);
+
+  container.replaceChildren();
+  let mounted: SurfaceHandle | null = null;
+  let disposed = false;
+  /* Nothing is called on the element, so the mount is all this has to wait for: the DOCUMENT is
+     what this surface renders, and `jx-button` settles its own template one `connectedCallback`
+     later without anybody here asking it to (§1.1, "await the element"). */
+  void mountSurface("settings-rawjson", scope, container).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+      return;
+    }
+    mounted = surface;
+  });
+
+  return {
+    /* While the mount is still in flight this surface owns the container only for as long as the
+       container is still the empty one it was handed: a settings section is drawn into the pane's
+       content area, and if something else has claimed it in the meantime the document must not
+       land on top of that. Once mounted, the question is simply whether the root is still there —
+       a section that was switched away from had its root taken out from under it. */
+    connected: () =>
+      !disposed &&
+      (mounted === null
+        ? container.childNodes.length === 0
+        : (mounted.root as Node).parentNode === container),
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+    },
+    update: (patch) => project(scope, patch),
+  };
+}