@jxsuite/studio 6.1.1 → 8.0.0

package/src/canvas/canvas-surface.ts

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

package/src/canvas/canvas-utils.ts

@@ -4,7 +4,7 @@
  * template creation, centering, transform application, zoom indicator, and fit-to-screen.
  */
 
-import type { CanvasPanel, JsonValue } from "../types";
+import type { CanvasPanel } from "../types";
 
 import { renderOnly } from "../store";
 import {
@@ -39,6 +39,7 @@ import {
 import type { CanvasStageHandle, CanvasStagePanelItem } from "../surfaces/canvas-stage";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 import type { CommandArgValues } from "../commands/command-args";
+import { isNumber, isString } from "@jxsuite/schema/guards";
 import type { Tab } from "../tabs/tab";
 
 /*
@@ -106,6 +107,22 @@ function setZoomOf(surface: CanvasSurface, zoom: number): void {
   }
 }
 
+/** The {@link CanvasPanel} fields that hold the board's drawn nodes. */
+type CanvasPanelNodeKey = "canvas" | "element" | "scrollContainer" | "viewport";
+
+/**
+ * A panel record as it may be before {@link bindCanvasPanels} has run: its DOM fields can still be
+ * null, because {@link canvasPanelEntry} builds them that way. A bound {@link CanvasPanel} is
+ * assignable to it, so a reader that must tolerate an unbound board takes this type.
+ */
+export type UnboundCanvasPanel = Omit<CanvasPanel, CanvasPanelNodeKey> &
+  Record<CanvasPanelNodeKey, HTMLElement | null>;
+
+/** Whether the stage has wired a board's canvas and viewport nodes into its record yet. */
+export function isPanelBound(panel: UnboundCanvasPanel): boolean {
+  return Boolean(panel.canvas && panel.viewport);
+}
+
 /**
  * One artboard: the record the geometry reads, and the item the stage document draws.
  *
@@ -139,7 +156,7 @@ export function canvasPanelEntry(
   fullWidth: boolean,
   width: number | null = null,
 ): CanvasPanelEntry {
-  const panel = {
+  const unbound: UnboundCanvasPanel = {
     _width: width || null,
     canvas: null,
     element: null,
@@ -148,7 +165,11 @@ export function canvasPanelEntry(
     renderScope: null,
     scrollContainer: null,
     viewport: null,
-  } as unknown as CanvasPanel;
+  };
+  /* SAFETY: the record is handed out unbound and filled in place by `bindCanvasPanels` once the
+     stage has drawn it; every reader that can run before that (`tabOfMountedPanel`, `applyEditZoom`,
+     `updateActivePanelHeaders`) reads it as an UnboundCanvasPanel and checks the nodes first. */
+  const panel = unbound as CanvasPanel;
   /* The viewport takes the declared width, the canvas takes it too — but a FULL-WIDTH board's
      viewport does not, because "full width" means "as wide as the box you are in". Carried as two
      custom properties rather than as `width:` so `applyEditZoom`'s inline write on the canvas still
@@ -186,9 +207,13 @@ export function canvasPanelEntry(
  */
 export function bindCanvasPanels(entries: CanvasPanelEntry[], stage: CanvasStageHandle): void {
   for (const { item, panel } of entries) {
-    panel.element = stage.panelNode(item.key, "panel") as HTMLElement;
-    panel.viewport = stage.panelNode(item.key, "panel-viewport") as HTMLElement;
-    panel.canvas = stage.panelNode(item.key, "panel-canvas") as HTMLElement;
+    /* SAFETY: callers bind only after `drawStage` has settled, and the stage document draws the
+       `panel`, `panel-viewport` and `panel-canvas` parts for every item it was given, keyed by
+       `item.key`, so each lookup finds its node. */
+    const node = (part: string) => stage.panelNode(item.key, part) as HTMLElement;
+    panel.element = node("panel");
+    panel.viewport = node("panel-viewport");
+    panel.canvas = node("panel-canvas");
   }
 }
 
@@ -232,8 +257,10 @@ export function centerCanvas(surface: CanvasSurface) {
   const wrapWidth = surface.wrap.clientWidth;
   const contentWidth = surface.panzoomWrap.scrollWidth;
   const zoom = zoomOf(surface);
-  const scaledWidth = contentWidth * zoom;
-  surface.panX = Math.max(16, (wrapWidth - scaledWidth) / 2);
+  const free = wrapWidth - contentWidth * zoom;
+  /* Content that fits is centred, however little room is left over: a 16px floor on a fitted page
+     pushed its right edge 16px past the pane. Content wider than the pane starts 16px in. */
+  surface.panX = free >= 0 ? free / 2 : 16;
   surface.panY = 0;
 }
 
@@ -349,7 +376,7 @@ export function applyEditZoom(
     return;
   }
   const [panel] = surface.panels;
-  if (!panel?.canvas || !panel.viewport) {
+  if (!panel || !isPanelBound(panel)) {
     return;
   }
   const canvasEl = panel.canvas;
@@ -458,6 +485,14 @@ export function requestEditZoom(
   );
 }
 
+/** The screen pixels a stage reserves above its boards (`--boards-inset`), or 0 for none. */
+export function boardsInset(panzoomWrap: HTMLElement): number {
+  // The inset is declared in px (`--boards-inset:40px`); unset reads as "", which is no inset.
+  const declared = getComputedStyle(panzoomWrap).getPropertyValue("--boards-inset").trim();
+  const inset = Number(declared.replace(/px$/, ""));
+  return Number.isFinite(inset) ? inset : 0;
+}
+
 /**
  * Compute and apply a geometric fit. Pure arithmetic — it declares nothing.
  *
@@ -470,7 +505,9 @@ function applyGeometricFit(surface: CanvasSurface, axis: "width" | "page", maxZo
     return;
   }
   const wrapWidth = surface.wrap.clientWidth;
-  const wrapHeight = surface.wrap.clientHeight;
+  // The boards' own top clearance (`--boards-inset`, the Project Styles bar) is screen space the
+  // Artboards cannot use, so the page is fitted into what is left below it.
+  const wrapHeight = surface.wrap.clientHeight - boardsInset(surface.panzoomWrap);
   const gap = 24;
   const padding = 32;
   let totalPanelWidth = 0;
@@ -571,12 +608,12 @@ export const FIT_WORDS: readonly string[] = ["width", "page", "none"];
  * assistant sees. It stays as the typed read the body needs (`args.fit` is `unknown`) and as the
  * refusal for a caller that reaches the body directly.
  */
-function fitArg(commandId: string, args: Record<string, unknown>, key: string): FitMode {
+function fitArg(commandId: string, args: CommandArgValues, key: string): FitMode {
   const value = args[key];
-  if (typeof value === "string" && FIT_WORDS.includes(value)) {
-    return value as FitMode;
+  if (isFitWord(value)) {
+    return value;
   }
-  if (typeof value === "number" && value >= PAN_ZOOM_MIN && value <= PAN_ZOOM_MAX) {
+  if (isNumber(value) && value >= PAN_ZOOM_MIN && value <= PAN_ZOOM_MAX) {
     return value;
   }
   throw new RangeError(
@@ -585,6 +622,11 @@ function fitArg(commandId: string, args: Record<string, unknown>, key: string):
   );
 }
 
+/** Whether a value is one of {@link FIT_WORDS}, the named (non-scale) fits. */
+function isFitWord(value: unknown): value is Exclude<FitMode, number> {
+  return isString(value) && FIT_WORDS.includes(value);
+}
+
 /** Declared fits, keyed per tab + document. */
 const _fits = new Map<string, FitMode>();
 
@@ -641,7 +683,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;
@@ -733,11 +775,12 @@ export function resetZoom(surface: CanvasSurface = activeCanvasSurface()) {
  * hands a rect back), so one arithmetic serves a rect measured from a parent DOM element and a rect
  * measured inside a canvas iframe alike.
  *
- * **The viewport is the box that SCROLLS, not the stage.** Edit docks the Document Header card
- * above its scroller, inside the same stage cell, so there the stage is the band plus the page and
- * its centre is half a band too high: a reveal would land the node that far above the middle of
- * what the author can actually see. {@link revealScroller} is that box wherever there is one, and
- * where there is none (Design, Stylebook, a comparison) the stage is still the viewport.
+ * **The viewport is the box that SCROLLS, not the stage.** Over a collection entry Edit stands the
+ * writing banner above its scroller, inside the same stage cell, so there the stage is the banner
+ * plus the page and its centre is half a banner too high: a reveal would land the node that far
+ * above the middle of what the author can actually see. {@link revealScroller} is that box wherever
+ * there is one, and where there is none (Design, Stylebook, a comparison) the stage is still the
+ * viewport.
  */
 function centeringOffset(surface: CanvasSurface, rect: { top: number; height: number }): number {
   const viewport = rectOf(revealScroller(surface) ?? surface.wrap);
@@ -810,6 +853,37 @@ export function panToParentRect(
   revealBy(surface, centeringOffset(surface, rect), false);
 }
 
+/**
+ * Bring a PARENT-VIEWPORT rect into view on a pan/zoom stage, moving as little as it must: not at
+ * all when the rect is already wholly in view, and never so far that the boards' top edge comes
+ * down past where it stands now.
+ *
+ * {@link panToParentRect} always centres, which is right for a jump to a diff change or a node the
+ * author asked to see. The stylebook's Outline is a list the author clicks DOWN, and centring its
+ * first rows meant the h1 at the very top of a fitted catalogue pulled every board half a pane
+ * down, leaving an empty band above them and no specimen that had moved into view.
+ */
+export function revealParentRect(
+  rect: { top: number; height: number },
+  surface: CanvasSurface = activeCanvasSurface(),
+) {
+  const viewport = rectOf(surface.wrap);
+  if (rect.top >= viewport.top && rect.top + rect.height <= viewport.top + viewport.height) {
+    return;
+  }
+  const offset = centeringOffset(surface, rect);
+  const ceiling = Math.max(surface.panY, 0) - surface.panY;
+  const step = Math.min(offset, ceiling);
+  if (step !== 0) {
+    /* A reveal is a pan somebody asked for, so the entry's centring stands down as a user's pan
+       makes it: a frame still growing to its height would otherwise re-centre the stage (top
+       aligned) under the card just brought on screen, which is what a reveal on a fresh stylebook
+       canvas did. */
+    surface.needsCenter = false;
+    animatePanBy(surface, step);
+  }
+}
+
 /** Animate a stage's `panY` by `offsetY` with the shared 250ms ease-out. */
 function animatePanBy(surface: CanvasSurface, offsetY: number) {
   const startY = surface.panY;
@@ -844,6 +918,7 @@ export const CANVAS_MODES = [
   "preview",
   "source",
   "stylebook",
+  "tokens",
   "grid",
   "git-diff",
 ] as const;
@@ -853,6 +928,11 @@ export type CanvasMode = (typeof CANVAS_MODES)[number];
 /** The base modes the preview flag composes with — the two the Canvas view axis shows it beside. */
 const PREVIEWABLE_BASE_MODES = new Set(["edit", "design"]);
 
+/** Whether a base mode is one the preview flag composes with: a member of PREVIEWABLE_BASE_MODES. */
+function isPreviewableBase(mode: string): mode is "edit" | "design" {
+  return PREVIEWABLE_BASE_MODES.has(mode);
+}
+
 // ─── The Canvas view (§4.2) ──────────────────────────────────────────────────
 // `Edit │ Design` is a radio and `Preview` is a TOGGLE beside it, because that is what the storage
 // Has always been: `preview` is not a base mode, it is a flag that composes with one.
@@ -913,7 +993,13 @@ export function canvasBaseViewsFor(tab: ViewableTab): CanvasView[] {
 /** The base view the tab returns to — what the radio marks while preview is on. */
 export function canvasBaseViewOf(tab: ViewableTab): CanvasView | null {
   const base = tab.session.ui.canvasMode;
-  return PREVIEWABLE_BASE_MODES.has(base) ? (base as CanvasView) : null;
+  return isPreviewableBase(base) ? base : null;
+}
+
+/** A tab's Preview toggle: whether it is offered, and whether it is pressed. */
+export interface PreviewState {
+  available: boolean;
+  on: boolean;
 }
 
 /**
@@ -922,7 +1008,7 @@ export function canvasBaseViewOf(tab: ViewableTab): CanvasView | null {
  * `available` is a fact about the DOCUMENT (its declared modes) and about the base it is currently
  * in — `source` composes with no preview, so the toggle is not offered there.
  */
-export function previewStateOf(tab: ViewableTab): { available: boolean; on: boolean } {
+export function previewStateOf(tab: ViewableTab): PreviewState {
   return {
     available:
       tab.capabilities.modes.includes("preview") &&
@@ -1041,7 +1127,7 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
    * than the control it replaced, which is the opposite of the point.
    */
   function contextTab(commandId: string, args: CommandArgValues) {
-    const { pane } = args as { pane?: unknown };
+    const { pane } = args;
     if (pane === undefined) {
       return requireTab(commandId);
     }
@@ -1073,8 +1159,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 [
@@ -1103,7 +1189,7 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
         description:
           "Switch the active document's editor mode. edit and design put its element tree on " +
           "the canvas, where the document tools work; preview renders it as a visitor sees it; " +
-          "source shows the JSON; stylebook, grid and git-diff open other editors. Use it to " +
+          "source shows the JSON; stylebook, tokens, grid and git-diff open other editors. Use it to " +
           "return a document to edit or design when the tree tools are refused.",
         name: "set_canvas_mode",
         /* `after.editor.kind` rather than the tab's own field: it is the gate's read (`treeEditable`
@@ -1258,9 +1344,9 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
        * so it simply renders at the pane's width — which is the same clamp the drag applies, arrived
        * at by CSS instead of by arithmetic. Refusing would make the verb depend on the window size.
        */
-      run: (_commandCtx, args) => {
+      run: (_commandCtx, args: CommandArgValues) => {
         const tab = contextTab("canvas.setEditWidth", args);
-        const { width } = args as { width?: unknown };
+        const { width } = args;
         if (width === null) {
           clearEditWidth(paneOfArgs(args));
           repaint(args);
@@ -1311,10 +1397,10 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
       group: "3_canvas",
       requires: "an open document",
       when: documentOpen,
-      run: (_commandCtx, args) => {
+      run: (_commandCtx, args: CommandArgValues) => {
         const tab = contextTab("canvas.setBreakpoint", args);
-        const { media } = args as { media?: unknown };
-        if (media !== null && typeof media !== "string") {
+        const { media } = args;
+        if (media !== null && !isString(media)) {
           throw new RangeError(
             `command "canvas.setBreakpoint" argument "media": expected a breakpoint key or null`,
           );
@@ -1323,9 +1409,7 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
            that does not exist — the rule `data.expandRow` applies to a state entry's name.
            `getEffectiveMedia` and not `document.$media`: the popover offers the SITE's breakpoints
            too, and a command that refused what the control offers would be worse than no command. */
-        const declared = Object.keys(
-          getEffectiveMedia(tab.doc.document?.$media as Record<string, string> | undefined),
-        );
+        const declared = Object.keys(getEffectiveMedia(tab.doc.document.$media));
         if (media !== null && !declared.includes(media)) {
           throw new RangeError(
             `command "canvas.setBreakpoint" argument "media": "${media}" is not a breakpoint this ` +
@@ -1359,7 +1443,7 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
           args,
           "scheme",
           COLOR_SCHEMES,
-        ) as "auto" | "dark" | "light";
+        );
         repaint(args);
       },
       title: "Set Color Scheme",
@@ -1372,9 +1456,9 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
      * preset owns it. What is left over is genuinely a rendering context, and it is the half of
      * site-architecture.md §13.4 the canvas can show today: the artboard root's `lang` and `dir`.
      * That is why this is a verb and not a label — an RTL locale mirrors the layout on screen.
-     * (That section's other half, `$page.locale` in the rendered state, is injected by the
-     * compiler and not by the canvas's `substitutePreviewParams`; previewing it is a separate
-     * change to the render path.)
+     * (That section's other half, `$page.locale`, is injected into the canvas render from the
+     * page's route, as the build injects it (studio.md §4.1). This verb leaves it alone: the
+     * pane's language is a rendering context, not the page's (§20.2).)
      *
      * It lives in this file rather than in `i18n/i18n-commands.ts` because `contextTab`, `paneArg`
      * and `repaint` are local closures here, and every rendering-context verb needs all three: the
@@ -1475,16 +1559,18 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
       level: "document",
       menus: ["palette"],
       requires: "a popover in the open document",
-      run: (_commandCtx, args) => {
+      run: (_commandCtx, args: CommandArgValues) => {
         const tab = contextTab("canvas.setPopoverOpen", args);
-        const raw = (args ?? {}) as { open?: unknown; path?: JxPath };
+        /* SAFETY: `registry.run` coerces args against this record's schema before `run`, and the
+           schema declares `path` an array of strings and numbers, which is what a JxPath is. */
+        const explicitPath = args["path"] as JxPath | undefined;
         const open =
-          raw.open === undefined ? true : booleanArg("canvas.setPopoverOpen", args, "open");
-        if (!open && raw.path === undefined) {
+          args["open"] === undefined ? true : booleanArg("canvas.setPopoverOpen", args, "open");
+        if (!open && explicitPath === undefined) {
           deps.setOpenPopover(tab, null);
           return;
         }
-        const path = popoverPathFor(tab, raw.path);
+        const path = popoverPathFor(tab, explicitPath);
         /* REFUSES a path that is not a popover rather than opening nothing — the rule
            `canvas.setBreakpoint` applies to a breakpoint key. A <dialog> is refused with it: its UA
            rules key off `open`, not `popover`, so de-popovering one falls back to a different rule
@@ -1535,16 +1621,18 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
       level: "document",
       menus: ["palette"],
       requires: "a dialog in the open document",
-      run: (_commandCtx, args) => {
+      run: (_commandCtx, args: CommandArgValues) => {
         const tab = contextTab("canvas.setDialogOpen", args);
-        const raw = (args ?? {}) as { open?: unknown; path?: JxPath };
+        /* SAFETY: `registry.run` coerces args against this record's schema before `run`, and the
+           schema declares `path` an array of strings and numbers, which is what a JxPath is. */
+        const explicitPath = args["path"] as JxPath | undefined;
         const open =
-          raw.open === undefined ? true : booleanArg("canvas.setDialogOpen", args, "open");
-        if (!open && raw.path === undefined) {
+          args["open"] === undefined ? true : booleanArg("canvas.setDialogOpen", args, "open");
+        if (!open && explicitPath === undefined) {
           deps.setOpenDialog(tab, null);
           return;
         }
-        const path = dialogPathFor(tab, raw.path);
+        const path = dialogPathFor(tab, explicitPath);
         /* REFUSES a path that is not a dialog, for the same reason its twin refuses a non-popover:
            the canvas would draw it under the wrong rule and with the wrong name. */
         if (path === null) {
@@ -1586,14 +1674,14 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
        * (`scripts/screenshots/README.md`) forbids outright. The pointer and the camera use the same
        * door.
        */
-      run: (_commandCtx, args) => {
+      run: (_commandCtx, args: CommandArgValues) => {
         // Resolve the tab first, so a pane with no document refuses before anything opens.
         contextTab("canvas.setResolvingOpen", args);
-        const { open, pane } = args as { open?: unknown; pane?: unknown };
+        const { open, pane } = args;
         // `open` defaults to true and is never COERCED: `{ open: "no" }` would otherwise read as a
         // Close, the class of silent wrong answer this setter family exists to stop.
         deps.setResolvingOpen(
-          typeof pane === "string" ? pane : workspace.activePaneId,
+          isString(pane) ? pane : workspace.activePaneId,
           open === undefined || booleanArg("canvas.setResolvingOpen", args, "open"),
         );
       },
@@ -1636,26 +1724,24 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
       group: "3_canvas",
       requires: "an open component document",
       when: documentOpen,
-      run: (_commandCtx, args) => {
+      run: (_commandCtx, args: CommandArgValues) => {
         const tab = contextTab("canvas.setTestProp", args);
         const name = stringArg("canvas.setTestProp", args, "name");
         // REFUSES a prop the component does not declare, rather than seeding a value nothing reads
         // — the rule `data.expandRow` and `canvas.setBreakpoint` both apply to their own names.
-        const declared = Object.keys(
-          (tab.doc.document?.state as Record<string, unknown> | undefined) ?? {},
-        );
+        const declared = Object.keys(tab.doc.document.state ?? {});
         if (!declared.includes(name)) {
           throw new RangeError(
             `command "canvas.setTestProp" argument "name": "${name}" is not a prop this component ` +
               `declares — it declares: ${declared.length > 0 ? declared.join(", ") : "nothing"}`,
           );
         }
-        const { value } = args as { value?: unknown };
+        const { value } = args;
         const next = { ...tab.session.ui.previewProps };
         if (value === null || value === undefined) {
           delete next[name];
         } else {
-          next[name] = value as JsonValue;
+          next[name] = value;
         }
         tab.session.ui.previewProps = Object.keys(next).length > 0 ? next : null;
         repaint(args);
@@ -1723,13 +1809,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,