@jxsuite/studio 0.28.5 → 0.29.0

package/src/tabs/transact.ts

@@ -2,16 +2,77 @@
 import { toRaw } from "../reactivity";
 import { jsonClone } from "../utils/studio-utils";
 import { childIndex, getNodeAtPath, isAncestor, parentElementPath, pathsEqual } from "../state";
+import {
+  beginRecording,
+  endRecording,
+  getPatchConsumer,
+  recordDocOp,
+  recordPatch,
+} from "./patch-ops";
+
+import type { JxDocOp, JxDocOpPair, TransactionRecord } from "./patch-ops";
 
 import type { Tab } from "../tabs/tab";
 import type { JxPath } from "../state";
 
 import type { JsonValue } from "../types";
 import type { JxEventBinding, JxMutableNode, JxStateObject, JxStyle } from "@jxsuite/schema/types";
-import { ensureNestedStyle, getNestedStyle } from "@jxsuite/schema/guards";
+import { ensureNestedStyle, getNestedStyle, isEventBinding } from "@jxsuite/schema/guards";
 
 const HISTORY_LIMIT = 100;
 
+/** Every Nth history entry stores a full snapshot so states can be materialized by replay. */
+const CHECKPOINT_INTERVAL = 20;
+
+/** Opt-out flag for patch-based history (forces full-snapshot-per-edit legacy behavior). */
+function patchHistoryEnabled() {
+  try {
+    return typeof localStorage === "undefined" || !localStorage.getItem("jx-legacy-history");
+  } catch {
+    return true;
+  }
+}
+
+/** Deep-clone a recorded value (undefined passes through; reactive proxies are read through). */
+function cloneValue<T>(v: T): T {
+  return v === undefined || v === null ? v : (jsonClone(v as object) as T);
+}
+
+/** Forward/inverse pair for a single-key change on the node at path. */
+function setKeyPair(path: JxPath, key: string, before: unknown, after: unknown): JxDocOpPair {
+  return {
+    forward: { key, op: "set-key", path, value: after },
+    inverse: { key, op: "set-key", path, value: before },
+  };
+}
+
+/**
+ * Translate `path` into post-splice coordinates when it descends through `parentPath`'s children at
+ * or beyond the spliced index: a removal (delta -1) at fromIndex shifts deeper paths down; an
+ * insertion (delta +1, inclusive) shifts them up. Returns `path` unchanged when the splice doesn't
+ * affect it. Used to express a move's inverse in post-mutation coordinates.
+ */
+function shiftPrefixedIndex(
+  parentPath: JxPath,
+  path: JxPath,
+  spliceIndex: number,
+  delta: number,
+  inclusive: boolean,
+): 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") {
+    return path;
+  }
+  const idx = path[d + 1] as number;
+  if (inclusive ? idx < spliceIndex : idx <= spliceIndex) {
+    return path;
+  }
+  const shifted = [...path];
+  shifted[d + 1] = idx + delta;
+  return shifted;
+}
+
 /** Any value that can sit at a document node key (undefined/null/"" deletes it). */
 export type JxNodeValue =
   | JsonValue
@@ -52,30 +113,121 @@ export function transactDoc(
   if (!tab) {
     return;
   }
-  mutationFn(tab);
+  const selectionBefore = tab.session.selection ? [...tab.session.selection] : null;
+  beginRecording();
+  let record: TransactionRecord;
+  try {
+    mutationFn(tab);
+  } finally {
+    record = endRecording();
+  }
 
   // Replace the document root reference so effects tracking tab.doc.document re-trigger.
   // Nested objects are shared — the mutation already modified them in place.
   const raw = toRaw(tab.doc.document);
-  tab.doc.document = { ...raw };
+  const newRef = { ...raw };
 
-  if (!skipHistory) {
-    const snapshot = {
-      document: jsonClone(raw),
-      selection: tab.session.selection ? [...tab.session.selection] : null,
-    };
-    const truncated = tab.history.snapshots.slice(0, tab.history.index + 1);
-    truncated.push(snapshot);
-    if (truncated.length > HISTORY_LIMIT) {
-      truncated.shift();
+  // When the canvas patcher can apply this change surgically, mark the new root reference as
+  // Consumed BEFORE assigning it — the canvas doc-effect runs synchronously on assignment and
+  // Skips the full render for consumed references. Panels' own effects still fire as before.
+  // Anything unrecorded or unclassifiable falls through to today's full-render path.
+  const consumer = getPatchConsumer();
+  const verdict =
+    consumer === null
+      ? { patchable: false, reason: "no-patch-consumer" }
+      : record.ops.length === 0
+        ? { patchable: false, reason: "unrecorded-mutation" }
+        : consumer.classify(tab, record.ops);
+  if (verdict.patchable) {
+    consumer!.markConsumed(newRef);
+  }
+
+  tab.doc.document = newRef;
+
+  if (verdict.patchable) {
+    try {
+      consumer!.apply(tab, record.ops);
+    } catch (error) {
+      consumer!.escalate(
+        `patch-apply-failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
     }
-    tab.history.snapshots = truncated;
-    tab.history.index = truncated.length - 1;
+  }
+
+  if (!skipHistory) {
+    pushHistoryEntry(tab, raw, record, selectionBefore);
   }
 
   tab.doc.dirty = true;
 }
 
+/**
+ * Append a history entry for a completed transaction. With patch-based history, entries carry
+ * replayable forward/inverse ops and only periodic checkpoints store full document snapshots —
+ * eliminating the whole-document clone per edit. Non-invertible or un-instrumented transactions
+ * store a snapshot, which always keeps every state recoverable.
+ *
+ * @param {Tab} tab
+ * @param {JxMutableNode} raw Post-mutation raw document
+ * @param {TransactionRecord} record
+ * @param {JxPath | null} selectionBefore
+ */
+function pushHistoryEntry(
+  tab: Tab,
+  raw: JxMutableNode,
+  record: TransactionRecord,
+  selectionBefore: JxPath | null,
+) {
+  const truncated = tab.history.snapshots.slice(0, tab.history.index + 1);
+  const useOps = patchHistoryEnabled() && record.invertible && record.docOps.length > 0;
+  const needCheckpoint = !useOps || truncated.length % CHECKPOINT_INTERVAL === 0;
+  truncated.push({
+    document: needCheckpoint ? jsonClone(raw) : null,
+    forwardOps: useOps ? record.docOps.map((p) => p.forward) : null,
+    inverseOps: useOps ? record.docOps.map((p) => p.inverse) : null,
+    selection: tab.session.selection ? [...tab.session.selection] : null,
+    selectionBefore,
+  });
+  if (truncated.length > HISTORY_LIMIT) {
+    // The new base entry must be a self-contained checkpoint before the old base is dropped.
+    if (!truncated[1]!.document) {
+      truncated[1]!.document = materializeState(truncated, 1);
+    }
+    truncated.shift();
+  }
+  tab.history.snapshots = truncated;
+  tab.history.index = truncated.length - 1;
+}
+
+/**
+ * Reconstruct the document at history state `target`: copy the nearest checkpoint at or before it,
+ * then replay forward ops. Every entry holds either a snapshot or forward ops, so this always
+ * succeeds.
+ *
+ * @param {HistorySnapshot[]} snapshots
+ * @param {number} target
+ * @returns {JxMutableNode}
+ */
+function materializeState(
+  snapshots: { document: JxMutableNode | null; forwardOps?: JxDocOp[] | null }[],
+  target: number,
+): JxMutableNode {
+  let base = target;
+  while (base >= 0 && !snapshots[base]!.document) {
+    base -= 1;
+  }
+  if (base < 0) {
+    throw new Error("history-missing-checkpoint");
+  }
+  const doc = jsonClone(snapshots[base]!.document) as JxMutableNode;
+  for (let i = base + 1; i <= target; i++) {
+    for (const op of snapshots[i]!.forwardOps ?? []) {
+      applyDocOpToDoc(doc, op);
+    }
+  }
+  return doc;
+}
+
 /**
  * Convenience: transact with a mutation fn that receives the document directly.
  *
@@ -91,17 +243,168 @@ export function transact(
   transactDoc(tab, (t) => fn(t.doc.document), opts);
 }
 
+// ─── Document-op application ─────────────────────────────────────────────────
+
+/** Document-level keys whose changes require a full scope/panel rebuild on the canvas. */
+const DOC_META_KEYS = new Set(["state", "$media", "$head", "$elements", "imports", "$layout"]);
+
+/**
+ * Apply a replayable doc op to a bare document tree (history replay — no canvas recording).
+ *
+ * @param {JxMutableNode} doc
+ * @param {JxDocOp} op
+ */
+function applyDocOpToDoc(doc: JxMutableNode, op: JxDocOp) {
+  switch (op.op) {
+    case "set-key": {
+      const node = getNodeAtPath(doc, op.path);
+      if (!node) {
+        throw new Error(`doc-op-node-not-found:${op.path.join("/")}`);
+      }
+      if (op.value === undefined) {
+        delete node[op.key];
+      } else {
+        node[op.key] = cloneValue(op.value) as JxNodeValue;
+      }
+      return;
+    }
+    case "insert-child": {
+      const parent = getNodeAtPath(doc, op.parentPath);
+      childArray(parent).splice(op.index, 0, cloneValue(op.node) as JxMutableNode);
+      return;
+    }
+    case "remove-child": {
+      const parent = getNodeAtPath(doc, op.parentPath);
+      childArray(parent).splice(op.index, 1);
+      return;
+    }
+    case "set-child": {
+      const parent = getNodeAtPath(doc, op.parentPath);
+      childArray(parent).splice(op.index, 1, cloneValue(op.node) as JxMutableNode);
+      return;
+    }
+    case "move-child": {
+      const fromParent = getNodeAtPath(doc, op.fromParentPath);
+      const toParent = getNodeAtPath(doc, op.toParentPath);
+      const [node] = childArray(fromParent).splice(op.fromIndex, 1);
+      childArray(toParent).splice(op.toIndex, 0, node!);
+      return;
+    }
+    default: {
+      throw new Error(`unknown-doc-op:${(op as JxDocOp).op}`);
+    }
+  }
+}
+
+/**
+ * Apply a doc op to the live document AND record the matching canvas patch op, so undo/redo
+ * transactions patch the canvas surgically like any other edit.
+ *
+ * @param {Tab} tab
+ * @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;
+  applyDocOpToDoc(tab.doc.document, op);
+  switch (op.op) {
+    case "set-key": {
+      if (DOC_META_KEYS.has(op.key)) {
+        recordPatch({ key: op.key, op: "doc-meta" });
+      } else if (op.key === "style") {
+        recordPatch({ op: "set-style", path: op.path });
+      } else if (op.key === "textContent") {
+        recordPatch({ op: "set-text", path: op.path });
+      } else if (op.key === "attributes" || op.key === "cases" || op.key === "$props") {
+        recordPatch({ op: "replace", path: op.path });
+      } else {
+        const isEvent =
+          op.key.startsWith("on") && (isEventBinding(op.value) || isEventBinding(prev));
+        recordPatch({ isEvent, key: op.key, op: "set-prop", path: op.path });
+      }
+      return;
+    }
+    case "insert-child": {
+      recordPatch({ index: op.index, op: "insert", parentPath: op.parentPath });
+      return;
+    }
+    case "remove-child": {
+      recordPatch({ op: "remove", path: [...op.parentPath, "children", op.index] });
+      return;
+    }
+    case "set-child": {
+      recordPatch({ op: "replace", path: [...op.parentPath, "children", op.index] });
+      return;
+    }
+    case "move-child": {
+      recordPatch({
+        fromPath: [...op.fromParentPath, "children", op.fromIndex],
+        op: "move",
+        toIndex: op.toIndex,
+        toParentPath: op.toParentPath,
+      });
+      return;
+    }
+    default: {
+      break;
+    }
+  }
+}
+
 // ─── Undo / Redo ─────────────────────────────────────────────────────────────
 
+/** Restore a materialized snapshot state (full-render path). */
+function restoreState(tab: Tab, index: number) {
+  const { snapshots } = tab.history;
+  tab.doc.document = materializeState(snapshots, index);
+  const snap = snapshots[index]!;
+  tab.session.selection = snap.selection ? [...toRaw(snap.selection)] : null;
+}
+
+/** Debug-flag assertion: ops-based undo/redo must land on the same state replay produces. */
+function assertHistoryConsistency(tab: Tab, index: number) {
+  try {
+    if (typeof localStorage === "undefined" || !localStorage.getItem("jx-canvas-debug")) {
+      return;
+    }
+  } catch {
+    return;
+  }
+  const expected = JSON.stringify(materializeState(tab.history.snapshots, index));
+  const actual = JSON.stringify(jsonClone(toRaw(tab.doc.document)));
+  if (expected !== actual) {
+    console.error("jx history: ops-based undo/redo diverged from checkpoint replay", {
+      index,
+    });
+  }
+}
+
 /** @param {Tab} tab */
 export function undo(tab: Tab) {
   if (tab.history.index <= 0) {
     return;
   }
-  tab.history.index -= 1;
-  const snap = tab.history.snapshots[tab.history.index];
-  tab.doc.document = structuredClone(toRaw(snap.document));
-  tab.session.selection = snap.selection ? [...toRaw(snap.selection)] : null;
+  const entry = tab.history.snapshots[tab.history.index]!;
+  const inverseOps = patchHistoryEnabled() ? entry.inverseOps : null;
+  if (inverseOps && inverseOps.length > 0) {
+    // Surgical path: apply inverse ops through the normal transaction pipeline (the canvas
+    // Patches in place when it can), in reverse recording order.
+    transactDoc(
+      tab,
+      (t) => {
+        for (let i = inverseOps.length - 1; i >= 0; i--) {
+          applyDocOp(t, toRaw(inverseOps[i]) as JxDocOp);
+        }
+      },
+      { skipHistory: true },
+    );
+    tab.session.selection = entry.selectionBefore ? [...toRaw(entry.selectionBefore)] : null;
+    tab.history.index -= 1;
+    assertHistoryConsistency(tab, tab.history.index);
+  } else {
+    tab.history.index -= 1;
+    restoreState(tab, tab.history.index);
+  }
   tab.doc.dirty = true;
 }
 
@@ -110,10 +413,25 @@ export function redo(tab: Tab) {
   if (tab.history.index >= tab.history.snapshots.length - 1) {
     return;
   }
-  tab.history.index += 1;
-  const snap = tab.history.snapshots[tab.history.index];
-  tab.doc.document = structuredClone(toRaw(snap.document));
-  tab.session.selection = snap.selection ? [...toRaw(snap.selection)] : null;
+  const entry = tab.history.snapshots[tab.history.index + 1]!;
+  const forwardOps = patchHistoryEnabled() ? entry.forwardOps : null;
+  if (forwardOps && forwardOps.length > 0) {
+    transactDoc(
+      tab,
+      (t) => {
+        for (const op of forwardOps) {
+          applyDocOp(t, toRaw(op) as JxDocOp);
+        }
+      },
+      { skipHistory: true },
+    );
+    tab.session.selection = entry.selection ? [...toRaw(entry.selection)] : null;
+    tab.history.index += 1;
+    assertHistoryConsistency(tab, tab.history.index);
+  } else {
+    tab.history.index += 1;
+    restoreState(tab, tab.history.index);
+  }
   tab.doc.dirty = true;
 }
 
@@ -136,6 +454,11 @@ export function mutateInsertNode(
     return;
   }
   childArray(parent).splice(index, 0, structuredClone(nodeDef));
+  recordPatch({ index, op: "insert", parentPath });
+  recordDocOp({
+    forward: { index, node: cloneValue(nodeDef), op: "insert-child", parentPath },
+    inverse: { index, op: "remove-child", parentPath },
+  });
 }
 
 /**
@@ -148,7 +471,15 @@ export function mutateRemoveNode(tab: Tab, path: JxPath) {
   }
   const elemPath = parentElementPath(path) as JxPath;
   const idx = childIndex(path) as number;
-  (getNodeAtPath(tab.doc.document, elemPath).children as JxMutableNode[]).splice(idx, 1);
+  const [removed] = (getNodeAtPath(tab.doc.document, elemPath).children as JxMutableNode[]).splice(
+    idx,
+    1,
+  );
+  recordPatch({ op: "remove", path });
+  recordDocOp({
+    forward: { index: idx, op: "remove-child", parentPath: elemPath },
+    inverse: { index: idx, node: cloneValue(removed), op: "insert-child", parentPath: elemPath },
+  });
   if (tab.session.selection && isAncestor(path, tab.session.selection)) {
     tab.session.selection = null;
   }
@@ -170,6 +501,11 @@ export function mutateDuplicateNode(tab: Tab, path: JxPath) {
   const idx = childIndex(path) as number;
   const clone = structuredClone(toRaw(node));
   (getNodeAtPath(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 },
+    inverse: { index: idx + 1, op: "remove-child", parentPath: elemPath },
+  });
   tab.session.selection = [...elemPath, "children", idx + 1];
 }
 
@@ -192,7 +528,13 @@ export function mutateWrapNode(tab: Tab, path: JxPath, wrapperTag = "div") {
     children: [structuredClone(toRaw(node))],
     tagName: wrapperTag,
   };
+  const original = cloneValue(node);
   (getNodeAtPath(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 },
+    inverse: { index: idx, node: original, op: "set-child", parentPath: elemPath },
+  });
   tab.session.selection = [...elemPath, "children", idx];
 }
 
@@ -223,6 +565,26 @@ export function mutateMoveNode(tab: Tab, fromPath: JxPath, toParentPath: JxPath,
     adjustedIndex -= 1;
   }
   childArray(toParent).splice(adjustedIndex, 0, node);
+  recordPatch({ fromPath, op: "move", toIndex: adjustedIndex, toParentPath });
+  recordDocOp({
+    forward: {
+      fromIndex: fromIdx,
+      fromParentPath,
+      op: "move-child",
+      toIndex: adjustedIndex,
+      toParentPath,
+    },
+    inverse: {
+      fromIndex: adjustedIndex,
+      // The inverse runs against the post-move document, so both parent paths are translated
+      // Into post-move coordinates: the removal shifted paths under fromParent, the insertion
+      // Shifted paths under toParent.
+      fromParentPath: shiftPrefixedIndex(fromParentPath, toParentPath, fromIdx, -1, false),
+      op: "move-child",
+      toIndex: fromIdx,
+      toParentPath: shiftPrefixedIndex(toParentPath, fromParentPath, adjustedIndex, 1, true),
+    },
+  });
 
   if (pathsEqual(tab.session.selection, fromPath)) {
     let idx = toIndex;
@@ -245,11 +607,25 @@ export function mutateMoveNode(tab: Tab, fromPath: JxPath, toParentPath: JxPath,
  */
 export function mutateUpdateProperty(tab: Tab, path: JxPath, key: string, value?: JxNodeValue) {
   const node = getNodeAtPath(tab.doc.document, path);
+  const prev = node[key];
+  const before = cloneValue(prev);
   if (value === undefined || value === null || value === "") {
     delete node[key];
   } else {
     node[key] = value;
   }
+  recordDocOp(setKeyPair(path, key, before, cloneValue(node[key])));
+  if (key === "textContent") {
+    recordPatch({ op: "set-text", path });
+  } else if (key === "style") {
+    recordPatch({ op: "set-style", path });
+  } else {
+    // Event-binding edits are invisible on the canvas (stripped in design/edit renders); the
+    // Deleted-value case checks the previous value since the new one is gone.
+    const bindingValue = value === undefined || value === null || value === "" ? prev : value;
+    const isEvent = key.startsWith("on") && isEventBinding(bindingValue);
+    recordPatch({ isEvent, key, op: "set-prop", path });
+  }
 }
 
 /**
@@ -260,6 +636,7 @@ export function mutateUpdateProperty(tab: Tab, path: JxPath, key: string, value?
  */
 export function mutateUpdateStyle(tab: Tab, path: JxPath, prop: string, value: string | undefined) {
   const node = getNodeAtPath(tab.doc.document, path);
+  const styleBefore = cloneValue(node.style);
   if (!node.style) {
     node.style = {};
   }
@@ -271,6 +648,8 @@ export function mutateUpdateStyle(tab: Tab, path: JxPath, prop: string, value: s
   if (Object.keys(node.style).length === 0) {
     delete node.style;
   }
+  recordDocOp(setKeyPair(path, "style", styleBefore, cloneValue(node.style)));
+  recordPatch({ op: "set-style", path });
 }
 
 /**
@@ -286,6 +665,7 @@ export function mutateUpdateAttribute(
   value?: string | undefined,
 ) {
   const node = getNodeAtPath(tab.doc.document, path);
+  const attrsBefore = cloneValue(node.attributes);
   if (!node.attributes) {
     node.attributes = {};
   }
@@ -297,6 +677,8 @@ export function mutateUpdateAttribute(
   if (Object.keys(node.attributes).length === 0) {
     delete node.attributes;
   }
+  recordDocOp(setKeyPair(path, "attributes", attrsBefore, cloneValue(node.attributes)));
+  recordPatch({ attr, op: "set-attr", path });
 }
 
 /**
@@ -317,6 +699,7 @@ export function mutateUpdateMediaStyle(
     return mutateUpdateStyle(tab, path, prop, value);
   }
   const node = getNodeAtPath(tab.doc.document, path);
+  const styleBefore = cloneValue(node.style);
   if (!node.style) {
     node.style = {};
   }
@@ -333,6 +716,8 @@ export function mutateUpdateMediaStyle(
   if (Object.keys(node.style).length === 0) {
     delete node.style;
   }
+  recordDocOp(setKeyPair(path, "style", styleBefore, cloneValue(node.style)));
+  recordPatch({ op: "set-style", path });
 }
 
 /**
@@ -350,6 +735,7 @@ export function mutateUpdateNestedStyle(
   value: string | undefined,
 ) {
   const node = getNodeAtPath(tab.doc.document, path);
+  const styleBefore = cloneValue(node.style);
   if (!node.style) {
     node.style = {};
   }
@@ -365,6 +751,8 @@ export function mutateUpdateNestedStyle(
   if (Object.keys(node.style).length === 0) {
     delete node.style;
   }
+  recordDocOp(setKeyPair(path, "style", styleBefore, cloneValue(node.style)));
+  recordPatch({ op: "set-style", path });
 }
 
 /**
@@ -384,6 +772,7 @@ export function mutateUpdateMediaNestedStyle(
   value: string | undefined,
 ) {
   const node = getNodeAtPath(tab.doc.document, path);
+  const styleBefore = cloneValue(node.style);
   if (!node.style) {
     node.style = {};
   }
@@ -404,6 +793,8 @@ export function mutateUpdateMediaNestedStyle(
   if (Object.keys(node.style).length === 0) {
     delete node.style;
   }
+  recordDocOp(setKeyPair(path, "style", styleBefore, cloneValue(node.style)));
+  recordPatch({ op: "set-style", path });
 }
 
 /**
@@ -424,6 +815,7 @@ export function mutateUpdateNestedStylePath(
   value: string | undefined,
 ) {
   const node = getNodeAtPath(tab.doc.document, path);
+  const styleBefore = cloneValue(node.style);
   if (!node.style) {
     node.style = {};
   }
@@ -436,9 +828,9 @@ export function mutateUpdateNestedStylePath(
     // Clean up empty parent objects
     let cur: JxStyle | undefined = node.style;
     for (let i = 0; i < stylePath.length && cur; i++) {
-      const child = getNestedStyle(cur, stylePath[i]);
+      const child = getNestedStyle(cur, stylePath[i]!);
       if (child && Object.keys(child).length === 0) {
-        delete cur[stylePath[i]];
+        delete cur[stylePath[i]!];
         break;
       }
       cur = child;
@@ -449,6 +841,8 @@ export function mutateUpdateNestedStylePath(
   if (Object.keys(node.style).length === 0) {
     delete node.style;
   }
+  recordDocOp(setKeyPair(path, "style", styleBefore, cloneValue(node.style)));
+  recordPatch({ op: "set-style", path });
 }
 
 /**
@@ -470,6 +864,7 @@ export function mutateUpdateMediaNestedStylePath(
   value: string | undefined,
 ) {
   const node = getNodeAtPath(tab.doc.document, path);
+  const styleBefore = cloneValue(node.style);
   if (!node.style) {
     node.style = {};
   }
@@ -483,9 +878,9 @@ export function mutateUpdateMediaNestedStylePath(
     delete obj[prop];
     let cur: JxStyle | undefined = media;
     for (let i = 0; i < stylePath.length && cur; i++) {
-      const child = getNestedStyle(cur, stylePath[i]);
+      const child = getNestedStyle(cur, stylePath[i]!);
       if (child && Object.keys(child).length === 0) {
-        delete cur[stylePath[i]];
+        delete cur[stylePath[i]!];
         break;
       }
       cur = child;
@@ -499,6 +894,8 @@ export function mutateUpdateMediaNestedStylePath(
   if (Object.keys(node.style).length === 0) {
     delete node.style;
   }
+  recordDocOp(setKeyPair(path, "style", styleBefore, cloneValue(node.style)));
+  recordPatch({ op: "set-style", path });
 }
 
 /**
@@ -508,11 +905,14 @@ export function mutateUpdateMediaNestedStylePath(
  */
 export function mutateReplaceStyle(tab: Tab, path: JxPath, style: JxStyle | undefined) {
   const node = getNodeAtPath(tab.doc.document, path);
+  const styleBefore = cloneValue(node.style);
   if (style && Object.keys(style).length > 0) {
     node.style = style;
   } else {
     delete node.style;
   }
+  recordDocOp(setKeyPair(path, "style", styleBefore, cloneValue(node.style)));
+  recordPatch({ op: "set-style", path });
 }
 
 /**
@@ -522,10 +922,13 @@ export function mutateReplaceStyle(tab: Tab, path: JxPath, style: JxStyle | unde
  */
 export function mutateAddDef(tab: Tab, name: string, def: Record<string, JsonValue>) {
   const doc = tab.doc.document;
+  const before = cloneValue(doc.state);
   if (!doc.state) {
     doc.state = {};
   }
   doc.state[name] = def;
+  recordDocOp(setKeyPair([], "state", before, cloneValue(doc.state)));
+  recordPatch({ key: "state", op: "doc-meta" });
 }
 
 /**
@@ -535,10 +938,13 @@ export function mutateAddDef(tab: Tab, name: string, def: Record<string, JsonVal
 export function mutateRemoveDef(tab: Tab, name: string) {
   const doc = tab.doc.document;
   if (doc.state) {
+    const before = cloneValue(doc.state);
     delete doc.state[name];
     if (Object.keys(doc.state).length === 0) {
       delete doc.state;
     }
+    recordDocOp(setKeyPair([], "state", before, cloneValue(doc.state)));
+    recordPatch({ key: "state", op: "doc-meta" });
   }
 }
 
@@ -549,6 +955,7 @@ export function mutateRemoveDef(tab: Tab, name: string) {
  */
 export function mutateUpdateDef(tab: Tab, name: string, updates: Record<string, unknown>) {
   const doc = tab.doc.document;
+  const stateBefore = cloneValue(doc.state);
   if (!doc.state) {
     doc.state = {};
   }
@@ -566,6 +973,8 @@ export function mutateUpdateDef(tab: Tab, name: string, updates: Record<string,
       delete entry[k];
     }
   }
+  recordDocOp(setKeyPair([], "state", stateBefore, cloneValue(doc.state)));
+  recordPatch({ key: "state", op: "doc-meta" });
 }
 
 /**
@@ -578,8 +987,11 @@ export function mutateRenameDef(tab: Tab, oldName: string, newName: string) {
   if (!doc.state || !doc.state[oldName]) {
     return;
   }
+  const before = cloneValue(doc.state);
   doc.state[newName] = doc.state[oldName];
   delete doc.state[oldName];
+  recordDocOp(setKeyPair([], "state", before, cloneValue(doc.state)));
+  recordPatch({ key: "state", op: "doc-meta" });
 }
 
 /**
@@ -589,6 +1001,7 @@ export function mutateRenameDef(tab: Tab, oldName: string, newName: string) {
  */
 export function mutateUpdateMedia(tab: Tab, name: string, query?: string | undefined) {
   const doc = tab.doc.document;
+  const mediaBefore = cloneValue(doc.$media);
   if (!doc.$media) {
     doc.$media = {};
   }
@@ -600,6 +1013,8 @@ export function mutateUpdateMedia(tab: Tab, name: string, query?: string | undef
   } else {
     doc.$media[name] = query;
   }
+  recordDocOp(setKeyPair([], "$media", mediaBefore, cloneValue(doc.$media)));
+  recordPatch({ key: "$media", op: "doc-meta" });
 }
 
 /**
@@ -610,6 +1025,7 @@ export function mutateUpdateMedia(tab: Tab, name: string, query?: string | undef
  */
 export function mutateUpdateProp(tab: Tab, path: JxPath, propName: string, value: JsonValue) {
   const node = getNodeAtPath(tab.doc.document, path);
+  const propsBefore = cloneValue(node.$props);
   if (!node.$props) {
     node.$props = {};
   }
@@ -621,6 +1037,8 @@ export function mutateUpdateProp(tab: Tab, path: JxPath, propName: string, value
   if (Object.keys(node.$props).length === 0) {
     delete node.$props;
   }
+  recordDocOp(setKeyPair(path, "$props", propsBefore, cloneValue(node.$props)));
+  recordPatch({ op: "replace", path });
 }
 
 /**
@@ -636,10 +1054,13 @@ export function mutateAddSwitchCase(
   caseDef?: JxMutableNode,
 ) {
   const node = getNodeAtPath(tab.doc.document, path);
+  const before = cloneValue(node.cases);
   if (!node.cases) {
     node.cases = {};
   }
   node.cases[caseName] = caseDef || { tagName: "div", textContent: caseName };
+  recordDocOp(setKeyPair(path, "cases", before, cloneValue(node.cases)));
+  recordPatch({ op: "replace", path });
 }
 
 /**
@@ -650,7 +1071,10 @@ export function mutateAddSwitchCase(
 export function mutateRemoveSwitchCase(tab: Tab, path: JxPath, caseName: string) {
   const node = getNodeAtPath(tab.doc.document, path);
   if (node.cases) {
+    const before = cloneValue(node.cases);
     delete node.cases[caseName];
+    recordDocOp(setKeyPair(path, "cases", before, cloneValue(node.cases)));
+    recordPatch({ op: "replace", path });
   }
 }
 
@@ -665,8 +1089,11 @@ export function mutateRenameSwitchCase(tab: Tab, path: JxPath, oldName: string,
   if (!node.cases || !node.cases[oldName]) {
     return;
   }
+  const before = cloneValue(node.cases);
   node.cases[newName] = node.cases[oldName];
   delete node.cases[oldName];
+  recordDocOp(setKeyPair(path, "cases", before, cloneValue(node.cases)));
+  recordPatch({ op: "replace", path });
 }
 
 // ─── Frontmatter ─────────────────────────────────────────────────────────────