@jxsuite/studio 6.1.0 → 6.1.2

package/src/tabs/selection.ts

@@ -42,6 +42,8 @@
  * standing between a mixed selection and a half-applied, unrecorded delete.
  */
 
+import { isNumber } from "@jxsuite/schema/guards";
+
 import type { JxPath } from "../state";
 import { isAncestor, pathsEqual } from "../state";
 
@@ -52,7 +54,7 @@ import { isAncestor, pathsEqual } from "../state";
  * @returns {JxPath | null}
  */
 export function primarySelection(selection: readonly JxPath[] | null | undefined): JxPath | null {
-  return selection && selection.length > 0 ? (selection.at(-1) as JxPath) : null;
+  return selection?.at(-1) ?? null;
 }
 
 /**
@@ -62,7 +64,7 @@ export function primarySelection(selection: readonly JxPath[] | null | undefined
  * @returns {JxPath | null}
  */
 export function selectionAnchor(selection: readonly JxPath[] | null | undefined): JxPath | null {
-  return selection && selection.length > 0 ? (selection[0] as JxPath) : null;
+  return selection?.[0] ?? null;
 }
 
 /**
@@ -187,7 +189,7 @@ export function comparePaths(a: JxPath, b: JxPath): number {
     if (x === y) {
       continue;
     }
-    if (typeof x === "number" && typeof y === "number") {
+    if (isNumber(x) && isNumber(y)) {
       return x - y;
     }
     return String(x) < String(y) ? -1 : 1;
@@ -231,7 +233,27 @@ export function topLevelSelection(selection: readonly JxPath[]): JxPath[] {
  * @returns {boolean}
  */
 export function isSpliceablePath(path: JxPath): boolean {
-  return path.at(-2) === "children" && typeof path.at(-1) === "number";
+  return spliceCoordinate(path) !== null;
+}
+
+/** Where a structural verb splices: the parent element's path and the index in its children. */
+export interface SpliceCoordinate {
+  parentPath: JxPath;
+  index: number;
+}
+
+/**
+ * The splice coordinate `path` names, or `null` for no path and for every path
+ * {@link isSpliceablePath} refuses.
+ *
+ * @param {JxPath | null | undefined} path
+ * @returns {SpliceCoordinate | null}
+ */
+export function spliceCoordinate(path: JxPath | null | undefined): SpliceCoordinate | null {
+  const index = path?.at(-1);
+  return path && path.at(-2) === "children" && isNumber(index)
+    ? { index, parentPath: path.slice(0, -2) }
+    : null;
 }
 
 /**
@@ -289,7 +311,13 @@ export function selectionsEqual(
 ): boolean {
   const x = a ?? [];
   const y = b ?? [];
-  return x.length === y.length && x.every((p, i) => pathsEqual(p, y[i] as JxPath));
+  return x.length === y.length && x.every((p, i) => pathsEqual(p, y[i] ?? null));
+}
+
+/** One field's value read across the selection: `mixed` when the selected nodes disagree. */
+export interface UnifiedValue<T> {
+  mixed: boolean;
+  value: T | undefined;
 }
 
 /**
@@ -306,13 +334,13 @@ export function selectionsEqual(
  *
  * @template T
  * @param {readonly T[]} values One per selected node, in selection order.
- * @returns {{ mixed: boolean; value: T | undefined }}
+ * @returns {UnifiedValue<T>}
  */
-export function unifyValues<T>(values: readonly T[]): { mixed: boolean; value: T | undefined } {
+export function unifyValues<T>(values: readonly T[]): UnifiedValue<T> {
   if (values.length === 0) {
     return { mixed: false, value: undefined };
   }
-  const first = values[0] as T;
+  const [first] = values;
   const key = JSON.stringify(first ?? null);
   for (let i = 1; i < values.length; i++) {
     if (JSON.stringify(values[i] ?? null) !== key) {

package/src/tabs/tab.ts

@@ -1,12 +1,13 @@
 /// <reference lib="dom" />
 import { effectScope, reactive } from "../reactivity";
 import { formatByName, formatForPath } from "../format/format-host";
+import type { FormatFrontmatter } from "../format/format-host";
 import { normalizeArrayChildren } from "../state";
 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";
 
@@ -125,7 +126,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 +178,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;
@@ -230,7 +230,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 +249,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,7 +264,7 @@ 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",
@@ -295,8 +295,8 @@ 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;
@@ -320,8 +320,8 @@ export function createTab({
   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;
@@ -342,45 +342,56 @@ export function createTab({
   const initialCanvasMode = resolvedModes.find((m) => m !== "preview") ?? "edit";
   const initialPreview = resolvedModes[0] === "preview";
 
+  const doc: Tab["doc"] = {
+    content: { frontmatter: frontmatter || {} },
+    dirty: false,
+    document,
+    handlersSource: null,
+    layout,
+    mode: inferDocumentMode(documentPath, sourceFormat),
+    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;
 }
 
 /**

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 {