@jxsuite/studio 6.1.0 → 6.1.2

package/src/canvas/diff-toolbar.ts

@@ -32,6 +32,7 @@ import {
   setDiffView,
   stepDiff,
 } from "./diff-view";
+import { isString } from "@jxsuite/schema/guards";
 import type { DiffView } from "./diff-view";
 import type { ChangeStep } from "./diff-marks";
 import { panToParentRect } from "./canvas-utils";
@@ -158,7 +159,7 @@ function describeStep(step: ChangeStep, index: number, total: number): string {
  * it is, so a reveal that could not measure leaves a correct toolbar over an unmoved canvas.
  */
 function onStepClick(paneId: string, delta: 1 | -1): void {
-  stepDiffAndReveal(paneId, delta).catch((error: unknown) => {
+  stepDiffAndReveal(paneId, delta).catch((error) => {
     console.warn("stepDiffAndReveal:", error);
   });
 }
@@ -180,8 +181,8 @@ export async function stepDiffAndReveal(paneId: string, delta: 1 | -1): Promise<
   renderDiffToolbar(paneId);
   const step = diffChangeMapOf(paneId)?.steps[landed];
   const { panels } = surfaceForPane(paneId);
-  const original = panels[0]?.canvas as HTMLElement | undefined;
-  const current = panels[1]?.canvas as HTMLElement | undefined;
+  const original = panels[0]?.canvas;
+  const current = panels[1]?.canvas;
   if (!step) {
     return;
   }
@@ -252,10 +253,10 @@ export function diffToolbarView(paneId: string): DiffToolbarView {
   return {
     codeChecked: showing === "code" ? "true" : "false",
     countLabel,
-    degraded: !code && map?.degraded ? "shown" : "hidden",
+    degraded: !code && map.degraded ? "shown" : "hidden",
     nextDisabled: index >= total - 1,
     prevDisabled: index <= 0,
-    rootKeys: !code && map?.rootKeys.length ? "shown" : "hidden",
+    rootKeys: !code && map.rootKeys.length > 0 ? "shown" : "hidden",
     rootKeysTitle: `Changed: ${map?.rootKeys.join(", ") ?? ""}`,
     stepper: total === 0 ? "hidden" : "shown",
     // A file the canvas cannot render arrives with a null map: there is no visual half to offer.
@@ -266,8 +267,8 @@ export function diffToolbarView(paneId: string): DiffToolbarView {
 
 /** The pane a diff verb addresses: named, or the focused one. */
 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;
 }
 
 const paneProperty = stringProperty("Which pane to act on. Defaults to the focused one.");

package/src/canvas/edit-width-drag.ts

@@ -58,7 +58,7 @@ export function applyEditWidth(surface: CanvasSurface, column: HTMLElement, widt
     return;
   }
   column.style.maxWidth = `${Math.round(width)}px`;
-  if ((tab.session.ui.editZoom ?? 1) !== 1) {
+  if (tab.session.ui.editZoom !== 1) {
     applyEditZoom(surface);
   }
   const rendered = rectOf(column).width || width;
@@ -183,5 +183,8 @@ export function mountEditWidthHandle(
   if (!handle || !column || _wired.has(handle)) {
     return;
   }
+  /* SAFETY: Every caller passes one of the two `jx-split` slots `surfaces/canvas-stage.json` draws
+     beside the column, and a `jx-split` carries the `value`/`min`/`max`/`collapse` share
+     properties `SplitElement` names; `bindSplit` only writes them. */
   _wired.set(handle, bindSplit(handle as SplitElement, editWidthTarget(surface, column, grow)));
 }

package/src/canvas/edit-width.ts

@@ -78,9 +78,7 @@ const _editWidths = new Map<string, EditWidthRecord>();
 
 /** The size breakpoints and base width a tab renders against, site context included. */
 function mediaEntriesOfTab(tab: Tab) {
-  return parseMediaEntries(
-    getEffectiveMedia(tab.doc.document?.$media as Record<string, string> | undefined),
-  );
+  return parseMediaEntries(getEffectiveMedia(tab.doc.document.$media));
 }
 
 /**

package/src/canvas/iframe-channel.ts

@@ -9,6 +9,8 @@
  * plus an in-memory `fakeChannelPair` so cross-frame logic is unit-testable without a live iframe.
  */
 
+import { isNonNullObject } from "@jxsuite/schema/guards";
+
 /**
  * A typed, bidirectional message channel. `TOut` is what this side sends; `TIn` is what it
  * receives. Implementations: a real `postMessage` channel over an `<iframe>` (added with the iframe
@@ -26,8 +28,14 @@ export interface IframeChannel<TOut, TIn> {
 /** Envelope key that tags every cross-frame message so foreign `message` events are ignored. */
 const ENVELOPE = "jx:canvas";
 
-interface PostMessageTarget {
-  postMessage: (message: unknown, targetOrigin: string) => void;
+/** What crosses the frame boundary: the session token beside the typed message it authenticates. */
+export interface CanvasEnvelope<T> {
+  [ENVELOPE]: string;
+  payload: T;
+}
+
+interface PostMessageTarget<TOut> {
+  postMessage: (message: CanvasEnvelope<TOut>, targetOrigin: string) => void;
 }
 
 interface MessageSource {
@@ -46,7 +54,7 @@ interface MessageSource {
  * origin.
  */
 export function postMessageChannel<TOut, TIn>(opts: {
-  target: PostMessageTarget;
+  target: PostMessageTarget<TOut>;
   source: MessageSource;
   targetOrigin: string;
   acceptOrigin: string;
@@ -59,12 +67,15 @@ export function postMessageChannel<TOut, TIn>(opts: {
     if (acceptOrigin !== "*" && event.origin !== acceptOrigin) {
       return;
     }
-    const data = event.data as { [ENVELOPE]?: string; payload?: TIn } | null;
-    if (!data || typeof data !== "object" || data[ENVELOPE] !== token) {
+    const envelope: unknown = event.data;
+    if (!isNonNullObject(envelope) || !(ENVELOPE in envelope) || envelope[ENVELOPE] !== token) {
       return;
     }
+    /* SAFETY: The envelope carries this session's secret token, which only the peer channel holds,
+       and that peer's `post` is typed to send exactly `TIn`; a foreign page cannot forge the token. */
+    const payload = ("payload" in envelope ? envelope.payload : undefined) as TIn;
     for (const handler of handlers) {
-      handler(data.payload as TIn);
+      handler(payload);
     }
   };
   source.addEventListener("message", listener);
@@ -84,19 +95,22 @@ export function postMessageChannel<TOut, TIn>(opts: {
   };
 }
 
+/** Both ends of an in-memory channel, and the controls that deliver what they posted. */
+export interface FakeChannelPair<ParentOut, IframeOut> {
+  parent: IframeChannel<ParentOut, IframeOut>;
+  iframe: IframeChannel<IframeOut, ParentOut>;
+  flush: () => void;
+  /** Number of messages waiting to be delivered (both directions). */
+  pending: () => number;
+}
+
 /**
  * Two in-memory channels wired to each other for tests. A message `parent.post(x)` is delivered to
  * the `iframe` side's handlers (and vice versa) only when `flush()` is called — so tests drive the
  * inherently-async postMessage ordering deterministically. Messages posted _during_ a flush are
  * queued for the next flush, never delivered re-entrantly.
  */
-export function fakeChannelPair<ParentOut, IframeOut>(): {
-  parent: IframeChannel<ParentOut, IframeOut>;
-  iframe: IframeChannel<IframeOut, ParentOut>;
-  flush: () => void;
-  /** Number of messages waiting to be delivered (both directions). */
-  pending: () => number;
-} {
+export function fakeChannelPair<ParentOut, IframeOut>(): FakeChannelPair<ParentOut, IframeOut> {
   let toIframe: ParentOut[] = [];
   let toParent: IframeOut[] = [];
   const iframeHandlers = new Set<(m: ParentOut) => void>();

package/src/canvas/iframe-drop.ts

@@ -17,7 +17,7 @@
  */
 
 import { parseJxPath } from "./path-mapping";
-import { displayTagName } from "@jxsuite/schema/guards";
+import { displayTagName, isNonNullObject } from "@jxsuite/schema/guards";
 import { rectOf, elementAtPoint } from "../utils/geometry";
 import { getNodeAtPath, isAncestor, pathsEqual } from "../state";
 import type { DragSrcKind, DropPreview } from "./iframe-protocol";
@@ -52,9 +52,11 @@ const VOID_TAGS = new Set([
  * reuse it. Returns null when no addressable node is found.
  */
 function nearestPathEl(start: Element | null): HTMLElement | null {
-  let el = start instanceof Element ? (start as HTMLElement) : null;
+  // Only an `HTMLElement` is ever stamped (`makeStamper` skips every other node), so the walk
+  // Passes over SVG and other foreign elements on its way up.
+  let el = start;
   while (el) {
-    if (el.dataset?.jxPath) {
+    if (el instanceof HTMLElement && el.dataset.jxPath) {
       return el;
     }
     el = el.parentElement;
@@ -94,15 +96,15 @@ export function computeDropInstruction(
   shadowDoc: JxMutableNode,
   src: DragSrcKind,
 ): DropPreview | null {
-  const serialized = targetEl.dataset?.jxPath;
+  const serialized = targetEl.dataset.jxPath;
   if (serialized == null) {
     return null;
   }
-  const targetPath = parseJxPath(serialized) as JxPath;
+  const targetPath = parseJxPath(serialized);
 
   // Root: pick the nearest child edge among the element's element children.
   if (targetPath.length === 0) {
-    const children = [...targetEl.children] as HTMLElement[];
+    const children = [...targetEl.children];
     if (children.length === 0) {
       return canDrop(src, targetPath)
         ? {
@@ -120,11 +122,10 @@ export function computeDropInstruction(
     return null;
   }
 
-  const node = getNodeAtPath(shadowDoc, targetPath) as JxMutableNode | undefined;
+  const node = getNodeAtPath(shadowDoc, targetPath);
   const tag = (displayTagName(node?.tagName) || "div").toLowerCase();
   const hasElementChildren =
-    Array.isArray(node?.children) &&
-    node.children.some((c: unknown) => c != null && typeof c === "object");
+    Array.isArray(node?.children) && node.children.some((c) => isNonNullObject(c));
   const isLeaf = VOID_TAGS.has(tag) || !hasElementChildren;
 
   const rect = rectFor(targetEl);
@@ -150,7 +151,7 @@ export function computeDropInstruction(
  * parentElementPath(slice(0,-2)) / childIndex(at(-1)) read the same parent + index.
  */
 function nearestChildEdge(
-  children: HTMLElement[],
+  children: Element[],
   cursorY: number,
   parentPath: JxPath,
   src: DragSrcKind,
@@ -175,7 +176,7 @@ function nearestChildEdge(
     }
   }
 
-  const childPath = [...parentPath, "children", closestIdx] as JxPath;
+  const childPath: JxPath = [...parentPath, "children", closestIdx];
   if (!canDrop(src, childPath)) {
     return null;
   }
@@ -192,7 +193,7 @@ function canDrop(src: DragSrcKind, targetPath: JxPath): boolean {
   if (src.type !== "tree-node") {
     return true;
   }
-  const srcPath = src.path as JxPath;
+  const srcPath = src.path;
   if (pathsEqual(srcPath, targetPath)) {
     return false;
   }

package/src/canvas/iframe-editable-root.ts

@@ -35,6 +35,7 @@ import {
   toDomPosition,
 } from "./iframe-position";
 import { serializeJxPath } from "./path-mapping";
+import { isFunction } from "@jxsuite/schema/guards";
 import type { DocPos, DocRange, EditablePredicate } from "./iframe-position";
 import type { JxPath } from "../state";
 
@@ -167,6 +168,14 @@ export interface EditableRootHandle {
   isComposing: () => boolean;
 }
 
+/**
+ * Whether an element carries `dataset`. HTML, SVG and MathML elements all mix in
+ * `HTMLOrSVGElement`; an element from any other namespace has no `dataset` at all.
+ */
+function hasDataset(el: Element): el is Element & HTMLOrSVGElement {
+  return "dataset" in el;
+}
+
 /** Wire the editing host on `container`. */
 export function startEditableRoot(
   container: HTMLElement,
@@ -183,13 +192,13 @@ export function startEditableRoot(
     return mode === undefined || mode === "design" || mode === "edit";
   };
 
-  /** Pending idle-commit timer, or 0 when none is armed. */
-  let commitTimer = 0;
+  /** Pending idle-commit timer, or null when none is armed. */
+  let commitTimer: ReturnType<typeof setTimeout> | null = null;
 
   const cancelCommitTick = () => {
-    if (commitTimer) {
+    if (commitTimer !== null) {
       clearTimeout(commitTimer);
-      commitTimer = 0;
+      commitTimer = null;
     }
   };
 
@@ -202,7 +211,7 @@ export function startEditableRoot(
    * idle commit invisible — without it, typing would jump the caret every time you paused.
    */
   const commitTick = () => {
-    commitTimer = 0;
+    commitTimer = null;
     if (!activeEl || !deps.onCommitTick) {
       return;
     }
@@ -233,7 +242,7 @@ export function startEditableRoot(
       return;
     }
     cancelCommitTick();
-    commitTimer = setTimeout(commitTick, deps.commitDelayMs ?? COMMIT_IDLE_MS) as unknown as number;
+    commitTimer = setTimeout(commitTick, deps.commitDelayMs ?? COMMIT_IDLE_MS);
   };
 
   const onCompositionStart = () => {
@@ -349,7 +358,8 @@ export function startEditableRoot(
   const affectedRange = (
     e: InputEvent,
   ): { from: DocPos; to: DocPos; endEl: HTMLElement } | null => {
-    const [target] = typeof e.getTargetRanges === "function" ? e.getTargetRanges() : [];
+    // Happy-dom ships no `getTargetRanges` at all, so the method's presence is probed, not assumed.
+    const [target] = isFunction(e.getTargetRanges) ? e.getTargetRanges() : [];
     const sel = doc.getSelection();
     const useSelection = sel && sel.rangeCount > 0 && (sel.isCollapsed || !target);
     let startNode: Node | null;
@@ -370,8 +380,7 @@ export function startEditableRoot(
     return from && to && endBlock ? { endEl: endBlock.el, from, to } : null;
   };
 
-  const onBeforeInput = (event: Event) => {
-    const e = event as InputEvent;
+  const onBeforeInput = (e: InputEvent) => {
     if (!editingAllowed()) {
       return;
     }
@@ -435,21 +444,25 @@ export function startEditableRoot(
     if (!editingAllowed() || !deps.onPropActivate) {
       return;
     }
-    let el = e.target instanceof Element ? (e.target as HTMLElement) : null;
+    let el = e.target instanceof Element ? e.target : null;
     while (el && el !== container) {
-      if (el.dataset?.jxBoundProp) {
-        if (el !== activeEl) {
+      if (hasDataset(el) && el.dataset.jxBoundProp) {
+        /* SAFETY: The runtime builds SVG and MathML nodes as `createElementNS(...) as HTMLElement`
+           and stamps `data-jx-bound-prop` through that same `HTMLElement`-typed path, so a
+           foreign-namespace prop host already travels downstream as an `HTMLElement`. */
+        const host = el as HTMLElement;
+        if (host !== activeEl) {
           deactivate();
-          if (deps.onPropActivate(el)) {
+          if (deps.onPropActivate(host)) {
             // Adopt the nested host so the caret landing inside it is not read as a block change.
-            activeEl = el;
+            activeEl = host;
             activeKey = null;
           }
         }
         return;
       }
       // A stamped page block first means this is ordinary page DOM, not component internals.
-      if (el.dataset?.jxPath) {
+      if (hasDataset(el) && el.dataset.jxPath) {
         return;
       }
       el = el.parentElement;
@@ -493,7 +506,7 @@ export function startEditableRoot(
       if (composing) {
         return;
       }
-      if (commitTimer) {
+      if (commitTimer !== null) {
         cancelCommitTick();
         commitTick();
       }

package/src/canvas/iframe-entry.ts

@@ -7,7 +7,7 @@
 
 import { postMessageChannel } from "./iframe-channel";
 import { rectOf } from "../utils/geometry";
-import { displayTagName } from "@jxsuite/schema/guards";
+import { displayTagName, isNonNullObject } from "@jxsuite/schema/guards";
 import {
   applyCanvasDialogOpen,
   applyCanvasPopoverOpen,
@@ -59,16 +59,17 @@ import {
 import { resolveAssetRef } from "./asset-resolve";
 import type { AssetContext } from "./asset-resolve";
 import { KIT_LOADERS } from "@jxsuite/ui/loaders";
-import type { IframeChannel } from "./iframe-channel";
+import type { CanvasEnvelope, IframeChannel } from "./iframe-channel";
 import type {
   CanvasMode,
+  DragOverMsg,
   DragSrcKind,
   FileDropHit,
   IframeToParent,
   LayoutHit,
   ParentToIframe,
 } from "./iframe-protocol";
-import type { JxDocument, JxMutableNode, JxStyle } from "@jxsuite/schema/types";
+import type { JxDocument, JxMutableNode } from "@jxsuite/schema/types";
 import type { IframeRenderCtx, RenderHandle } from "./iframe-render";
 import { setBundleBase } from "../services/bundle-base";
 
@@ -153,12 +154,12 @@ export function fileDropHitFor(
   targetEl: HTMLElement,
   shadowDoc: JxMutableNode | null,
 ): FileDropHit | null {
-  const serialized = targetEl.dataset?.jxPath;
+  const serialized = targetEl.dataset.jxPath;
   if (serialized == null) {
     return null;
   }
   const path = parseJxPath(serialized);
-  const node = shadowDoc ? (getNodeAtPath(shadowDoc, path as JxPath) as JxMutableNode) : undefined;
+  const node = shadowDoc ? getNodeAtPath(shadowDoc, path) : undefined;
   return {
     path,
     rect: rectFor(targetEl),
@@ -186,7 +187,8 @@ export function layoutHitFor(target: EventTarget | null): LayoutHit | null {
     return null;
   }
   return {
-    className: typeof el.className === "string" ? el.className : "",
+    // An `HTMLElement`'s `className` is always the string form (only SVG's is an animated value).
+    className: el.className,
     layoutFile: el.dataset.jxLayoutFile ?? "",
     layoutPath: parseJxPath(el.dataset.jxLayoutPath ?? "[]"),
     rect: rectFor(el),
@@ -194,6 +196,34 @@ export function layoutHitFor(target: EventTarget | null): LayoutHit | null {
   };
 }
 
+/**
+ * The text a failed patch or render reports: the thrown value's `message` when it has one, the
+ * value itself otherwise.
+ */
+function failureText(cause: unknown): string {
+  const message = isNonNullObject(cause) && "message" in cause ? cause.message : undefined;
+  return String(message ?? cause);
+}
+
+/** The edge-hold auto-scroll loop's last cursor, and the drag it belongs to. */
+interface AutoScrollCursor {
+  x: number;
+  y: number;
+  dragSeq: number;
+  withCursor: boolean;
+  src?: DragSrcKind;
+  gen?: number;
+}
+
+/**
+ * The two document APIs the `idle` sample reads, as a frame may or may not provide them. lib.dom
+ * declares both unconditionally; happy-dom implements neither.
+ */
+interface IdleProbeDocument {
+  getAnimations?: Document["getAnimations"];
+  fonts?: FontFaceSet;
+}
+
 /** Set-key keys the patcher applies IN PLACE (never a subtree re-render) — safe under a live edit. */
 const IN_PLACE_KEYS = new Set(["style", "textContent"]);
 
@@ -317,14 +347,7 @@ export function startCanvasIframe(opts: {
   // (the parent has no pointer of its own then). Parent-driven flows (1/2/4) leave `src` undefined
   // And `withCursor` false — the tick falls back to `dragSrc`/`dragGen` and the parent moves the
   // Ghost from its own raw pointer.
-  let autoScrollCursor: {
-    x: number;
-    y: number;
-    dragSeq: number;
-    withCursor: boolean;
-    src?: DragSrcKind;
-    gen?: number;
-  } | null = null;
+  let autoScrollCursor: AutoScrollCursor | null = null;
   const win = container.ownerDocument.defaultView;
 
   function stopAutoScroll(): void {
@@ -353,16 +376,17 @@ export function startCanvasIframe(opts: {
       return;
     }
     const preview = previewAt(autoScrollCursor, src, shadowDoc, container.ownerDocument);
-    channel.post({
-      // Flow 3 (withCursor) re-posts the cursor so the parent keeps tracking the ghost at an edge-hold.
-      ...(autoScrollCursor.withCursor
-        ? { cursor: { x: autoScrollCursor.x, y: autoScrollCursor.y } }
-        : {}),
+    const over: DragOverMsg = {
       dragSeq: autoScrollCursor.dragSeq,
       gen: autoScrollCursor.gen ?? dragGen,
       kind: "dragOver",
       preview,
-    });
+    };
+    // Flow 3 (withCursor) re-posts the cursor so the parent keeps tracking the ghost at an edge-hold.
+    if (autoScrollCursor.withCursor) {
+      over.cursor = { x: autoScrollCursor.x, y: autoScrollCursor.y };
+    }
+    channel.post(over);
     autoScrollFrame = win.requestAnimationFrame(autoScrollTick);
   }
 
@@ -381,13 +405,12 @@ export function startCanvasIframe(opts: {
       stopAutoScroll();
       return;
     }
-    autoScrollCursor = {
-      dragSeq,
-      withCursor: flow3 != null,
-      x: cursor.x,
-      y: cursor.y,
-      ...(flow3 ? { gen: flow3.gen, src: flow3.src } : {}),
-    };
+    const next: AutoScrollCursor = { dragSeq, withCursor: flow3 != null, x: cursor.x, y: cursor.y };
+    if (flow3) {
+      next.gen = flow3.gen;
+      next.src = flow3.src;
+    }
+    autoScrollCursor = next;
     if (!autoScrollFrame) {
       autoScrollFrame = win.requestAnimationFrame(autoScrollTick);
     }
@@ -522,13 +545,11 @@ export function startCanvasIframe(opts: {
   }
 
   function sampleIdle(): Extract<IframeToParent, { kind: "idle" }> {
-    const running =
-      typeof frameDoc.getAnimations === "function"
-        ? frameDoc.getAnimations().filter((a) => a.playState === "running").length
-        : 0;
+    const probe: IdleProbeDocument = frameDoc;
+    const running = probe.getAnimations?.().filter((a) => a.playState === "running").length ?? 0;
     return {
       animations: running,
-      fonts: frameDoc.fonts ? frameDoc.fonts.status === "loaded" : true,
+      fonts: probe.fonts ? probe.fonts.status === "loaded" : true,
       gen: renderedGen,
       images: pendingImageRetries(),
       kind: "idle",
@@ -750,12 +771,7 @@ export function startCanvasIframe(opts: {
       // The wrong scope); the parent additionally gen-gates the reply against its own state.
       const results =
         msg.gen === renderedGen && renderCtx && shadowDoc
-          ? evaluateLiveExprs(
-              msg.exprs,
-              renderCtx.defs as Record<string, unknown>,
-              shadowDoc,
-              msg.contextPath,
-            )
+          ? evaluateLiveExprs(msg.exprs, renderCtx.defs, shadowDoc, msg.contextPath)
           : [];
       channel.post({ gen: msg.gen, kind: "evalResult", reqId: msg.reqId, results });
       return;
@@ -820,11 +836,7 @@ export function startCanvasIframe(opts: {
         channel.post({ gen, kind: "patchComplete" });
         armIdleWatch();
       } catch (error) {
-        channel.post({
-          gen,
-          kind: "patchError",
-          message: String((error as Error)?.message ?? error),
-        });
+        channel.post({ gen, kind: "patchError", message: failureText(error) });
       }
       return;
     }
@@ -835,14 +847,10 @@ export function startCanvasIframe(opts: {
       if (msg.gen !== renderedGen || !shadowDoc) {
         return;
       }
-      (shadowDoc as { style?: JxStyle }).style = msg.style as JxStyle;
+      shadowDoc.style = msg.style;
       const rootEl = container.firstElementChild;
       if (rootEl instanceof HTMLElement) {
-        reapplyStyle(
-          rootEl,
-          msg.style as JxStyle,
-          (shadowDoc as { $media?: Record<string, string> }).$media ?? {},
-        );
+        reapplyStyle(rootEl, msg.style, shadowDoc.$media ?? {});
       }
       return;
     }
@@ -945,7 +953,10 @@ export function startCanvasIframe(opts: {
     if (msg.kind === "redefineElement") {
       /* The canvas half of embedding.md §7. The definition is replaced in THIS realm; instances
          already on the canvas keep the old one until the host's next render replaces them. */
-      void redefineElement(msg.doc as never, msg.base);
+      /* SAFETY: The host posts only the component definition a save just wrote
+         (`redefineElementOnCanvases`), a whole `.json` element document, and `redefineElement`
+         itself rejects one whose `tagName` is not a hyphenated literal. */
+      void redefineElement(msg.doc as JxDocument, msg.base);
       return;
     }
     if (msg.kind === "setLocale") {
@@ -988,6 +999,8 @@ export function startCanvasIframe(opts: {
     // A document with no format, where the studio's own element metadata answers on its own.
     setEditableVerdicts(msg.editableTags ?? null);
     const { gen, mapperCtx } = msg;
+    /* SAFETY: The host posts `shadowDoc` as a JSON round-trip of the tab's raw page document (or of
+       the stylebook specimen), so it is a `JxMutableNode` in the forward-op coordinate space. */
     const rawDoc = msg.shadowDoc as JxMutableNode;
     void (async () => {
       try {
@@ -1002,9 +1015,11 @@ export function startCanvasIframe(opts: {
            than a theoretical one. It used to be exactly that, one orphaned `<style>` per styled
            element per render. */
         resetDocumentStyles(container.ownerDocument);
-        handle = await renderResolvedDocument({
+        const renderOpts: Parameters<typeof renderResolvedDocument>[0] = {
           assets: versionedAssets(msg.assets ?? null),
           container,
+          /* SAFETY: The host posts `doc` as a JSON round-trip of `resolveCanvasDocument`'s render
+             document (or the stylebook specimen), which is the resolved `JxDocument` it renders. */
           doc: msg.doc as JxDocument,
           docBase: msg.docBase,
           mapperCtx: {
@@ -1019,8 +1034,11 @@ export function startCanvasIframe(opts: {
           popoverOpen: msg.popoverOpen ? serializeJxPath(msg.popoverOpen) : null,
           dialogOpen: msg.dialogOpen ? serializeJxPath(msg.dialogOpen) : null,
           siteStyle: msg.siteStyle,
-          ...(msg.allowAutoRequests ? { allowAutoRequests: true } : {}),
-        });
+        };
+        if (msg.allowAutoRequests) {
+          renderOpts.allowAutoRequests = true;
+        }
+        handle = await renderResolvedDocument(renderOpts);
         if (gen === latestGen) {
           /* A render replaces the DOM, so the open attribute goes with it. The host sends the value
              on the render message for exactly this reason; a frame that kept only its own copy
@@ -1042,7 +1060,7 @@ export function startCanvasIframe(opts: {
           // BuildScope returns, and serializeDataScope reads defs[key], so the effect tracks those
           // Refs and RE-POSTS an updated snapshot when the data settles (the host gen-gates stale
           // Ones). Isolated in try/catch: a serialization failure never breaks the render ack above.
-          const defs = handle.ctx.defs as Record<string, unknown>;
+          const { defs } = handle.ctx;
           stopDataScopeWatch = observeScope(() => {
             try {
               channel.post({ gen, kind: "dataScope", scope: serializeDataScope(defs) });
@@ -1054,11 +1072,7 @@ export function startCanvasIframe(opts: {
           postContentHeight();
         }
       } catch (error) {
-        channel.post({
-          gen,
-          kind: "renderError",
-          message: String((error as Error)?.message ?? error),
-        });
+        channel.post({ gen, kind: "renderError", message: failureText(error) });
       }
     })();
   });
@@ -1094,7 +1108,9 @@ export function startCanvasIframe(opts: {
 interface BootWindow {
   location: { search: string };
   document: { querySelector: (selectors: string) => Element | null; body: HTMLElement };
-  parent: { postMessage: (message: unknown, targetOrigin: string) => void };
+  parent: {
+    postMessage: (message: CanvasEnvelope<IframeToParent>, targetOrigin: string) => void;
+  };
   addEventListener: (type: "message", listener: (event: MessageEvent) => void) => void;
   removeEventListener: (type: "message", listener: (event: MessageEvent) => void) => void;
 }
@@ -1122,8 +1138,9 @@ export function bootCanvasIframe(win: BootWindow): () => void {
         "The parent origin did not round-trip; the channel relies on the shared token alone.",
     );
   }
-  const container = (win.document.querySelector("#jx-canvas-root") ??
-    win.document.body) as HTMLElement;
+  // `canvas.html` draws `#jx-canvas-root` as a `<div>`; a page without it renders into `<body>`.
+  const root = win.document.querySelector("#jx-canvas-root");
+  const container = root instanceof HTMLElement ? root : win.document.body;
   const channel = postMessageChannel<IframeToParent, ParentToIframe>({
     acceptOrigin: parentOrigin,
     source: win,
@@ -1136,5 +1153,5 @@ export function bootCanvasIframe(win: BootWindow): () => void {
 
 // Boot only when actually loaded as the iframe document (has a real parent frame), never in tests.
 if (typeof window !== "undefined" && window.parent !== window) {
-  bootCanvasIframe(window as unknown as BootWindow);
+  bootCanvasIframe(window);
 }