@jxsuite/studio 6.1.1 → 6.1.2

package/src/style/token-ref.ts

@@ -13,6 +13,7 @@
  * hop would report `var(--color-brand)` as a colour.
  */
 
+import { isNumber, isString } from "@jxsuite/schema/guards";
 import type { JxStyle } from "@jxsuite/schema/types";
 
 /** A value that is EXACTLY one `var()` reference — not `calc(var(--a) * 2)`, which is a value. */
@@ -24,11 +25,11 @@ const MAX_HOPS = 10;
 /**
  * The token a value references, or null when the value is not a bare reference.
  *
- * @param {unknown} value
+ * @param {string | number} value
  * @returns {string | null}
  */
-export function tokenRefName(value: unknown): string | null {
-  if (typeof value !== "string") {
+export function tokenRefName(value: string | number): string | null {
+  if (!isString(value)) {
     return null;
   }
   return TOKEN_REF_RE.exec(value)?.[1] ?? null;
@@ -75,7 +76,7 @@ export function resolveTokenValue(
     }
     seen.add(ref);
     const next = style?.[ref];
-    if (typeof next !== "string" && typeof next !== "number") {
+    if (!isString(next) && !isNumber(next)) {
       return undefined;
     }
     current = next;

package/src/surfaces/about.ts

@@ -17,19 +17,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 aboutDoc from "./about.json";
-import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle, SurfaceOption } from "../ui/surface";
 
-registerSurface("about", aboutDoc as unknown as JxDocument);
-
-/** One row of the metadata list: a label and the value beside it. */
-export interface AboutRow {
-  label: string;
-  value: string;
-}
+registerSurface("about", aboutDoc);
 
 /** One external link in the dialog's link row. */
 export interface AboutLink {
@@ -41,7 +34,7 @@ export interface AboutSurfaceOptions {
   /** Where the dialog is mounted — the dialog layer. */
   layer: HTMLElement;
   headline: string;
-  rows: AboutRow[];
+  rows: SurfaceOption[];
   links: AboutLink[];
   /** The dialog closed, for any reason the platform owns as well as the Close button. */
   onClosed: () => void;
@@ -49,7 +42,7 @@ export interface AboutSurfaceOptions {
 
 /** What the flow may change once the dialog is up: the package list, when it arrives. */
 export interface AboutSurfacePatch {
-  rows?: AboutRow[];
+  rows?: SurfaceOption[];
   packages?: { name: string; version: string }[];
 }
 
@@ -60,9 +53,9 @@ export interface AboutSurfaceHandle {
   close: () => void;
 }
 
-interface AboutScope extends Record<string, unknown> {
+interface AboutScope {
   headline: string;
-  rows: AboutRow[];
+  rows: SurfaceOption[];
   links: AboutLink[];
   packages: { name: string; version: string }[];
   /**
@@ -100,7 +93,11 @@ export function openAboutSurface(options: AboutSurfaceOptions): AboutSurfaceHand
     closed = true;
     options.onClosed();
   };
-  const scope = reactive<AboutScope>({
+  /* 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;
+  const scope: AboutScope = reactive<AboutScope>({
     close: () => handle.close(),
     closed: finish,
     headline: options.headline,
@@ -108,13 +105,15 @@ export function openAboutSurface(options: AboutSurfaceOptions): AboutSurfaceHand
     packages: [],
     packagesState: "loading",
     rows: options.rows,
-  }) as AboutScope;
+  });
 
   let mounted: SurfaceHandle | null = null;
   const ready = mountSurface("about", scope, slot).then(async (surface) => {
     mounted = surface;
+    // SAFETY: `about.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;
     }
@@ -125,7 +124,7 @@ export function openAboutSurface(options: AboutSurfaceOptions): AboutSurfaceHand
        `openDialogSurface` rather than reimplemented, because both surfaces are `jx-dialog`s and
        there is one answer to when one of those is ready. */
     await whenReady(element);
-    if (closed) {
+    if (isClosed()) {
       return element;
     }
     showModal(element);
@@ -140,7 +139,7 @@ export function openAboutSurface(options: AboutSurfaceOptions): AboutSurfaceHand
       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);
       }
       mounted?.dispose();
       mounted = null;

package/src/surfaces/add-repo.ts

@@ -31,14 +31,13 @@
 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 { focusField } from "@jxsuite/ui/behaviors/textfield";
 import { whenReady } from "./dialog";
 import addRepoDoc from "./add-repo.json";
-import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle, SurfaceOption } from "../ui/surface";
 
-registerSurface("add-repo", addRepoDoc as unknown as JxDocument);
+registerSurface("add-repo", addRepoDoc);
 
 /** One repository, as the list draws it. Every field is already a string or a flag. */
 export interface AddRepoRow {
@@ -68,12 +67,6 @@ export interface AddRepoAccessLink {
   title: string;
 }
 
-/** One entry of the account filter. `""` is every account. */
-export interface AddRepoOwner {
-  value: string;
-  label: string;
-}
-
 /**
  * Why the repository list is empty, when it is.
  *
@@ -105,7 +98,7 @@ export interface AddRepoView {
   /** The account the list is narrowed to; `""` is every account. */
   owner: string;
   /** The account filter's entries, "All accounts" first; empty hides it (one account, or none). */
-  owners: AddRepoOwner[];
+  owners: SurfaceOption[];
   /** The listing is in flight. Its own state, because "not yet asked" is not "reaches nothing". */
   loading: boolean;
   /** The repositories to draw, already filtered and ordered. */
@@ -226,8 +219,7 @@ interface AddRepoFlags {
   confirmDisabled: boolean;
 }
 
-interface AddRepoScope
-  extends Record<string, unknown>, Omit<AddRepoView, "rows" | "locations">, AddRepoFlags {
+interface AddRepoScope extends Omit<AddRepoView, "rows" | "locations">, AddRepoFlags {
   setFilter: (value: string) => void;
   setOwner: (value: string) => void;
   select: (fullName: string) => void;
@@ -277,7 +269,7 @@ function derive(view: AddRepoView): Omit<AddRepoView, "rows" | "locations"> & Ad
       ? "loading"
       : rows.length > 0
         ? "listed"
-        : (`empty-${view.emptyState}` as AddRepoFlags["listState"]),
+        : (`empty-${view.emptyState}` as const),
     locations,
     refreshDisabled: view.loading || view.busy,
     rows,
@@ -309,8 +301,12 @@ export function openAddRepoSurface(options: AddRepoSurfaceOptions): AddRepoSurfa
     closed = true;
     options.onClosed();
   };
+  /* 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;
 
-  const scope = reactive({
+  const scope: AddRepoScope = reactive<AddRepoScope>({
     ...derive(options.view),
     closed: finish,
     confirm: () => {
@@ -350,18 +346,20 @@ export function openAddRepoSurface(options: AddRepoSurfaceOptions): AddRepoSurfa
       scope.owner = value;
       options.onOwner(value);
     },
-  }) as AddRepoScope;
+  });
 
   let mounted: SurfaceHandle | null = null;
   const ready = mountSurface("add-repo", scope, slot).then(async (surface) => {
     mounted = surface;
+    // SAFETY: `add-repo.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;
     }
     showModal(element);
@@ -384,7 +382,7 @@ export function openAddRepoSurface(options: AddRepoSurfaceOptions): AddRepoSurfa
       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/ai-chat.ts

@@ -27,15 +27,16 @@
  * @docs studio/ai/chat
  */
 
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { trustedHtml } from "../services/trusted-types";
 import { mountSurface, registerSurface } from "../ui/surface";
 import aiChatDoc from "./ai-chat.json";
-import type { JxElement, JxDocument } from "@jxsuite/schema/types";
+import type { JsonObject, JxElement } from "@jxsuite/schema/types";
 import type { JxScope } from "@jxsuite/runtime/types";
-import type { SurfaceHandle } from "../ui/surface";
+import type { KeyedLabel, SurfaceHandle } from "../ui/surface";
 
-registerSurface("ai-chat", aiChatDoc as unknown as JxDocument);
+registerSurface("ai-chat", aiChatDoc);
 
 /** How close (px) to the bottom of a scroller still counts as "following along". */
 const STICK_THRESHOLD = 48;
@@ -51,7 +52,7 @@ const LOG_STICK_THRESHOLD = 24;
  * rendering of the registry rather than a second place its capabilities are decided
  * (`studio-ui-guidelines.md` §12.5).
  */
-export interface ChatCommandView extends Record<string, unknown> {
+export interface ChatCommandView {
   /** The reconcile key. The command id, because a button is drawn once per bar. */
   key: string;
   /** What `run` is given. */
@@ -68,14 +69,8 @@ export interface ChatCommandView extends Record<string, unknown> {
   disabled: boolean;
 }
 
-/** One answer an `ask_user` card offers as a shortcut. */
-export interface ChatAskOption extends Record<string, unknown> {
-  key: string;
-  label: string;
-}
-
 /** One line an import run has reported. */
-export interface ChatLogLine extends Record<string, unknown> {
+export interface ChatLogLine {
   key: string;
   phase: string;
   message: string;
@@ -88,7 +83,7 @@ export interface ChatLogLine extends Record<string, unknown> {
  * `$switch` chooses on one: a chip that omitted `options` would leave the question case reading an
  * absent path.
  */
-export interface ChatChipView extends Record<string, unknown> {
+export interface ChatChipView {
   /** The tool-call id — the reconcile key. */
   key: string;
   /** The tool's name, for a test and for the `data-tool` attribute. */
@@ -114,7 +109,8 @@ export interface ChatChipView extends Record<string, unknown> {
   hasContext: boolean;
   /** `pending`, `unanswered`, `answered`, `failed` or `none` — which half of the card to draw. */
   askState: string;
-  options: ChatAskOption[];
+  /** The answers an `ask_user` card offers as shortcuts. */
+  options: KeyedLabel[];
   /** What the reader replied, once they have. */
   answer: string;
   /** `run` when this call has an import to report, `none` otherwise. */
@@ -133,7 +129,7 @@ export interface ChatChipView extends Record<string, unknown> {
 }
 
 /** One file a turn changed. */
-export interface ChatChangeView extends Record<string, unknown> {
+export interface ChatChangeView {
   key: string;
   path: string;
   /** The tool that wrote it, or the sentence saying why it did not. */
@@ -143,14 +139,8 @@ export interface ChatChangeView extends Record<string, unknown> {
   disk: boolean;
 }
 
-/** One attached-context chip on a user turn. */
-export interface ChatContextChip extends Record<string, unknown> {
-  key: string;
-  label: string;
-}
-
 /** One line of the transcript. */
-export interface ChatRowView extends Record<string, unknown> {
+export interface ChatRowView {
   /** The message id. The `$map` key, and what `restore` is given. */
   key: string;
   /** `user`, `assistant`, `streaming`, `typing` or `tool-error`. */
@@ -159,7 +149,8 @@ export interface ChatRowView extends Record<string, unknown> {
   body: string;
   /** Sanitized model output for an `assistant` row. Filled into the island, never bound. */
   markdown: string;
-  contextChips: ChatContextChip[];
+  /** The attached-context chips on a user turn. */
+  contextChips: KeyedLabel[];
   hasContextChips: boolean;
   chips: ChatChipView[];
   hasChips: boolean;
@@ -172,7 +163,7 @@ export interface ChatRowView extends Record<string, unknown> {
 }
 
 /** One row of the chat history. */
-export interface ChatSessionView extends Record<string, unknown> {
+export interface ChatSessionView {
   /** The session id — the key, and what a row opens or deletes. */
   key: string;
   title: string;
@@ -181,7 +172,7 @@ export interface ChatSessionView extends Record<string, unknown> {
 }
 
 /** One chip the composer is carrying. */
-export interface ChatComposerChip extends Record<string, unknown> {
+export interface ChatComposerChip {
   /** The chip's kind — one chip per kind, so the kind IS the identity. */
   key: string;
   label: string;
@@ -277,7 +268,7 @@ export interface AiChatSurface {
 }
 
 /** The scope the document reads: the view, the flow's actions, and the scroller's own handler. */
-interface AiChatScope extends Record<string, unknown>, AiChatView, AiChatActions {
+interface AiChatScope extends AiChatView, AiChatActions {
   scrolled: () => void;
 }
 
@@ -353,21 +344,21 @@ export function emptyAiChatView(): AiChatView {
 
 /** The `part` a node's definition carries, or "" for a text node or an unmarked element. */
 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 : "";
 }
 
 /** The `$map` item a node was rendered inside, if it was rendered inside one. */
-function mapItem(state: JxScope | undefined): Record<string, unknown> | null {
-  const map = state?.["$map"] as { item?: unknown } | undefined;
-  const item = map?.item;
-  return item !== null && typeof item === "object" ? (item as Record<string, unknown>) : null;
+function mapItem(state: JxScope | undefined): JsonObject | null {
+  const map = state?.["$map"];
+  const item = isJsonObject(map) ? map["item"] : undefined;
+  return isJsonObject(item) ? item : null;
 }
 
 /** A string field off a `$map` item, or "". */
-function itemString(item: Record<string, unknown> | null, field: string): string {
+function itemString(item: JsonObject | null, field: string): string {
   const value = item?.[field];
-  return typeof value === "string" ? value : "";
+  return isString(value) ? value : "";
 }
 
 /** Keep a scroller pinned to its newest line, unless the reader has scrolled away from it. */
@@ -406,7 +397,7 @@ export function mountAiChatSurface(
   /** The import logs, by chip key. */
   const logs = new Map<string, HTMLElement>();
 
-  const scope = reactive<AiChatScope>({
+  const scope: AiChatScope = reactive<AiChatScope>({
     ...emptyAiChatView(),
     ...actions,
     scrolled: () => {
@@ -416,7 +407,7 @@ export function mountAiChatSurface(
           STICK_THRESHOLD;
       }
     },
-  }) as AiChatScope;
+  });
   project(scope, view);
 
   /**
@@ -451,7 +442,11 @@ export function mountAiChatSurface(
    * value assigned here is a `TrustedHTML`; without one the same assertion has still run.
    */
   function fillIsland(node: HTMLElement, html: string): void {
-    (node as unknown as { innerHTML: unknown }).innerHTML = trustedHtml(html);
+    /* SAFETY: lib.dom declares `innerHTML` as `string`, but the setter's IDL type is
+       `(TrustedHTML or DOMString)`, and `trustedHtml` returns one of exactly those two: the policy's
+       `TrustedHTML`, or the asserted string where the API is absent. Widening the property to what
+       the sink accepts is an upcast of this HTMLElement, so the write reaches the same setter. */
+    (node as { innerHTML: unknown }).innerHTML = trustedHtml(html);
   }
 
   let mounted: SurfaceHandle | null = null;

package/src/surfaces/ai-credentials-form.ts

@@ -29,18 +29,9 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import credentialsDoc from "./ai-credentials-form.json";
-import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle, SurfaceOption } from "../ui/surface";
 
-registerSurface("ai-credentials-form", credentialsDoc as unknown as JxDocument);
-
-/** One row of the listed catalogue, as the combobox draws it. */
-export interface CredentialsModelRow {
-  /** The model id — the row's key, and what a pick writes into the model draft. */
-  value: string;
-  /** What the row reads. */
-  label: string;
-}
+registerSurface("ai-credentials-form", credentialsDoc);
 
 /** What the form says right now. Every field is the flow's, never a state it derives. */
 export interface AiCredentialsView {
@@ -51,7 +42,7 @@ export interface AiCredentialsView {
   modelDraft: string;
   baseUrlDraft: string;
   /** The catalogue the last successful listing returned; empty draws no chevron on the field. */
-  models: CredentialsModelRow[];
+  models: SurfaceOption[];
   /** A listing is in flight: the button says so and refuses a second one. */
   modelsLoading: boolean;
   /** What the fetch button reads — including while it is working, and once a list has landed. */
@@ -88,11 +79,10 @@ interface AiCredentialsFlags {
   /** Whether there is a refusal to draw beside the fetch button. */
   hasError: boolean;
   /** The catalogue as the kit's combobox draws it — the list, never a corpus it matches against. */
-  modelOptions: CredentialsModelRow[];
+  modelOptions: SurfaceOption[];
 }
 
-interface AiCredentialsScope
-  extends Record<string, unknown>, AiCredentialsView, AiCredentialsActions, AiCredentialsFlags {}
+interface AiCredentialsScope extends AiCredentialsView, AiCredentialsActions, AiCredentialsFlags {}
 
 /** The view plus the flags the document renders from. */
 function derive(view: AiCredentialsView): AiCredentialsView & AiCredentialsFlags {
@@ -119,7 +109,7 @@ export function createAiCredentialsSurface(
 ): AiCredentialsSurface {
   const host = document.createElement("div");
   host.style.display = "contents";
-  const scope = reactive({ ...derive(view), ...actions }) as AiCredentialsScope;
+  const scope: AiCredentialsScope = reactive<AiCredentialsScope>({ ...derive(view), ...actions });
 
   /** `null` while a mount is in flight — which is a standing surface, not a missing one. */
   let handle: SurfaceHandle | null = null;

package/src/surfaces/ai-managed-connect.ts

@@ -27,9 +27,8 @@ import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import connectDoc from "./ai-managed-connect.json";
 import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
 
-registerSurface("ai-managed-connect", connectDoc as unknown as JxDocument);
+registerSurface("ai-managed-connect", connectDoc);
 
 /** What the offer says right now. Every field is the flow's wording, never a state it derives. */
 export interface ManagedConnectView {
@@ -63,7 +62,7 @@ interface ManagedConnectFlags {
 }
 
 interface ManagedConnectScope
-  extends Record<string, unknown>, ManagedConnectView, ManagedConnectActions, ManagedConnectFlags {}
+  extends ManagedConnectView, ManagedConnectActions, ManagedConnectFlags {}
 
 /** The view plus the flag the document switches on. */
 function derive(view: ManagedConnectView): ManagedConnectView & ManagedConnectFlags {
@@ -87,7 +86,7 @@ export function createManagedConnectSurface(
 ): ManagedConnectSurface {
   const host = document.createElement("div");
   host.style.display = "contents";
-  const scope = reactive({ ...derive(view), ...actions }) as ManagedConnectScope;
+  const scope: ManagedConnectScope = reactive<ManagedConnectScope>({ ...derive(view), ...actions });
 
   /** `null` while a mount is in flight — which is a standing surface, not a missing one. */
   let handle: SurfaceHandle | null = null;

package/src/surfaces/ai-model-picker.ts

@@ -25,9 +25,8 @@ import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import pickerDoc from "./ai-model-picker.json";
 import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
 
-registerSurface("ai-model-picker", pickerDoc as unknown as JxDocument);
+registerSurface("ai-model-picker", pickerDoc);
 
 /** One row the control offers. Already a label — the flow decides what a row is called. */
 export interface ModelPickerRow {
@@ -79,8 +78,7 @@ interface ModelPickerFlags {
   hasFailure: boolean;
 }
 
-interface ModelPickerScope
-  extends Record<string, unknown>, ModelPickerView, ModelPickerActions, ModelPickerFlags {}
+interface ModelPickerScope extends ModelPickerView, ModelPickerActions, ModelPickerFlags {}
 
 /** The view plus the flag the document switches on. */
 function derive(view: ModelPickerView): ModelPickerView & ModelPickerFlags {
@@ -103,7 +101,7 @@ export function createModelPickerSurface(
 ): ModelPickerSurface {
   const host = document.createElement("div");
   host.style.display = "contents";
-  const scope = reactive({ ...derive(view), ...actions }) as ModelPickerScope;
+  const scope: ModelPickerScope = reactive<ModelPickerScope>({ ...derive(view), ...actions });
 
   /** `null` while a mount is in flight — which is a standing surface, not a missing one. */
   let handle: SurfaceHandle | null = null;

package/src/surfaces/block-action-bar.ts

@@ -29,15 +29,16 @@
  * @docs studio/editing/writing
  */
 
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import blockActionBarDoc from "./block-action-bar.json";
 
 import type { JxScope } from "@jxsuite/runtime/types";
-import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+import type { JxElement } from "@jxsuite/schema/types";
 import { rectOf } from "../utils/geometry";
 
-registerSurface("block-action-bar", blockActionBarDoc as unknown as JxDocument);
+registerSurface("block-action-bar", blockActionBarDoc);
 
 /** One button, already decided: what it is called, what it draws, and why it cannot act. */
 export interface BlockBarTool {
@@ -116,7 +117,7 @@ export interface BlockBarActions {
 }
 
 /** The scope `block-action-bar.json` reads. */
-interface BlockBarScope extends BlockBarView, Record<string, unknown> {
+interface BlockBarScope extends BlockBarView {
   linkValue: string;
   linkExisting: boolean;
   linkApplyLabel: string;
@@ -167,8 +168,8 @@ export function emptyBlockBarView(): BlockBarView {
 
 /** 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 : "";
 }
 
 /**
@@ -180,9 +181,10 @@ function partOf(def: JxElement | string): string {
  * same shape `surfaces/schema-form.ts` and `surfaces/properties-panel.ts` use.
  */
 function commandIdOf(state: JxScope | undefined): string {
-  const item = (state?.["$map"] as { item?: Record<string, unknown> } | undefined)?.item;
-  const id = item?.["id"];
-  return typeof id === "string" ? id : "";
+  const map = state?.["$map"];
+  const item = isJsonObject(map) ? map["item"] : undefined;
+  const id = isJsonObject(item) ? item["id"] : undefined;
+  return isString(id) ? id : "";
 }
 
 /** The bar's mounted surface, and every handle the flow is allowed to reach back through. */
@@ -250,22 +252,29 @@ export function mountBlockActionBar(host: HTMLElement, actions: BlockBarActions)
     linkApplyLabel: "Apply",
     linkExisting: false,
     linkInput: (_scope: JxScope, event: Event) => {
-      const value = (event.target as { value?: unknown } | null)?.value;
-      scope.linkValue = typeof value === "string" ? value : "";
+      const { target } = event;
+      const value = target !== null && "value" in target ? target.value : undefined;
+      scope.linkValue = isString(value) ? value : "";
     },
     linkValue: "",
     linkX: 0,
     linkY: 0,
     openMergeTags: (_scope: JxScope, event: Event) => {
       event.stopPropagation();
+      // SAFETY: Only the merge-tags `jx-action-button`'s `onclick` binds this handler, and during
+      // Dispatch `currentTarget` is the element the listener sits on.
       actions.openMergeTags(event.currentTarget as HTMLElement);
     },
     openOverflow: (_scope: JxScope, event: Event) => {
       event.stopPropagation();
+      // SAFETY: Only the overflow `jx-action-button`'s `onclick` binds this handler, and during
+      // Dispatch `currentTarget` is the element the listener sits on.
       actions.openOverflow(event.currentTarget as HTMLElement);
     },
     openTagMenu: (_scope: JxScope, event: Event) => {
       event.stopPropagation();
+      // SAFETY: Only the tag `jx-action-button`'s `onclick` binds this handler, and during
+      // Dispatch `currentTarget` is the element the listener sits on.
       actions.openTagMenu(event.currentTarget as HTMLElement);
     },
     removeLink: () => {
@@ -274,7 +283,7 @@ export function mountBlockActionBar(host: HTMLElement, actions: BlockBarActions)
     },
     run: (id: string) => actions.run(id),
     selectParent: () => actions.selectParent(),
-  }) as BlockBarScope;
+  });
 
   /* One mount for the life of the window, and no teardown to write. The bar is chrome the app
      never takes down: `dismissBlockActionBar` hides it through `visible`, and its layer slot is
@@ -295,6 +304,8 @@ export function mountBlockActionBar(host: HTMLElement, actions: BlockBarActions)
         return;
       }
       if (part === "link") {
+        // SAFETY: `part: "link"` is the document's `jx-popover`, whose class carries `open` and the
+        // `showPopover({ source })` overload that PopoverElement names.
         linkEl = element as PopoverElement;
         return;
       }

package/src/surfaces/boot-failure.ts

@@ -28,9 +28,8 @@ import { APP_NAME, GIT_COMMIT, VERSION } from "../version";
 import bootFailureDoc from "./boot-failure.json";
 import type { BootRefusal } from "../platforms/default-platform";
 import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
 
-registerSurface("boot-failure", bootFailureDoc as unknown as JxDocument);
+registerSurface("boot-failure", bootFailureDoc);
 
 /** The page the failure happened on — `location`, or a stand-in with the one field read. */
 export interface BootFailurePage {
@@ -49,7 +48,7 @@ export interface BootFailureView {
 }
 
 /** The scope `boot-failure.json` reads. */
-interface BootFailureScope extends Record<string, unknown>, BootFailureView {
+interface BootFailureScope extends BootFailureView {
   /** The last Copy landed on the clipboard; the button says so. */
   copied: boolean;
   reload: () => void;
@@ -135,7 +134,7 @@ export function mountBootFailureSurface(
   page: BootFailurePage = location,
 ): Promise<SurfaceHandle> {
   const view = bootFailureView(refusal, page);
-  const scope = reactive<BootFailureScope>({
+  const scope: BootFailureScope = reactive<BootFailureScope>({
     ...view,
     copied: false,
     async copy() {
@@ -151,6 +150,6 @@ export function mountBootFailureSurface(
     reload() {
       location.reload();
     },
-  }) as BootFailureScope;
+  });
   return mountSurface("boot-failure", scope, host);
 }