@jxsuite/studio 6.1.0 → 6.1.2

package/src/surfaces/inspector-dock.ts

@@ -23,14 +23,15 @@
  * @docs studio/interface
  */
 
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import inspectorDockDoc from "./inspector-dock.json";
-import type { JxDocument, JxElement } 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";
 
-registerSurface("inspector-dock", inspectorDockDoc as unknown as JxDocument);
+registerSurface("inspector-dock", inspectorDockDoc);
 
 /** One tab of the dock, as the document draws it. Every field is a value. */
 export interface InspectorTabView {
@@ -81,7 +82,7 @@ export interface InspectorDockHandle {
 }
 
 /** The scope the document reads. */
-interface InspectorDockScope extends Record<string, unknown>, InspectorDockValues {
+interface InspectorDockScope extends InspectorDockValues {
   selectTab: (id: string) => void;
 }
 
@@ -95,15 +96,15 @@ function project(scope: InspectorDockScope, values: InspectorDockValues): 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 : "";
 }
 
 /** 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;
 }
 
 /**
@@ -119,10 +120,10 @@ export function mountInspectorDock(
   actions: InspectorDockActions,
   options: InspectorDockOptions,
 ): InspectorDockHandle {
-  const scope = reactive<InspectorDockScope>({
+  const scope: InspectorDockScope = reactive<InspectorDockScope>({
     ...values,
     selectTab: actions.selectTab,
-  }) as InspectorDockScope;
+  });
 
   container.textContent = "";
   // @ts-expect-error -- _$litPart$ is lit's private render-part marker, not in the DOM types
@@ -136,7 +137,7 @@ export function mountInspectorDock(
         return;
       }
       const key = mapItem(state)?.["key"];
-      if (typeof key === "string" && key !== "") {
+      if (isString(key) && key !== "") {
         options.onBody(key, element);
       }
     },

package/src/surfaces/jump-bar.ts

@@ -23,10 +23,9 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import jumpBarDoc from "./jump-bar.json";
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("jump-bar", jumpBarDoc as unknown as JxDocument);
+registerSurface("jump-bar", jumpBarDoc);
 
 /**
  * One step of the address, as the document reads it.
@@ -35,7 +34,7 @@ registerSurface("jump-bar", jumpBarDoc as unknown as JxDocument);
  * and a `$switch` chooses on one: a step that omitted `title` would leave the readout case reading
  * an absent path.
  */
-export interface ProjectedStep extends Record<string, unknown> {
+export interface ProjectedStep {
   /** Unique within one bar: the repeater's key, and the argument `run` and `choose` receive. */
   key: string;
   /** `project` | `file` | `editor` | `node` — stamped so a test names a step without its text. */
@@ -73,7 +72,7 @@ export interface JumpBarSurface {
 }
 
 /** The scope `jump-bar.json` reads. */
-interface JumpBarScope extends Record<string, unknown>, JumpBarActions {
+interface JumpBarScope extends JumpBarActions {
   region: string;
   segments: ProjectedStep[];
   empty: boolean;
@@ -95,12 +94,12 @@ export function mountJumpBarSurface(
   region: string,
   actions: JumpBarActions,
 ): JumpBarSurface {
-  const scope = reactive<JumpBarScope>({
+  const scope: JumpBarScope = reactive<JumpBarScope>({
     ...actions,
     empty: true,
     region,
     segments: [],
-  }) as JumpBarScope;
+  });
 
   host.replaceChildren();
   let mounted: SurfaceHandle | null = null;

package/src/surfaces/jxsuite-update.ts

@@ -24,13 +24,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 jxsuiteUpdateDoc from "./jxsuite-update.json";
-import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
+import type { DialogLayerHandle, SurfaceHandle } from "../ui/surface";
 
-registerSurface("jxsuite-update", jxsuiteUpdateDoc as unknown as JxDocument);
+registerSurface("jxsuite-update", jxsuiteUpdateDoc);
 
 /** One package the offer would move. Every field is already the string the row prints. */
 export interface JxsuiteUpdateRow {
@@ -55,16 +54,7 @@ export interface JxsuiteUpdateSurfaceOptions {
   onClosed: () => void;
 }
 
-export interface JxsuiteUpdateSurfaceHandle {
-  /** The slot in the dialog layer that carries the region. */
-  host: HTMLElement;
-  /** Resolves with the `jx-dialog` element once it has rendered and been opened. */
-  ready: Promise<HTMLElement>;
-  /** Close the dialog (the platform restores focus) and dispose the document. Idempotent. */
-  close: () => void;
-}
-
-interface JxsuiteUpdateScope extends Record<string, unknown> {
+interface JxsuiteUpdateScope {
   packages: JxsuiteUpdateRow[];
   confirm: () => void;
   cancel: () => void;
@@ -72,9 +62,7 @@ interface JxsuiteUpdateScope extends Record<string, unknown> {
 }
 
 /** Open the offer. The handle's `ready` resolves once the dialog is showing. */
-export function openJxsuiteUpdateSurface(
-  options: JxsuiteUpdateSurfaceOptions,
-): JxsuiteUpdateSurfaceHandle {
+export function openJxsuiteUpdateSurface(options: JxsuiteUpdateSurfaceOptions): DialogLayerHandle {
   const slot = document.createElement("div");
   /* The layer is `pointer-events: none` so a click passes through it when nothing is up, and every
      slot in it turns them back on for its own content. `pointer-events` INHERITS, and the top layer
@@ -98,8 +86,12 @@ export function openJxsuiteUpdateSurface(
     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<JxsuiteUpdateScope>({
+  const scope: JxsuiteUpdateScope = reactive<JxsuiteUpdateScope>({
     cancel: () => {
       options.onCancel();
     },
@@ -108,18 +100,20 @@ export function openJxsuiteUpdateSurface(
       options.onConfirm();
     },
     packages: options.packages,
-  }) as JxsuiteUpdateScope;
+  });
 
   let mounted: SurfaceHandle | null = null;
   const ready = mountSurface("jxsuite-update", scope, slot).then(async (surface) => {
     mounted = surface;
+    /* SAFETY: `jxsuite-update.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);
@@ -135,7 +129,7 @@ export function openJxsuiteUpdateSurface(
       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/library-pane.ts

@@ -28,14 +28,16 @@
  * @docs studio/projects/browse
  */
 
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
+import { placeholderBrokenImages } from "../utils/edit-display";
 import libraryDoc from "./library-pane.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";
+import type { SurfaceHandle, SurfaceOption } from "../ui/surface";
 
-registerSurface("library-pane", libraryDoc as unknown as JxDocument);
+registerSurface("library-pane", libraryDoc);
 
 /**
  * Which of nine things the body draws.
@@ -117,12 +119,6 @@ export interface LibraryChip {
   checked: "true" | "false";
 }
 
-/** One row of the language facet. */
-export interface LibraryOption {
-  value: string;
-  label: string;
-}
-
 /** Everything the document draws, as one value. */
 export interface LibraryView {
   /** The region id stamped on the root, so the screenshot pipeline can address the Library. */
@@ -139,7 +135,7 @@ export interface LibraryView {
    * chrome that says nothing.
    */
   localeState: "hidden" | "shown";
-  localeOptions: LibraryOption[];
+  localeOptions: SurfaceOption[];
   localeValue: string;
   query: string;
   /** Where an upload lands, as the label's tooltip says it — before the files are chosen. */
@@ -210,7 +206,7 @@ export interface LibrarySurfaceHandle {
 }
 
 /** The scope the document reads: {@link LibraryView} plus the actions its controls call. */
-interface LibraryScope extends Record<string, unknown>, LibraryView, LibraryActions {}
+interface LibraryScope extends LibraryView, LibraryActions {}
 
 /** Write a projection into the scope. */
 function project(scope: LibraryScope, view: LibraryView): void {
@@ -242,15 +238,16 @@ function project(scope: LibraryScope, view: LibraryView): void {
 
 /** 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 path of the mapped row a node was rendered inside, or "" when it was not in one. */
 function rowPath(state: JxScope | undefined): string {
-  const map = state?.["$map"] as { item?: { path?: unknown } } | undefined;
-  const path = map?.item?.path;
-  return typeof path === "string" ? path : "";
+  const map = state?.["$map"];
+  const item = isJsonObject(map) ? map["item"] : undefined;
+  const path = isJsonObject(item) ? item["path"] : undefined;
+  return isString(path) ? path : "";
 }
 
 /**
@@ -267,7 +264,11 @@ export function mountLibrarySurface(
   actions: LibraryActions,
 ): LibrarySurfaceHandle {
   host.replaceChildren();
-  const scope = reactive<LibraryScope>({
+  // A file that will not load, or a preview image with nothing to bind, draws a placeholder rather
+  // Than the browser's broken-image glyph.
+  const listening = new AbortController();
+  placeholderBrokenImages(host, listening.signal);
+  const scope: LibraryScope = reactive<LibraryScope>({
     bannerState: "hidden",
     bannerText: "",
     categories: [],
@@ -308,7 +309,7 @@ export function mountLibrarySurface(
     uploadAccept: "",
     uploadHint: "",
     view: "loading",
-  }) as LibraryScope;
+  });
   project(scope, view);
 
   let mounted: SurfaceHandle | null = null;
@@ -335,12 +336,15 @@ export function mountLibrarySurface(
       }
     },
   }).then((surface) => {
+    /* SAFETY: `library-pane.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 {
@@ -355,6 +359,7 @@ export function mountLibrarySurface(
     },
     dispose() {
       disposed = true;
+      listening.abort();
       mounted?.dispose();
       mounted = null;
     },

package/src/surfaces/logic-panel.ts

@@ -21,20 +21,15 @@
  * @docs studio/logic/events
  */
 
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import logicPanelDoc from "./logic-panel.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";
+import type { SurfaceAction, SurfaceHandle, SurfaceOption } from "../ui/surface";
 
-registerSurface("logic-panel", logicPanelDoc as unknown as JxDocument);
-
-/** A closed list of choices, in the shape the kit's select reads. */
-export interface LogicOption {
-  value: string;
-  label: string;
-}
+registerSurface("logic-panel", logicPanelDoc);
 
 /** Which control a bindable row draws. The flow picks it; the document switches on it. */
 export type LogicFieldKind = "control" | "text" | "select";
@@ -55,7 +50,7 @@ export interface LogicFieldView {
   /** What a `text` or `select` control holds. Empty for a control host. */
   value: string;
   placeholder: string;
-  options: LogicOption[];
+  options: SurfaceOption[];
   /** Draw the text control monospaced — a pointer or a template string. */
   mono: boolean;
   /** The rung's own id, for `data-source`. */
@@ -131,7 +126,7 @@ export interface LogicBindingView {
   /** The code body's text. Empty for every other body. */
   code: string;
   refValue: string;
-  refOptions: LogicOption[];
+  refOptions: SurfaceOption[];
   /** The escape hatch's accessible name — the code editor, or the formula workspace. */
   openTitle: string;
 }
@@ -149,12 +144,6 @@ export interface LogicKvView {
   tags: string;
 }
 
-/** One button of an empty state — an id the flow knows, and the words on it. */
-export interface LogicEmptyAction {
-  id: string;
-  label: string;
-}
-
 /** Everything the Logic tab shows, already decided. */
 export interface LogicView {
   /** `empty` or `ready` — no document, no selection and a stale one are all the first. */
@@ -164,7 +153,7 @@ export interface LogicView {
    * What the reader can do about it. An empty state that teaches nothing offers none
    * (studio-ui-guidelines.md §11.1).
    */
-  emptyActions: LogicEmptyAction[];
+  emptyActions: SurfaceAction[];
   hasEmptyActions: boolean;
 
   hasRepeater: boolean;
@@ -233,7 +222,7 @@ export interface LogicIslands {
   statementsSlot: (key: string, host: HTMLElement) => void;
 }
 
-interface LogicScope extends Record<string, unknown>, LogicView, LogicActions {}
+interface LogicScope extends LogicView, LogicActions {}
 
 export interface LogicSurface {
   /** Re-project. The document's bindings skip every value that did not move. */
@@ -279,23 +268,21 @@ export function emptyLogicView(): LogicView {
 
 /** Assign the projection field by field: the runtime writes only the bindings that moved. */
 function project(scope: LogicScope, view: LogicView): void {
-  for (const [key, value] of Object.entries(view)) {
-    (scope as Record<string, unknown>)[key] = value;
-  }
+  Object.assign(scope, view);
 }
 
 /** The `part` a node was rendered with, or "". */
 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 `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 : "";
 }
 
 /**
@@ -316,10 +303,10 @@ export function mountLogicSurface(
   actions: LogicActions,
   islands: LogicIslands,
 ): LogicSurface {
-  const scope = reactive<LogicScope>({
+  const scope: LogicScope = reactive<LogicScope>({
     ...emptyLogicView(),
     ...actions,
-  } as LogicScope) as LogicScope;
+  });
   project(scope, view);
 
   let mounted: SurfaceHandle | null = null;

package/src/surfaces/logic-workspace.ts

@@ -29,14 +29,15 @@
  * @docs studio/logic/formula-workspace
  */
 
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import logicWorkspaceDoc from "./logic-workspace.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("logic-workspace", logicWorkspaceDoc as unknown as JxDocument);
+registerSurface("logic-workspace", logicWorkspaceDoc);
 
 /** One chip of the pipeline, as the document draws it. */
 export interface LogicChipView {
@@ -112,8 +113,7 @@ export interface LogicWorkspaceIslands {
   treeSlot: (key: string, host: HTMLElement) => void;
 }
 
-interface LogicWorkspaceScope
-  extends Record<string, unknown>, LogicWorkspaceView, LogicWorkspaceActions {}
+interface LogicWorkspaceScope extends LogicWorkspaceView, LogicWorkspaceActions {}
 
 export interface LogicWorkspaceSurface {
   /** Re-project. The document's bindings skip every value that did not move. */
@@ -151,23 +151,21 @@ export function emptyLogicWorkspaceView(): LogicWorkspaceView {
 
 /** Assign the projection field by field: the runtime writes only the bindings that moved. */
 function project(scope: LogicWorkspaceScope, view: LogicWorkspaceView): void {
-  for (const [key, value] of Object.entries(view)) {
-    (scope as Record<string, unknown>)[key] = value;
-  }
+  Object.assign(scope, view);
 }
 
 /** The `part` a node was rendered with, or "". */
 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 `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 : "";
 }
 
 /**
@@ -187,10 +185,10 @@ export function mountLogicWorkspace(
   actions: LogicWorkspaceActions,
   islands: LogicWorkspaceIslands,
 ): LogicWorkspaceSurface {
-  const scope = reactive<LogicWorkspaceScope>({
+  const scope: LogicWorkspaceScope = reactive<LogicWorkspaceScope>({
     ...emptyLogicWorkspaceView(),
     ...actions,
-  } as LogicWorkspaceScope) as LogicWorkspaceScope;
+  });
   project(scope, view);
 
   let mounted: SurfaceHandle | null = null;

package/src/surfaces/media-browser.ts

@@ -26,10 +26,9 @@ import { openPopoverSurface } from "../ui/popover-surface";
 import { reactive } from "../reactivity";
 import { registerSurface } from "../ui/surface";
 import mediaBrowserDoc from "./media-browser.json";
-import type { JxDocument } from "@jxsuite/schema/types";
-import type { PopoverSurfaceHandle } from "../ui/popover-surface";
+import type { OpenPopoverSurfaceOptions, PopoverSurfaceHandle } from "../ui/popover-surface";
 
-registerSurface("media-browser", mediaBrowserDoc as unknown as JxDocument);
+registerSurface("media-browser", mediaBrowserDoc);
 
 /** The slot id, and so the panel's region: `overlay.menu:media-picker`. */
 const SLOT = "media-picker";
@@ -79,8 +78,7 @@ export interface MediaBrowserSurfaceHandle extends PopoverSurfaceHandle {
   update: (view: MediaBrowserView) => void;
 }
 
-interface MediaBrowserScope
-  extends Record<string, unknown>, MediaBrowserView, Omit<MediaBrowserActions, "dismissed"> {}
+interface MediaBrowserScope extends MediaBrowserView, Omit<MediaBrowserActions, "dismissed"> {}
 
 /** Write a projection into the scope. */
 function project(scope: MediaBrowserScope, view: MediaBrowserView): void {
@@ -107,7 +105,7 @@ export function openMediaBrowserSurface(
   actions: MediaBrowserActions,
   anchor: HTMLElement | null,
 ): MediaBrowserSurfaceHandle {
-  const scope = reactive<MediaBrowserScope>({
+  const scope: MediaBrowserScope = reactive<MediaBrowserScope>({
     emptyLabel: view.emptyLabel,
     filter: view.filter,
     measure: actions.measure,
@@ -119,15 +117,18 @@ export function openMediaBrowserSurface(
     setFilter: actions.setFilter,
     x: view.x,
     y: view.y,
-  }) as MediaBrowserScope;
+  });
 
-  const handle = openPopoverSurface({
+  const options: OpenPopoverSurfaceOptions<MediaBrowserScope> = {
     anchor,
     name: "media-browser",
     scope,
     slot: SLOT,
-    ...(actions.dismissed ? { onDismissed: actions.dismissed } : {}),
-  });
+  };
+  if (actions.dismissed) {
+    options.onDismissed = actions.dismissed;
+  }
+  const handle = openPopoverSurface(options);
 
   void handle.ready.then(() => {
     if (handle.isOpen()) {

package/src/surfaces/media-field.ts

@@ -22,10 +22,9 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import mediaFieldDoc from "./media-field.json";
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("media-field", mediaFieldDoc as unknown as JxDocument);
+registerSurface("media-field", mediaFieldDoc);
 
 /** Everything the control draws, as one value. */
 export interface MediaFieldView {
@@ -58,7 +57,7 @@ export interface MediaFieldHandle {
 }
 
 /** The scope the document reads. */
-interface MediaFieldScope extends Record<string, unknown>, MediaFieldView, MediaFieldActions {}
+interface MediaFieldScope extends MediaFieldView, MediaFieldActions {}
 
 /** Write a projection into the scope. */
 function project(scope: MediaFieldScope, view: MediaFieldView): void {
@@ -81,7 +80,7 @@ export function mountMediaFieldSurface(
   view: MediaFieldView,
   actions: MediaFieldActions,
 ): MediaFieldHandle {
-  const scope = reactive<MediaFieldScope>({
+  const scope: MediaFieldScope = reactive<MediaFieldScope>({
     browse: actions.browse,
     edit: actions.edit,
     label: view.label,
@@ -90,7 +89,7 @@ export function mountMediaFieldSurface(
     upload: actions.upload,
     value: view.value,
     warm: actions.warm,
-  }) as MediaFieldScope;
+  });
 
   let mounted: SurfaceHandle | null = null;
   let disposed = false;

package/src/surfaces/media-pane.ts

@@ -24,10 +24,9 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import mediaDoc from "./media-pane.json";
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("media-pane", mediaDoc as unknown as JxDocument);
+registerSurface("media-pane", mediaDoc);
 
 /**
  * Which element the stage draws the file in.
@@ -105,7 +104,7 @@ export interface MediaSurfaceHandle {
  * `$switch` discriminant derived here — "is there a list" is a restatement of the list, and a view
  * that had to keep the two in step would be a second place to get it wrong.
  */
-interface MediaScope extends Record<string, unknown>, MediaView, MediaActions {
+interface MediaScope extends MediaView, MediaActions {
   hasUsageFiles: boolean;
 }
 
@@ -141,7 +140,7 @@ export function mountMediaSurface(
   actions: MediaActions,
 ): MediaSurfaceHandle {
   host.replaceChildren();
-  const scope = reactive<MediaScope>({
+  const scope: MediaScope = reactive<MediaScope>({
     copyRef: actions.copyRef,
     extLabel: "",
     facts: "",
@@ -159,7 +158,7 @@ export function mountMediaSurface(
     usageFiles: [],
     usageHeadline: "",
     usageState: "hidden",
-  }) as MediaScope;
+  });
   project(scope, view);
 
   let mounted: SurfaceHandle | null = null;
@@ -171,9 +170,11 @@ export function mountMediaSurface(
   const ready = mountSurface("media-pane", scope, host).then((surface) => {
     if (disposed) {
       surface.dispose();
-      return surface.root as HTMLElement;
+    } else {
+      mounted = surface;
     }
-    mounted = surface;
+    /* SAFETY: `media-pane.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. */
     return surface.root as HTMLElement;
   });