@jxsuite/studio 6.1.1 → 8.0.0

package/src/surfaces/commandbar.ts

@@ -7,7 +7,8 @@
  * a command, so what the document is handed is a PROJECTION of the registry rather than a list of
  * buttons: `primary` is `forPlacement("commandbar/primary")` (capped at five by
  * `scripts/check-chrome-budget.ts`), `docks` is the three dock records with the shell's state
- * beside them, `layouts` is the project's own layout record, and the ⬢ Studio menu is
+ * beside them, `workspaces` is the five-workspace switcher with `shell.workspace` selected, the ⚙
+ * gear is the `settings/menu` placement, and the ⬢ Studio menu is
  * `forPlacement("commandbar/overflow")` opened on the `menu` surface. With no project open the same
  * document renders; the records' own `when` clauses empty it (§13.1: enablement is a predicate with
  * a sentence, never a second template).
@@ -24,22 +25,23 @@
  *   is the platform's.
  *
  * **Retired, with a name, a chord and a residue** (`studio-ui-guidelines.md` §12.2): Open Project +
- * New Project + recents → the pill and `Project: Open Recent…`; `Manage` → `File: Browse Library`;
- * `Publish` → the `Publish:` family; `Sync Project` → Source Control. The five-mode switcher lives
- * in the pane context bar and is reachable as `View: Set Canvas Mode` in the palette.
+ * New Project + recents → the pill and `Project: Open Recent…`; `Manage` → the Content workspace
+ * (`view.setWorkspace { workspace: "content" }`, ⌘2); `Publish` → the `Publish:` family; `Sync
+ * Project` → Source Control. The five-mode switcher lives in the pane context bar and is reachable
+ * as `View: Set Canvas Mode` in the palette.
  *
  * @docs studio/interface
  */
 
 import { presenceProjection } from "../collab/presence-chips";
 import { effect, effectScope, reactive } from "../reactivity";
-import { activeTab } from "../workspace/workspace";
+import { activeTab, workspace } from "../workspace/workspace";
 import { primarySelection } from "../tabs/selection";
+import { stylebookTarget } from "../style/stylebook-target";
 import { shell } from "../shell";
 import { openQuickSearch } from "../panels/quick-search";
-import { showPromptDialog } from "../ui/layers";
 import { getPlatform, hasPlatform } from "../platform";
-import { getPreviewNavigateHandler } from "../canvas/preview-navigate";
+import { openUrlExternally } from "../canvas/preview-navigate";
 import { armPreviewOverlay, flushPreviewOverlay } from "../preview/preview-overlay";
 import { documentUrlPattern, dynamicRouteParams } from "../page-params";
 import { getNodeAtPath, nodeLabel, projectState } from "../store";
@@ -49,6 +51,14 @@ import { notify } from "../services/notify";
 import { mountSurface, registerSurface } from "../ui/surface";
 import { rectOf } from "../utils/geometry";
 import { openMenu } from "./menu";
+import {
+  dismissSettingsMenu,
+  isSettingsMenuOpen,
+  openSettingsMenu,
+  SETTINGS_MENU_PLACEMENT,
+} from "../panels/settings-menu";
+import { WORKSPACES } from "../workspace/workspace-ids";
+import type { WorkspaceId } from "../workspace/workspace-ids";
 import commandbarDoc from "./commandbar.json";
 import type { PresenceProjection } from "../collab/presence-chips";
 import type { MenuHandle, MenuRowProjection } from "./menu";
@@ -57,9 +67,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.
@@ -122,12 +131,22 @@ export interface DockProjection {
   disabled: boolean;
 }
 
-/** One layout tab. */
-export interface LayoutTabProjection {
-  id: string;
-  name: string;
-  active: boolean;
+/** One workspace tab. */
+export interface WorkspaceTabProjection {
+  id: WorkspaceId;
   title: string;
+  icon: string;
+  /** The tab's tooltip: its title and chord, plus what its badge counts. */
+  tooltip: string;
+  /** The count drawn beside the title; empty for none, which hides the badge. */
+  badge: string;
+  /**
+   * What the badge counts, in words, as the tab's `aria-description`; empty for none. The badge is
+   * decorative, so this is how the count reaches a screen reader: the tab's NAME stays its title,
+   * which is what the label draws.
+   */
+  description: string;
+  hasBadge: boolean;
 }
 
 /** One segment of the address bar. */
@@ -146,12 +165,20 @@ 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;
-  layoutsVisible: boolean;
-  layouts: LayoutTabProjection[];
+  workspacesVisible: boolean;
+  workspaces: WorkspaceTabProjection[];
+  /** The selected workspace tab's value: `shell.workspace`. */
+  workspace: string;
+  /** The quick-publish chevron beside the Publish tab: `publish.quick`, drawn when registered. */
+  quickVisible: boolean;
+  quickDisabled: boolean;
+  quickTooltip: string;
+  settingsVisible: boolean;
+  settingsOpen: boolean;
   segments: SegmentProjection[];
   chord: string;
   hasChord: boolean;
@@ -162,9 +189,8 @@ interface CommandBarScope extends Record<string, unknown> {
   run: (id: string) => void;
   openSegment: (key: SegmentProjection["key"]) => void;
   openPicker: () => void;
-  setLayout: (id: string) => void;
-  renameLayout: (id: string) => void;
-  saveLayout: () => void;
+  setWorkspace: (id: string) => void;
+  openSettings: (anchor: EventTarget | null) => void;
   openStudioMenu: (opener: HTMLElement) => void;
   windowControl: (action: keyof WindowControls) => void;
 }
@@ -194,6 +220,9 @@ const DOCKS = [
   { dock: "bottom", icon: "rows", id: "view.toggleBottomDock", mirror: false },
 ] as const;
 
+/** The record the chevron beside the Publish tab renders. */
+const QUICK_PUBLISH = "publish.quick";
+
 /** The palette mode each segment of the address opens. */
 const SEGMENT_MODES = { document: "files", project: "projects", selection: "nodes" } as const;
 
@@ -262,7 +291,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(", ");
@@ -280,22 +309,6 @@ export function openInBrowserTarget(tab: Tab | null): BrowserTarget {
   return { path: route === "/" ? "/" : trailingSlash === "always" ? `${route}/` : route };
 }
 
-/**
- * Hand a URL to the user's real browser.
- *
- * Reuses the seam the desktop launchers already register for Preview link clicks
- * (`canvas/preview-navigate.ts`), which routes through the OS rather than navigating a webview with
- * no address bar; the browser build falls back to a new tab.
- */
-function openUrlExternally(url: string) {
-  const override = getPreviewNavigateHandler();
-  if (override) {
-    override(url);
-    return;
-  }
-  window.open(url, "_blank", "noopener,noreferrer");
-}
-
 /**
  * Run `View: Open in Browser`, reporting the blocking reason when there is one.
  *
@@ -482,8 +495,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. */
@@ -497,11 +510,21 @@ export function documentSegmentLabel(tab: Tab | null): string {
   return root && trimmed.startsWith(`${root}/`) ? trimmed.slice(root.length + 1) : trimmed;
 }
 
-/** The selection's label — the Outline's own `nodeLabel`, so the two never disagree. */
+/**
+ * The selection's label — the Outline's own `nodeLabel`, so the two never disagree.
+ *
+ * In the Styles workspace's Elements view the selection is a TAG (`stylebookTarget`), and the
+ * segment names it the way the status bar and the Style body do: `project.json › h1`, not the root
+ * node of the catalogue's document.
+ */
 export function selectionSegmentLabel(tab: Tab | null): string {
   if (shell.layoutSelection) {
     return "layout";
   }
+  const tag = stylebookTarget(tab);
+  if (tag) {
+    return tag.replaceAll(" ", " › ");
+  }
   const paths = tab?.session.selection ?? [];
   const selection = primarySelection(paths);
   if (!tab || !selection) {
@@ -515,30 +538,6 @@ export function selectionSegmentLabel(tab: Tab | null): string {
   return nodeLabel(getNodeAtPath(tab.doc.document, selection));
 }
 
-/** Ask for a name, then run the command. Exported for the same reason `runOpenInBrowser` is. */
-export async function saveLayoutPrompt(registry: CommandRegistry): Promise<void> {
-  const name = await showPromptDialog("Save layout", {
-    confirmLabel: "Save",
-    message: "Remembers this project's Navigator panel, dock widths and Inspector tab.",
-    placeholder: "Layout name",
-  });
-  if (name) {
-    await runReported(registry, "view.saveLayout", { name }, "Command Bar");
-  }
-}
-
-/** The double-click gesture, routed through the command so the rename has one implementation. */
-export async function renameLayoutPrompt(
-  registry: CommandRegistry,
-  layout: string,
-  current: string,
-): Promise<void> {
-  const name = await showPromptDialog("Rename layout", { confirmLabel: "Rename", value: current });
-  if (name) {
-    await runReported(registry, "view.renameLayout", { layout, name }, "Command Bar");
-  }
-}
-
 interface WindowControls {
   minimize: () => void;
   maximize: () => void;
@@ -546,11 +545,17 @@ 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 adapters that add
+     it is the desktop launcher's (`chromium/platform.ts` under the Electron shell), whose objects carry 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 ───────
+// ─── The Command Center pill, the workspace tabs and the docks, projected ────
 
 /**
  * `◈ project › document › selection`: four facts about where you are, in non-collapsible chrome
@@ -579,25 +584,35 @@ function projectSegments(tab: Tab | null): SegmentProjection[] {
 }
 
 /**
- * `Write · Design · Build · Ship · +` — named arrangements, as plain-text tabs.
+ * `Design · Content · Media · Styles · Publish`: the five workspaces, as a tablist.
  *
- * Each tab RUNS `view.setLayout`, so the click, the palette row and an agent all take the same
- * path; double-clicking one renames it, and `+` saves whatever is on screen now. **A layout
- * reconfigures; it never removes**: every panel stays on the rail, on its chord and in the palette
- * after any layout is applied.
+ * Each tab RUNS `view.setWorkspace`, so the click, ⌘1–5, the palette row and a script all take the
+ * same path, and the selected tab is `shell.workspace` rather than a second record of it. Publish
+ * carries the count of uncommitted changes, which is what the workspace is there to deal with; at
+ * zero the badge is not drawn, because "0" is a number a reader has to read to learn nothing.
  */
-function projectLayouts(registry: CommandRegistry | null): LayoutTabProjection[] {
+function projectWorkspaces(registry: CommandRegistry | null): WorkspaceTabProjection[] {
   // `get` first: a registry that has not been handed the shell's records yet (the skeleton the bar
   // Paints before the bootstrap composes them) has no verb to ask about.
-  if (!registry?.get("view.setLayout") || !registry.isEnabled("view.setLayout")) {
+  if (!registry?.get("view.setWorkspace") || !registry.isEnabled("view.setWorkspace")) {
     return [];
   }
-  return shell.layouts.map((preset) => ({
-    active: preset.id === shell.layout,
-    id: preset.id,
-    name: preset.name,
-    title: `${preset.name} layout — double-click to rename`,
-  }));
+  const dirty = shell.git.status?.files.length ?? 0;
+  return WORKSPACES.map((entry) => {
+    const badge = entry.id === "publish" && dirty > 0 ? String(dirty) : "";
+    const chord = registry.keymap.formatBinding(`workspace.focus.${entry.id}`);
+    const named = chord ? `${entry.title} (${chord})` : entry.title;
+    const description = badge ? `${badge} unpublished ${dirty === 1 ? "change" : "changes"}` : "";
+    return {
+      badge,
+      description,
+      hasBadge: badge !== "",
+      icon: entry.icon,
+      id: entry.id,
+      title: entry.title,
+      tooltip: description ? `${named}, ${description}` : named,
+    };
+  });
 }
 
 /** The primary verb cluster: exactly what declared `commandbar/primary`, in the registry's order. */
@@ -729,8 +744,6 @@ function state(): CommandBarScope {
     csd: "none",
     docks: [],
     hasChord: false,
-    layouts: [],
-    layoutsVisible: false,
     menuOpen: false,
     menuVisible: false,
     openPicker: () => {
@@ -739,37 +752,47 @@ function state(): CommandBarScope {
     openSegment: (key) => {
       openQuickSearch(SEGMENT_MODES[key]);
     },
+    openSettings: (anchor: EventTarget | null) => {
+      if (!(anchor instanceof HTMLElement)) {
+        return;
+      }
+      openSettingsMenu(anchor, {
+        rerender: () => {
+          if (_state) {
+            _state.settingsOpen = isSettingsMenuOpen();
+          }
+        },
+      });
+    },
     openStudioMenu,
     presence: NO_PRESENCE,
     presenceVisible: false,
     primary: [],
-    renameLayout: (id) => {
-      const registry = activeRegistry();
-      const preset = shell.layouts.find((layout) => layout.id === id);
-      if (registry && preset) {
-        void renameLayoutPrompt(registry, id, preset.name);
-      }
-    },
     run: (id) => {
       const registry = activeRegistry();
       if (registry?.isEnabled(id)) {
         void runReported(registry, id, undefined, "Command Bar");
       }
     },
-    saveLayout: () => {
-      const registry = activeRegistry();
-      if (registry) {
-        void saveLayoutPrompt(registry);
-      }
-    },
     segments: [],
-    setLayout: (id) => {
-      void runActiveReported("view.setLayout", { layout: id }, "Command Bar");
+    /* Run from each tab's CLICK, not from the strip's `change`: `jx-tabs` dispatches no change for
+       the tab already selected, and activating the selected workspace again is how an author gets
+       its home back after closing it. Enter and Space click the tab too (manual activation). */
+    setWorkspace: (id) => {
+      void runActiveReported("view.setWorkspace", { workspace: id }, "Command Bar");
     },
+    settingsOpen: false,
+    settingsVisible: false,
     windowControl: (action) => {
       windowControls()?.[action]();
     },
-  }) as CommandBarScope;
+    quickDisabled: true,
+    quickTooltip: "",
+    quickVisible: false,
+    workspace: "",
+    workspaces: [],
+    workspacesVisible: false,
+  });
   return _state;
 }
 
@@ -784,8 +807,20 @@ function project(): void {
   const controls = windowControls();
   scope.csd = controls ? (isMacPlatform() ? "mac" : "other") : "none";
   scope.menuVisible = registry !== null;
-  scope.layouts = projectLayouts(registry);
-  scope.layoutsVisible = scope.layouts.length > 0;
+  scope.workspaces = projectWorkspaces(registry);
+  scope.workspacesVisible = scope.workspaces.length > 0;
+  scope.workspace = shell.workspace;
+  /* The chevron is a rendering of `publish.quick`, beside the tablist that ends on Publish
+     (studio.md §22.2): drawn only with the tabs and only while the registry shows the record, and
+     disabled with its own reason rather than hidden when the project is not a repository. */
+  const quick = QUICK_PUBLISH;
+  scope.quickVisible =
+    scope.workspacesVisible && registry?.get(quick) !== undefined && registry.isVisible(quick);
+  scope.quickDisabled = !scope.quickVisible || !registry?.isEnabled(quick);
+  scope.quickTooltip = registry && scope.quickVisible ? commandTooltip(registry, quick) : "";
+  scope.settingsVisible =
+    registry !== null && registry.forPlacement(SETTINGS_MENU_PLACEMENT).length > 0;
+  scope.settingsOpen = isSettingsMenuOpen();
   scope.segments = projectSegments(tab);
   scope.chord = registry?.keymap.formatBinding("palette.open") ?? "";
   scope.hasChord = scope.chord !== "";
@@ -812,7 +847,7 @@ export function mount(rootEl: HTMLElement, _ctx: ToolbarCtx = {}): void {
   unmount();
   _rootEl = rootEl;
   if (windowControls()) {
-    rootEl.classList.add("electrobun-webkit-app-region-drag");
+    rootEl.classList.add("app-region-drag");
   }
   _scope = effectScope();
   _scope.run(() => {
@@ -825,10 +860,14 @@ export function mount(rootEl: HTMLElement, _ctx: ToolbarCtx = {}): void {
       void shell.docks.bottom.collapsed;
       void shell.git.status;
       void shell.layoutSelection;
-      // The layout tabs are a rendering of the project's own record, so the band repaints when a
-      // Layout is saved, renamed or deleted from anywhere.
-      void shell.layout;
-      void shell.layouts;
+      // The pill's selection segment names a Styles specimen's tag (`selectionSegmentLabel`).
+      void shell.stylebook.selection;
+      // The workspace tabs follow the shell, so a switch made by a chord, a script or a tab's
+      // Activation repaints the selected tab.
+      void shell.workspace;
+      // The project opening is what makes the workspace tabs (and the pill's project name) live:
+      // `projectState` is not reactive, and the reactive root it is opened beside is.
+      void workspace.projectRoot;
       // The registry itself is reactive state: it is composed AFTER this mount runs, and reading it
       // Here is what repaints the band from a skeleton into the real bar.
       void activeRegistry();
@@ -861,6 +900,7 @@ export function mount(rootEl: HTMLElement, _ctx: ToolbarCtx = {}): void {
 
 export function unmount(): void {
   _menu?.close();
+  dismissSettingsMenu();
   _scope?.stop();
   _scope = null;
   const pending = _mount;

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 {