@jxsuite/studio 6.1.0 → 6.1.2

package/src/browse/library-preview.ts

@@ -25,6 +25,7 @@ import {
   setCanvasAssetResolver,
   setSkipServerFunctions,
 } from "@jxsuite/runtime";
+import { isFunction } from "@jxsuite/schema/guards";
 import { assetContextFor, hostAssetDeclarations, resolveAssetRef } from "../canvas/asset-refs";
 import { assetVersionsSnapshot } from "../files/asset-versions";
 import { componentRegistry } from "../files/components";
@@ -74,12 +75,13 @@ export function createPreviewCache(limit: number = PREVIEW_CACHE_LIMIT): Preview
   const entries = new Map<string, HTMLElement>();
 
   function evict() {
-    // `size > limit` guarantees a first key, so the iterator result is never `done` here.
-    while (entries.size > limit) {
-      const oldest = entries.keys().next().value as string;
-      const stale = entries.get(oldest);
+    // Insertion order is LRU order, and deleting the entry being visited is safe mid-iteration.
+    for (const [oldest, stale] of entries) {
+      if (entries.size <= limit) {
+        break;
+      }
       entries.delete(oldest);
-      stale?.remove();
+      stale.remove();
     }
   }
 
@@ -127,8 +129,13 @@ export async function renderDocPreview(filePath: string): Promise<HTMLElement |
     let document_: JxDocument;
     if (formatForPath(filePath)) {
       const parsed = await parseSourceForPath(filePath, content);
+      /* SAFETY: a format class's parser returns its file as a Jx element tree (the format contract),
+         and the split hands that same tree back as `document`; a tree renderNode cannot draw throws
+         into the catch below, which is "no preview". */
       document_ = parsed.document as JxDocument;
     } else {
+      /* SAFETY: a `.json` file in the Library is a project document by the project layout; malformed
+         JSON or a shape renderNode cannot draw throws into the catch below, which is "no preview". */
       document_ = JSON.parse(content) as JxDocument;
     }
     const scope = await buildScope(document_, {}, location.href);
@@ -166,9 +173,7 @@ export async function previewFor(
   let rendered: HTMLElement | null | undefined;
   try {
     const component = componentRegistry.find((c: ComponentEntry) => c.path === path);
-    rendered = component
-      ? ((await renderComponentPreview(component)) as HTMLElement | undefined)
-      : await renderDocPreview(path);
+    rendered = component ? await renderComponentPreview(component) : await renderDocPreview(path);
   } catch {
     return undefined;
   }
@@ -219,7 +224,7 @@ export interface PreviewObserver {
  * retained on that path, so there is nothing for the sweep to find.
  */
 export function createPreviewObserver(onVisible: (element: Element) => void): PreviewObserver {
-  if (typeof IntersectionObserver !== "function") {
+  if (!isFunction(globalThis.IntersectionObserver)) {
     return {
       destroy() {
         /* Nothing to disconnect. */

package/src/browse/library-source.ts

@@ -93,7 +93,7 @@ export function createLibrarySource(dirs?: () => readonly string[]): LibrarySour
   let scan: LibraryScan | null = null;
   let inFlight: Promise<LibraryScan> | null = null;
 
-  const projectDirs = dirs ?? (() => (projectState?.projectDirs ?? []) as readonly string[]);
+  const projectDirs = dirs ?? (() => projectState?.projectDirs ?? []);
 
   async function ensureScan(): Promise<LibraryScan> {
     if (scan) {

package/src/canvas/asset-refs.ts

@@ -53,6 +53,9 @@ export function assetContextFor(
   const space = over?.space ?? "site";
   const mount = contentMountFor(
     documentPath,
+    /* SAFETY: `content` is the parser extension's opaque project section, which its project
+       fragment schema defines as a map of section entries; contentMountFor reads only each entry's
+       optional `source` and skips an entry without one. */
     projectState?.projectConfig?.content as Record<string, ContentSectionEntry> | undefined,
     projectLocales(),
   );
@@ -61,13 +64,16 @@ export function assetContextFor(
   if (space === "site" && !mount) {
     return null;
   }
-  return {
+  const context: AssetContext = {
     documentDir: dirOfPath(documentPath ?? ""),
-    ...(over?.fileBaseUrl === undefined ? {} : { fileBaseUrl: over.fileBaseUrl }),
     lanes: BUILD_LANES,
     mounts: mount ? [mount] : [],
     space,
   };
+  if (over?.fileBaseUrl !== undefined) {
+    context.fileBaseUrl = over.fileBaseUrl;
+  }
+  return context;
 }
 
 /**
@@ -99,6 +105,15 @@ export function previewAssetSrc(value: string): string {
   return loopbackAssetSrc(resolveAssetRef(value, versioned) ?? value);
 }
 
+/**
+ * The registered host's media declarations: its asset space, and the base project files serve
+ * under.
+ */
+export interface HostAssetDeclarations {
+  space?: "site" | "repo" | undefined;
+  fileBaseUrl: string;
+}
+
 /**
  * What the registered host says about media — the platform's `assetSpace`, and the base project
  * files are served under.
@@ -108,14 +123,14 @@ export function previewAssetSrc(value: string): string {
  * The canvas pipeline builds the same two values from the same two places; the difference is only
  * that it already has the document in hand.
  *
- * @returns {{ space?: "site" | "repo"; fileBaseUrl: string }} The host's declarations
+ * @returns {HostAssetDeclarations} The host's declarations
  */
-export function hostAssetDeclarations(): {
-  space?: "site" | "repo" | undefined;
-  fileBaseUrl: string;
-} {
-  return {
+export function hostAssetDeclarations(): HostAssetDeclarations {
+  const declarations: HostAssetDeclarations = {
     fileBaseUrl: documentBase(projectState?.projectRoot),
-    ...(hasPlatform() ? { space: getPlatform().assetSpace } : {}),
   };
+  if (hasPlatform()) {
+    declarations.space = getPlatform().assetSpace;
+  }
+  return declarations;
 }

package/src/canvas/asset-resolve.ts

@@ -45,29 +45,24 @@
 
 import {
   assetUrlFor,
+  CONTENT_SECTION_KEY,
   encodeProjectPath,
   isNonRelativeRef,
   joinProjectPath,
+  LOCALE_PLACEHOLDER,
   projectPathForRef,
+  SAFE_CONTENT_TYPE_NAME,
   splitRefSuffix,
 } from "@jxsuite/schema/asset-paths";
 import type { AssetLane, AssetMount } from "@jxsuite/schema/asset-paths";
+import { isString } from "@jxsuite/schema/guards";
 import type { ContentSectionEntry } from "../types";
 
-/** Content type names safe in a URL path segment. Mirrors `SAFE_TYPE_NAME` in the content loader. */
-const SAFE_TYPE_NAME = /^[\w.~-]+$/;
-
-/** The project.json section key content types live under; also their URL namespace. */
-const SECTION_KEY = "content";
-
-/**
- * The placeholder a content type's `source` may carry to say "one directory per locale".
- *
- * Held here rather than imported out of the parser extension's content loader ({@link
- * file://../../../../extensions/parser/src/content-loader.ts}): that module reads the filesystem
- * and this one runs in a browser. It is also an extension, and core may not import one.
- */
-const LOCALE_PLACEHOLDER = "{locale}";
+/* The content namespace, the URL-safe name test and the `{locale}` token come from
+   `@jxsuite/schema/asset-paths`, the one module both this browser-side resolver and the parser
+   extension's content loader may import: the loader reads the filesystem, and it is an extension,
+   which core may not import. Re-exported so Studio's content modules keep one local import. */
+export { LOCALE_PLACEHOLDER } from "@jxsuite/schema/asset-paths";
 
 /**
  * Everything the canvas needs to resolve one reference, as PLAIN DATA.
@@ -127,7 +122,7 @@ export interface AssetContext {
  * @returns {string} The versioned URL
  */
 export function withVersion(url: string, version: string | undefined): string {
-  if (typeof version !== "string" || version === "") {
+  if (!isString(version) || version === "") {
     return url;
   }
   const hashAt = url.indexOf("#");
@@ -172,7 +167,7 @@ function ownVersion(
     return undefined;
   }
   const version: unknown = versions[path];
-  return typeof version === "string" ? version : undefined;
+  return isString(version) ? version : undefined;
 }
 
 /**
@@ -184,13 +179,14 @@ function ownVersion(
  * file tree cannot reach in the first place.
  *
  * @param {string | null | undefined} documentPath - Project-relative path of the open document
- * @param {Record<string, ContentSectionEntry> | null | undefined} content - Project.json `content`
+ * @param {Record<string, ContentSectionEntry | null | undefined> | null | undefined} content -
+ *   Project.json `content`
  * @param {readonly string[]} [locales] - Canonical locale tags, for `{locale}` sources
  * @returns {AssetMount | null} The mount, project-relative
  */
 export function contentMountFor(
   documentPath: string | null | undefined,
-  content: Record<string, ContentSectionEntry> | null | undefined,
+  content: Record<string, ContentSectionEntry | null | undefined> | null | undefined,
   locales: readonly string[] = [],
 ): AssetMount | null {
   if (!documentPath || !content) {
@@ -204,7 +200,7 @@ export function contentMountFor(
     }
   };
   for (const [name, def] of Object.entries(content)) {
-    if (!def?.source || !SAFE_TYPE_NAME.test(name)) {
+    if (!def?.source || !SAFE_CONTENT_TYPE_NAME.test(name)) {
       continue;
     }
     const dir = normalizeSource(def.source);
@@ -222,7 +218,7 @@ export function contentMountFor(
     if (/\.[a-z0-9]+$/i.test(dir)) {
       continue;
     }
-    consider(dir, `/${SECTION_KEY}/${name}`);
+    consider(dir, `/${CONTENT_SECTION_KEY}/${name}`);
   }
   return best;
 }
@@ -256,15 +252,15 @@ function localeMountFor(
     return null;
   }
   const segment = path.slice(head.length).split("/")[0] ?? "";
-  if (segment === "" || !SAFE_TYPE_NAME.test(segment)) {
+  if (segment === "" || !SAFE_CONTENT_TYPE_NAME.test(segment)) {
     return null;
   }
   const canonical = locales.find((tag) => tag.toLowerCase() === segment.toLowerCase());
-  if (canonical === undefined || !SAFE_TYPE_NAME.test(canonical)) {
+  if (canonical === undefined || !SAFE_CONTENT_TYPE_NAME.test(canonical)) {
     return null;
   }
   const dir = `${head}${segment}${tail}`.replace(/\/+$/, "");
-  return { dir, urlPrefix: `/${SECTION_KEY}/${name}/${canonical}` };
+  return { dir, urlPrefix: `/${CONTENT_SECTION_KEY}/${name}/${canonical}` };
 }
 
 /** Strip `./` and any trailing slash from a configured `source`, the way collectionDirs does. */

package/src/canvas/canvas-helpers.ts

@@ -5,7 +5,8 @@
  * multiple canvas-related modules: element lookup, zoom, panel resolution, inline bubbling.
  */
 
-import { getNodeAtPath, parentElementPath } from "../store";
+import { getNodeAtPath } from "@jxsuite/schema/doc-ops";
+import { parentElementPath } from "../store";
 import { displayTagName } from "@jxsuite/schema/guards";
 import { activeCanvasSurface, activeMediaOfPane } from "./canvas-surface";
 import { isInlineInContext } from "../editor/inline-edit";
@@ -46,7 +47,7 @@ export function panelOfSurface(surface: CanvasSurface): CanvasPanel | null {
   }
   const activeMedia = activeMediaOfPane(surface.paneId);
   for (const p of canvasPanels) {
-    if (activeMedia === null && (p.mediaName === "base" || p.mediaName === null)) {
+    if (activeMedia === null && p.mediaName === "base") {
       return p;
     }
     if (p.mediaName === activeMedia) {
@@ -78,10 +79,10 @@ export function bubbleInlinePath(doc: JxMutableNode | undefined, path: JxPath) {
     return path;
   }
   let currentPath = path;
-  while (currentPath.length >= 2) {
+  // `parentElementPath` is null exactly when the path is too short to have a parent element.
+  for (let pPath = parentElementPath(currentPath); pPath; pPath = parentElementPath(currentPath)) {
     const node = getNodeAtPath(doc, currentPath);
-    const pPath = parentElementPath(currentPath);
-    const parentNode = pPath ? getNodeAtPath(doc, pPath) : null;
+    const parentNode = getNodeAtPath(doc, pPath);
     if (!node || !parentNode) {
       break;
     }
@@ -90,7 +91,7 @@ export function bubbleInlinePath(doc: JxMutableNode | undefined, path: JxPath) {
     if (!isInlineInContext(childTag, parentTag)) {
       break;
     }
-    currentPath = pPath as JxPath;
+    currentPath = pPath;
   }
   return currentPath;
 }

package/src/canvas/canvas-live-render.ts

@@ -7,7 +7,7 @@
  */
 
 import { projectState, stripEventHandlers } from "../store";
-import { displayTagName } from "@jxsuite/schema/guards";
+import { displayTagName, isMappedArray, isNonNullObject, isString } from "@jxsuite/schema/guards";
 import { canvasModeOfTab } from "./canvas-surface";
 import { toRaw } from "../reactivity";
 import {
@@ -20,7 +20,6 @@ import {
   resolveLayoutDoc,
 } from "../site-context";
 import { documentBase } from "./canvas-origin";
-import { getPlatform, hasPlatform } from "../platform";
 import { componentRegistry, computeRelativePath } from "../files/components";
 import { prepareForEditMode } from "../utils/edit-display";
 import {
@@ -29,10 +28,10 @@ import {
   substitutePreviewParams,
 } from "../page-params";
 import { isComponentDoc, substitutePreviewProps } from "../component-props";
-import { assetContextFor } from "./asset-refs";
+import { assetContextFor, hostAssetDeclarations } from "./asset-refs";
 
 import type { AssetContext } from "./asset-refs";
-import type { JxElement, JxMutableNode, JxPath } from "@jxsuite/schema/types";
+import type { JxElement, JxMutableNode, JxPath, JxStyle } from "@jxsuite/schema/types";
 import type { ComponentEntry } from "../files/components.js";
 import type { LayoutMarker } from "./path-mapping";
 import type { Tab } from "../tabs/tab";
@@ -55,19 +54,20 @@ function findPageContentPrefix(
   node: JxMutableNode,
   path: (string | number)[] = [],
 ): { prefix: (string | number)[]; offset: number } | null {
-  if (!node || typeof node !== "object") {
+  // Document JSON can hold a null or scalar where a node belongs; neither has page content.
+  if (!isNonNullObject(node)) {
     return null;
   }
   if (Array.isArray(node.children)) {
     const firstPageIdx = node.children.findIndex(
-      (child) => child && typeof child === "object" && !child.$__layout,
+      (child) => isNonNullObject(child) && !child.$__layout,
     );
     if (firstPageIdx !== -1) {
       return { offset: firstPageIdx, prefix: [...path, "children"] };
     }
     for (let i = 0; i < node.children.length; i++) {
       const child = node.children[i];
-      if (child && typeof child === "object" && child.$__layout) {
+      if (isNonNullObject(child) && child.$__layout) {
         const found = findPageContentPrefix(child, [...path, "children", i]);
         if (found) {
           return found;
@@ -87,13 +87,14 @@ function findPageContentPrefix(
  * editor can open the layout with that node selected. See {@link LayoutMarker}.
  */
 export function markLayoutNodes(node: JxMutableNode, file: string, path: JxPath = []) {
-  if (!node || typeof node !== "object") {
+  // Layout JSON can hold a null or scalar where a node belongs; there is nothing to mark on it.
+  if (!isNonNullObject(node)) {
     return;
   }
   node.$__layout = { file, path } satisfies LayoutMarker;
   if (Array.isArray(node.children)) {
     for (const [i, child] of node.children.entries()) {
-      if (typeof child === "string") {
+      if (isString(child)) {
         continue;
       }
       markLayoutNodes(child, file, [...path, "children", i]);
@@ -101,7 +102,10 @@ export function markLayoutNodes(node: JxMutableNode, file: string, path: JxPath
   }
   if (Array.isArray(node.$elements)) {
     for (const [i, el] of node.$elements.entries()) {
-      if (typeof el !== "string") {
+      if (!isString(el)) {
+        /* SAFETY: a non-string `$elements` entry is an inline element definition or a `{ $ref }`
+           import. markLayoutNodes stamps `$__layout` and walks `children` / `$elements`, which a
+           `$ref` entry simply lacks, so it is marked as a childless node. */
         markLayoutNodes(el as JxMutableNode, file, [...path, "$elements", i]);
       }
     }
@@ -157,7 +161,7 @@ export async function resolveCanvasDocument(
   /** How the canvas must address project media, or null when its origin serves the site URL space. */
   assets: AssetContext | null;
   mapperCtx: WireMapperCtx;
-  siteStyle: Record<string, unknown> | null;
+  siteStyle: JxStyle | null;
 }> {
   const S = { documentPath: tab?.documentPath, mode: tab?.doc.mode };
   const canvasMode = modeOverride ?? canvasModeOfTab(tab);
@@ -180,7 +184,7 @@ export async function resolveCanvasDocument(
   if (isPage && tab?.session.ui.showLayout !== false) {
     const layoutPath = getEffectiveLayoutPath(doc.$layout);
     if (layoutPath) {
-      const layoutDoc = (await resolveLayoutDoc(layoutPath)) as JxMutableNode | null;
+      const layoutDoc = await resolveLayoutDoc(layoutPath);
       if (layoutDoc) {
         // The SAME normalization resolveLayoutDoc reads the file with, so the marker's `file` is a
         // Path the editor can hand straight to navigateToComponent when the author asks to open it.
@@ -210,10 +214,7 @@ export async function resolveCanvasDocument(
    * — design and edit swap every bound src for a transparent pixel, so they never reached the
    * network to fail.
    */
-  const assets = assetContextFor(S.documentPath, {
-    fileBaseUrl: fileBase,
-    ...(hasPlatform() ? { space: getPlatform().assetSpace } : {}),
-  });
+  const assets = assetContextFor(S.documentPath, hostAssetDeclarations());
 
   // Substitute chosen dynamic route params ({$ref: "#/$params/x"} → literal), inject state.$page,
   // And bake the substituted class-prototype state entries via the backend resolver — in every
@@ -222,10 +223,8 @@ export async function resolveCanvasDocument(
   // (posted as shadowDoc), whose $refs must survive for editing/serialization.
   if (isPage && tab) {
     const { previewParams } = tab.session.ui;
-    if (previewParams && Object.keys(previewParams).length > 0) {
-      const boundKeys = paramBoundStateKeys(
-        (doc as { state?: Record<string, unknown> }).state ?? null,
-      );
+    if (Object.keys(previewParams).length > 0) {
+      const boundKeys = paramBoundStateKeys(doc.state ?? null);
       renderDoc = substitutePreviewParams(renderDoc, previewParams, S.documentPath);
       await resolveParamBoundState(renderDoc, boundKeys, docBase);
     }
@@ -253,30 +252,29 @@ export async function resolveCanvasDocument(
   const arrayPaths = new Set<string>();
   if (canvasMode !== "preview") {
     (function findArrayPaths(node: JxMutableNode, path: (string | number)[]) {
-      if (!node || typeof node !== "object") {
+      // Document JSON can hold a null or scalar where a node belongs; it holds no repeater.
+      if (!isNonNullObject(node)) {
         return;
       }
-      if ((node as unknown as { $prototype?: string }).$prototype === "Array") {
+      if (node.$prototype === "Array") {
         arrayPaths.add(path.join("/"));
-        const mapDef = (node as JxMutableNode).map;
-        if (mapDef && typeof mapDef === "object") {
+        const mapDef = node.map;
+        if (isNonNullObject(mapDef)) {
           findArrayPaths(mapDef, [...path, "map"]);
         }
         return;
       }
       if (Array.isArray(node.children)) {
-        for (let i = 0; i < node.children.length; i++) {
-          const child = node.children[i];
-          if (typeof child === "string") {
+        for (const [i, child] of node.children.entries()) {
+          if (isString(child)) {
             continue;
           }
-          findArrayPaths(child!, [...path, "children", i]);
+          findArrayPaths(child, [...path, "children", i]);
         }
-      } else if (
-        node.children &&
-        typeof node.children === "object" &&
-        (node.children as unknown as { $prototype?: string }).$prototype === "Array"
-      ) {
+      } else if (isMappedArray(node.children)) {
+        /* SAFETY: the bare mapped-array slot is a repeater node in all but its declared type, and
+           the walk reads only what isMappedArray just established (`$prototype`) and its `map`
+           template, an element definition. */
         findArrayPaths(node.children as JxMutableNode, [...path, "children"]);
       }
       if (node.$switch && node.cases) {
@@ -295,14 +293,19 @@ export async function resolveCanvasDocument(
   const isLayoutDoc =
     S.documentPath != null &&
     (S.documentPath.startsWith("layouts/") || S.documentPath.startsWith("./layouts/"));
+  /* SAFETY: a document's `$elements` entries are tag-name strings, `{ $ref }` imports or inline
+     element definitions, each a JxElement or a string; getEffectiveElements only dedups them by the
+     string itself or by `$ref`. */
   const effectiveElements = getEffectiveElements(renderDoc.$elements as (JxElement | string)[]);
   if ((S.mode === "content" || layoutWrapped || isLayoutDoc) && componentRegistry.length > 0) {
     const existingRefs = new Set(
-      effectiveElements.map((e: JxElement | string) => (typeof e === "string" ? e : e?.$ref)),
+      // A null entry in a document's `$elements` names nothing, so it contributes no ref.
+      effectiveElements.map((e: JxElement | string) => (isNonNullObject(e) ? e.$ref : e)),
     );
     const collectTags = (node: JxMutableNode): Set<string> => {
       const tags = new Set<string>();
-      if (!node || typeof node !== "object") {
+      // Document JSON can hold a null or scalar where a node belongs; it carries no tag.
+      if (!isNonNullObject(node)) {
         return tags;
       }
       if (node.tagName) {
@@ -310,7 +313,7 @@ export async function resolveCanvasDocument(
       }
       if (Array.isArray(node.children)) {
         for (const child of node.children) {
-          if (typeof child !== "string") {
+          if (!isString(child)) {
             for (const t of collectTags(child)) {
               tags.add(t);
             }
@@ -331,24 +334,12 @@ export async function resolveCanvasDocument(
     }
   }
   if (effectiveElements.length > 0) {
-    renderDoc.$elements = effectiveElements as (string | JxMutableNode | { $ref: string })[];
+    renderDoc.$elements = effectiveElements;
   }
   renderDoc.imports = getEffectiveImports(renderDoc.imports);
-  // The effective-media/head getters return the merged value or undefined. Optional properties
-  // Cannot be assigned undefined under exactOptionalPropertyTypes, so clear them by deleting the key
-  // When the getter yields nothing.
-  const media = getEffectiveMedia(renderDoc.$media);
-  if (media === undefined) {
-    delete renderDoc.$media;
-  } else {
-    renderDoc.$media = media as NonNullable<JxMutableNode["$media"]>;
-  }
-  const head = getEffectiveHead(renderDoc.$head);
-  if (head === undefined) {
-    delete renderDoc.$head;
-  } else {
-    renderDoc.$head = head as NonNullable<JxMutableNode["$head"]>;
-  }
+  // The effective-media/head getters always answer a value: the merge, or an empty one.
+  renderDoc.$media = getEffectiveMedia(renderDoc.$media);
+  renderDoc.$head = getEffectiveHead(renderDoc.$head);
 
   return {
     assets,
@@ -361,6 +352,6 @@ export async function resolveCanvasDocument(
       pageContentPrefix,
     },
     renderDoc,
-    siteStyle: (projectState?.projectConfig?.style as Record<string, unknown>) ?? null,
+    siteStyle: projectState?.projectConfig?.style ?? null,
   };
 }

package/src/canvas/canvas-patcher.ts

@@ -18,7 +18,9 @@
  * edit typed into the first, and how one failed patch would rebuild both.
  */
 
-import { getNodeAtPath, parentElementPath } from "../store";
+import { getNodeAtPath } from "@jxsuite/schema/doc-ops";
+import { isString } from "@jxsuite/schema/guards";
+import { parentElementPath } from "../store";
 import { canvasModeOfPane, surfacesShowingTab } from "./canvas-surface";
 import { toRaw } from "../reactivity";
 import { postPatchToHosts } from "./iframe-host";
@@ -29,6 +31,13 @@ import type { CanvasSurface } from "./surface-registry";
 import type { JxPatchOp, TransactionRecord } from "../tabs/patch-ops";
 import type { Tab } from "../tabs/tab.js";
 import type { JxPath } from "../state";
+import type { JxMutableNode } from "@jxsuite/schema/types";
+
+/** Whether a batch can be applied surgically, and why not when it cannot. */
+export interface PatchVerdict {
+  patchable: boolean;
+  reason: string;
+}
 
 /** Render-side callbacks injected at init so this module stays free of heavy canvas imports. */
 interface CanvasPatcherCtx {
@@ -62,10 +71,17 @@ export function initCanvasPatcher(ctx: CanvasPatcherCtx) {
     apply: applyPatchBatch,
     classify: classifyOps,
     escalate: escalateToFullRender,
-    markConsumed: (docRef: object, tab: Tab) => {
-      markConsumed(
-        docRef,
-        patchableSurfaces(tab).map((surface) => surface.paneId),
+    /* Records that `docRef`'s change has been applied surgically in each patchable pane.
+
+       No empty-list guard, because the list cannot be empty here: `transactDoc` marks only a batch
+       {@link classifyOps} called patchable, and that function rejects `patchableSurfaces(tab).length
+       === 0` before it can say so. A guard on an unreachable value is a branch no test can enter (the
+       gate's own rule), and `_consumed` is a `WeakMap` keyed on a reference `transactDoc` mints fresh
+       per transaction, so there is nothing for one to protect either. */
+    markConsumed: (docRef, tab) => {
+      _consumed.set(
+        toRaw(docRef),
+        new Set(patchableSurfaces(tab).map((surface) => surface.paneId)),
       );
     },
   });
@@ -96,32 +112,16 @@ function patchableSurfaces(tab: Tab | null): CanvasSurface[] {
   });
 }
 
-/**
- * Record that `docRef`'s change has been applied surgically in each of `paneIds`.
- *
- * No empty-list guard, because the list cannot be empty here: `transactDoc` marks only a batch
- * {@link classifyOps} called patchable, and that function rejects `patchableSurfaces(tab).length
- * === 0` before it can say so. A guard on an unreachable value is a branch no test can enter — the
- * gate's own rule — and `_consumed` is a `WeakMap` keyed on a reference `transactDoc` mints fresh
- * per transaction, so there is nothing for one to protect either.
- *
- * @param {object} docRef
- * @param {readonly string[]} paneIds
- */
-function markConsumed(docRef: object, paneIds: readonly string[]) {
-  _consumed.set(toRaw(docRef) as object, new Set(paneIds));
-}
-
 /**
  * One-shot check used by ONE PANE's canvas doc-effect: returns true (and clears that pane's mark)
  * when the given document reference was already applied to that pane's stage surgically, so its
  * full render can be skipped. One-shot so tab switches and repeat triggers still render fully.
  *
- * @param {object} doc
+ * @param {JxMutableNode} doc
  * @param {string} paneId
  */
-export function consumePatchedDocument(doc: object, paneId: string): boolean {
-  const raw = toRaw(doc) as object;
+export function consumePatchedDocument(doc: JxMutableNode, paneId: string): boolean {
+  const raw = toRaw(doc);
   const panes = _consumed.get(raw);
   if (!panes?.has(paneId)) {
     return false;
@@ -221,7 +221,7 @@ function containerVerdict(tab: Tab, parentPath: JxPath, requireArray = true): st
    * definition escalated to a full render — in a component-heavy project, the most common authoring
    * action there is.
    */
-  if (parentPath.length > 0 && typeof parent.tagName === "string" && parent.tagName.includes("-")) {
+  if (parentPath.length > 0 && isString(parent.tagName) && parent.tagName.includes("-")) {
     return "structure-in-custom-element";
   }
   if (parent.innerHTML) {
@@ -253,7 +253,7 @@ function replaceVerdict(tab: Tab, path: JxPath): string | null {
   if (pathHasDynamicSegment(path)) {
     return "replace-on-cases-path";
   }
-  const parentPath = parentElementPath(path) as JxPath | null;
+  const parentPath = parentElementPath(path);
   if (!parentPath) {
     return "replace-no-parent";
   }
@@ -295,7 +295,7 @@ function opVerdict(tab: Tab, op: JxPatchOp): string | null {
       if (!node) {
         return "node-not-found";
       }
-      if (typeof node.tagName === "string" && node.tagName.includes("-")) {
+      if (isString(node.tagName) && node.tagName.includes("-")) {
         return "text-on-custom-element";
       }
       if (node.innerHTML) {
@@ -320,14 +320,14 @@ function opVerdict(tab: Tab, op: JxPatchOp): string | null {
       return containerVerdict(tab, op.parentPath);
     }
     case "remove": {
-      const parentPath = parentElementPath(op.path) as JxPath | null;
+      const parentPath = parentElementPath(op.path);
       return parentPath === null ? "remove-no-parent" : containerVerdict(tab, parentPath);
     }
     case "move": {
       if (pathHasDynamicSegment(op.fromPath)) {
         return "structure-on-cases-path";
       }
-      const fromParentPath = parentElementPath(op.fromPath) as JxPath | null;
+      const fromParentPath = parentElementPath(op.fromPath);
       if (fromParentPath === null) {
         return "move-no-parent";
       }
@@ -347,7 +347,7 @@ function opVerdict(tab: Tab, op: JxPatchOp): string | null {
  * @param {Tab} tab
  * @param {JxPatchOp[]} ops
  */
-export function classifyOps(tab: Tab, ops: JxPatchOp[]): { patchable: boolean; reason: string } {
+export function classifyOps(tab: Tab, ops: JxPatchOp[]): PatchVerdict {
   const reject = (reason: string) => {
     recordEscalation(reason);
     return { patchable: false, reason };