@jxsuite/studio 6.1.0 → 6.1.2

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");
   }
 }
 
@@ -289,6 +314,36 @@ export function clampEditZoom(zoom: number): number {
   return Math.min(EDIT_ZOOM_MAX, Math.max(EDIT_ZOOM_MIN, zoom));
 }
 
+/**
+ * Where an Edit-mode zoom is anchored: the scroller, the zoom the canvas is DRAWN at now, and the
+ * layout-px offset into the canvas of the content line at viewport-y `anchorY` (the cursor for a
+ * wheel, the scroller's middle for a button or a chord).
+ *
+ * The drawn zoom is read from the panel's applied layout width rather than from `ui.editZoom`,
+ * which a wheel burst has already moved on: the reactive write lands per event and the DOM once a
+ * frame.
+ */
+function editZoomAnchor(
+  surface: CanvasSurface,
+  layoutWidth: number | null,
+  anchorY: number | null,
+): { layoutY: number; scroller: HTMLElement; zoom: number } | null {
+  const scroller = surface.wrap.querySelector<HTMLElement>('[part="edit-canvas"]');
+  const canvasEl = surface.panels[0]?.canvas;
+  if (!scroller || !canvasEl) {
+    return null;
+  }
+  const column = surface.wrap.querySelector<HTMLElement>('[part="edit-column"]');
+  const renderWidth = column ? rectOf(column).width : 0;
+  const zoom = layoutWidth && renderWidth > 0 ? renderWidth / layoutWidth : 1;
+  let y = anchorY;
+  if (y === null) {
+    const box = rectOf(scroller);
+    y = box.top + box.height / 2;
+  }
+  return { layoutY: Math.max(0, (y - rectOf(canvasEl).top) / zoom), scroller, zoom };
+}
+
 /**
  * Apply the active tab's edit-mode content zoom to the single edit panel.
  *
@@ -309,19 +364,23 @@ export function clampEditZoom(zoom: number): number {
  * bare style writes only; the iframe's own ResizeObserver re-posts `contentHeight` after the
  * reflow, which also finalizes the viewport height.
  */
-export function applyEditZoom(surface: CanvasSurface = activeCanvasSurface()) {
+export function applyEditZoom(
+  surface: CanvasSurface = activeCanvasSurface(),
+  anchorY: number | null = null,
+) {
   // THIS pane's effective mode. It was the focused pane's, so a side pane in Edit was refused its
   // Own content zoom whenever the primary happened to be in Design.
   if (canvasModeOfPane(surface.paneId) !== "edit") {
     return;
   }
   const [panel] = surface.panels;
-  if (!panel?.canvas || !panel.viewport) {
+  if (!panel || !isPanelBound(panel)) {
     return;
   }
   const canvasEl = panel.canvas;
   const iframe = canvasEl.querySelector("iframe");
   const editZoom = tabOfSurface(surface)?.session.ui.editZoom ?? 1;
+  const anchor = editZoomAnchor(surface, panel._width ?? null, anchorY);
   if (editZoom === 1) {
     // Exactly today's fluid behavior — no inline width, no transform, auto viewport height.
     panel._width = null;
@@ -357,6 +416,11 @@ export function applyEditZoom(surface: CanvasSurface = activeCanvasSurface()) {
       panel.viewport.style.height = `${iframe.offsetHeight * editZoom}px`;
     }
   }
+  if (anchor) {
+    // The content line that was under the anchor goes back under it: it sat `layoutY` layout px
+    // Into the canvas, which now draws it `layoutY * (new - old)` px further down.
+    anchor.scroller.scrollTop += anchor.layoutY * (editZoom - anchor.zoom);
+  }
   // Re-anchor the fixed block-action-bar over the rescaled canvas.
   renderOnly("overlays");
 }
@@ -386,17 +450,25 @@ export function setEditZoom(zoom: number, surface: CanvasSurface = activeCanvasS
  */
 const _editZoomRafs = new Map<string, number>();
 
+/** The viewport-y each stage's pending frame zooms around — the latest wheel event's cursor. */
+const _editZoomAnchors = new Map<string, number | null>();
+
 /**
  * Wheel-rate edit-zoom setter: the reactive `editZoom` write lands immediately (the zoom pod's
  * label tracks it), but the DOM work — an iframe width resize, i.e. a real reflow — is coalesced to
  * one `applyEditZoom()` per animation frame so a fast ctrl+scroll burst doesn't thrash layout.
  */
-export function requestEditZoom(zoom: number, surface: CanvasSurface = activeCanvasSurface()) {
+export function requestEditZoom(
+  zoom: number,
+  surface: CanvasSurface = activeCanvasSurface(),
+  anchorY: number | null = null,
+) {
   const tab = tabOfSurface(surface);
   if (!tab) {
     return;
   }
   tab.session.ui.editZoom = clampEditZoom(zoom);
+  _editZoomAnchors.set(surface.paneId, anchorY);
   if (_editZoomRafs.has(surface.paneId)) {
     return;
   }
@@ -404,7 +476,9 @@ export function requestEditZoom(zoom: number, surface: CanvasSurface = activeCan
     surface.paneId,
     requestAnimationFrame(() => {
       _editZoomRafs.delete(surface.paneId);
-      applyEditZoom(surface);
+      const at = _editZoomAnchors.get(surface.paneId) ?? null;
+      _editZoomAnchors.delete(surface.paneId);
+      applyEditZoom(surface, at);
     }),
   );
 }
@@ -522,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(
@@ -536,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>();
 
@@ -592,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;
@@ -607,22 +686,15 @@ export function setFit(fit: FitMode, surface: CanvasSurface = activeCanvasSurfac
   applyFit(fit, surface);
 }
 
-/**
- * Record the active document's CURRENT pan-zoom as its declared fit.
- *
- * For the gesture paths that move the zoom themselves and then have to say so — ctrl+scroll writes
- * `ui.zoom` directly, pinch will too. An author-chosen zoom is a numeric fit, so re-entering the
- * mode restores it instead of re-framing over the top of it.
- */
-export function markExplicitZoom(surface: CanvasSurface = activeCanvasSurface()): void {
-  declareFit(clampPanZoom(zoomOf(surface)), surface);
-}
-
 /**
  * Set the active tab's pan-zoom on the author's behalf: clamped, declared as this document's fit,
  * and applied. Every author-facing pan-zoom control routes through here.
  */
-export function setUserZoom(zoom: number, surface: CanvasSurface = activeCanvasSurface()): void {
+export function setUserZoom(
+  zoom: number,
+  surface: CanvasSurface = activeCanvasSurface(),
+  at: { clientX: number; clientY: number } | null = null,
+): void {
   const tab = tabOfSurface(surface);
   if (!tab) {
     return;
@@ -631,7 +703,23 @@ export function setUserZoom(zoom: number, surface: CanvasSurface = activeCanvasS
   // Synchronously on assignment, and the zoom pod reads `getFit()` while it renders — so declaring
   // Second means the control repaints one interaction behind the state it is reporting.
   const next = clampPanZoom(zoom);
+  const ratio = next / zoomOf(surface);
   declareFit(next, surface);
+  if (surface.panzoomWrap && ratio !== 1) {
+    /* Zoom AROUND a point: the cursor for a wheel, the stage's middle for a button or a chord.
+       Measured from the wrap's own drawn box, not the stage's: the wrap's layout origin is not the
+       stage's (it centres itself with `margin-block: auto`, and Stylebook puts a lead slot before
+       it), and the cursor-minus-stage arithmetic this replaced drifted by exactly that offset. A
+       content point `d` px into the drawn box is `d * ratio` px in after the zoom, so the pan
+       moves by the difference. */
+    const box = rectOf(surface.panzoomWrap);
+    const stage = rectOf(surface.wrap);
+    const x = at?.clientX ?? stage.left + stage.width / 2;
+    const y = at?.clientY ?? stage.top + stage.height / 2;
+    surface.panX += (x - box.left) * (1 - ratio);
+    surface.panY += (y - box.top) * (1 - ratio);
+    surface.needsCenter = false;
+  }
   setZoomOf(surface, next);
   applyTransform(surface);
 }
@@ -795,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.
@@ -855,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;
 }
 
 /**
@@ -864,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") &&
@@ -983,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);
     }
@@ -1015,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 [
@@ -1200,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);
@@ -1253,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`,
           );
@@ -1265,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 ` +
@@ -1301,7 +1398,7 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
           args,
           "scheme",
           COLOR_SCHEMES,
-        ) as "auto" | "dark" | "light";
+        );
         repaint(args);
       },
       title: "Set Color Scheme",
@@ -1417,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
@@ -1477,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) {
@@ -1528,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"),
         );
       },
@@ -1578,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);
@@ -1665,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

package/src/canvas/dialog-path.ts

@@ -12,8 +12,9 @@
  */
 
 import { activeTab } from "../workspace/workspace";
-import { getNodeAtPath } from "../state";
+import { getNodeAtPath } from "@jxsuite/schema/doc-ops";
 import { documentHasDialog, isDialog } from "@jxsuite/schema/dialogs";
+import { isNonNullObject } from "@jxsuite/schema/guards";
 import { primarySelection } from "../tabs/selection";
 import type { JxMutableNode } from "@jxsuite/schema/types";
 import type { JxPath } from "../state";
@@ -39,7 +40,8 @@ export function ancestorDialogPath(
   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" && isDialog(node)) {
+    // A path can end on a text child or a value, so only an element is asked about its tag.
+    if (isNonNullObject(node) && isDialog(node)) {
       return prefix;
     }
   }
@@ -58,19 +60,22 @@ export function ancestorDialogPath(
  * @returns The dialog's path, or null.
  */
 export function dialogPathFor(tab: Tab, explicit?: JxPath): JxPath | null {
+  /* SAFETY: a widening, so it cannot hide a mismatch: `Tab` declares the document always present,
+     but a tab record without one must answer null rather than throw (tests/dialog-path.test.ts,
+     "a tab with no document"), and the widened type keeps that guard checked. */
   const doc = tab.doc.document as JxMutableNode | undefined;
   if (!doc) {
     return null;
   }
   if (explicit) {
     const node = getNodeAtPath(doc, explicit);
-    return node && typeof node === "object" && isDialog(node) ? explicit : null;
+    return isNonNullObject(node) && isDialog(node) ? explicit : null;
   }
   return ancestorDialogPath(doc, primarySelection(tab.session.selection));
 }
 
 /** Whether the active document holds a `<dialog>` at all — the command's `enablement`. */
 export function activeDocumentHasDialog(): boolean {
-  const doc = activeTab.value?.doc.document as JxMutableNode | undefined;
+  const doc = activeTab.value?.doc.document;
   return doc ? documentHasDialog(doc) : false;
 }

package/src/canvas/dialog-state.ts

@@ -19,7 +19,6 @@ import { ancestorDialogPath } from "./dialog-path";
 import { postDialogOpen } 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";
 
@@ -51,7 +50,7 @@ export function setOpenDialog(tab: Tab, path: JxPath | null): void {
  * @returns Whether anything changed.
  */
 export function openDialogFor(tab: Tab, path: JxPath | null): boolean {
-  const target = ancestorDialogPath(tab.doc.document as JxMutableNode, path);
+  const target = ancestorDialogPath(tab.doc.document, path);
   if (target === null || samePath(tab.session.ui.openDialog, target)) {
     return false;
   }

package/src/canvas/diff-marks.ts

@@ -35,6 +35,7 @@
  */
 
 import { deepEqual, matchChildren } from "@jxsuite/collab/diff-core";
+import { isJsonObject } from "@jxsuite/schema/guards";
 import type { JxMutableNode, JxPath } from "@jxsuite/schema/types";
 
 /** What happened to a node. `modified` means the node survived and its own content changed. */
@@ -84,10 +85,6 @@ export interface ChangeMapOptions {
 
 const DEFAULT_MAX_CELLS = 250_000;
 
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 class ChangeWalker {
   readonly original: ChangeMark[] = [];
   readonly current: ChangeMark[] = [];
@@ -121,12 +118,7 @@ class ChangeWalker {
     this.steps.push({ currentPath: bPath, kind, originalPath: aPath });
   }
 
-  diffNode(
-    aPath: JxPath,
-    bPath: JxPath,
-    a: Record<string, unknown>,
-    b: Record<string, unknown>,
-  ): void {
+  diffNode(aPath: JxPath, bPath: JxPath, a: JxMutableNode, b: JxMutableNode): void {
     const isRoot = aPath.length === 0 && bPath.length === 0;
     let ownChanged = false;
     for (const key of new Set([...Object.keys(a), ...Object.keys(b)])) {
@@ -161,8 +153,8 @@ class ChangeWalker {
   private diffChildren(
     aPath: JxPath,
     bPath: JxPath,
-    ca: readonly unknown[],
-    cb: readonly unknown[],
+    ca: readonly (JxMutableNode | string)[],
+    cb: readonly (JxMutableNode | string)[],
   ): void {
     if (ca.length * cb.length > this.maxCells) {
       this.degraded = true;
@@ -183,7 +175,7 @@ class ChangeWalker {
       if (!match.identical) {
         const aItem = ca[match.aIndex];
         const bItem = cb[match.bIndex];
-        if (isPlainObject(aItem) && isPlainObject(bItem)) {
+        if (isJsonObject(aItem) && isJsonObject(bItem)) {
           this.diffNode(
             [...aPath, "children", match.aIndex],
             [...bPath, "children", match.bIndex],
@@ -211,11 +203,12 @@ class ChangeWalker {
     kind: "added" | "removed",
     aPath: JxPath,
     bPath: JxPath,
-    item: unknown,
+    // Every caller reads in bounds, but an indexed read is typed possibly undefined; it is no element.
+    item: JxMutableNode | string | undefined,
     aIndex: number | null,
     bIndex: number | null,
   ): void {
-    if (!isPlainObject(item)) {
+    if (!isJsonObject(item)) {
       this.emit("modified", aPath, bPath);
       return;
     }
@@ -241,7 +234,7 @@ export function buildChangeMap(
   opts: ChangeMapOptions = {},
 ): ChangeMap {
   const walker = new ChangeWalker(opts.maxCells ?? DEFAULT_MAX_CELLS);
-  walker.diffNode([], [], a as Record<string, unknown>, b as Record<string, unknown>);
+  walker.diffNode([], [], a, b);
   return {
     current: walker.current,
     degraded: walker.degraded,