@jxsuite/studio 6.1.0 → 6.1.2

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

package/src/surfaces/bottom-dock.ts

@@ -15,23 +15,14 @@
  * @docs studio/interface
  */
 
+import { isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import bottomDockDoc from "./bottom-dock.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("bottom-dock", bottomDockDoc as unknown as JxDocument);
-
-/** One tab of the strip, as the document draws it. */
-export interface BottomTabView {
-  /** The panel id — the row's identity, the strip's `selected` value, and `data-tab`. */
-  key: string;
-  /** The record's title with its badge already appended ("Problems 2"). */
-  label: string;
-  /** The tab element's own id, which the one panel names as its `aria-labelledby`. */
-  tabId: string;
-}
+registerSurface("bottom-dock", bottomDockDoc);
 
 /** What the dock says right now. */
 export interface BottomDockValues {
@@ -41,7 +32,7 @@ export interface BottomDockValues {
   tabId: string;
   /** `dock.bottom/panel:<id>`, or empty when no tab is showing and the body has no identity. */
   bodyRegion: string;
-  tabs: BottomTabView[];
+  tabs: SurfaceTab[];
 }
 
 export interface BottomDockActions {
@@ -62,7 +53,7 @@ export interface BottomDockHandle {
   dispose: () => void;
 }
 
-interface BottomDockScope extends Record<string, unknown>, BottomDockValues, BottomDockActions {}
+interface BottomDockScope extends BottomDockValues, BottomDockActions {}
 
 function project(scope: BottomDockScope, values: BottomDockValues): void {
   scope.tab = values.tab;
@@ -73,8 +64,8 @@ function project(scope: BottomDockScope, values: BottomDockValues): void {
 
 /** 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 : "";
 }
 
 /**
@@ -90,7 +81,7 @@ export function mountBottomDockSurface(
   actions: BottomDockActions,
   options: BottomDockOptions,
 ): BottomDockHandle {
-  const scope = reactive<BottomDockScope>({ ...values, ...actions }) as BottomDockScope;
+  const scope: BottomDockScope = reactive<BottomDockScope>({ ...values, ...actions });
 
   container.textContent = "";
   // @ts-expect-error -- _$litPart$ is lit's private render-part marker, not in the DOM types

package/src/surfaces/canvas-stage.ts

@@ -29,14 +29,15 @@
  * @docs studio/interface/canvas
  */
 
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import canvasStageDoc from "./canvas-stage.json";
-import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+import type { JxElement } from "@jxsuite/schema/types";
 import type { JxScope } from "@jxsuite/runtime/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("canvas-stage", canvasStageDoc as unknown as JxDocument);
+registerSurface("canvas-stage", canvasStageDoc);
 
 /** One artboard, as the document reads it. Every field is already a string or a boolean. */
 export interface CanvasStagePanelItem {
@@ -104,7 +105,7 @@ export interface CanvasStageHandle {
 }
 
 /** The scope the document reads: {@link CanvasStageView} plus the one control it draws. */
-interface CanvasStageScope extends Record<string, unknown>, CanvasStageView {
+interface CanvasStageScope extends CanvasStageView {
   pickPanel: (key: string) => void;
 }
 
@@ -117,16 +118,16 @@ interface CanvasStageScope extends Record<string, unknown>, CanvasStageView {
  * `data-side` tells the two width handles apart — the one part the document draws twice.
  */
 function attrOf(def: JxElement | string, name: string): string {
-  const value = typeof def === "string" ? undefined : def.attributes?.[name];
-  return typeof value === "string" ? value : "";
+  const value = isString(def) ? undefined : def.attributes?.[name];
+  return isString(value) ? value : "";
 }
 
 /** The `key` of the `$map` item a node was rendered inside, or "". */
 function itemKey(state: JxScope | undefined): string {
-  const item = (state?.["$map"] as { item?: unknown } | undefined)?.item;
-  const key =
-    item !== null && typeof item === "object" ? (item as Record<string, unknown>).key : "";
-  return typeof key === "string" ? key : "";
+  const map = state?.["$map"];
+  const item = isJsonObject(map) ? map["item"] : undefined;
+  const key = isJsonObject(item) ? item["key"] : "";
+  return isString(key) ? key : "";
 }
 
 /** The three parts an artboard is made of; everything else is a singleton host. */
@@ -180,7 +181,7 @@ export function mountCanvasStage(
      "the iframe survives" means — so the record a fresh render builds is filled from here rather
      than from a callback that will not fire again. */
   const boards = new Map<string, Map<string, HTMLElement>>();
-  const scope = reactive<CanvasStageScope>({
+  const scope: CanvasStageScope = reactive<CanvasStageScope>({
     frame: "boards",
     framePart: "panzoom",
     frameVars: "",
@@ -190,7 +191,7 @@ export function mountCanvasStage(
     lead: "none",
     panels: [],
     pickPanel: actions.pickPanel,
-  }) as CanvasStageScope;
+  });
   project(scope, view);
 
   let mounted: SurfaceHandle | null = null;

package/src/surfaces/cf-account-picker.ts

@@ -25,25 +25,19 @@
 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 pickerDoc from "./cf-account-picker.json";
 import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
+import type { CfAccount } from "../publish/pages-service";
 
-registerSurface("cf-account-picker", pickerDoc as unknown as JxDocument);
-
-/** One account the grant reaches, as the list draws it. */
-export interface CfAccountPickerRow {
-  id: string;
-  name: string;
-}
+registerSurface("cf-account-picker", pickerDoc);
 
 /** What the flow knows. Every one of these may change while the dialog is up. */
 export interface CfAccountPickerView {
   /** The listing is in flight. Its own state, because "not yet asked" is not "reaches nothing". */
   loading: boolean;
-  accounts: CfAccountPickerRow[];
+  accounts: CfAccount[];
   /** The last refusal — a listing that failed, or an account the broker would not accept. */
   failure: string;
   /** The id being committed, so its own row can say so rather than the whole list going grey. */
@@ -88,15 +82,14 @@ interface CfAccountPickerFlags {
 }
 
 /** One row, as the document reads it: what it says, and whether it may be pressed. */
-interface CfAccountPickerScopeRow extends CfAccountPickerRow {
+interface CfAccountPickerScopeRow extends CfAccount {
   /** This row's own button text — "Selecting…" while it is the one being committed. */
   label: string;
   /** Every row is disabled while any commit is in flight: one answer at a time. */
   busy: boolean;
 }
 
-interface CfAccountPickerScope
-  extends Record<string, unknown>, CfAccountPickerView, CfAccountPickerFlags {
+interface CfAccountPickerScope extends CfAccountPickerView, CfAccountPickerFlags {
   choose: (id: string) => void;
   retry: () => void;
   closed: () => void;
@@ -150,8 +143,12 @@ export function openCfAccountPickerSurface(options: CfAccountPickerOptions): CfA
     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: CfAccountPickerScope = reactive<CfAccountPickerScope>({
     ...derive({ accounts: [], choosing: "", failure: "", loading: true }),
     choose: (id: string) => {
       options.onChoose(id);
@@ -160,18 +157,20 @@ export function openCfAccountPickerSurface(options: CfAccountPickerOptions): CfA
     retry: () => {
       options.onRetry();
     },
-  }) as CfAccountPickerScope;
+  });
 
   let mounted: SurfaceHandle | null = null;
   const ready = mountSurface("cf-account-picker", scope, slot).then(async (surface) => {
     mounted = surface;
+    /* SAFETY: `cf-account-picker.json`'s root definition is a `jx-dialog` element, 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);
@@ -186,7 +185,7 @@ export function openCfAccountPickerSurface(options: CfAccountPickerOptions): CfA
       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/commandbar.ts

@@ -57,9 +57,8 @@ import type { Tab } from "../tabs/tab";
 import type { SiteBuildResult, SitePreviewResult, StudioPlatform } from "../types";
 import type { CommandRegistry } from "../commands/registry";
 import type { EffectScope } from "@vue/reactivity";
-import type { JxDocument } from "@jxsuite/schema/types";
 
-registerSurface("commandbar", commandbarDoc as unknown as JxDocument);
+registerSurface("commandbar", commandbarDoc);
 
 /**
  * What the Command Bar is handed at mount.
@@ -146,7 +145,7 @@ export interface SegmentProjection {
 export type WindowControlLayout = "none" | "mac" | "other";
 
 /** The document's scope: the projections, and the host functions its handlers `call`. */
-interface CommandBarScope extends Record<string, unknown> {
+interface CommandBarScope {
   csd: WindowControlLayout;
   menuVisible: boolean;
   menuOpen: boolean;
@@ -262,7 +261,7 @@ export function openInBrowserTarget(tab: Tab | null): BrowserTarget {
   }
   const params = dynamicRouteParams(documentPath);
   if (params.length > 0) {
-    const chosen = (tab?.session.ui.previewParams ?? {}) as Record<string, string>;
+    const chosen: Record<string, string> = tab?.session.ui.previewParams ?? {};
     const missing = params.filter((name) => !chosen[name]);
     if (missing.length > 0) {
       const names = missing.map((name) => `:${name}`).join(", ");
@@ -482,8 +481,8 @@ const BUILD_SITE = "project.buildSite";
 const OPEN_IN_BROWSER = "view.openInBrowser";
 
 /** The sentence in an unknown thrown value. */
-function errorText(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
+function errorText(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause);
 }
 
 /** The document's label: its path without the project root, which is already segment one. */
@@ -546,8 +545,14 @@ interface WindowControls {
 }
 
 function windowControls(): WindowControls | undefined {
-  return (globalThis as unknown as { __jxPlatform?: { windowControls?: WindowControls } })
-    .__jxPlatform?.windowControls;
+  const platform = globalThis.__jxPlatform;
+  if (platform == null || !("windowControls" in platform)) {
+    return undefined;
+  }
+  /* SAFETY: the PAL interface deliberately leaves `windowControls` undeclared; the one adapter that
+     adds it is the desktop launcher's (`packages/desktop/src/platform.ts`), whose object carries the
+     `close`, `maximize` and `minimize` functions this bar calls. */
+  return platform.windowControls as WindowControls | undefined;
 }
 
 // ─── The Command Center pill, the layout tabs and the docks, projected ───────
@@ -769,7 +774,7 @@ function state(): CommandBarScope {
     windowControl: (action) => {
       windowControls()?.[action]();
     },
-  }) as CommandBarScope;
+  });
   return _state;
 }
 

package/src/surfaces/convert-repeater.ts

@@ -25,14 +25,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 { selectValue } from "@jxsuite/ui/behaviors/textfield";
 import { whenReady } from "./dialog";
 import convertRepeaterDoc from "./convert-repeater.json";
-import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle, SurfaceOption } from "../ui/surface";
 
-registerSurface("convert-repeater", convertRepeaterDoc as unknown as JxDocument);
+registerSurface("convert-repeater", convertRepeaterDoc);
 
 /**
  * The items-source row that is not a definition: pick it and the dialog asks for a name instead.
@@ -42,12 +41,6 @@ registerSurface("convert-repeater", convertRepeaterDoc as unknown as JxDocument)
  */
 export const CREATE_NEW_SOURCE = "__new__";
 
-/** One row of either picker. */
-export interface ConvertRepeaterOption {
-  value: string;
-  label: string;
-}
-
 /** What the flow knows. Every one of these may change while the dialog is up. */
 export interface ConvertRepeaterView {
   /** State definitions that hold an array, in the order they were found. */
@@ -97,9 +90,9 @@ export interface ConvertRepeaterSurfaceHandle {
 /** What the document discriminates on, and the rows it maps. Derived, never handed in. */
 interface ConvertRepeaterFlags {
   /** The source picker's rows: every array definition, then `Create new…`. */
-  sourceOptions: ConvertRepeaterOption[];
+  sourceOptions: SurfaceOption[];
   /** The filter and sort pickers' rows: `None`, then every function definition. */
-  functionOptions: ConvertRepeaterOption[];
+  functionOptions: SurfaceOption[];
   /** The chosen source is the sentinel, so the name field is drawn. */
   creating: boolean;
   /** There is at least one function to offer, so the two optional rows are drawn. */
@@ -108,8 +101,7 @@ interface ConvertRepeaterFlags {
   invalid: boolean;
 }
 
-interface ConvertRepeaterScope
-  extends Record<string, unknown>, ConvertRepeaterView, ConvertRepeaterFlags {
+interface ConvertRepeaterScope extends ConvertRepeaterView, ConvertRepeaterFlags {
   pickSource: (value: string) => void;
   setName: (value: string) => void;
   pickFilter: (value: string) => void;
@@ -163,8 +155,12 @@ export function openConvertRepeaterSurface(
     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: ConvertRepeaterScope = reactive<ConvertRepeaterScope>({
     ...derive(options.view),
     closed: finish,
     confirm: () => {
@@ -191,7 +187,7 @@ export function openConvertRepeaterSurface(
       scope.newName = value;
       options.onName(value);
     },
-  }) as ConvertRepeaterScope;
+  });
 
   let mounted: SurfaceHandle | null = null;
 
@@ -218,13 +214,15 @@ export function openConvertRepeaterSurface(
 
   const ready = mountSurface("convert-repeater", scope, slot).then(async (surface) => {
     mounted = surface;
+    /* SAFETY: `convert-repeater.json`'s root definition is a `jx-dialog` element, 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);
@@ -243,7 +241,7 @@ export function openConvertRepeaterSurface(
       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/data-actions.ts

@@ -18,10 +18,9 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import dataActionsDoc from "./data-actions.json";
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("data-actions", dataActionsDoc as unknown as JxDocument);
+registerSurface("data-actions", dataActionsDoc);
 
 /** Everything the row draws. */
 export interface DataActionsView {
@@ -52,7 +51,7 @@ export interface DataActionsSurfaceHandle {
   dispose: () => void;
 }
 
-interface DataActionsScope extends Record<string, unknown>, DataActionsView, DataActionsCallbacks {}
+interface DataActionsScope extends DataActionsView, DataActionsCallbacks {}
 
 /** Write a projection into the scope. */
 function project(scope: DataActionsScope, view: DataActionsView): void {
@@ -78,7 +77,7 @@ export function mountDataActionsSurface(
   view: DataActionsView,
   actions: DataActionsCallbacks,
 ): DataActionsSurfaceHandle {
-  const scope = reactive<DataActionsScope>({
+  const scope: DataActionsScope = reactive<DataActionsScope>({
     openGrid: actions.openGrid,
     push: actions.push,
     resultOk: "false",
@@ -89,18 +88,21 @@ export function mountDataActionsSurface(
     testDisabled: false,
     testLabel: "Test Connection",
     testState: "hidden",
-  }) as DataActionsScope;
+  });
   project(scope, view);
 
   let mounted: SurfaceHandle | null = null;
   let disposed = false;
   const ready = mountSurface("data-actions", scope, host).then((surface) => {
+    /* SAFETY: `data-actions.json`'s root definition is a `div` element, 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 {