@jxsuite/studio 0.28.5 → 0.29.0

package/src/settings/general-settings.ts

@@ -31,7 +31,7 @@ export function renderGeneralSettings(container: HTMLElement) {
   };
 
   const onAdapterChange = (e: Event) => {
-    updateSiteConfig({
+    void updateSiteConfig({
       build: { ...config.build, adapter: (e.target as HTMLInputElement).value },
     });
   };
@@ -40,7 +40,7 @@ export function renderGeneralSettings(container: HTMLElement) {
     // Lazy import breaks the general-settings ↔ settings-modal module cycle
     const { closeSettingsModal } = await import("./settings-modal");
     closeSettingsModal();
-    openFileInTab("project.json");
+    void openFileInTab("project.json");
   };
 
   // ─── Breakpoints ($media) ───────────────────────────────────────────────────
@@ -50,7 +50,7 @@ export function renderGeneralSettings(container: HTMLElement) {
 
   const onMediaValueChange = (key: string) => (e: Event) => {
     const updated = { ...media, [key]: (e.target as HTMLInputElement).value };
-    updateSiteConfig({ $media: updated });
+    void updateSiteConfig({ $media: updated });
   };
 
   const onMediaNameChange = (oldKey: string) => (e: Event) => {
@@ -63,20 +63,20 @@ export function renderGeneralSettings(container: HTMLElement) {
     for (const [k, v] of Object.entries(media)) {
       updated[k === oldKey ? newKey : k] = v;
     }
-    updateSiteConfig({ $media: updated });
+    void updateSiteConfig({ $media: updated });
     renderGeneralSettings(container);
   };
 
   const onRemoveBreakpoint = (key: string) => () => {
     const updated = { ...media };
     delete updated[key];
-    updateSiteConfig({ $media: updated });
+    void updateSiteConfig({ $media: updated });
     renderGeneralSettings(container);
   };
 
   const onAddBreakpoint = () => {
     const updated = { ...media, "--new": "(max-width: 480px)" };
-    updateSiteConfig({ $media: updated });
+    void updateSiteConfig({ $media: updated });
     renderGeneralSettings(container);
   };
 

package/src/settings/head-editor.ts

@@ -23,7 +23,7 @@ export function renderHeadEditor(container: HTMLElement) {
   const headEntries = config.$head || ([] as JxHeadEntry[]);
 
   const save = () => {
-    updateSiteConfig({ $head: headEntries });
+    void updateSiteConfig({ $head: headEntries });
   };
 
   const addEntry = (tag: string) => {
@@ -52,7 +52,7 @@ export function renderHeadEditor(container: HTMLElement) {
   };
 
   const updateEntry = (idx: number, key: string, val: string) => {
-    const entry = headEntries[idx];
+    const entry = headEntries[idx]!;
     if (key === "content" && (entry.tagName === "script" || entry.tagName === "style")) {
       entry.textContent = val;
     } else {

package/src/site-context.ts

@@ -170,7 +170,7 @@ export async function resolveLayoutDoc(layoutPath: string) {
   try {
     const platform = getPlatform();
     const content = await platform.readFile(normalized);
-    const doc = JSON.parse(content);
+    const doc = JSON.parse(content) as JxMutableNode;
     layoutCache.set(normalized, doc);
     return structuredClone(doc);
   } catch {

package/src/state.ts

@@ -84,6 +84,52 @@ export function childList(node: JxMutableNode | null | undefined): (JxMutableNod
   return Array.isArray(node?.children) ? node.children : [];
 }
 
+/**
+ * Normalize a document in place to the canonical array-member form: a legacy whole-children
+ * repeater (`children: { $prototype: "Array", … }`) becomes a single member of a children array
+ * (`children: [{ $prototype: "Array", … }]`). Recurses through children, repeater templates, and
+ * `$switch` cases. Runs once when a document is loaded into a tab so every in-studio doc — and its
+ * history checkpoints — uses the member form before any mutation.
+ *
+ * @param {unknown} node
+ * @returns {unknown} The same node (mutated)
+ */
+export function normalizeArrayChildren(node: unknown): unknown {
+  if (!node || typeof node !== "object") {
+    return node;
+  }
+  if (Array.isArray(node)) {
+    for (const child of node) {
+      normalizeArrayChildren(child);
+    }
+    return node;
+  }
+  const n = node as JxMutableNode;
+  const { children } = n;
+  if (
+    children &&
+    typeof children === "object" &&
+    !Array.isArray(children) &&
+    (children as JxMutableNode).$prototype === "Array"
+  ) {
+    n.children = [children as JxMutableNode];
+  }
+  if (Array.isArray(n.children)) {
+    for (const child of n.children) {
+      normalizeArrayChildren(child);
+    }
+  }
+  if (n.$prototype === "Array" && n.map && typeof n.map === "object") {
+    normalizeArrayChildren(n.map);
+  }
+  if (n.cases && typeof n.cases === "object") {
+    for (const caseDef of Object.values(n.cases)) {
+      normalizeArrayChildren(caseDef);
+    }
+  }
+  return node;
+}
+
 /**
  * Return the path to the parent element (strips trailing 'children' + index).
  *
@@ -180,6 +226,19 @@ export function flattenTree(
     return [{ depth, node: doc, nodeType: "text", path }];
   }
 
+  // Array pseudo-element (repeater): a first-class node at its own path. Emit the "map" row, then
+  // Recurse into its single template at `[...path, "map"]`. This is reached both when the array is
+  // A member of a children array (path `[…, "children", i]`) and the legacy whole-children form
+  // (path `[…, "children"]`).
+  if ((doc as JxMutableNode).$prototype === "Array") {
+    const rows: FlatRow[] = [{ depth, node: doc, nodeType: "map", path }];
+    const mapDef = (doc as JxMutableNode).map;
+    if (mapDef && typeof mapDef === "object") {
+      rows.push(...flattenTree(mapDef as JxMutableNode, [...path, "map"], depth + 1));
+    }
+    return rows;
+  }
+
   const rows: FlatRow[] = [{ depth, node: doc, nodeType: "element", path }];
 
   // Custom component instances without user-authored children are atomic in the layer tree
@@ -192,24 +251,15 @@ export function flattenTree(
   if (Array.isArray(children)) {
     for (let i = 0; i < children.length; i++) {
       const childPath = [...path, "children", i];
-      rows.push(...flattenTree(children[i], childPath, depth + 1));
+      rows.push(...flattenTree(children[i]!, childPath, depth + 1));
     }
   } else if (
     children &&
     typeof children === "object" &&
     (children as JxMutableNode).$prototype === "Array"
   ) {
-    // $map — emit the map container, then recurse into the template
-    rows.push({
-      depth: depth + 1,
-      node: children as JxMutableNode,
-      nodeType: "map",
-      path: [...path, "children"],
-    });
-    const mapDef = (children as JxMutableNode).map;
-    if (mapDef && typeof mapDef === "object") {
-      rows.push(...flattenTree(mapDef as JxMutableNode, [...path, "children", "map"], depth + 2));
-    }
+    // Legacy whole-children repeater: the array occupies the children slot itself.
+    rows.push(...flattenTree(children as JxMutableNode, [...path, "children"], depth + 1));
   }
 
   // $switch — emit each case as a virtual child
@@ -262,6 +312,10 @@ export function nodeLabel(node: JxMutableNode | null) {
   if (node.$id) {
     return node.$id;
   }
+  if (node.tagName === "slot") {
+    const name = node.attributes?.name;
+    return typeof name === "string" && name.trim() ? `slot: ${name.trim()}` : "slot";
+  }
   const tag = node.tagName ?? "div";
   const suffix = node.$switch ? " ⇆" : "";
   if (typeof node.textContent === "string" && node.textContent.length > 0) {

package/src/store.ts

@@ -54,6 +54,18 @@ export function initShellRefs() {
 
 export const elToPath = new WeakMap<Element, JxPath>();
 
+/**
+ * Canvas element → the runtime scope its children render with. Captured during live renders so the
+ * canvas patcher can re-render a subtree in isolation with the same prototype-chained scope.
+ */
+export const elToScope = new WeakMap<Element, Record<string, unknown>>();
+
+/**
+ * Subtree root element → the effect scope created for its surgical render. Stopped when the subtree
+ * is replaced or removed so render-time reactive effects don't accumulate.
+ */
+export const elToRenderScope = new WeakMap<Element, { stop: () => void }>();
+
 export const canvasPanels: CanvasPanel[] = [];
 
 // ─── Shared constants ────────────────────────────────────────────────────────
@@ -97,7 +109,7 @@ export function isNestedSelector(k: string) {
 
 // ─── Shared utilities ────────────────────────────────────────────────────────
 
-const _styleDebounceTimers = new Map();
+const _styleDebounceTimers = new Map<string, ReturnType<typeof setTimeout>>();
 
 /**
  * @param {string} prop
@@ -139,7 +151,7 @@ export function stripEventHandlers(node: JxMutableNode): JxMutableNode {
   }
   if (Array.isArray(node)) {
     // Arrays of nodes round-trip element-wise; the array itself is not a node.
-    return node.map((n) => stripEventHandlers(n)) as unknown as JxMutableNode;
+    return node.map((n: JxMutableNode) => stripEventHandlers(n)) as unknown as JxMutableNode;
   }
   const out: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(node)) {
@@ -148,7 +160,7 @@ export function stripEventHandlers(node: JxMutableNode): JxMutableNode {
     }
     if (k === "children") {
       out.children = Array.isArray(v)
-        ? v.map((c) => stripEventHandlers(c))
+        ? v.map((c: JxMutableNode) => stripEventHandlers(c))
         : stripEventHandlers(v as JxMutableNode);
     } else if (k === "cases" && typeof v === "object") {
       const cases: Record<string, unknown> = {};

package/src/studio.ts

@@ -29,11 +29,19 @@ import { effect } from "./reactivity";
 import { view } from "./view";
 
 import { isEditableBlock, isEditing } from "./editor/inline-edit";
-import { initComponentInlineEdit } from "./editor/component-inline-edit";
+import { enterComponentInlineEdit, initComponentInlineEdit } from "./editor/component-inline-edit";
 import { enterInlineEdit } from "./editor/content-inline-edit";
 import { applyTransform, initCanvasUtils, positionZoomIndicator } from "./canvas/canvas-utils";
 import { findCanvasElement, getActivePanel, initCanvasHelpers } from "./canvas/canvas-helpers";
-import { initCanvasRender, renderCanvas } from "./canvas/canvas-render";
+import {
+  applyCanvasMediaOverrides,
+  initCanvasRender,
+  renderCanvas,
+  renderOverlays,
+  scheduleCanvasRender,
+} from "./canvas/canvas-render";
+import { consumePatchedDocument, initCanvasPatcher } from "./canvas/canvas-patcher";
+import { registerSubtreeDnD } from "./panels/canvas-dnd";
 import { initCanvasLiveRender } from "./canvas/canvas-live-render";
 import {
   mountStatusbar,
@@ -84,6 +92,7 @@ import * as overlaysPanel from "./panels/overlays";
 import * as rightPanelMod from "./panels/right-panel";
 import * as leftPanelMod from "./panels/left-panel";
 import * as tabStrip from "./panels/tab-strip";
+import * as tabBar from "./panels/tab-bar";
 import { renderStylebookOverlays } from "./panels/stylebook-panel";
 import { registerLayersDnD, registerComponentsDnD, registerElementsDnD } from "./panels/dnd";
 import { defaultDef } from "./panels/shared";
@@ -98,7 +107,7 @@ import { initWelcome } from "./panels/welcome-screen";
 import { openNewProjectModal } from "./new-project/new-project-modal";
 import type { DocumentStackEntry, GitDiffState } from "./types";
 import type { JxPath } from "./state";
-import type { JxMutableNode } from "@jxsuite/schema/types";
+import type { JxMutableNode, ProjectConfig } from "@jxsuite/schema/types";
 
 void _swc;
 
@@ -133,7 +142,7 @@ async function navigateToComponent(componentPath: string) {
     if (!content) {
       return;
     }
-    const parsed = JSON.parse(content);
+    const parsed = JSON.parse(content) as JxMutableNode;
     const tab = activeTab.value;
     if (!tab) {
       return;
@@ -289,7 +298,7 @@ requestIdleCallback(() => {
   const frag = document.createDocumentFragment();
   for (const [name] of webdata.cssProps) {
     const opt = document.createElement("option");
-    opt.value = name;
+    opt.value = name!;
     frag.append(opt);
   }
   dl.append(frag);
@@ -316,11 +325,8 @@ initShellRefs();
 toolbarPanel.mount(toolbarEl, {
   closeFunctionEditor: () => closeFunctionEditor(),
   getCanvasMode,
-  navigateBack: () => navigateBack(),
-  navigateToLevel: (i: number) => navigateToLevel(i),
   openProject: () => openProject(),
   openRecentProject: (root: string) => openRecentProject(root),
-  parseMediaEntries,
   renderCanvas: () => renderCanvas(),
   safeRenderRightPanel: () => safeRenderRightPanel(),
   saveFile: () => saveFile(),
@@ -332,6 +338,15 @@ initQuickSearch();
 
 tabStrip.mount(document.querySelector("#tab-strip") as HTMLElement);
 
+tabBar.mount(document.querySelector("#tab-bar") as HTMLElement, {
+  closeFunctionEditor: () => closeFunctionEditor(),
+  exportFile,
+  getCanvasMode,
+  navigateBack: () => navigateBack(),
+  navigateToLevel: (i: number) => navigateToLevel(i),
+  parseMediaEntries,
+});
+
 overlaysPanel.mount({
   getCanvasMode,
   isEditing,
@@ -366,9 +381,16 @@ initPanelEvents({
 initCanvasLiveRender({
   getCanvasMode,
 });
+initCanvasPatcher({
+  applyCanvasMediaOverrides,
+  enterComponentInlineEdit,
+  getCanvasMode,
+  registerSubtreeDnD,
+  renderOverlays,
+  scheduleCanvasRender,
+  updateForcedPseudoPreview,
+});
 initCanvasRender({
-  closeFunctionEditor: () => closeFunctionEditor(),
-  exportFile,
   getCanvasMode,
   get gitDiffState() {
     return gitDiffState;
@@ -385,20 +407,32 @@ initWelcome({
   openNewProject: async () => {
     const result = await openNewProjectModal();
     if (result) {
-      openRecentProject(result.root);
+      void openRecentProject(result.root);
     }
   },
   openProject: () => openProject(),
   openRecentProject: (root: string) => openRecentProject(root),
 });
 
-// Effect-driven canvas rendering: auto-triggers renderCanvas when reactive deps change.
-// Uses double-RAF so the canvas render yields to higher-priority panel paints first.
-let _canvasRafId = 0;
+// Effect-driven canvas rendering, split into two triggers so document changes can be
+// Distinguished from mode/UI changes:
+// - doc-effect: tracks only the document root reference. Document mutations that were
+//   Consumed surgically by the canvas patcher skip the full render here.
+// - ui-effect: tracks canvas mode and UI flags; always schedules a full render.
+// Scheduling is deduped inside scheduleCanvasRender (double-RAF).
+effect(() => {
+  const tab = activeTab.value;
+  if (tab) {
+    const doc = tab.doc.document;
+    if (doc && consumePatchedDocument(doc)) {
+      return;
+    }
+  }
+  scheduleCanvasRender();
+});
 effect(() => {
   const tab = activeTab.value;
   if (tab) {
-    void tab.doc.document;
     void tab.doc.mode;
     void tab.session.ui.canvasMode;
     void tab.session.ui.editingFunction;
@@ -408,18 +442,7 @@ effect(() => {
     void tab.session.ui.stylebookFilter;
     void tab.session.ui.stylebookCustomizedOnly;
   }
-  if (!_canvasRafId) {
-    _canvasRafId = requestAnimationFrame(() => {
-      _canvasRafId = requestAnimationFrame(() => {
-        _canvasRafId = 0;
-        try {
-          renderCanvas();
-        } catch (error) {
-          console.error("renderCanvas error:", error);
-        }
-      });
-    });
-  }
+  scheduleCanvasRender();
 });
 
 rightPanelMod.mount({
@@ -499,7 +522,7 @@ if (_projectParam) {
     render();
     const platform = getPlatform();
     // oxlint-disable-next-line unicorn/prefer-top-level-await -- deliberate fire-and-forget: project probing must not block the initial render
-    (async () => {
+    void (async () => {
       try {
         const siteCtx = platform.resolveSiteContext
           ? await platform.resolveSiteContext(_projectParam)
@@ -592,14 +615,14 @@ if (_projectParam) {
             ({ frontmatter } = result);
             parsedMode = result.mode;
           } else {
-            parsedDoc = JSON.parse(content);
+            parsedDoc = JSON.parse(content) as JxMutableNode;
           }
 
           // Open in a tab
           openTab({
             id: fileRelPath,
             documentPath: fileRelPath,
-            document: parsedDoc,
+            document: parsedDoc as JxMutableNode,
             ...(frontmatter != null && { frontmatter }),
             sourceFormat: fileFormat?.name ?? null,
           });
@@ -621,7 +644,7 @@ if (_projectParam) {
   }
 } else {
   // Normal mode: probe for project at server root
-  loadProject();
+  void loadProject();
   render();
 }
 
@@ -643,9 +666,26 @@ function openProject() {
 async function openRecentProject(root: string) {
   try {
     const platform = getPlatform();
+
+    // Multi-window (desktop): if this window already holds a project, open the chosen one in a new
+    // Window (focusing an existing window if it's already open) rather than replacing this project.
+    if (projectState && platform.openProjectInNewWindow) {
+      await platform.openProjectInNewWindow(root);
+      return;
+    }
+
+    // Multi-window (desktop): bind THIS window's backend to the project before reading from it. If
+    // The project is already open in another window, that window is focused and we bail here.
+    if (platform.setWindowProject) {
+      const res = await platform.setWindowProject(root);
+      if (res.deduped) {
+        return;
+      }
+    }
+
     platform.projectRoot = root;
     const content = await platform.readFile("project.json");
-    const config = JSON.parse(content);
+    const config = JSON.parse(content) as ProjectConfig;
 
     closeAllTabs();
 
@@ -654,7 +694,7 @@ async function openRecentProject(root: string) {
       dirs: new Map(),
       expanded: new Set(),
       isSiteProject: true,
-      name: config.name || root.split("/").pop(),
+      name: config.name || root.split("/").pop()!,
       projectConfig: config,
       projectRoot: root,
       searchQuery: "",

package/src/tabs/patch-ops.ts

@@ -0,0 +1,143 @@
+/**
+ * Patch ops — typed descriptors of document mutations, recorded by the mutators in transact.ts
+ * during a transaction. The canvas patcher consumes them to update the live canvas DOM surgically
+ * instead of re-rendering everything. Ops carry paths, not values: consumers read the post-mutation
+ * document as the single source of truth.
+ */
+
+import type { JxPath } from "../state";
+import type { Tab } from "./tab.js";
+
+export type JxPatchOp =
+  /** The node's style changed (any depth: base prop, @media block, nested selector). */
+  | { op: "set-style"; path: JxPath }
+  /** The node's textContent changed. */
+  | { op: "set-text"; path: JxPath }
+  /** A non-style, non-text node property changed (key = property name). */
+  | { op: "set-prop"; path: JxPath; key: string; isEvent?: boolean }
+  /** The node's attributes[attr] changed. */
+  | { op: "set-attr"; path: JxPath; attr: string }
+  /** A node was inserted at parentPath.children[index]. */
+  | { op: "insert"; parentPath: JxPath; index: number }
+  /** The node at path was removed. */
+  | { op: "remove"; path: JxPath }
+  /** The node moved between/within children arrays (indices are post-mutation document truth). */
+  | { op: "move"; fromPath: JxPath; toParentPath: JxPath; toIndex: number }
+  /** The node at path was structurally replaced (wrap, tagName change, $props edit). */
+  | { op: "replace"; path: JxPath }
+  /** A document-level key changed (state/$media/$head/$elements/imports/$layout) — escalates. */
+  | { op: "doc-meta"; key: string };
+
+/**
+ * Value-carrying document mutation, replayable in either direction. Mutators record a
+ * forward/inverse pair per change; history applies them for surgical undo/redo and for
+ * materializing states from checkpoints — without whole-document snapshots per edit.
+ */
+export type JxDocOp =
+  /** Set (or delete, when value is undefined) a key on the node at path. */
+  | { op: "set-key"; path: JxPath; key: string; value?: unknown }
+  /** Insert a node at parentPath.children[index]. */
+  | { op: "insert-child"; parentPath: JxPath; index: number; node: unknown }
+  /** Remove parentPath.children[index]. */
+  | { op: "remove-child"; parentPath: JxPath; index: number }
+  /** Replace parentPath.children[index] with node. */
+  | { op: "set-child"; parentPath: JxPath; index: number; node: unknown }
+  /** Raw two-splice move: remove fromParent.children[fromIndex], insert at toParent[toIndex]. */
+  | {
+      op: "move-child";
+      fromParentPath: JxPath;
+      fromIndex: number;
+      toParentPath: JxPath;
+      toIndex: number;
+    };
+
+export interface JxDocOpPair {
+  forward: JxDocOp;
+  inverse: JxDocOp;
+}
+
+/** Everything recorded during one transaction. */
+export interface TransactionRecord {
+  /** Canvas patch ops (path-only) for surgical DOM updates. */
+  ops: JxPatchOp[];
+  /** Replayable forward/inverse document ops for patch-based history. */
+  docOps: JxDocOpPair[];
+  /**
+   * False when some mutation in the transaction could not produce a guaranteed-correct inverse
+   * (e.g. a move whose parents' paths interact) — history falls back to a checkpoint snapshot.
+   */
+  invertible: boolean;
+}
+
+/**
+ * The canvas-side consumer of patch batches. Registered by the canvas patcher at studio init;
+ * absent in headless tests, where every transaction falls back to the full-render path.
+ */
+export interface PatchConsumer {
+  /** Decide whether this batch can be applied surgically in the current canvas state. */
+  classify: (tab: Tab, ops: JxPatchOp[]) => { patchable: boolean; reason: string };
+  /** Mark a document root reference as surgically consumed (checked by the canvas doc-effect). */
+  markConsumed: (docRef: object) => void;
+  /** Apply the batch to all ready canvas panels. Throws on any failure (caller escalates). */
+  apply: (tab: Tab, ops: JxPatchOp[]) => void;
+  /** Schedule a full canvas render as the fallback path, recording the reason. */
+  escalate: (reason: string) => void;
+}
+
+let _consumer: PatchConsumer | null = null;
+
+export function setPatchConsumer(consumer: PatchConsumer | null) {
+  _consumer = consumer;
+}
+
+export function getPatchConsumer(): PatchConsumer | null {
+  return _consumer;
+}
+
+// ─── Recording ───────────────────────────────────────────────────────────────
+
+let _recording: JxPatchOp[] | null = null;
+let _docOps: JxDocOpPair[] | null = null;
+let _invertible = true;
+
+/** Begin recording patch ops for a transaction. */
+export function beginRecording() {
+  _recording = [];
+  _docOps = [];
+  _invertible = true;
+}
+
+/** Record a patch op describing an in-place mutation. No-op outside a transaction. */
+export function recordPatch(op: JxPatchOp) {
+  if (_recording) {
+    _recording.push(op);
+  }
+}
+
+/** Record a replayable forward/inverse document-op pair. No-op outside a transaction. */
+export function recordDocOp(pair: JxDocOpPair) {
+  if (_docOps) {
+    _docOps.push(pair);
+  }
+}
+
+/** Mark the current transaction as non-invertible — history stores a checkpoint instead. */
+export function markNonInvertible() {
+  _invertible = false;
+}
+
+/**
+ * End recording and return everything recorded. An empty ops array means the mutation ran without
+ * instrumentation (unknown change shape) — callers must treat that as not patchable.
+ */
+export function endRecording(): TransactionRecord {
+  const record: TransactionRecord = {
+    docOps: _docOps ?? [],
+    invertible: _invertible,
+    ops: _recording ?? [],
+  };
+  _recording = null;
+  _docOps = null;
+  _invertible = true;
+  return record;
+}

package/src/tabs/tab.ts

@@ -1,6 +1,7 @@
 /// <reference lib="dom" />
 import { effectScope, reactive } from "../reactivity";
 import { formatByName, formatForPath } from "../format/format-host";
+import { normalizeArrayChildren } from "../state";
 import type {
   DocumentStackEntry,
   FunctionEditDef,
@@ -10,6 +11,7 @@ import type {
   InlineEditDef,
 } from "../types";
 import type { JxMutableNode } from "@jxsuite/schema/types";
+import type { JxDocOp } from "./patch-ops";
 
 export interface TabUi {
   rightTab: string;
@@ -39,8 +41,16 @@ export interface TabUi {
 }
 
 interface HistorySnapshot {
-  document: Record<string, unknown>;
+  /** Full document at this state (checkpoint), or null when the ops describe the transition. */
+  document: Record<string, unknown> | null;
+  /** Selection after this state's transaction. */
   selection: (string | number)[] | null;
+  /** Selection before this state's transaction (restored on surgical undo). */
+  selectionBefore?: (string | number)[] | null;
+  /** Replayable ops transforming the previous state into this one. */
+  forwardOps?: JxDocOp[] | null;
+  /** Replayable ops transforming this state back into the previous one. */
+  inverseOps?: JxDocOp[] | null;
 }
 
 export interface Tab {
@@ -145,6 +155,10 @@ export function createTab({
 }) {
   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 resolvedModes = capabilities?.modes ?? inferModes(documentPath, sourceFormat);
 
   const tab = scope.run(() => ({