@jxsuite/studio 6.1.1 → 6.1.2

package/src/surfaces/settings-deploy.ts

@@ -19,23 +19,16 @@
 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-extensions.ts

@@ -26,10 +26,9 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import extensionsDoc from "./settings-extensions.json";
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("settings-extensions", extensionsDoc as unknown as JxDocument);
+registerSurface("settings-extensions", extensionsDoc);
 
 /** One `project.json` key an extension owns, as the chip repeater reads it. */
 export interface ExtensionSectionView {
@@ -117,7 +116,7 @@ export interface ExtensionsSurfaceHandle {
  * value already in the view, and a view that had to keep them in step would be a second place to
  * get it wrong.
  */
-interface ExtensionsScope extends Record<string, unknown>, ExtensionsView, ExtensionsActions {
+interface ExtensionsScope extends ExtensionsView, ExtensionsActions {
   /** Whether to draw the groups or the sentence that says what this region is for. */
   listState: "empty" | "groups";
   hasError: boolean;
@@ -147,14 +146,14 @@ export function mountExtensionsSurface(
   view: ExtensionsView,
   actions: ExtensionsActions,
 ): ExtensionsSurfaceHandle {
-  const scope = reactive<ExtensionsScope>({
+  const scope: ExtensionsScope = reactive<ExtensionsScope>({
     error: "",
     groups: [],
     hasError: false,
     listState: "empty",
     remove: actions.remove,
     toggle: actions.toggle,
-  }) as ExtensionsScope;
+  });
   project(scope, view);
 
   container.replaceChildren();
@@ -182,7 +181,7 @@ export function mountExtensionsSurface(
       !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-head.ts

@@ -18,6 +18,7 @@
  * @docs studio/projects/settings
  */
 
+import { isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { projectState } from "../store";
 import { updateSiteConfig } from "../site-context";
@@ -29,24 +30,15 @@ import {
   isGoogleFontEntry,
 } from "../utils/google-fonts";
 import { mountSurface, registerSurface } from "../ui/surface";
+import { HEAD_EDIT_DEBOUNCE } from "../ui/timing";
 import headDoc from "./settings-head.json";
-import type { JxDocument, JxHeadEntry, ProjectConfig } from "@jxsuite/schema/types";
-import type { SurfaceHandle } from "../ui/surface";
+import type { JsonValue, JxHeadEntry, ProjectConfig } from "@jxsuite/schema/types";
+import type { SurfaceHandle, TaggedLabel } from "../ui/surface";
 
-registerSurface("settings-head", headDoc as unknown as JxDocument);
-
-/**
- * How long a keystroke waits before it is written.
- *
- * Every field commit is a `project.json` write, and the two body fields commit on `input` — one
- * write per keystroke without this. The lit editor debounced per ENTRY, with one timer shared by
- * that entry's fields, so editing `rel` and then `href` inside the window cancelled the first write
- * outright; the timers are per field here, which is why each edit lands.
- */
-const EDIT_DEBOUNCE_MS = 300;
+registerSurface("settings-head", headDoc);
 
 /** One `$head` entry as the document draws it: which fields, and what is in them. */
-interface HeadRow extends Record<string, unknown> {
+interface HeadRow {
   id: string;
   /** The tag name, drawn as `<link>` and named in the delete button. */
   tag: string;
@@ -64,18 +56,12 @@ interface HeadRow extends Record<string, unknown> {
 }
 
 /** One Google Fonts stylesheet link, by the family it loads. */
-interface FontRow extends Record<string, unknown> {
+interface FontRow {
   id: string;
   family: string;
 }
 
-/** One of the four tags the section can add, and the button that adds it. */
-interface AddTag extends Record<string, unknown> {
-  tag: string;
-  label: string;
-}
-
-interface HeadScope extends Record<string, unknown> {
+interface HeadScope {
   rows: HeadRow[];
   fonts: FontRow[];
   /**
@@ -85,7 +71,8 @@ interface HeadScope extends Record<string, unknown> {
   fontsState: "empty" | "listed";
   /** What is in the family field. The document reads it back, so clearing it is an assignment. */
   fontDraft: string;
-  tags: AddTag[];
+  /** The four tags the section can add, each with the words on the button that adds it. */
+  tags: TaggedLabel[];
   add: (tag: string) => void;
   remove: (id: string) => void;
   edit: (id: string, key: string, value: string) => void;
@@ -94,7 +81,7 @@ interface HeadScope extends Record<string, unknown> {
   removeFont: (id: string) => void;
 }
 
-const ADD_TAGS: AddTag[] = [
+const ADD_TAGS: TaggedLabel[] = [
   { label: "+ Link", tag: "link" },
   { label: "+ Meta", tag: "meta" },
   { label: "+ Script", tag: "script" },
@@ -137,7 +124,7 @@ let _entries: JxHeadEntry[] = [];
  * between would answer "no entries" and lose the tag that was just added.
  */
 function entries(): JxHeadEntry[] {
-  const config = (projectState?.projectConfig ?? null) as ProjectConfig | null;
+  const config = projectState?.projectConfig ?? null;
   if (config !== _config) {
     _config = config;
     _entries = [];
@@ -150,7 +137,7 @@ function entries(): JxHeadEntry[] {
   }
   const declared = config?.$head;
   if (Array.isArray(declared)) {
-    _entries = declared as JxHeadEntry[];
+    _entries = declared;
   }
   return _entries;
 }
@@ -161,8 +148,8 @@ function entryFor(id: string): JxHeadEntry | undefined {
 }
 
 /** A `$head` attribute as a field's text: anything that is not a string has none to show. */
-function text(value: unknown): string {
-  return typeof value === "string" ? value : "";
+function text(value: JsonValue | undefined): string {
+  return isString(value) ? value : "";
 }
 
 // ─── The projection ───────────────────────────────────────────────────────────
@@ -171,19 +158,21 @@ function text(value: unknown): string {
 function row(entry: JxHeadEntry): HeadRow {
   const attributes = entry.attributes ?? {};
   const src = text(attributes["src"]);
-  const tag = String(entry.tagName ?? "");
-  const kinds: Record<string, HeadRow["kind"]> = {
-    link: "link",
-    meta: "meta",
-    script: src === "" ? "script-inline" : "script",
-    style: "style",
-  };
+  /* `project.json` is read off disk unvalidated, so an entry can arrive without a `tagName`; like
+     an attribute, a tag that is not a string has none to show. */
+  const tag = text(entry.tagName);
+  const kinds = new Map<string, HeadRow["kind"]>([
+    ["link", "link"],
+    ["meta", "meta"],
+    ["script", src === "" ? "script-inline" : "script"],
+    ["style", "style"],
+  ]);
   return {
     body: text(entry.textContent),
     content: text(attributes["content"]),
     href: text(attributes["href"]),
     id: idOf(entry),
-    kind: kinds[tag] ?? "none",
+    kind: kinds.get(tag) ?? "none",
     name: text(attributes["name"]),
     rel: text(attributes["rel"]),
     src,
@@ -212,7 +201,12 @@ function save(): void {
   void updateSiteConfig({ $head: entries() });
 }
 
-/** Field edits waiting out {@link EDIT_DEBOUNCE_MS}, one per field. */
+/**
+ * Field edits waiting out {@link HEAD_EDIT_DEBOUNCE}, one per field. The two body fields commit on
+ * `input`, so without the wait every keystroke would be a `project.json` write; the lit editor
+ * shared one timer per ENTRY, so editing `rel` and then `href` inside the window cancelled the
+ * first write outright.
+ */
 const _pending = new Map<string, { commit: () => void; timer: ReturnType<typeof setTimeout> }>();
 
 /**
@@ -302,7 +296,7 @@ function state(): HeadScope {
         _pending.delete(token);
         write(id, key, value);
       };
-      _pending.set(token, { commit, timer: setTimeout(commit, EDIT_DEBOUNCE_MS) });
+      _pending.set(token, { commit, timer: setTimeout(commit, HEAD_EDIT_DEBOUNCE) });
     },
     fonts: [],
     fontDraft: "",
@@ -339,7 +333,7 @@ function state(): HeadScope {
     },
     rows: [],
     tags: ADD_TAGS,
-  }) as HeadScope;
+  });
   return _scope;
 }
 

package/src/surfaces/settings-locales.ts

@@ -24,28 +24,16 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import localesDoc from "./settings-locales.json";
-import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle, SurfaceOption, TaggedLabel } from "../ui/surface";
 
-registerSurface("settings-locales", localesDoc as unknown as JxDocument);
-
-/** One declared language: the tag as the author wrote it, and the name that language calls itself. */
-export interface LocaleRow {
-  tag: string;
-  label: string;
-}
-
-/** One row of a picker. */
-export interface LocaleChoice {
-  value: string;
-  label: string;
-}
+registerSurface("settings-locales", localesDoc);
 
 /** What the section shows — the flow's projection of `project.json` and of the form beside it. */
 export interface LocalesView {
-  locales: LocaleRow[];
-  localeOptions: LocaleChoice[];
-  routings: LocaleChoice[];
+  /** Each declared language: the tag as the author wrote it, and the name it calls itself. */
+  locales: TaggedLabel[];
+  localeOptions: SurfaceOption[];
+  routings: SurfaceOption[];
   defaultLocale: string;
   routing: string;
   /** The tag being typed, kept so an outside redraw does not take it away. */
@@ -80,7 +68,7 @@ interface LocalesFlags {
   hasError: boolean;
 }
 
-interface LocalesScope extends Record<string, unknown>, LocalesView, LocalesActions, LocalesFlags {}
+interface LocalesScope extends LocalesView, LocalesActions, LocalesFlags {}
 
 interface Mounted {
   scope: LocalesScope;
@@ -124,7 +112,7 @@ export function renderLocalesSurface(
   }
   existing?.handle?.dispose();
   host.textContent = "";
-  const scope = reactive({ ...derive(view), ...actions }) as LocalesScope;
+  const scope: LocalesScope = reactive<LocalesScope>({ ...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-overview.ts

@@ -24,10 +24,9 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import overviewDoc from "./settings-overview.json";
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("settings-overview", overviewDoc as unknown as JxDocument);
+registerSurface("settings-overview", overviewDoc);
 
 /** Which control a failure belongs under. `"section"` puts it at the top of the section. */
 export type OverviewErrorField = "name" | "description" | "url" | "favicon" | "section";
@@ -74,7 +73,7 @@ export interface OverviewSurfaceHandle {
  * The scope the document reads: one field per binding, because `$switch` is the only conditional a
  * document has and `error.field === "name"` is not a value it can switch on.
  */
-interface OverviewScope extends Record<string, unknown> {
+interface OverviewScope {
   nameValue: string;
   nameError: string;
   nameInvalid: boolean;
@@ -157,7 +156,7 @@ export function mountOverviewSurface(
   values: OverviewValues,
   actions: OverviewActions,
 ): OverviewSurfaceHandle {
-  const scope = reactive<OverviewScope>({
+  const scope: OverviewScope = reactive<OverviewScope>({
     descriptionError: "",
     descriptionInvalid: false,
     descriptionValue: "",
@@ -180,7 +179,7 @@ export function mountOverviewSurface(
     urlError: "",
     urlInvalid: false,
     urlValue: "",
-  }) as OverviewScope;
+  });
   project(scope, values);
 
   container.replaceChildren();
@@ -208,7 +207,7 @@ export function mountOverviewSurface(
       !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-packages.ts

@@ -32,9 +32,8 @@ 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);
+registerSurface("settings-packages", packagesDoc);
 
 /** One dependency, as the table draws it. Every field is already a string the row can print. */
 export interface PackageRow {
@@ -79,7 +78,7 @@ export interface PackagesActions {
 }
 
 /** One row plus the flag its buttons switch on. */
-interface RowScope extends Record<string, unknown>, PackageRow {
+interface RowScope extends PackageRow {
   /** Whether to draw the update button — `upgrade` said as something a `$switch` can read. */
   canUpdate: boolean;
 }
@@ -96,11 +95,13 @@ interface PackagesFlags {
   hasUpdates: boolean;
 }
 
-interface PackagesScope
-  extends Record<string, unknown>, Omit<PackagesView, "rows">, PackagesActions, PackagesFlags {
+/** Everything {@link derive} computes from a view: the scope minus the reader's actions. */
+interface PackagesDerived extends Omit<PackagesView, "rows">, PackagesFlags {
   rows: RowScope[];
 }
 
+interface PackagesScope extends PackagesDerived, PackagesActions {}
+
 interface Mounted {
   scope: PackagesScope;
   /** `null` while the mount is still in flight — which is a standing surface, not a missing one. */
@@ -110,7 +111,7 @@ interface Mounted {
 const mounts = new WeakMap<HTMLElement, Mounted>();
 
 /** The view plus the flags the document switches on. */
-function derive(view: PackagesView): Omit<PackagesScope, keyof PackagesActions> {
+function derive(view: PackagesView): PackagesDerived {
   const rows = view.rows.map((row): RowScope => ({ ...row, canUpdate: row.upgrade !== "" }));
   return {
     addName: view.addName,
@@ -145,7 +146,7 @@ export function renderPackagesSurface(
   }
   existing?.handle?.dispose();
   host.textContent = "";
-  const scope = reactive({ ...derive(view), ...actions }) as PackagesScope;
+  const scope: PackagesScope = reactive<PackagesScope>({ ...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-pane.ts

@@ -15,22 +15,14 @@
  * @docs studio/projects/settings
  */
 
+import { isString } from "@jxsuite/schema/guards";
 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";
+import type { JxElement } from "@jxsuite/schema/types";
+import type { SurfaceHandle, SurfaceTab } 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;
-}
+registerSurface("settings-pane", settingsPaneDoc);
 
 /** What the editor says right now. */
 export interface SettingsPaneValues {
@@ -40,7 +32,7 @@ export interface SettingsPaneValues {
   active: string;
   /** The current section's row id, so the body is named by the row that chose it. */
   activeTabId: string;
-  sections: SettingsNavView[];
+  sections: SurfaceTab[];
   /**
    * Whether a renderer will draw into the island.
    *
@@ -75,13 +67,12 @@ export interface SettingsPaneHandle {
   dispose: () => void;
 }
 
-interface SettingsPaneScope
-  extends Record<string, unknown>, SettingsPaneValues, SettingsPaneActions {}
+interface SettingsPaneScope extends 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 : "";
+  const part = isString(def) ? undefined : def.attributes?.["part"];
+  return isString(part) ? part : "";
 }
 
 /**
@@ -101,7 +92,7 @@ export function mountSettingsPaneSurface(
   values: SettingsPaneValues,
   actions: SettingsPaneActions,
 ): SettingsPaneHandle {
-  const scope = reactive<SettingsPaneScope>({ ...values, ...actions }) as SettingsPaneScope;
+  const scope: SettingsPaneScope = reactive<SettingsPaneScope>({ ...values, ...actions });
 
   container.textContent = "";
   // @ts-expect-error -- _$litPart$ is lit's private render-part marker, not in the DOM types

package/src/surfaces/settings-rawjson.ts

@@ -16,10 +16,9 @@
 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);
+registerSurface("settings-rawjson", rawJsonDoc);
 
 /** What the section says the surface should be showing right now. */
 export interface RawJsonValues {
@@ -43,7 +42,7 @@ export interface RawJsonSurfaceHandle {
 }
 
 /** The scope the document reads. */
-interface RawJsonScope extends Record<string, unknown> {
+interface RawJsonScope {
   json: string;
   editAsCode: () => void;
 }
@@ -66,10 +65,10 @@ export function mountRawJsonSurface(
   values: RawJsonValues,
   actions: RawJsonActions,
 ): RawJsonSurfaceHandle {
-  const scope = reactive<RawJsonScope>({
+  const scope: RawJsonScope = reactive<RawJsonScope>({
     editAsCode: actions.editAsCode,
     json: "",
-  }) as RawJsonScope;
+  });
   project(scope, values);
 
   container.replaceChildren();
@@ -96,7 +95,7 @@ export function mountRawJsonSurface(
       !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/shell.ts

@@ -16,9 +16,8 @@
 import { mountSurface, registerSurface } from "../ui/surface";
 import shellDoc from "./shell.json";
 import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
 
-registerSurface("shell", shellDoc as unknown as JxDocument);
+registerSurface("shell", shellDoc);
 
 /**
  * Render the frame into `host`, and resolve once its cells exist.

package/src/surfaces/slash-menu.ts

@@ -41,17 +41,16 @@ import { clearLayerSlot, getLayerSlot } from "../ui/layers";
 import { mountSurface, registerSurface } from "../ui/surface";
 import { overlayRegion, REGION_ATTR } from "../ui/regions";
 import slashMenuDoc from "./slash-menu.json";
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { JxScope } from "@jxsuite/runtime/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("slash-menu", slashMenuDoc as unknown as JxDocument);
+registerSurface("slash-menu", slashMenuDoc);
 
 /** The popover slot id; the region is `overlay.menu:slash-menu`, which is what the shots crop. */
 const SLOT = "slash-menu";
 
 /** One offer, as the document reads it. */
-export interface SlashMenuRow extends Record<string, unknown> {
+export interface SlashMenuRow {
   /**
    * The element's tag — unique in the list, so it is the repeater's key AND the row's `value`,
    * which is what a picked row names in its `select` event.
@@ -103,7 +102,7 @@ export interface SlashMenuSurface {
 }
 
 /** The scope `slash-menu.json` reads. */
-interface SlashMenuScope extends Record<string, unknown> {
+interface SlashMenuScope {
   x: number;
   y: number;
   showFilter: boolean;
@@ -168,7 +167,7 @@ export function openSlashMenuSurface(
   let mounted: SurfaceHandle | null = null;
   let closed = false;
 
-  const scope = reactive<SlashMenuScope>({
+  const scope: SlashMenuScope = reactive<SlashMenuScope>({
     activeId: activeIdOf(view),
     expanded: view.rows.length > 0,
     filter: view.filter,
@@ -184,6 +183,9 @@ export function openSlashMenuSurface(
          one bubbling handler on the listbox replaces a closure per row, and the position the flow
          wants is resolved here against the list the panel is showing rather than baked into the
          row when it was drawn. */
+      /* SAFETY: `slash-menu.json` binds this handler to the listbox's `onselect` alone, and `select`
+         is raised by the `dispatchEvent` statement in `jx-option.json`, which the runtime always
+         constructs as a `CustomEvent` whose `detail` is the row's value. */
       const tag = String((event as CustomEvent<unknown>).detail);
       const index = scope.rows.findIndex((row) => row.key === tag);
       if (index !== -1) {
@@ -194,7 +196,7 @@ export function openSlashMenuSurface(
     showFilter: view.showFilter,
     x: view.x,
     y: view.y,
-  }) as SlashMenuScope;
+  });
 
   const finish = (fromPlatform: boolean): void => {
     if (closed) {
@@ -210,12 +212,20 @@ export function openSlashMenuSurface(
     }
   };
 
+  /* Read through a call, not the property path: `close()` can abort the controller while the panel
+     is awaiting `jx-ready`, and a direct test after that `await` would be narrowed to the value the
+     test before it saw. */
+  const aborted = (): boolean => controller.signal.aborted;
+
   const ready = (async () => {
     const surface = await mountSurface("slash-menu", scope, slot, { signal: controller.signal });
-    if (controller.signal.aborted) {
+    if (aborted()) {
       return;
     }
     mounted = surface;
+    /* SAFETY: `slash-menu.json`'s root definition carries `tagName: "jx-popover"`, so the mounted
+       root is the kit's popover element, which reflects `open` and inherits `showPopover` and
+       `hidePopover` from HTMLElement. */
     panel = surface.root as PopoverElement;
     /* The region rides on the PANEL as well as on the slot `getLayerSlot` stamped: a popover is
        `position: fixed` in the top layer, so the slot around it has a zero-height box and the
@@ -223,7 +233,7 @@ export function openSlashMenuSurface(
        takes the last match in document order, which is the panel. */
     panel.setAttribute(REGION_ATTR, overlayRegion("popover", SLOT));
     panel.addEventListener("toggle", (event) => {
-      if ((event as { newState?: string }).newState === "closed") {
+      if (event.newState === "closed") {
         finish(true);
       }
     });
@@ -234,7 +244,7 @@ export function openSlashMenuSurface(
         panel!.addEventListener("jx-ready", () => resolve(), { once: true });
       });
     }
-    if (controller.signal.aborted) {
+    if (aborted()) {
       return;
     }
     panel.showPopover(anchor instanceof HTMLElement ? { source: anchor } : undefined);