@jxsuite/studio 6.1.1 → 8.0.0

package/src/tabs/tab.ts

@@ -1,12 +1,14 @@
 /// <reference lib="dom" />
 import { effectScope, reactive } from "../reactivity";
 import { formatByName, formatForPath } from "../format/format-host";
-import { normalizeArrayChildren } from "../state";
+import type { FormatFrontmatter } from "../format/format-host";
+import { normalizeDocument } from "./bare-repeaters";
+import type { BareRepeaters } from "./bare-repeaters";
 import type { JxPath } from "../state";
 import type { FormulaEditDef, FunctionEditDef, InlineEditDef, JsonValue } from "../types";
 import { editorKindForMode } from "../commands/context";
 import type { EditorKind } from "../commands/context";
-import type { JxMutableNode } from "@jxsuite/schema/types";
+import type { JsonObject, JxMutableNode } from "@jxsuite/schema/types";
 import type { JxDocOp, JxFmOp } from "./patch-ops";
 import type { JsonLayout } from "@jxsuite/schema/json-layout";
 
@@ -14,13 +16,20 @@ import type { JsonLayout } from "@jxsuite/schema/json-layout";
  * The project's configuration file, project-relative.
  *
  * Named here rather than at the four places that used to spell it, because it is a DOCUMENT PATH —
- * `inferModes` answers `["stylebook", "source"]` for it (editor kind `config`), and
- * `tabs/project-config.ts` binds the tab at this path as the configuration document.
+ * `inferModes` answers `["stylebook", "tokens", "source"]` for it (the Styles workspace's Elements,
+ * Variables and Code views; editor kind `config`), and `tabs/project-config.ts` binds the tab at
+ * this path as the configuration document.
  */
 export const PROJECT_CONFIG_PATH = "project.json";
 
 export interface TabUi {
+  /** The Inspector leaf showing (`shell.ts`'s `INSPECTOR_TAB_IDS`); Page on a fresh tab (§6). */
   rightTab: string;
+  /**
+   * The Element leaf last shown — Content, Style or Logic — so the selection-driven switch from
+   * Page returns to the view the author was using rather than always to Content (§6).
+   */
+  elementTab: string;
   canvasMode: string;
   /** Preview toggle — composes with an edit/design canvasMode; the effective mode becomes "preview". */
   preview: boolean;
@@ -125,7 +134,7 @@ export interface StoredLivePreview {
 
 interface HistorySnapshot {
   /** Full document at this state (checkpoint), or null when the ops describe the transition. */
-  document: Record<string, unknown> | null;
+  document: JxMutableNode | null;
   /** Selection after this state's transaction — the whole set, so a batch undoes back to it. */
   selection: (string | number)[][];
   /** Selection before this state's transaction (restored on surgical undo). */
@@ -177,11 +186,10 @@ export interface Tab {
   scope: {
     stop: () => void;
     run: <T>(fn: () => T) => T | undefined;
-    [k: string]: unknown;
   };
   doc: {
     document: JxMutableNode;
-    content: { frontmatter: Record<string, unknown> };
+    content: { frontmatter: FormatFrontmatter };
     mode: string;
     sourceFormat: string | null;
     handlersSource: string | null;
@@ -198,6 +206,22 @@ export interface Tab {
      * file.
      */
     layout: JsonLayout | null;
+    /**
+     * The text a format-class file (Markdown) was read as, or null for a JSON document, a new
+     * document or a stub. The format's serializer is handed it on save
+     * (`files/serialize-document.ts`) so every frontmatter key the author did not edit keeps its
+     * own spelling and the body keeps its markers (`@jxsuite/parser` `source-style.ts`). The
+     * lifetime is `layout`'s: an edit leaves it alone, and a read from disk, a source-view commit,
+     * a peer's text or a save replaces it with the text just read or written.
+     */
+    source: string | null;
+    /**
+     * The repeaters the file wrote as a node's whole `children`, which loading rewrote into the
+     * member form the editor works in (`tabs/bare-repeaters.ts`); null when it wrote none. A fact
+     * about the file with the lifetime `layout` has: a reload or a source-view commit replaces it,
+     * an edit or an undo leaves it alone, and a save writes those repeaters back as they were.
+     */
+    bareRepeaters: BareRepeaters | null;
   };
   session: {
     /**
@@ -230,7 +254,7 @@ export interface Tab {
       // A serializable snapshot of the iframe's resolved `$defs` (data-source values), posted over
       // The bridge as a `dataScope` message and read by the data-explorer panel. Plain data now —
       // The old live `EffectScope` (with `.stop()`) moved into the iframe realm with buildScope.
-      scope: Record<string, unknown> | null;
+      scope: JsonObject | null;
       // Latest live (iframe-evaluated) expression previews keyed by editing-target id, stored
       // Beside `scope` the same way (services/live-preview.ts owns reads/writes).
       livePreviews: Record<string, StoredLivePreview> | null;
@@ -249,7 +273,7 @@ export interface Tab {
  * @param {boolean} preview — initial preview-toggle state
  * @returns {TabUi}
  */
-function createDefaultUi(canvasMode: string, preview = false) {
+function createDefaultUi(canvasMode: string, preview = false): TabUi {
   return {
     activeMedia: null,
     activeSelector: null,
@@ -264,10 +288,11 @@ function createDefaultUi(canvasMode: string, preview = false) {
     pendingInlineEdit: null,
     preview,
     previewColorScheme: "auto" as const,
-    previewLocale: null as string | null,
+    previewLocale: null,
     previewParams: {},
     previewProps: null,
-    rightTab: "properties",
+    rightTab: "page",
+    elementTab: "properties",
     showLayout: true,
     styleFilter: "",
     styleSections: {},
@@ -295,13 +320,14 @@ const ALL_MODES = ["edit", "design", "preview", "source", "stylebook", "git-diff
  *   id: string;
  *   documentPath?: string | null;
  *   fileHandle?: FileSystemFileHandle | null;
- *   document: Record<string, unknown>;
- *   frontmatter?: Record<string, unknown>;
+ *   document: JxMutableNode;
+ *   frontmatter?: FormatFrontmatter;
  *   sourceFormat?: string | null;
  *   capabilities?: { modes?: string[] };
  *   openedFrom?: TabOrigin | null;
  *   preview?: boolean;
  *   layout?: JsonLayout | null;
+ *   source?: string | null;
  * }} opts
  * @returns {Tab}
  */
@@ -316,71 +342,93 @@ export function createTab({
   openedFrom = null,
   preview: previewTab = false,
   layout = null,
+  source = null,
+  canvasMode,
 }: {
   id: string;
   documentPath?: string | null;
   fileHandle?: FileSystemFileHandle | null;
-  document: Record<string, unknown>;
-  frontmatter?: Record<string, unknown>;
+  document: JxMutableNode;
+  frontmatter?: FormatFrontmatter;
   sourceFormat?: string | null;
   capabilities?: { modes?: string[] };
   openedFrom?: TabOrigin | null;
   preview?: boolean;
   layout?: JsonLayout | null;
+  /** The text a format-class file was read as (`doc.source`). */
+  source?: string | null;
+  /**
+   * The mode to open in instead of the first declared one: a comparison opens straight into
+   * `git-diff`, so the tab is never active in an edit mode that belongs to another workspace.
+   */
+  canvasMode?: string | undefined;
 }) {
   const scope = effectScope();
 
   // Normalize legacy whole-children repeaters to the canonical array-member form before the doc
   // (and its first history checkpoint) are stored.
-  normalizeArrayChildren(document);
+  const bareRepeaters = normalizeDocument(document);
 
   const resolvedModes = capabilities?.modes ?? inferModes(documentPath, sourceFormat);
   // A tab opens in its first allowed mode — never one the toolbar would disable.
   // Formats author mode order so the default comes first (edit, stylebook, etc.).
   // "preview" is a per-tab toggle rather than a base mode: a preview-first format opens
   // In its first non-preview mode with the toggle already on.
-  const initialCanvasMode = resolvedModes.find((m) => m !== "preview") ?? "edit";
+  const initialCanvasMode = canvasMode ?? resolvedModes.find((m) => m !== "preview") ?? "edit";
   const initialPreview = resolvedModes[0] === "preview";
 
+  const doc: Tab["doc"] = {
+    bareRepeaters,
+    content: { frontmatter: frontmatter || {} },
+    dirty: false,
+    document,
+    handlersSource: null,
+    layout,
+    mode: inferDocumentMode(documentPath, sourceFormat),
+    source,
+    sourceFormat,
+  };
+  const history: Tab["history"] = {
+    index: 0,
+    snapshots: [{ document: structuredClone(document), selection: [] }],
+  };
+  const session: Tab["session"] = {
+    canvas: {
+      refreshing: false,
+      error: null,
+      livePreviews: null,
+      pendingInlineEdit: null,
+      scope: null,
+      status: "idle",
+    },
+    clipboard: null,
+    hover: null,
+    openedFrom,
+    selection: [],
+    ui: createDefaultUi(initialCanvasMode, initialPreview),
+  };
+
+  /* SAFETY: `reactive()` returns a deep proxy carrying its target's own members, and none of these
+     Three trees holds a ref for `UnwrapNestedRefs` to unwrap, so each proxy IS the shape it is cast
+     To. The type argument is pinned to `object` because `UnwrapNestedRefs<JxMutableNode>` recurses
+     Deeply enough for tsc to give up (TS2589); the proxies are deep either way. */
   const tab = scope.run(() => ({
     capabilities: { modes: resolvedModes },
-    doc: reactive({
-      content: { frontmatter: frontmatter || {} },
-      dirty: false,
-      document,
-      handlersSource: null,
-      layout,
-      mode: inferDocumentMode(documentPath, sourceFormat),
-      sourceFormat,
-    }),
+    doc: reactive<object>(doc) as Tab["doc"],
     documentPath,
     fileHandle,
-    history: reactive({
-      index: 0,
-      snapshots: [{ document: structuredClone(document), selection: [] }],
-    }),
+    history: reactive<object>(history) as Tab["history"],
     id,
     pinned: false,
     preview: previewTab,
     scope,
-    session: reactive({
-      canvas: {
-        refreshing: false,
-        error: null,
-        livePreviews: null,
-        pendingInlineEdit: null,
-        scope: null,
-        status: "idle",
-      },
-      clipboard: null,
-      hover: null,
-      openedFrom,
-      selection: [],
-      ui: createDefaultUi(initialCanvasMode, initialPreview),
-    }),
-  })) as unknown as Tab;
+    session: reactive<object>(session) as Tab["session"],
+  }));
 
-  return tab;
+  /* SAFETY: `scope` was created at the top of this function and nothing has stopped it, and an
+     Active scope's `run` always returns its callback's value; `undefined` is only what an inactive
+     Scope answers. */
+  return tab as Tab;
 }
 
 /**
@@ -393,7 +441,10 @@ export function createTab({
  */
 function inferModes(documentPath: string | null | undefined, sourceFormat: string | null) {
   if (documentPath === PROJECT_CONFIG_PATH) {
-    return ["stylebook", "source"];
+    /* Elements, Variables and Code: the Styles workspace's three views. Spelled here rather than
+       imported from `style/project-styles` (`STYLES_TAB_MODES`), whose imports reach `store`,
+       which imports this module; `tests/project-config.test.ts` holds the two lists equal. */
+    return ["stylebook", "tokens", "source"];
   }
   const format = formatByName(sourceFormat) ?? formatForPath(documentPath);
   if (format) {

package/src/tabs/transact.ts

@@ -4,9 +4,9 @@ import { jsonClone } from "../utils/studio-utils";
 import { childIndex, getNodeAtPath, parentElementPath, pathsEqual } from "../state";
 import {
   cloneSelection,
-  isSpliceablePath,
   primarySelection,
   pruneSelection,
+  spliceCoordinate,
   structuralBatch,
 } from "./selection";
 import { applyDocOpToDoc, childArray, cloneValue, inverseOf } from "./doc-op-apply";
@@ -19,7 +19,7 @@ import {
   recordPatch,
 } from "./patch-ops";
 
-import type { JxDocOp, JxDocOpPair, JxFmOp, TransactionRecord } from "./patch-ops";
+import type { JxDocOp, JxDocOpPair, TransactionRecord } from "./patch-ops";
 
 import type { Tab } from "../tabs/tab";
 import type { JxPath } from "../state";
@@ -27,12 +27,19 @@ import type { JxPath } from "../state";
 import type { JsonValue } from "../types";
 import type {
   JxAttributeValue,
+  JxDocumentValue,
   JxEventBinding,
   JxMutableNode,
   JxStateObject,
   JxStyle,
 } from "@jxsuite/schema/types";
-import { ensureNestedStyle, getNestedStyle, isEventBinding } from "@jxsuite/schema/guards";
+import {
+  ensureNestedStyle,
+  getNestedStyle,
+  isEventBinding,
+  isNonNullObject,
+  isNumber,
+} from "@jxsuite/schema/guards";
 
 const HISTORY_LIMIT = 100;
 
@@ -48,8 +55,26 @@ function patchHistoryEnabled() {
   }
 }
 
+/**
+ * The node `path` names, for a mutation that cannot proceed without one. A path that no longer
+ * resolves throws a TypeError inside the transaction, which rolls the transaction back, exactly as
+ * dereferencing the missing node did before this check existed.
+ */
+function requireNodeAt(doc: JxMutableNode, path: JxPath): JxMutableNode {
+  const node = getNodeAtPath(doc, path);
+  if (!node) {
+    throw new TypeError(`No node at path [${path.join(", ")}]`);
+  }
+  return node;
+}
+
 /** Forward/inverse pair for a single-key change on the node at path. */
-function setKeyPair(path: JxPath, key: string, before: unknown, after: unknown): JxDocOpPair {
+function setKeyPair(
+  path: JxPath,
+  key: string,
+  before: JxDocumentValue | undefined,
+  after: JxDocumentValue | undefined,
+): JxDocOpPair {
   return {
     forward: { key, op: "set-key", path, value: after },
     inverse: { key, op: "set-key", path, value: before },
@@ -71,10 +96,10 @@ function shiftPrefixedIndex(
 ): JxPath {
   const d = parentPath.length;
   const isProperPrefix = d < path.length && parentPath.every((seg, i) => seg === path[i]);
-  if (!isProperPrefix || path[d] !== "children" || typeof path[d + 1] !== "number") {
+  const idx = path[d + 1];
+  if (!isProperPrefix || path[d] !== "children" || !isNumber(idx)) {
     return path;
   }
-  const idx = path[d + 1] as number;
   if (inclusive ? idx < spliceIndex : idx <= spliceIndex) {
     return path;
   }
@@ -152,7 +177,7 @@ function rollbackFailedTransaction(
   dirtyBefore: boolean,
 ) {
   for (let i = record.docOps.length - 1; i >= 0; i--) {
-    applyDocOpToDoc(tab.doc.document, toRaw(record.docOps[i]!.inverse) as JxDocOp);
+    applyDocOpToDoc(tab.doc.document, toRaw(record.docOps[i]!.inverse));
   }
   for (let i = record.fmOps.length - 1; i >= 0; i--) {
     const op = record.fmOps[i]!;
@@ -355,10 +380,11 @@ function materializeState(
   while (base >= 0 && !snapshots[base]!.document) {
     base -= 1;
   }
-  if (base < 0) {
+  const checkpoint = base < 0 ? null : snapshots[base]!.document;
+  if (!checkpoint) {
     throw new Error("history-missing-checkpoint");
   }
-  const doc = jsonClone(snapshots[base]!.document) as JxMutableNode;
+  const doc = jsonClone(checkpoint);
   for (let i = base + 1; i <= target; i++) {
     for (const op of snapshots[i]!.forwardOps ?? []) {
       applyDocOpToDoc(doc, op);
@@ -418,8 +444,11 @@ const DOC_META_KEYS = new Set(["state", "$media", "$head", "$elements", "imports
  * @param {JxDocOp} op
  */
 function applyDocOp(tab: Tab, op: JxDocOp) {
-  const prev =
-    op.op === "set-key" ? (getNodeAtPath(tab.doc.document, op.path)?.[op.key] as unknown) : null;
+  let prev: JxDocumentValue | undefined | null = null;
+  if (op.op === "set-key") {
+    const node = getNodeAtPath(tab.doc.document, op.path);
+    prev = node?.[op.key];
+  }
   applyDocOpToDoc(tab.doc.document, op);
   // The canvas lives in an iframe and can only be patched from VALUE-CARRYING ops (`record.docOps`),
   // Which is what crosses the bridge. Recording only the classification patch below left docOps
@@ -617,12 +646,12 @@ export function undo(tab: Tab) {
       (t) => {
         if (inverseOps) {
           for (let i = inverseOps.length - 1; i >= 0; i--) {
-            applyDocOp(t, toRaw(inverseOps[i]) as JxDocOp);
+            applyDocOp(t, toRaw(inverseOps[i]!));
           }
         }
         if (fmOps) {
           for (let i = fmOps.length - 1; i >= 0; i--) {
-            const op = toRaw(fmOps[i]) as JxFmOp;
+            const op = toRaw(fmOps[i]!);
             applyFmState(t, op.field, op.before);
           }
         }
@@ -666,12 +695,12 @@ export function redo(tab: Tab) {
       (t) => {
         if (forwardOps) {
           for (const op of forwardOps) {
-            applyDocOp(t, toRaw(op) as JxDocOp);
+            applyDocOp(t, toRaw(op));
           }
         }
         if (fmOps) {
           for (const op of fmOps) {
-            const raw = toRaw(op) as JxFmOp;
+            const raw = toRaw(op);
             applyFmState(t, raw.field, raw.after);
           }
         }
@@ -731,15 +760,20 @@ export function mutateInsertNode(
  * @param {JxPath} path
  */
 export function mutateRemoveNode(tab: Tab, path: JxPath) {
-  if (!path || !isSpliceablePath(path)) {
+  const at = spliceCoordinate(path);
+  if (!at) {
     return;
   }
-  const elemPath = parentElementPath(path) as JxPath;
-  const idx = childIndex(path) as number;
-  const [removed] = (getNodeAtPath(tab.doc.document, elemPath).children as JxMutableNode[]).splice(
-    idx,
-    1,
-  );
+  const { index: idx, parentPath: elemPath } = at;
+  /* SAFETY: a spliceable path addresses a member of its parent's children, and every document a
+     tab holds is in the static-array member form (`normalizeArrayChildren` runs on load), so the
+     parent resolves to a node whose children are an array. The paths that reach here are live ones
+     (the pruned selection, an inline edit's own block), so the index names a member and the splice
+     removes exactly one. A stale parent path throws (`requireNodeAt`), inside the transaction, which
+     rolls back. */
+  const [removed] = (
+    requireNodeAt(tab.doc.document, elemPath).children as (JxMutableNode | string)[]
+  ).splice(idx, 1) as [JxMutableNode | string];
   recordPatch({ op: "remove", path });
   recordDocOp({
     forward: { index: idx, op: "remove-child", parentPath: elemPath },
@@ -753,17 +787,19 @@ export function mutateRemoveNode(tab: Tab, path: JxPath) {
  * @param {JxPath} path
  */
 export function mutateDuplicateNode(tab: Tab, path: JxPath) {
-  if (!path || !isSpliceablePath(path)) {
+  const at = spliceCoordinate(path);
+  if (!at) {
     return;
   }
   const node = getNodeAtPath(tab.doc.document, path);
   if (!node) {
     return;
   }
-  const elemPath = parentElementPath(path) as JxPath;
-  const idx = childIndex(path) as number;
+  const { index: idx, parentPath: elemPath } = at;
   const clone = structuredClone(toRaw(node));
-  (getNodeAtPath(tab.doc.document, elemPath).children as JxMutableNode[]).splice(idx + 1, 0, clone);
+  /* SAFETY: `node` resolved above, so its parent does too, and every document a tab holds keeps
+     static children arrays (`normalizeArrayChildren` runs on load) — `node` is a member of one. */
+  (requireNodeAt(tab.doc.document, elemPath).children as JxMutableNode[]).splice(idx + 1, 0, clone);
   recordPatch({ index: idx + 1, op: "insert", parentPath: elemPath });
   recordDocOp({
     forward: { index: idx + 1, node: cloneValue(clone), op: "insert-child", parentPath: elemPath },
@@ -813,17 +849,16 @@ export function mutateDuplicateNodes(tab: Tab, paths: readonly JxPath[]) {
     const before = tab.session.selection;
     mutateDuplicateNode(tab, path);
     const made = primarySelection(tab.session.selection);
+    const at = spliceCoordinate(made);
     // `mutateDuplicateNode` refuses a path that addresses nothing and leaves the selection alone;
-    // Only a real insertion contributes a clone.
-    if (!made || tab.session.selection === before) {
+    // Only a real insertion contributes a clone, and it selects the clone at a splice coordinate.
+    if (!made || !at || tab.session.selection === before) {
       continue;
     }
     // Descending order keeps the ORIGINALS valid, but not the clones already made: this insertion
     // Sits before them, so every one of their coordinates moved up by one. Translating them here
     // Is the difference between "the copies are selected" and "two of the originals are".
-    const parentPath = parentElementPath(made) as JxPath;
-    const spliceIndex = childIndex(made) as number;
-    clones = clones.map((clone) => shiftPrefixedIndex(parentPath, clone, spliceIndex, 1, true));
+    clones = clones.map((clone) => shiftPrefixedIndex(at.parentPath, clone, at.index, 1, true));
     clones.unshift(made);
   }
   if (clones.length > 0) {
@@ -837,21 +872,23 @@ export function mutateDuplicateNodes(tab: Tab, paths: readonly JxPath[]) {
  * @param {string} wrapperTag
  */
 export function mutateWrapNode(tab: Tab, path: JxPath, wrapperTag = "div") {
-  if (!path || !isSpliceablePath(path)) {
+  const at = spliceCoordinate(path);
+  if (!at) {
     return;
   }
   const node = getNodeAtPath(tab.doc.document, path);
   if (!node) {
     return;
   }
-  const elemPath = parentElementPath(path) as JxPath;
-  const idx = childIndex(path) as number;
+  const { index: idx, parentPath: elemPath } = at;
   const wrapper = {
     children: [structuredClone(toRaw(node))],
     tagName: wrapperTag,
   };
   const original = cloneValue(node);
-  (getNodeAtPath(tab.doc.document, elemPath).children as JxMutableNode[]).splice(idx, 1, wrapper);
+  /* SAFETY: `node` resolved above, so its parent does too, and every document a tab holds keeps
+     static children arrays (`normalizeArrayChildren` runs on load) — `node` is a member of one. */
+  (requireNodeAt(tab.doc.document, elemPath).children as JxMutableNode[]).splice(idx, 1, wrapper);
   recordPatch({ op: "replace", path });
   recordDocOp({
     forward: { index: idx, node: cloneValue(wrapper), op: "set-child", parentPath: elemPath },
@@ -868,9 +905,9 @@ export function mutateWrapNode(tab: Tab, path: JxPath, wrapperTag = "div") {
  */
 export function mutateMoveNode(tab: Tab, fromPath: JxPath, toParentPath: JxPath, toIndex: number) {
   const doc = tab.doc.document;
-  const fromParentPath = parentElementPath(fromPath) as JxPath;
-  const fromIdx = childIndex(fromPath) as number;
-  if (!fromParentPath || typeof fromIdx !== "number") {
+  const fromParentPath = parentElementPath(fromPath);
+  const fromIdx = childIndex(fromPath);
+  if (!fromParentPath || !isNumber(fromIdx)) {
     return;
   }
   const fromParent = getNodeAtPath(doc, fromParentPath);
@@ -967,7 +1004,7 @@ export function mutateUpdateProperty(tab: Tab, path: JxPath, key: string, value?
  * @param {string | undefined} value
  */
 export function mutateUpdateStyle(tab: Tab, path: JxPath, prop: string, value: string | undefined) {
-  const node = getNodeAtPath(tab.doc.document, path);
+  const node = requireNodeAt(tab.doc.document, path);
   const styleBefore = cloneValue(node.style);
   if (!node.style) {
     node.style = {};
@@ -996,7 +1033,7 @@ export function mutateUpdateAttribute(
   attr: string,
   value?: JxAttributeValue | undefined,
 ) {
-  const node = getNodeAtPath(tab.doc.document, path);
+  const node = requireNodeAt(tab.doc.document, path);
   const attrsBefore = cloneValue(node.attributes);
   if (!node.attributes) {
     node.attributes = {};
@@ -1030,7 +1067,7 @@ export function mutateUpdateMediaStyle(
   if (!mediaName) {
     return mutateUpdateStyle(tab, path, prop, value);
   }
-  const node = getNodeAtPath(tab.doc.document, path);
+  const node = requireNodeAt(tab.doc.document, path);
   const styleBefore = cloneValue(node.style);
   if (!node.style) {
     node.style = {};
@@ -1066,7 +1103,7 @@ export function mutateUpdateNestedStyle(
   prop: string,
   value: string | undefined,
 ) {
-  const node = getNodeAtPath(tab.doc.document, path);
+  const node = requireNodeAt(tab.doc.document, path);
   const styleBefore = cloneValue(node.style);
   if (!node.style) {
     node.style = {};
@@ -1103,7 +1140,7 @@ export function mutateUpdateMediaNestedStyle(
   prop: string,
   value: string | undefined,
 ) {
-  const node = getNodeAtPath(tab.doc.document, path);
+  const node = requireNodeAt(tab.doc.document, path);
   const styleBefore = cloneValue(node.style);
   if (!node.style) {
     node.style = {};
@@ -1186,7 +1223,7 @@ export function mutateUpdateNestedStylePath(
   prop: string,
   value: string | undefined,
 ) {
-  const node = getNodeAtPath(tab.doc.document, path);
+  const node = requireNodeAt(tab.doc.document, path);
   const styleBefore = cloneValue(node.style);
   if (!node.style) {
     node.style = {};
@@ -1226,7 +1263,7 @@ export function mutateUpdateMediaNestedStylePath(
   prop: string,
   value: string | undefined,
 ) {
-  const node = getNodeAtPath(tab.doc.document, path);
+  const node = requireNodeAt(tab.doc.document, path);
   const styleBefore = cloneValue(node.style);
   if (!node.style) {
     node.style = {};
@@ -1259,7 +1296,7 @@ export function mutateUpdateMediaNestedStylePath(
  * @param {Record<string, string | undefined> | undefined} style
  */
 export function mutateReplaceStyle(tab: Tab, path: JxPath, style: JxStyle | undefined) {
-  const node = getNodeAtPath(tab.doc.document, path);
+  const node = requireNodeAt(tab.doc.document, path);
   const styleBefore = cloneValue(node.style);
   if (style && Object.keys(style).length > 0) {
     node.style = style;
@@ -1308,17 +1345,25 @@ export function mutateRemoveDef(tab: Tab, name: string) {
  * @param {string} name
  * @param {Record<string, JsonValue>} updates
  */
-export function mutateUpdateDef(tab: Tab, name: string, updates: Record<string, unknown>) {
+export function mutateUpdateDef(
+  tab: Tab,
+  name: string,
+  updates: Record<string, JxDocumentValue | undefined>,
+) {
   const doc = tab.doc.document;
   const stateBefore = cloneValue(doc.state);
   if (!doc.state) {
     doc.state = {};
   }
   const existing = doc.state[name];
+  /* SAFETY: what is left after null, primitives and arrays is one of the object entry forms (an
+     expanded signal, or a function, prototype, expression or server-function def). Each is a plain
+     record whose keys the loop below edits one by one, and JxStateObject is the open record that
+     edit needs; nothing here relies on a member that only one of the forms carries. */
   const entry: JxStateObject =
     existing == null
       ? {}
-      : typeof existing !== "object" || Array.isArray(existing)
+      : !isNonNullObject(existing) || Array.isArray(existing)
         ? { default: existing }
         : (existing as JxStateObject);
   doc.state[name] = entry;
@@ -1379,7 +1424,7 @@ export function mutateUpdateMedia(tab: Tab, name: string, query?: string | undef
  * @param {JsonValue} value
  */
 export function mutateUpdateProp(tab: Tab, path: JxPath, propName: string, value: JsonValue) {
-  const node = getNodeAtPath(tab.doc.document, path);
+  const node = requireNodeAt(tab.doc.document, path);
   const propsBefore = cloneValue(node.$props);
   if (!node.$props) {
     node.$props = {};
@@ -1408,7 +1453,7 @@ export function mutateAddSwitchCase(
   caseName: string,
   caseDef?: JxMutableNode,
 ) {
-  const node = getNodeAtPath(tab.doc.document, path);
+  const node = requireNodeAt(tab.doc.document, path);
   const before = cloneValue(node.cases);
   if (!node.cases) {
     node.cases = {};
@@ -1424,7 +1469,7 @@ export function mutateAddSwitchCase(
  * @param {string} caseName
  */
 export function mutateRemoveSwitchCase(tab: Tab, path: JxPath, caseName: string) {
-  const node = getNodeAtPath(tab.doc.document, path);
+  const node = requireNodeAt(tab.doc.document, path);
   if (node.cases) {
     const before = cloneValue(node.cases);
     delete node.cases[caseName];
@@ -1440,7 +1485,7 @@ export function mutateRemoveSwitchCase(tab: Tab, path: JxPath, caseName: string)
  * @param {string} newName
  */
 export function mutateRenameSwitchCase(tab: Tab, path: JxPath, oldName: string, newName: string) {
-  const node = getNodeAtPath(tab.doc.document, path);
+  const node = requireNodeAt(tab.doc.document, path);
   if (!node.cases || !node.cases[oldName]) {
     return;
   }
@@ -1479,7 +1524,7 @@ export function mutateUpdateFrontmatter(tab: Tab, field: string, value?: JsonVal
  * Unlike `mutateUpdateFrontmatter`, values like `""`/`false`/`null` are written verbatim (source
  * round-trips can put them there) and no fm op is recorded — history replay must not re-record.
  */
-function applyFmState(tab: Tab, field: string, value: unknown) {
+function applyFmState(tab: Tab, field: string, value: JxDocumentValue | undefined) {
   if (value === undefined) {
     delete tab.doc.content.frontmatter[field];
   } else {