@jxsuite/studio 6.1.0 → 6.1.2

package/src/canvas/iframe-protocol.ts

@@ -12,16 +12,7 @@
 import type { AssetContext } from "./asset-resolve";
 import type { JxDocOp } from "../tabs/patch-ops";
 import type { JxContentResult, SlashCommand } from "../editor/inline-edit";
-import type { JxExpressionNode, JxMutableNode } from "@jxsuite/schema/types";
-
-/**
- * The wire form of a value-carrying document op (the `forward` half of a recorded
- * {@link JxDocOpPair} — see {@link file://../tabs/patch-ops.ts}). It is structurally a
- * {@link JxDocOp}: it carries the inserted/replaced `node` and the set `value`, NOT just a path, so
- * the iframe can fold it into its shadow doc and re-render subtrees without ever reading the
- * parent's reactive document.
- */
-export type WireDocOp = JxDocOp;
+import type { JsonObject, JxExpressionNode, JxMutableNode, JxStyle } from "@jxsuite/schema/types";
 
 export const CANVAS_MODES = ["preview", "design", "edit", "stylebook", "git-diff"] as const;
 
@@ -37,7 +28,7 @@ export const CANVAS_MODES = ["preview", "design", "edit", "stylebook", "git-diff
 export type CanvasMode = (typeof CANVAS_MODES)[number];
 
 export function isCanvasMode(value: unknown): value is CanvasMode {
-  return typeof value === "string" && (CANVAS_MODES as readonly string[]).includes(value);
+  return typeof value === "string" && CANVAS_MODES.some((mode) => mode === value);
 }
 
 /**
@@ -121,7 +112,7 @@ export type ParentToIframe =
        */
       assets?: AssetContext | null;
       mapperCtx: WireMapperCtx;
-      siteStyle: Record<string, unknown> | null;
+      siteStyle: JxStyle | null;
       // Forced color-scheme preview (spec.md §9.5): "light"/"dark" sets data-color-scheme on the
       // Iframe root, null clears it (auto — follow the OS).
       colorScheme: "light" | "dark" | null;
@@ -239,7 +230,7 @@ export type ParentToIframe =
   // Render-free; the superseding render carries the same style via its own siteStyle.
   | {
       kind: "siteStyleUpdate";
-      siteStyle: Record<string, unknown> | null;
+      siteStyle: JxStyle | null;
       media: Record<string, string>;
     }
   // Ask the iframe to measure the given document paths and post their current rects back. Used to
@@ -255,7 +246,12 @@ export type ParentToIframe =
   // In place. `gen` matches the last render so the iframe drops patches superseded by a re-render.
   | {
       kind: "patch";
-      forwardOps: WireDocOp[];
+      /**
+       * The `forward` halves of the recorded {@link JxDocOp} pairs (tabs/patch-ops.ts). Each carries
+       * the inserted/replaced `node` and the set `value`, not just a path, so the iframe folds it
+       * into its shadow doc without ever reading the parent's reactive document.
+       */
+      forwardOps: JxDocOp[];
       gen: number;
       /**
        * Paths whose DOM the RECIPIENT already has correct, because this patch is the echo of an
@@ -273,7 +269,7 @@ export type ParentToIframe =
   // Regenerates the whole scoped-CSS cascade (real @media included) without a re-render. `style` is
   // Already transposed parent-side (transposeStylebookStyle); `gen` must equal the iframe's
   // RenderedGen — a stale update is dropped (the superseding render carries the same style).
-  | { kind: "styleUpdate"; style: Record<string, unknown>; gen: number }
+  | { kind: "styleUpdate"; style: JxStyle; gen: number }
   // Enter inline editing on the node at `path` (used to re-enter after a split/insert re-renders).
   | {
       kind: "enterEdit";
@@ -490,7 +486,7 @@ export type IframeToParent =
   // `S.canvas.scope` so the data-explorer panel shows live data instead of "pending" (the iframe,
   // Not the parent, now resolves the scope). `gen` lets the parent drop a snapshot from a superseded
   // Render. Posted right after `renderComplete`; values are JSON-safe deep clones (see serialize-scope).
-  | { kind: "dataScope"; gen: number; scope: Record<string, unknown> }
+  | { kind: "dataScope"; gen: number; scope: JsonObject }
   // The frame's own quiescence, ANSWERED rather than polled (studio.md §13.5).
   // Nothing in the parent realm can see inside a cross-origin frame, so a parent that wanted to
   // Know whether the canvas had settled could only sleep. The frame samples itself at its own rAF
@@ -563,6 +559,9 @@ export type IframeToParent =
   // Inline editing started in the iframe (the parent shows the format toolbar from here). `prop`
   // Names the component-instance prop when the session edits prop-bound text (plain sessions).
   | { kind: "editStart"; path: (string | number)[]; prop?: string }
+  // The first keystroke of a typing burst, ahead of the idle tick's commit: the parent marks the tab
+  // Dirty now, so Save is enabled the instant there is text a save would keep.
+  | { kind: "editInput" }
   // Committed inline-edit content (rich `children` else `textContent`) for the parent to persist.
   | {
       kind: "editCommit";

package/src/canvas/iframe-render.ts

@@ -38,7 +38,8 @@ import { elementForPath } from "./iframe-position";
 import type { AssetContext } from "./asset-resolve";
 import { SITE_STYLE_ID, buildSiteStyleCSS } from "@jxsuite/site/site-style";
 import type { CanvasMode, WireDiffMarks } from "./iframe-protocol";
-import type { JxDocument } from "@jxsuite/schema/types";
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
+import type { JxDocument, JxElement, JxStyle } from "@jxsuite/schema/types";
 import type { PathMapCtx } from "./path-mapping";
 
 /**
@@ -61,18 +62,12 @@ export interface RenderHandle {
   ctx: IframeRenderCtx;
 }
 
-interface HeadEntry {
-  tagName?: string;
-  attributes?: Record<string, unknown>;
-  textContent?: string;
-}
-
 /**
  * Register the document's `$elements` (components) in this iframe realm so the runtime can render
  * them.
  */
 export async function registerElements(doc: JxDocument, docBase: string): Promise<void> {
-  const elements = (doc as { $elements?: unknown[] }).$elements;
+  const elements = doc.$elements;
   if (!Array.isArray(elements)) {
     return;
   }
@@ -81,13 +76,16 @@ export async function registerElements(doc: JxDocument, docBase: string): Promis
   await Promise.all(
     elements.map(async (entry) => {
       const task = (async () => {
-        if (typeof entry === "string") {
+        if (isString(entry)) {
           const specifier =
             entry.startsWith("/") || entry.startsWith(".") ? entry : `/node_modules/${entry}`;
           await import(specifier);
-        } else if (entry && typeof entry === "object" && "$ref" in entry) {
-          await defineElement(new URL(String((entry as { $ref: string }).$ref), docBase).href);
-        } else if (entry && typeof entry === "object") {
+        } else if (isNonNullObject(entry) && "$ref" in entry) {
+          await defineElement(new URL(String(entry.$ref), docBase).href);
+        } else if (isNonNullObject(entry)) {
+          /* SAFETY: an `$elements` entry that is neither a specifier nor a `$ref` is an inline
+           * component definition by the schema (JxDocument is JxElement with a literal tagName).
+           * A malformed one throws inside this task, which the race below catches and logs. */
           await defineElement(entry as JxDocument, docBase);
         }
       })();
@@ -696,11 +694,11 @@ export function syncStylebookCss(doc: Document, mode: CanvasMode): void {
  * selectors can win (spec.md §9.5), and so removed tokens can't linger on reused iframes.
  */
 export function applySiteStyle(
-  siteStyle: Record<string, unknown> | null | undefined,
+  siteStyle: JxStyle | null | undefined,
   mediaQueries: Record<string, string> = {},
 ): void {
   const existing = document.head.querySelector(`#${SITE_STYLE_ID}`);
-  if (!siteStyle || typeof siteStyle !== "object") {
+  if (!siteStyle || !isNonNullObject(siteStyle)) {
     existing?.remove();
     return;
   }
@@ -746,15 +744,15 @@ export function applyPreviewColorScheme(doc: Document, scheme: "light" | "dark"
  * @docs studio/interface/canvas
  */
 export function applyCanvasPopoverOpen(root: ParentNode, path: string | null): void {
-  for (const el of root.querySelectorAll("[data-jx-popover-open]")) {
-    delete (el as HTMLElement).dataset.jxPopoverOpen;
+  for (const el of root.querySelectorAll<HTMLElement>("[data-jx-popover-open]")) {
+    delete el.dataset.jxPopoverOpen;
   }
   if (path === null) {
     return;
   }
-  const target = root.querySelector(`[data-jx-popover]${jxPathSelector(path)}`);
+  const target = root.querySelector<HTMLElement>(`[data-jx-popover]${jxPathSelector(path)}`);
   if (target) {
-    (target as HTMLElement).dataset.jxPopoverOpen = "";
+    target.dataset.jxPopoverOpen = "";
   }
 }
 
@@ -783,26 +781,27 @@ export function applyCanvasPopoverOpen(root: ParentNode, path: string | null): v
  * backdrop and all.
  */
 export function applyCanvasDialogOpen(root: ParentNode, path: string | null): void {
-  for (const el of root.querySelectorAll("[data-jx-dialog-open]")) {
-    delete (el as HTMLElement).dataset.jxDialogOpen;
+  for (const el of root.querySelectorAll<HTMLElement>("[data-jx-dialog-open]")) {
+    delete el.dataset.jxDialogOpen;
   }
   if (path === null) {
     return;
   }
-  const target = root.querySelector(`dialog${jxPathSelector(path)}`);
+  const target = root.querySelector<HTMLElement>(`dialog${jxPathSelector(path)}`);
   if (target) {
-    (target as HTMLElement).dataset.jxDialogOpen = "";
+    target.dataset.jxDialogOpen = "";
   }
 }
 
 /** Inject the document's `$head` (link/meta/script) into the iframe's <head>, de-duped by href/src. */
 export function injectHead(doc: JxDocument, assets: AssetContext | null = null): void {
-  const head = (doc as { $head?: HeadEntry[] }).$head;
+  const head = doc.$head;
   if (!Array.isArray(head)) {
     return;
   }
   for (const entry of head) {
-    if (!entry?.tagName) {
+    // A `$head` array read off disk can hold a null or a tagless entry; neither emits anything.
+    if (!isNonNullObject(entry) || !entry.tagName) {
       continue;
     }
     const tag = String(entry.tagName).toLowerCase();
@@ -810,10 +809,10 @@ export function injectHead(doc: JxDocument, assets: AssetContext | null = null):
     if (tag === "script" && !entry.attributes?.src) {
       continue;
     }
-    const attrs = { ...entry.attributes } as Record<string, unknown>;
+    const attrs = { ...entry.attributes };
     for (const key of ["href", "src"]) {
       const val = attrs[key];
-      if (typeof val !== "string" || val === "") {
+      if (!isString(val) || val === "") {
         continue;
       }
       if (!val.startsWith("/") && !val.startsWith(".") && !val.startsWith("http")) {
@@ -833,7 +832,7 @@ export function injectHead(doc: JxDocument, assets: AssetContext | null = null):
       el.setAttribute(k, String(v));
     }
     if (entry.textContent) {
-      el.textContent = entry.textContent;
+      el.textContent = String(entry.textContent);
     }
     document.head.append(el);
   }
@@ -856,7 +855,7 @@ export function makeStamper(ctx: PathMapCtx) {
       (island) => path.length > island.length && island.every((seg, i) => path[i] === seg),
     );
 
-  return (created: Node, path: (string | number)[], def: unknown) => {
+  return (created: Node, path: (string | number)[], def: JxElement | string) => {
     if (!(created instanceof HTMLElement)) {
       return;
     }
@@ -866,7 +865,10 @@ export function makeStamper(ctx: PathMapCtx) {
     // Editable tree and re-render a live instance with default state. Mark the root so the
     // Runtime's element class leaves it alone (see defineElement's connectedCallback guard).
     const isDefinitionRoot =
-      path.length === 0 && (def as { tagName?: string } | null)?.tagName?.includes("-");
+      path.length === 0 &&
+      isNonNullObject(def) &&
+      isString(def.tagName) &&
+      def.tagName.includes("-");
     if (isDefinitionRoot) {
       created.dataset.jxDefinitionRoot = "";
     }
@@ -984,7 +986,7 @@ export async function renderResolvedDocument(opts: {
   docBase: string;
   mode: CanvasMode;
   mapperCtx: PathMapCtx;
-  siteStyle?: Record<string, unknown> | null;
+  siteStyle?: JxStyle | null;
   /**
    * How this host addresses project media, or null when the canvas origin serves the site's own URL
    * space (desktop, `jx dev`) and references need no resolution at all.
@@ -1018,8 +1020,11 @@ export async function renderResolvedDocument(opts: {
   // Sections feeding back into an ever-growing height. Set every render (the iframe always wants it).
   setCanvasViewportTranspose(true);
   // De-link `<a href>` in design/edit so clicks select the anchor instead of navigating the iframe;
-  // Preview keeps real links live (mirrors the server-function gate above).
-  setCanvasDelinkAnchors(opts.mode !== "preview");
+  // Preview keeps real links live (mirrors the server-function gate above). So does Project Styles:
+  // An `<a>` without `href` is not a link, so `:link`, `:any-link` and the UA's link colour could
+  // Never match its specimen, and a project could not see the link styles it was setting there.
+  // Its clicks are refused in the frame instead (`iframe-interaction.ts`).
+  setCanvasDelinkAnchors(opts.mode !== "preview" && opts.mode !== "stylebook");
   /* De-popover in the same modes and for the same reason: an OPEN popover is in the top layer,
      whose containing block is the viewport — a fiction here, since the frame is sized to its own
      content — and which contributes to no ancestor's scrollable overflow, so the artboard could
@@ -1034,7 +1039,7 @@ export async function renderResolvedDocument(opts: {
   // Iframe clears it (page-level templates are inert in design/edit via prepareForEditMode, so only
   // Component internals get stamped).
   setStampPropBindings(opts.mode === "design" || opts.mode === "edit");
-  applySiteStyle(opts.siteStyle, (opts.doc as { $media?: Record<string, string> }).$media ?? {});
+  applySiteStyle(opts.siteStyle, opts.doc.$media ?? {});
   injectHead(opts.doc, assets);
   syncEditModeCss(opts.container.ownerDocument, opts.mode);
   // The substitute rules for the attributes the de-link above renamed. Same predicate as the
@@ -1049,7 +1054,7 @@ export async function renderResolvedDocument(opts: {
   // But no own `$media` resolves the breakpoint to its real query (the iframe path calls buildScope
   // Directly and never the runtime's `Jx()` entry, which is the only other place _rootMedia is set).
   // Set it every render (even to `{}`) so a stale map from a previous document cannot leak.
-  setRootMedia((opts.doc as { $media?: Record<string, string> }).$media ?? {});
+  setRootMedia(opts.doc.$media ?? {});
   // Register components BEFORE renderNode. The runtime only applies a custom element's `$props` when
   // That element is ALREADY defined (renderNode gates renderCustomElementWithProps on a truthy
   // `customElements.get(tagName)`); if we register after render, every component paints with its
@@ -1063,8 +1068,8 @@ export async function renderResolvedDocument(opts: {
   // The scope MUST be the runtime's (runScoped): renderNode creates its binding effects with the
   // Runtime's copy of @vue/reactivity, and scope collection is per module instance — a studio
   // EffectScope here collects nothing and dispose() would leak every effect of this render.
-  const { result: el, stop } = runScoped(
-    () => renderNode(opts.doc, $defs, { _path: [], onNodeCreated }) as HTMLElement,
+  const { result: el, stop } = runScoped(() =>
+    renderNode(opts.doc, $defs, { _path: [], onNodeCreated }),
   );
   opts.container.replaceChildren(el);
   applyCanvasPopoverOpen(opts.container, opts.popoverOpen ?? null);

package/src/canvas/iframe-slash.ts

@@ -21,7 +21,17 @@ import type { IframeToParent, ParentToIframe } from "./iframe-protocol";
 
 type SlashNavKey = Extract<IframeToParent, { kind: "slashNav" }>["key"];
 
-const NAV_KEYS = new Set(["ArrowUp", "ArrowDown", "Enter", "Escape"]);
+const NAV_KEYS = new Set<string>([
+  "ArrowUp",
+  "ArrowDown",
+  "Enter",
+  "Escape",
+] satisfies SlashNavKey[]);
+
+/** Whether `key` is one of the four keys the parent menu navigates by. */
+function isNavKey(key: string): key is SlashNavKey {
+  return NAV_KEYS.has(key);
+}
 
 /**
  * Register the bridge SlashController for this iframe realm and wire its keyboard/dismissal
@@ -55,28 +65,31 @@ export function startIframeSlashBridge(
       open = true;
       lastPostedFilter = filter;
       const r = rectOf(anchorEl);
-      channel.post({
+      const message: Extract<IframeToParent, { kind: "slashShow" }> = {
         filter,
         kind: "slashShow",
         rect: { height: r.height, width: r.width, x: r.left, y: r.top },
-        /* Carried, because the parent draws the menu and only the FRAME knows why it opened. A
-           menu opened by name has no "/…" run in the document to filter with, so it needs its own
-           field; the "/" gesture needs none, because the author types into the block. This option
-           was dropped at this boundary and the loss was invisible — the menu still appeared, just
-           with no way past fifteen items but scrolling. */
-        ...(cbs.showFilter === true ? { showFilter: true } : {}),
-      });
+      };
+      /* Carried, because the parent draws the menu and only the FRAME knows why it opened. A
+         menu opened by name has no "/…" run in the document to filter with, so it needs its own
+         field; the "/" gesture needs none, because the author types into the block. This option
+         was dropped at this boundary and the loss was invisible — the menu still appeared, just
+         with no way past fifteen items but scrolling. */
+      if (cbs.showFilter === true) {
+        message.showFilter = true;
+      }
+      channel.post(message);
     },
   };
   setSlashController(controller);
 
   const onKeyDown = (e: KeyboardEvent) => {
-    if (!open || !NAV_KEYS.has(e.key)) {
+    if (!open || !isNavKey(e.key)) {
       return;
     }
     e.preventDefault();
     e.stopPropagation();
-    channel.post({ key: e.key as SlashNavKey, kind: "slashNav" });
+    channel.post({ key: e.key, kind: "slashNav" });
   };
   const onMouseDown = () => {
     // The parent menu's outside-click listener can't see iframe clicks — any in-iframe press while

package/src/canvas/iframe-subtree.ts

@@ -12,6 +12,7 @@
  */
 
 import { releaseElementStyles, renderNode, runScoped } from "@jxsuite/runtime";
+import { isNumber, isString } from "@jxsuite/schema/guards";
 import { getNodeAtPath } from "../state";
 import { makeStamper } from "./iframe-render";
 import { prepareForEditMode } from "../utils/edit-display";
@@ -39,11 +40,14 @@ export function renderSubtreeIframe(
   docPath: JxPath,
   ctx: IframeRenderCtx,
 ): HTMLElement | Text {
+  /* SAFETY: a widening of getNodeAtPath's declared return. A patch path addresses an entry of a
+   * `children` array, which the schema types as `JxMutableNode | string`, and a missing step
+   * answers undefined, so those three cases are the whole range. */
   const node = getNodeAtPath(shadowDoc, docPath) as JxMutableNode | string | undefined;
   if (node === undefined) {
     throw new Error(`iframe-patch-node-not-found:${docPath.join("/")}`);
   }
-  const def = typeof node === "string" ? node : prepareForEditMode(stripEventHandlers(node));
+  const def = isString(node) ? node : prepareForEditMode(stripEventHandlers(node));
   const { result: rendered, stop } = runScoped(() =>
     renderNode(def, ctx.defs, {
       _path: docPathToRenderPath(docPath, ctx),
@@ -98,7 +102,7 @@ function docPathToRenderPath(docPath: JxPath, ctx: IframeRenderCtx): (string | n
   const { mapperCtx } = ctx;
   if (mapperCtx.layoutWrapped && mapperCtx.pageContentPrefix && docPath[0] === "children") {
     const [, idx] = docPath;
-    return typeof idx === "number"
+    return isNumber(idx)
       ? [
           ...mapperCtx.pageContentPrefix,
           idx + (mapperCtx.pageContentOffset ?? 0),

package/src/canvas/path-mapping.ts

@@ -11,6 +11,8 @@
  * result for the `data-jx-path` attribute.
  */
 
+import { isJsonObject, isNonNullObject, isNumber, isString } from "@jxsuite/schema/guards";
+import type { JxElement } from "@jxsuite/schema/types";
 import type { JxPath } from "../state";
 
 /**
@@ -83,22 +85,27 @@ export function wrapsPageContent(path: JxPath, prefix: JxPath | null): boolean {
  * Resolve a runtime render path to a document path (or flag it as layout-originated). Pure — the
  * caller decides whether to record the result in a WeakMap or `data-jx-*` attributes.
  */
-export function classifyRenderNode(path: JxPath, def: unknown, ctx: PathMapCtx): RenderNodeClass {
+export function classifyRenderNode(
+  path: JxPath,
+  def: JxElement | string,
+  ctx: PathMapCtx,
+): RenderNodeClass {
   // Layout-originated nodes have no page-document path; the caller stamps their origin instead
   // (data-jx-layout-path / data-jx-layout-file).
-  const marker =
-    ctx.layoutWrapped && typeof def === "object"
-      ? (def as { $__layout?: unknown } | null)?.$__layout
-      : undefined;
+  const marker = ctx.layoutWrapped && isNonNullObject(def) ? def["$__layout"] : undefined;
   if (marker) {
-    const origin = (typeof marker === "object" ? marker : {}) as Partial<LayoutMarker>;
+    // A legacy bare `true` marker carries no origin, so it reads as an empty one.
+    const origin = isJsonObject(marker) ? marker : {};
+    const { file, path: originPath } = origin;
     return {
       // The root is never chrome even when the layout distributed nothing: it IS the render, and a
       // Dimmed, frozen root would be a canvas nobody can touch.
       chrome: path.length > 0 && !wrapsPageContent(path, ctx.pageContentPrefix),
       kind: "layout",
-      layoutFile: typeof origin.file === "string" ? origin.file : "",
-      layoutPath: Array.isArray(origin.path) ? origin.path : [],
+      layoutFile: isString(file) ? file : "",
+      /* SAFETY: markLayoutNodes (canvas-live-render.ts) is the only writer of `$__layout`, and the
+       * `path` it stamps is a LayoutMarker's JxPath. */
+      layoutPath: Array.isArray(originPath) ? (originPath as JxPath) : [],
     };
   }
 
@@ -112,10 +119,9 @@ export function classifyRenderNode(path: JxPath, def: unknown, ctx: PathMapCtx):
     if (path.length >= pfx.length && pfx.every((seg, i) => path[i] === seg)) {
       const rest = path.slice(pfx.length);
       const [containerIdx] = rest;
-      mappedPath =
-        typeof containerIdx === "number"
-          ? ["children", containerIdx - (ctx.pageContentOffset ?? 0), ...rest.slice(1)]
-          : ["children", ...rest];
+      mappedPath = isNumber(containerIdx)
+        ? ["children", containerIdx - (ctx.pageContentOffset ?? 0), ...rest.slice(1)]
+        : ["children", ...rest];
     }
   }
 
@@ -154,5 +160,6 @@ export function serializeJxPath(path: JxPath): string {
 
 /** Decode a `data-jx-path` attribute back into a document path. */
 export function parseJxPath(serialized: string): JxPath {
+  // SAFETY: only serializeJxPath writes `data-jx-path`, and it is JSON.stringify of a JxPath.
   return JSON.parse(serialized) as JxPath;
 }

package/src/canvas/popover-path.ts

@@ -14,6 +14,7 @@
 import { activeTab } from "../workspace/workspace";
 import { getNodeAtPath } from "../state";
 import { documentHasPopover, isPopover } from "@jxsuite/schema/overlays";
+import { isNonNullObject } from "@jxsuite/schema/guards";
 import { INVOKER_TAGS, POPOVER_TAGS } from "@jxsuite/ui";
 import { primarySelection } from "../tabs/selection";
 import type { JxMutableNode } from "@jxsuite/schema/types";
@@ -49,7 +50,7 @@ export function ancestorPopoverPath(
   for (let end = path.length; end >= 0; end -= 1) {
     const prefix = path.slice(0, end);
     const node = getNodeAtPath(doc, prefix);
-    if (node && typeof node === "object" && isPopover(node, KIT_SCOPE)) {
+    if (isNonNullObject(node) && isPopover(node, KIT_SCOPE)) {
       return prefix;
     }
   }
@@ -72,13 +73,16 @@ export function ancestorPopoverPath(
  * @returns The popover's path, or null.
  */
 export function popoverPathFor(tab: Tab, explicit?: JxPath): JxPath | null {
+  /* SAFETY: a widening, not a narrowing. A tab built by createTab always carries a document, but
+   * the command is a public entry point and the contract (pinned in popover-state.test.ts) is that
+   * a tab record without one answers null rather than throwing inside getNodeAtPath. */
   const doc = tab.doc.document as JxMutableNode | undefined;
   if (!doc) {
     return null;
   }
   if (explicit) {
     const node = getNodeAtPath(doc, explicit);
-    return node && typeof node === "object" && isPopover(node, KIT_SCOPE) ? explicit : null;
+    return isNonNullObject(node) && isPopover(node, KIT_SCOPE) ? explicit : null;
   }
   return ancestorPopoverPath(doc, primarySelection(tab.session.selection));
 }
@@ -101,6 +105,6 @@ export function popoverPathFor(tab: Tab, explicit?: JxPath): JxPath | null {
  * @returns True when the focused document declares at least one popover.
  */
 export function activeDocumentHasPopover(): boolean {
-  const doc = activeTab.value?.doc.document as JxMutableNode | undefined;
+  const doc = activeTab.value?.doc.document;
   return doc ? documentHasPopover(doc, KIT_SCOPE) : false;
 }

package/src/canvas/popover-state.ts

@@ -31,7 +31,6 @@ import { effect, pauseTracking, resetTracking } from "../reactivity";
 import { postPopoverOpen, revealCanvasPath } from "./iframe-host";
 import { primarySelection } from "../tabs/selection";
 import { updateSession } from "../store";
-import type { JxMutableNode } from "@jxsuite/schema/types";
 import type { JxPath } from "../state";
 import type { Tab } from "../tabs/tab";
 
@@ -59,7 +58,7 @@ export function setOpenPopover(tab: Tab, path: JxPath | null): void {
 
 /** Open the popover containing `path`, if any. Returns whether anything changed. */
 function openPopoverFor(tab: Tab, path: JxPath | null): boolean {
-  const target = ancestorPopoverPath(tab.doc.document as JxMutableNode, path);
+  const target = ancestorPopoverPath(tab.doc.document, path);
   if (target === null || samePath(tab.session.ui.openPopover, target)) {
     return false;
   }

package/src/canvas/serialize-scope.ts

@@ -12,6 +12,10 @@
  * Pure and DOM-free — no reactivity/runtime imports — so it stays trivially unit-testable.
  */
 
+import { isFunction } from "@jxsuite/schema/guards";
+import type { JsonObject, JsonValue } from "@jxsuite/schema/types";
+import type { JxScope } from "@jxsuite/runtime/types";
+
 /**
  * Per-value size cap (in JSON-string chars). A single large content collection can be tens of KB;
  * past this cap we store a small placeholder so one big data source can't bloat every render's
@@ -34,18 +38,21 @@ const LARGE_VALUE_PLACEHOLDER = "[large value omitted]";
  * @param defs The resolved `$defs` scope (may be a Vue reactive proxy).
  * @returns A plain object safe to `postMessage` (every value is JSON-round-trippable).
  */
-export function serializeDataScope(defs: Record<string, unknown>): Record<string, unknown> {
-  const out: Record<string, unknown> = {};
+export function serializeDataScope(defs: JxScope): JsonObject {
+  const out: JsonObject = {};
   for (const key of Object.keys(defs)) {
     try {
       // Reading through the reactive proxy auto-unwraps a top-level ref/computed to its value, and
       // Can THROW (a computed getter that throws) — done inside the try so that maps the key to null
       // Rather than aborting the whole snapshot.
       const value = defs[key];
-      if (typeof value === "function") {
+      if (isFunction(value)) {
         continue; // Data sources only — a resolved server/handler fn isn't a "value".
       }
-      const json = JSON.stringify(value);
+      /* SAFETY: a widening of lib.d.ts's `string` to the real range. JSON.stringify answers
+       * undefined for a top-level undefined, a symbol, or a value whose toJSON() returns undefined
+       * (ECMA-262 SerializeJSONProperty), and the branch below depends on seeing that. */
+      const json = JSON.stringify(value) as string | undefined;
       if (json === undefined) {
         // JSON.stringify returns undefined for a bare function/symbol/undefined at the top level.
         out[key] = null;
@@ -55,7 +62,8 @@ export function serializeDataScope(defs: Record<string, unknown>): Record<string
         out[key] = LARGE_VALUE_PLACEHOLDER;
         continue;
       }
-      out[key] = JSON.parse(json) as unknown;
+      // SAFETY: `json` is JSON.stringify's own output above, so it parses back to JSON data.
+      out[key] = JSON.parse(json) as JsonValue;
     } catch {
       // A circular structure or a throwing getter → the key exists but carries no serializable value.
       out[key] = null;

package/src/canvas/stage-scrollbar.ts

@@ -32,6 +32,7 @@
  */
 
 import { PANE_SELECTOR } from "../surfaces/pane-grid";
+import { stageOf } from "./surface-registry";
 import type { CanvasSurface } from "./surface-registry";
 
 /**
@@ -61,7 +62,7 @@ export function scrollbarWidthOf(scroller: HTMLElement): number {
 
 /** The cell a stage belongs to, or the document root when it is outside every cell. */
 function cellOf(surface: CanvasSurface): HTMLElement {
-  return surface.wrap?.closest<HTMLElement>(PANE_SELECTOR) ?? document.documentElement;
+  return stageOf(surface)?.closest<HTMLElement>(PANE_SELECTOR) ?? document.documentElement;
 }
 
 /**

package/src/canvas/surface-registry.ts

@@ -154,7 +154,7 @@ export function surfaceForPane(paneId: string): CanvasSurface {
 
 /** A surface record with nothing in it. One place the per-stage defaults are written down. */
 function freshSurface(paneId: string): CanvasSurface {
-  return {
+  const record: Omit<CanvasSurface, "wrap"> & { wrap: HTMLElement | null } = {
     centerObserver: null,
     monacoDiffEditor: null,
     monacoEditor: null,
@@ -171,8 +171,26 @@ function freshSurface(paneId: string): CanvasSurface {
     renderGeneration: 0,
     sourceCollabCleanup: null,
     stageScrollbar: null,
-    wrap: null as unknown as HTMLElement,
+    wrap: null,
   };
+  /* SAFETY: `wrap` is the only member that differs from CanvasSurface, and it is null only until
+   * registerCanvasSurface attaches the pane's stage. The grid registers a cell's stage as it builds
+   * the cell, before any renderer runs (§18.1 rule 1), and the paths that can run earlier read the
+   * element through stageOf(), which keeps the nullable type. */
+  return record as CanvasSurface;
+}
+
+/**
+ * The surface's stage element, or null before {@link registerCanvasSurface} attaches one.
+ *
+ * `wrap` is typed non-null for the renderers, which only run after registration. The gestures and
+ * teardowns that can reach a surface before its host exists read it through here instead.
+ *
+ * @param {CanvasSurface} surface
+ * @returns {HTMLElement | null}
+ */
+export function stageOf(surface: CanvasSurface): HTMLElement | null {
+  return surface.wrap;
 }
 
 /**
@@ -199,7 +217,7 @@ export function stageContaining(node: Node | null): CanvasSurface | null {
     return null;
   }
   for (const surface of _surfaces.values()) {
-    if (surface.wrap?.contains(node)) {
+    if (stageOf(surface)?.contains(node)) {
       return surface;
     }
   }

package/src/collab/collab-commands.ts

@@ -19,7 +19,12 @@ import { collabState } from "./collab-state";
 import { isCollabEnabled, setCollabEnabled } from "./collab-session";
 import { notify } from "../services/notify";
 import { activeTab } from "../workspace/workspace";
-import { booleanArg, booleanProperty, stringProperty } from "../commands/command-args";
+import {
+  booleanArg,
+  booleanProperty,
+  optionalStringArg,
+  stringProperty,
+} from "../commands/command-args";
 
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 import type { Tab } from "../tabs/tab";
@@ -173,7 +178,7 @@ export function collabCommands(): AnyCommand[] {
         if (!active) {
           return;
         }
-        const login = (args as { login?: string } | undefined)?.login;
+        const login = optionalStringArg("collab.follow", args, "login");
         const { peers } = collabState(active);
         const peer = login ? peers.find((p) => p.state.user.login === login) : peers[0];
         if (!peer) {