@jxsuite/studio 6.1.1 → 6.1.2

package/src/canvas/canvas-render.ts

@@ -4,13 +4,17 @@
  * dispatches to manage/settings/source/edit/design/preview rendering paths.
  */
 
-import { render as litRender, nothing } from "lit-html";
+import { render, nothing } from "lit-html";
 import type * as monaco from "monaco-editor";
 import type { WireDiffMarks } from "./iframe-protocol";
 import type * as Y from "yjs";
 import { loadedMonaco, loadMonaco, mountStillWanted } from "../services/monaco-lazy";
 
-import { getNodeAtPath, updateCanvas } from "../store";
+import { getNodeAtPath } from "@jxsuite/schema/doc-ops";
+import { isString } from "@jxsuite/schema/guards";
+import { errorMessage } from "@jxsuite/schema/parse";
+import { stageOf } from "./surface-registry";
+import { updateCanvas } from "../store";
 import { activeTab, tabIsLive, workspace } from "../workspace/workspace";
 import {
   activeMediaOfPane,
@@ -40,8 +44,6 @@ import { canRenderComparison } from "../panels/git-diff-open";
 import { releaseStageScrollbar, trackStageScrollbar } from "./stage-scrollbar";
 import { renderDiffToolbar, setDiffRepaint, setDiffToolbarHost } from "./diff-toolbar";
 import { attachCursorStyles } from "../collab/monaco-cursors";
-import type { AwarenessLike } from "../collab/monaco-cursors";
-import type { BindingAwareness } from "../collab/monaco-binding";
 import { monacoTheme, shell } from "../shell";
 import { parseSourceForPath } from "../files/file-ops";
 import { serializeDocument } from "../files/serialize-document";
@@ -412,13 +414,15 @@ async function createSourceCollabBinding(
 ): Promise<() => void> {
   const { bindMonacoToYText } = await import("../collab/monaco-binding");
   const unbind = bindMonacoToYText({
-    awareness: ctx.awareness as unknown as BindingAwareness,
+    awareness: ctx.awareness,
     editors: [editor],
     model,
     origin: ctx.localOrigin,
+    /* SAFETY: collabSourceContext's `text` is `collab.sourceText(handle.doc)`, the session's shared
+       source Y.Text, attached to the handle's Y.Doc as the binding requires. */
     text: ctx.text as Y.Text,
   });
-  const detachStyles = attachCursorStyles(ctx.awareness as unknown as AwarenessLike, document);
+  const detachStyles = attachCursorStyles(ctx.awareness, document);
   return () => {
     detachStyles();
     unbind();
@@ -558,7 +562,7 @@ function sideMarks(
  */
 async function mountDiffEditor(
   surface: CanvasSurface,
-  container: Element,
+  container: HTMLElement,
   state: GitDiffState,
 ): Promise<void> {
   const { paneId } = surface;
@@ -589,17 +593,20 @@ async function mountDiffEditor(
     lang,
     monaco.Uri.parse(uris.work),
   );
-  const editor = monaco.editor.createDiffEditor(container as HTMLElement, {
-    automaticLayout: true,
-    fontFamily: "'JetBrains Mono', 'SF Mono', 'Fira Code', 'Consolas', monospace",
-    fontSize: 12,
-    minimap: { enabled: false },
-    originalEditable: false,
-    readOnly: true,
-    renderSideBySide: true,
-    scrollBeyondLastLine: false,
-    theme: monacoTheme(),
-  }) as NonNullable<CanvasSurface["monacoDiffEditor"]>;
+  const editor: NonNullable<CanvasSurface["monacoDiffEditor"]> = monaco.editor.createDiffEditor(
+    container,
+    {
+      automaticLayout: true,
+      fontFamily: "'JetBrains Mono', 'SF Mono', 'Fira Code', 'Consolas', monospace",
+      fontSize: 12,
+      minimap: { enabled: false },
+      originalEditable: false,
+      readOnly: true,
+      renderSideBySide: true,
+      scrollBeyondLastLine: false,
+      theme: monacoTheme(),
+    },
+  );
   editor.setModel({ modified, original });
   editor._diffKey = key;
   surface.monacoDiffEditor = editor;
@@ -663,7 +670,7 @@ function resetCanvasView(surface: CanvasSurface) {
 async function mountSourceEditor(
   tab: Tab,
   surface: CanvasSurface,
-  editorContainer: Element,
+  editorContainer: HTMLElement,
   filePath: string,
   lang: string,
 ): Promise<void> {
@@ -757,7 +764,7 @@ async function mountSourceEditor(
   // Typed as the surface `view` declares (the editor plus `_ignoreNextChange` / `_writes`), because
   // The instance is HELD here now rather than re-read off `view.monacoEditor` in every callback.
   const sourceEditor: NonNullable<typeof surface.monacoEditor> = monaco.editor.create(
-    editorContainer as unknown as HTMLElement,
+    editorContainer,
     {
       automaticLayout: true,
       fontFamily: "'JetBrains Mono', 'SF Mono', 'Fira Code', 'Consolas', monospace",
@@ -832,7 +839,7 @@ async function mountSourceEditor(
           if (!tabIsLive(tab)) {
             return;
           }
-          tab.doc.document = document as JxMutableNode;
+          tab.doc.document = document;
           tab.doc.content.frontmatter = frontmatter;
           tab.doc.dirty = true;
           writes.markSettled();
@@ -845,6 +852,8 @@ async function mountSourceEditor(
           // The buffer's text is the author's own layout now — the objects they opened up or
           // Closed, the blank lines they left — so it is what the next save preserves.
           const parsed = parseJsonDocument(sourceEditor.getValue());
+          /* SAFETY: a JSON source tab holds a Jx document, whose schema makes the top-level object
+             parseJsonDocument returns a node; text that does not parse throws into the catch. */
           tab.doc.document = parsed.document as JxMutableNode;
           tab.doc.layout = parsed.layout;
           tab.doc.dirty = true;
@@ -930,7 +939,7 @@ function renderDerivationNotice(
   surface.wrap.style.display = "block";
   const registry = activeRegistry();
   const pin = registry?.get("pane.pin");
-  litRender(
+  render(
     emptyState(surface.wrap, {
       message,
       ...(held && { detail: `${tabLabel(held)} is still open here.` }),
@@ -954,7 +963,7 @@ function renderCanvasImpl(surface: CanvasSurface) {
   /* Every read below is scoped to ONE pane. The stage, the panels it mounted and the mode it draws
      are the surface's; the document is whatever tab that pane is showing, which is `activeTab` only
      when the pane is the focused one. */
-  const canvasWrap = surface.wrap;
+  const canvasWrap = stageOf(surface);
   /* A pane with no stage renders nothing — it is not an error and it is not a fallback to some
      other pane's stage. Two schedulers can name a stage-less pane: a frame queued for a pane that
      lost the shell's single stage between the schedule and the rAF, and `escalateToFullRender` on
@@ -1012,6 +1021,8 @@ function renderCanvasImpl(surface: CanvasSurface) {
     );
     return;
   }
+  /* SAFETY: `initCanvasRender` runs at studio boot (studio.ts), before the shell schedules the first
+     pane render, and nothing resets `_ctx` afterwards. */
   const ctx = _ctx as CanvasRenderCtx;
   const S = {
     document: tab.doc.document,
@@ -1193,8 +1204,8 @@ function renderCanvasImpl(surface: CanvasSurface) {
       curFilter !== surface.prevStylebookFilter ||
       curCustomized !== surface.prevStylebookCustomizedOnly;
     if (!filterChanged) {
-      const style = transposeStylebookStyle(getEffectiveStyle(tab.doc.document?.style));
-      if (postStyleUpdateToStylebookHosts(style as Record<string, unknown>) > 0) {
+      const style = transposeStylebookStyle(getEffectiveStyle(tab.doc.document.style));
+      if (postStyleUpdateToStylebookHosts(style) > 0) {
         return;
       }
     }
@@ -1261,7 +1272,7 @@ function renderCanvasImpl(surface: CanvasSurface) {
        leaving, and lit's part, which the empty-state and welcome paths own. */
     releaseCanvasHosts(canvasWrap);
     detachCanvasStage(surface);
-    litRender(nothing, canvasWrap);
+    render(nothing, canvasWrap);
     surface.panzoomWrap = null;
     // Reset inline style overrides from other modes
     canvasWrap.style.padding = "";
@@ -1465,7 +1476,7 @@ function renderCanvasImpl(surface: CanvasSurface) {
        decided rather than the opener: a comparison reaches this branch from three doors (the panel,
        a Diff lens, the Editor axis) and only this one sees every arrival. Forcing it here also
        leaves `diffView` alone, so a document opened after a `.css` still comes up Visual. */
-    const renderable = canRenderComparison(gitDiffState.filePath ?? "");
+    const renderable = canRenderComparison(gitDiffState.filePath);
     if (diffShowsCode(surface.paneId, renderable)) {
       /* A null map is how the toolbar learns there is no visual half to offer: it draws Code as a
          static label rather than as half of a choice, and reports the line marks instead of a node
@@ -1518,12 +1529,15 @@ function renderCanvasImpl(surface: CanvasSurface) {
 
     /** @param {string} content */
     const parseContent = (content: string): Promise<JxMutableNode> => {
-      const fmtPath = gitDiffState.filePath ?? "";
+      const fmtPath = gitDiffState.filePath;
       if (formatForPath(fmtPath)) {
         return parseSourceForPath(fmtPath, content).then((r) => r.document);
       }
       return Promise.resolve().then(() => {
         try {
+          /* SAFETY: a side of a VISUAL comparison is a revision of a document the canvas renders
+             (canRenderComparison chose this half), a JSON Jx document; unparseable text throws into
+             the catch, which draws the failure instead. */
           return JSON.parse(content) as JxMutableNode;
         } catch {
           return {
@@ -1636,8 +1650,8 @@ function renderCanvasImpl(surface: CanvasSurface) {
     const entry = canvasPanelEntry(null, null, true);
     // A component-definition doc (root tag is a custom element) is a fragment, not a page: it should
     // Hug its content rather than have the column fill+stretch to the viewport (dead scroll space).
-    const rootTag = (S.document as { tagName?: unknown }).tagName;
-    const isComponentDoc = typeof rootTag === "string" && rootTag.includes("-");
+    const rootTag = S.document.tagName;
+    const isComponentDoc = isString(rootTag) && rootTag.includes("-");
     const { featureToggles: editToggles } = S.ui;
     /* The stage stacks when it carries the card: the band first, the page's scroller below it.
        Set on every render rather than on the transition, because whether a document HAS a header
@@ -1680,6 +1694,8 @@ function renderCanvasImpl(surface: CanvasSurface) {
       }
       const editColumn = stageHost(surface, "edit-column");
       const scroller = stageHost(surface, "edit-canvas");
+      /* SAFETY: the edit stage view always draws its `edit-canvas` part, and this runs only once
+         drawStage settled with that stage (the `!stage` return above). */
       entry.panel.scrollContainer = scroller as HTMLElement;
       /* The one mode whose stage SCROLLS under the zoom pod, so the one that tells the pane how
          wide its scrollbar is. The pod floats in the pane's chrome layer, which spans the gutter
@@ -1733,7 +1749,7 @@ function renderCanvasImpl(surface: CanvasSurface) {
   if (!hasMedia) {
     // Single panel — use baseWidth if a custom one is defined, otherwise full-width
     const effectiveMedia = getEffectiveMedia(S.document.$media);
-    const hasBaseWidth = effectiveMedia && effectiveMedia["--"];
+    const hasBaseWidth = effectiveMedia["--"];
     const label = hasBaseWidth ? `${mediaDisplayName("--")} (${baseWidth}px)` : null;
     const entry = canvasPanelEntry(
       hasBaseWidth ? "base" : null,
@@ -1900,8 +1916,11 @@ function renderCanvasIntoPanel(
 ) {
   const gen = passGen ?? surface.renderGeneration;
   const tab = tabOfPane(surface.paneId);
+  /* SAFETY: every caller is a renderCanvasImpl pass, which returns before drawing any panel when its
+     pane has no tab, so without an override `tab` was non-null when this pass began; the git-diff
+     callers always pass their override. */
   const docToRender = docOverride || (tab?.doc.document as JxMutableNode);
-  const canvas = panel.canvas as HTMLElement;
+  const { canvas } = panel;
 
   canvasPerf.panelRenders += 1;
   panel.ready = false;
@@ -1947,14 +1966,16 @@ function renderCanvasIntoPanel(
         // The canvas you are looking at; it says so itself.
       }
     })
-    .catch((error: unknown) => {
-      const detail = error instanceof Error ? error.message : String(error);
-      notify.error("The canvas could not be mounted.", {
-        detail,
-        key: "canvas.mount",
-        source: "Canvas",
-      });
-    });
+    .catch(reportMountFailure);
+}
+
+/** A canvas mount that rejected, reported as a Problem with the failure's own message. */
+function reportMountFailure(cause: unknown): void {
+  notify.error("The canvas could not be mounted.", {
+    detail: errorMessage(cause),
+    key: "canvas.mount",
+    source: "Canvas",
+  });
 }
 
 /*
@@ -2012,7 +2033,7 @@ function refuseUnresolvableToken(token: string): void {
     throw new RangeError(`command "insert.data" needs an open document; no tab is active`);
   }
   const root = tokenRoot(token);
-  const state = (tab.doc.document.state ?? {}) as Record<string, unknown>;
+  const state = tab.doc.document.state ?? {};
   if (root === "state") {
     const name = token.split(".")[1] ?? "";
     if (!(name in state)) {

package/src/canvas/canvas-surface.ts

@@ -17,6 +17,7 @@ import { allCanvasSurfaces, stageContaining, surfaceForPane } from "./surface-re
 import type { CanvasSurface } from "./surface-registry";
 import type { PaneDerivation } from "../workspace/workspace";
 import type { CanvasPanel } from "../types";
+import type { UnboundCanvasPanel } from "./canvas-utils";
 import type { Tab } from "../tabs/tab";
 
 export {
@@ -149,11 +150,12 @@ export function panelHostingCanvas(
  * answers with the FOCUSED pane's tab, which is a different document the moment the click is in a
  * pane the keyboard is not in.
  *
- * @param {CanvasPanel} panel
+ * @param {UnboundCanvasPanel} panel
  * @returns {Tab | null}
  */
-export function tabOfMountedPanel(panel: CanvasPanel): Tab | null {
-  const canvasEl = panel.canvas as HTMLElement | null;
+export function tabOfMountedPanel(panel: UnboundCanvasPanel): Tab | null {
+  // An unbound board (no canvas node yet) has no pane mounting it.
+  const canvasEl = panel.canvas;
   const mounted = canvasEl ? panelHostingCanvas(canvasEl) : null;
   return mounted ? tabOfPane(mounted.surface.paneId) : null;
 }

package/src/canvas/canvas-utils.ts

@@ -4,7 +4,7 @@
  * template creation, centering, transform application, zoom indicator, and fit-to-screen.
  */
 
-import type { CanvasPanel, JsonValue } from "../types";
+import type { CanvasPanel } from "../types";
 
 import { renderOnly } from "../store";
 import {
@@ -39,6 +39,7 @@ import {
 import type { CanvasStageHandle, CanvasStagePanelItem } from "../surfaces/canvas-stage";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 import type { CommandArgValues } from "../commands/command-args";
+import { isNumber, isString } from "@jxsuite/schema/guards";
 import type { Tab } from "../tabs/tab";
 
 /*
@@ -106,6 +107,22 @@ function setZoomOf(surface: CanvasSurface, zoom: number): void {
   }
 }
 
+/** The {@link CanvasPanel} fields that hold the board's drawn nodes. */
+type CanvasPanelNodeKey = "canvas" | "element" | "scrollContainer" | "viewport";
+
+/**
+ * A panel record as it may be before {@link bindCanvasPanels} has run: its DOM fields can still be
+ * null, because {@link canvasPanelEntry} builds them that way. A bound {@link CanvasPanel} is
+ * assignable to it, so a reader that must tolerate an unbound board takes this type.
+ */
+export type UnboundCanvasPanel = Omit<CanvasPanel, CanvasPanelNodeKey> &
+  Record<CanvasPanelNodeKey, HTMLElement | null>;
+
+/** Whether the stage has wired a board's canvas and viewport nodes into its record yet. */
+export function isPanelBound(panel: UnboundCanvasPanel): boolean {
+  return Boolean(panel.canvas && panel.viewport);
+}
+
 /**
  * One artboard: the record the geometry reads, and the item the stage document draws.
  *
@@ -139,7 +156,7 @@ export function canvasPanelEntry(
   fullWidth: boolean,
   width: number | null = null,
 ): CanvasPanelEntry {
-  const panel = {
+  const unbound: UnboundCanvasPanel = {
     _width: width || null,
     canvas: null,
     element: null,
@@ -148,7 +165,11 @@ export function canvasPanelEntry(
     renderScope: null,
     scrollContainer: null,
     viewport: null,
-  } as unknown as CanvasPanel;
+  };
+  /* SAFETY: the record is handed out unbound and filled in place by `bindCanvasPanels` once the
+     stage has drawn it; every reader that can run before that (`tabOfMountedPanel`, `applyEditZoom`,
+     `updateActivePanelHeaders`) reads it as an UnboundCanvasPanel and checks the nodes first. */
+  const panel = unbound as CanvasPanel;
   /* The viewport takes the declared width, the canvas takes it too — but a FULL-WIDTH board's
      viewport does not, because "full width" means "as wide as the box you are in". Carried as two
      custom properties rather than as `width:` so `applyEditZoom`'s inline write on the canvas still
@@ -186,9 +207,13 @@ export function canvasPanelEntry(
  */
 export function bindCanvasPanels(entries: CanvasPanelEntry[], stage: CanvasStageHandle): void {
   for (const { item, panel } of entries) {
-    panel.element = stage.panelNode(item.key, "panel") as HTMLElement;
-    panel.viewport = stage.panelNode(item.key, "panel-viewport") as HTMLElement;
-    panel.canvas = stage.panelNode(item.key, "panel-canvas") as HTMLElement;
+    /* SAFETY: callers bind only after `drawStage` has settled, and the stage document draws the
+       `panel`, `panel-viewport` and `panel-canvas` parts for every item it was given, keyed by
+       `item.key`, so each lookup finds its node. */
+    const node = (part: string) => stage.panelNode(item.key, part) as HTMLElement;
+    panel.element = node("panel");
+    panel.viewport = node("panel-viewport");
+    panel.canvas = node("panel-canvas");
   }
 }
 
@@ -349,7 +374,7 @@ export function applyEditZoom(
     return;
   }
   const [panel] = surface.panels;
-  if (!panel?.canvas || !panel.viewport) {
+  if (!panel || !isPanelBound(panel)) {
     return;
   }
   const canvasEl = panel.canvas;
@@ -571,12 +596,12 @@ export const FIT_WORDS: readonly string[] = ["width", "page", "none"];
  * assistant sees. It stays as the typed read the body needs (`args.fit` is `unknown`) and as the
  * refusal for a caller that reaches the body directly.
  */
-function fitArg(commandId: string, args: Record<string, unknown>, key: string): FitMode {
+function fitArg(commandId: string, args: CommandArgValues, key: string): FitMode {
   const value = args[key];
-  if (typeof value === "string" && FIT_WORDS.includes(value)) {
-    return value as FitMode;
+  if (isFitWord(value)) {
+    return value;
   }
-  if (typeof value === "number" && value >= PAN_ZOOM_MIN && value <= PAN_ZOOM_MAX) {
+  if (isNumber(value) && value >= PAN_ZOOM_MIN && value <= PAN_ZOOM_MAX) {
     return value;
   }
   throw new RangeError(
@@ -585,6 +610,11 @@ function fitArg(commandId: string, args: Record<string, unknown>, key: string):
   );
 }
 
+/** Whether a value is one of {@link FIT_WORDS}, the named (non-scale) fits. */
+function isFitWord(value: unknown): value is Exclude<FitMode, number> {
+  return isString(value) && FIT_WORDS.includes(value);
+}
+
 /** Declared fits, keyed per tab + document. */
 const _fits = new Map<string, FitMode>();
 
@@ -641,7 +671,7 @@ export function applyFit(fit?: FitMode, surface: CanvasSurface = activeCanvasSur
     applyTransform(surface);
     return;
   }
-  if (typeof chosen === "number") {
+  if (isNumber(chosen)) {
     setZoomOf(surface, clampPanZoom(chosen));
     applyTransform(surface);
     return;
@@ -853,6 +883,11 @@ export type CanvasMode = (typeof CANVAS_MODES)[number];
 /** The base modes the preview flag composes with — the two the Canvas view axis shows it beside. */
 const PREVIEWABLE_BASE_MODES = new Set(["edit", "design"]);
 
+/** Whether a base mode is one the preview flag composes with: a member of PREVIEWABLE_BASE_MODES. */
+function isPreviewableBase(mode: string): mode is "edit" | "design" {
+  return PREVIEWABLE_BASE_MODES.has(mode);
+}
+
 // ─── The Canvas view (§4.2) ──────────────────────────────────────────────────
 // `Edit │ Design` is a radio and `Preview` is a TOGGLE beside it, because that is what the storage
 // Has always been: `preview` is not a base mode, it is a flag that composes with one.
@@ -913,7 +948,13 @@ export function canvasBaseViewsFor(tab: ViewableTab): CanvasView[] {
 /** The base view the tab returns to — what the radio marks while preview is on. */
 export function canvasBaseViewOf(tab: ViewableTab): CanvasView | null {
   const base = tab.session.ui.canvasMode;
-  return PREVIEWABLE_BASE_MODES.has(base) ? (base as CanvasView) : null;
+  return isPreviewableBase(base) ? base : null;
+}
+
+/** A tab's Preview toggle: whether it is offered, and whether it is pressed. */
+export interface PreviewState {
+  available: boolean;
+  on: boolean;
 }
 
 /**
@@ -922,7 +963,7 @@ export function canvasBaseViewOf(tab: ViewableTab): CanvasView | null {
  * `available` is a fact about the DOCUMENT (its declared modes) and about the base it is currently
  * in — `source` composes with no preview, so the toggle is not offered there.
  */
-export function previewStateOf(tab: ViewableTab): { available: boolean; on: boolean } {
+export function previewStateOf(tab: ViewableTab): PreviewState {
   return {
     available:
       tab.capabilities.modes.includes("preview") &&
@@ -1041,7 +1082,7 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
    * than the control it replaced, which is the opposite of the point.
    */
   function contextTab(commandId: string, args: CommandArgValues) {
-    const { pane } = args as { pane?: unknown };
+    const { pane } = args;
     if (pane === undefined) {
       return requireTab(commandId);
     }
@@ -1073,8 +1114,8 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
 
   /** The pane a rendering-context verb addresses, named or focused. {@link repaint}'s own rule. */
   function paneOfArgs(args: CommandArgValues): string {
-    const { pane } = args as { pane?: unknown };
-    return typeof pane === "string" ? pane : workspace.activePaneId;
+    const { pane } = args;
+    return isString(pane) ? pane : workspace.activePaneId;
   }
 
   return [
@@ -1258,9 +1299,9 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
        * so it simply renders at the pane's width — which is the same clamp the drag applies, arrived
        * at by CSS instead of by arithmetic. Refusing would make the verb depend on the window size.
        */
-      run: (_commandCtx, args) => {
+      run: (_commandCtx, args: CommandArgValues) => {
         const tab = contextTab("canvas.setEditWidth", args);
-        const { width } = args as { width?: unknown };
+        const { width } = args;
         if (width === null) {
           clearEditWidth(paneOfArgs(args));
           repaint(args);
@@ -1311,10 +1352,10 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
       group: "3_canvas",
       requires: "an open document",
       when: documentOpen,
-      run: (_commandCtx, args) => {
+      run: (_commandCtx, args: CommandArgValues) => {
         const tab = contextTab("canvas.setBreakpoint", args);
-        const { media } = args as { media?: unknown };
-        if (media !== null && typeof media !== "string") {
+        const { media } = args;
+        if (media !== null && !isString(media)) {
           throw new RangeError(
             `command "canvas.setBreakpoint" argument "media": expected a breakpoint key or null`,
           );
@@ -1323,9 +1364,7 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
            that does not exist — the rule `data.expandRow` applies to a state entry's name.
            `getEffectiveMedia` and not `document.$media`: the popover offers the SITE's breakpoints
            too, and a command that refused what the control offers would be worse than no command. */
-        const declared = Object.keys(
-          getEffectiveMedia(tab.doc.document?.$media as Record<string, string> | undefined),
-        );
+        const declared = Object.keys(getEffectiveMedia(tab.doc.document.$media));
         if (media !== null && !declared.includes(media)) {
           throw new RangeError(
             `command "canvas.setBreakpoint" argument "media": "${media}" is not a breakpoint this ` +
@@ -1359,7 +1398,7 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
           args,
           "scheme",
           COLOR_SCHEMES,
-        ) as "auto" | "dark" | "light";
+        );
         repaint(args);
       },
       title: "Set Color Scheme",
@@ -1475,16 +1514,18 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
       level: "document",
       menus: ["palette"],
       requires: "a popover in the open document",
-      run: (_commandCtx, args) => {
+      run: (_commandCtx, args: CommandArgValues) => {
         const tab = contextTab("canvas.setPopoverOpen", args);
-        const raw = (args ?? {}) as { open?: unknown; path?: JxPath };
+        /* SAFETY: `registry.run` coerces args against this record's schema before `run`, and the
+           schema declares `path` an array of strings and numbers, which is what a JxPath is. */
+        const explicitPath = args["path"] as JxPath | undefined;
         const open =
-          raw.open === undefined ? true : booleanArg("canvas.setPopoverOpen", args, "open");
-        if (!open && raw.path === undefined) {
+          args["open"] === undefined ? true : booleanArg("canvas.setPopoverOpen", args, "open");
+        if (!open && explicitPath === undefined) {
           deps.setOpenPopover(tab, null);
           return;
         }
-        const path = popoverPathFor(tab, raw.path);
+        const path = popoverPathFor(tab, explicitPath);
         /* REFUSES a path that is not a popover rather than opening nothing — the rule
            `canvas.setBreakpoint` applies to a breakpoint key. A <dialog> is refused with it: its UA
            rules key off `open`, not `popover`, so de-popovering one falls back to a different rule
@@ -1535,16 +1576,18 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
       level: "document",
       menus: ["palette"],
       requires: "a dialog in the open document",
-      run: (_commandCtx, args) => {
+      run: (_commandCtx, args: CommandArgValues) => {
         const tab = contextTab("canvas.setDialogOpen", args);
-        const raw = (args ?? {}) as { open?: unknown; path?: JxPath };
+        /* SAFETY: `registry.run` coerces args against this record's schema before `run`, and the
+           schema declares `path` an array of strings and numbers, which is what a JxPath is. */
+        const explicitPath = args["path"] as JxPath | undefined;
         const open =
-          raw.open === undefined ? true : booleanArg("canvas.setDialogOpen", args, "open");
-        if (!open && raw.path === undefined) {
+          args["open"] === undefined ? true : booleanArg("canvas.setDialogOpen", args, "open");
+        if (!open && explicitPath === undefined) {
           deps.setOpenDialog(tab, null);
           return;
         }
-        const path = dialogPathFor(tab, raw.path);
+        const path = dialogPathFor(tab, explicitPath);
         /* REFUSES a path that is not a dialog, for the same reason its twin refuses a non-popover:
            the canvas would draw it under the wrong rule and with the wrong name. */
         if (path === null) {
@@ -1586,14 +1629,14 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
        * (`scripts/screenshots/README.md`) forbids outright. The pointer and the camera use the same
        * door.
        */
-      run: (_commandCtx, args) => {
+      run: (_commandCtx, args: CommandArgValues) => {
         // Resolve the tab first, so a pane with no document refuses before anything opens.
         contextTab("canvas.setResolvingOpen", args);
-        const { open, pane } = args as { open?: unknown; pane?: unknown };
+        const { open, pane } = args;
         // `open` defaults to true and is never COERCED: `{ open: "no" }` would otherwise read as a
         // Close, the class of silent wrong answer this setter family exists to stop.
         deps.setResolvingOpen(
-          typeof pane === "string" ? pane : workspace.activePaneId,
+          isString(pane) ? pane : workspace.activePaneId,
           open === undefined || booleanArg("canvas.setResolvingOpen", args, "open"),
         );
       },
@@ -1636,26 +1679,24 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
       group: "3_canvas",
       requires: "an open component document",
       when: documentOpen,
-      run: (_commandCtx, args) => {
+      run: (_commandCtx, args: CommandArgValues) => {
         const tab = contextTab("canvas.setTestProp", args);
         const name = stringArg("canvas.setTestProp", args, "name");
         // REFUSES a prop the component does not declare, rather than seeding a value nothing reads
         // — the rule `data.expandRow` and `canvas.setBreakpoint` both apply to their own names.
-        const declared = Object.keys(
-          (tab.doc.document?.state as Record<string, unknown> | undefined) ?? {},
-        );
+        const declared = Object.keys(tab.doc.document.state ?? {});
         if (!declared.includes(name)) {
           throw new RangeError(
             `command "canvas.setTestProp" argument "name": "${name}" is not a prop this component ` +
               `declares — it declares: ${declared.length > 0 ? declared.join(", ") : "nothing"}`,
           );
         }
-        const { value } = args as { value?: unknown };
+        const { value } = args;
         const next = { ...tab.session.ui.previewProps };
         if (value === null || value === undefined) {
           delete next[name];
         } else {
-          next[name] = value as JsonValue;
+          next[name] = value;
         }
         tab.session.ui.previewProps = Object.keys(next).length > 0 ? next : null;
         repaint(args);
@@ -1723,13 +1764,13 @@ export function registerCanvasViewCommands(
  */
 export function updateActivePanelHeaders(surface: CanvasSurface = activeCanvasSurface()) {
   const activeMedia = activeMediaOfPane(surface.paneId);
-  for (const p of surface.panels) {
+  // A board the stage has not bound yet has no header to mark.
+  const panels: readonly UnboundCanvasPanel[] = surface.panels;
+  for (const p of panels) {
     const header = p.element?.querySelector('[part="panel-header"]');
     if (header) {
       const isActive =
-        (activeMedia === null && p.mediaName === "base") ||
-        (activeMedia === null && p.mediaName === null) ||
-        activeMedia === p.mediaName;
+        (activeMedia === null && p.mediaName === "base") || activeMedia === p.mediaName;
       /* An ATTRIBUTE the document does not bind, written from outside it. Which board is current is
          a fact about the pane's session that changes without the stage being rebuilt — the same
          reason the pan transform is written rather than bound — so a reconcile can never disagree