@jxsuite/studio 1.0.0 → 1.1.0

package/src/services/document-assistant.ts

@@ -12,16 +12,22 @@
 import { createChatState, createProxyStreamingClient, createToolRegistry } from "@jxsuite/ai";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 import { getPlatform } from "../platform";
-import { activeTab, workspace } from "../workspace/workspace";
+import { activeTab, setWorkspaceProject, workspace } from "../workspace/workspace";
 import { toRaw } from "../reactivity";
+import { projectState, setProjectState } from "../store";
+import type { Tab } from "../tabs/tab";
 import { componentRegistry } from "../files/components";
 import { registerAiTools } from "./ai-tools";
+import { registerProjectTools } from "./ai-project-tools";
+import { createGatedToolRegistry } from "./gated-registry";
+import type { ToolAvailability } from "./gated-registry";
+import { adoptProject } from "./project-adoption";
 import { runAgentLoop } from "./tool-executor";
-import { buildSystemPrompt } from "./ai-system-prompt";
+import { AI_TOOL_TIERS, buildSystemPrompt, tierActive } from "./ai-system-prompt";
 import { getBaseUrl, getModel, getOpenAiKey } from "./ai-settings";
 import { trimContext } from "./context-manager";
 import { renderCheck } from "./render-critic";
-import { openFileInTab } from "../files/files";
+import { openFileInTab, reloadFileInTab } from "../files/files";
 import * as sessionStore from "./ai-session-store";
 
 /**
@@ -51,8 +57,23 @@ function projectRoot() {
 export function createDocumentAssistant() {
   const chatState = createChatState({ model: getModel() });
 
-  const toolRegistry = createToolRegistry();
-  registerAiTools(toolRegistry, {
+  /** The persisted session backing the live chat; null = fresh unsaved chat. */
+  let sessionId: string | null = null;
+
+  const getProjectStyle = () =>
+    (workspace.projectConfig as ProjectConfig | null)?.style as Record<string, string> | undefined;
+
+  const findOpenTab = (path: string): Tab | null => {
+    for (const tab of workspace.tabs.values()) {
+      if (tab.documentPath === path) {
+        return tab;
+      }
+    }
+    return null;
+  };
+
+  const innerRegistry = createToolRegistry();
+  registerAiTools(innerRegistry, {
     getTab: () => activeTab.value,
     saveFile: async (relPath: string, content: string) => {
       const plat = getPlatform();
@@ -62,23 +83,72 @@ export function createDocumentAssistant() {
       doc: unknown,
     ) => Promise<{ ok: true } | { ok: false; error: string }>,
     openDocument: openFileInTab,
-    projectStyle: (workspace.projectConfig as ProjectConfig | null)?.style as
-      | Record<string, string>
-      | undefined,
+    getProjectStyle,
+    findOpenTab,
+    reloadTab: reloadFileInTab,
+  });
+  registerProjectTools(innerRegistry, {
+    getTab: () => activeTab.value,
+    renderCheck: renderCheck as (
+      doc: unknown,
+    ) => Promise<{ ok: true } | { ok: false; error: string }>,
+    getProjectStyle,
+    findOpenTab,
+    reloadTab: reloadFileInTab,
+    adoptProject,
+    // Re-key the live chat from the unscoped store to the adopted project so the bootstrap
+    // Conversation keeps persisting (saveSession drops writes for ids missing from the index).
+    onProjectAdopted: (root: string) => {
+      if (sessionId) {
+        sessionStore.moveSession("", root, sessionId);
+      }
+    },
+    onProjectConfigWritten: (config: object) => {
+      setWorkspaceProject(workspace.projectRoot, config);
+      if (projectState) {
+        setProjectState({ ...projectState, projectConfig: config as ProjectConfig });
+      }
+    },
   });
 
-  let controller: AbortController | null = null;
+  /*
+   * Gate tool advertisement/execution on live studio state, derived from the same tier table the
+   * system prompt renders — the model is never shown a tool it cannot execute. listForLLM() runs
+   * every agent-loop round, so a mid-loop create_project unlocks the higher tiers immediately.
+   */
+  const TIER_REQUIREMENTS = {
+    "no-project": "no project to be open (it bootstraps one)",
+    project: "an open project",
+    document: "an open document (use open_document first)",
+  } as const;
+  const availability = new Map<string, ToolAvailability>(
+    AI_TOOL_TIERS.map((t) => [
+      t.name,
+      {
+        when: () => tierActive(t.tier, Boolean(workspace.projectRoot), Boolean(activeTab.value)),
+        requires: TIER_REQUIREMENTS[t.tier],
+      },
+    ]),
+  );
+  const toolRegistry = createGatedToolRegistry(innerRegistry, availability);
 
-  /** The persisted session backing the live chat; null = fresh unsaved chat. */
-  let sessionId: string | null = null;
+  let controller: AbortController | null = null;
 
   function buildPrompt() {
     const tab = activeTab.value;
+    const inventory = projectState
+      ? [...projectState.dirs.values()]
+          .flat()
+          .filter((e) => e.type === "file")
+          .map((e) => e.path)
+      : undefined;
     return buildSystemPrompt({
       document: tab ? toRaw(tab.doc.document) : undefined,
       projectConfig: (workspace.projectConfig as ProjectConfig | null) || undefined,
       components: componentRegistry.length > 0 ? componentRegistry : undefined,
       projectRoot: workspace.projectRoot || undefined,
+      hasProject: Boolean(workspace.projectRoot),
+      ...(inventory && inventory.length > 0 ? { fileInventory: inventory } : {}),
     });
   }
 

package/src/services/gated-registry.ts

@@ -0,0 +1,72 @@
+/**
+ * Gated-registry.ts — state-aware tool advertisement for the AI assistant.
+ *
+ * Wraps a `@jxsuite/ai` ToolRegistry so each tool is only advertised to the LLM while its
+ * availability predicate holds (no project open → bootstrap tools only; project open → file tools;
+ * document open → document tools). `runAgentLoop` calls `listForLLM()` every round, so availability
+ * flips mid-loop: after `create_project` succeeds, the very next round advertises the file and
+ * document tools without any extra plumbing.
+ *
+ * Executing a tool whose predicate currently fails returns a tool error naming the missing state
+ * instead of throwing, so the agent loop can self-correct.
+ *
+ * @license MIT
+ */
+
+import type { ToolDefinition, ToolRegistry } from "@jxsuite/ai/tools";
+
+export interface ToolAvailability {
+  /** Whether the tool is currently advertised/executable. */
+  when: () => boolean;
+  /** Human-readable requirement, surfaced when execution is refused (e.g. "a project is open"). */
+  requires: string;
+}
+
+/**
+ * Wrap `inner` so tools listed in `availability` are only advertised/executable while their
+ * predicate holds. Tools without an entry are always available.
+ *
+ * @param {ToolRegistry} inner
+ * @param {Map<string, ToolAvailability>} availability
+ * @returns {ToolRegistry}
+ */
+export function createGatedToolRegistry(
+  inner: ToolRegistry,
+  availability: Map<string, ToolAvailability>,
+): ToolRegistry {
+  function isAvailable(name: string): boolean {
+    const gate = availability.get(name);
+    return gate ? gate.when() : true;
+  }
+
+  return {
+    register(tool: ToolDefinition) {
+      inner.register(tool);
+    },
+    list() {
+      return inner.list().filter((t) => isAvailable(t.name));
+    },
+    listForLLM() {
+      const available = new Set(this.list().map((t) => t.name));
+      return inner
+        .listForLLM()
+        .filter((t) => available.has((t as { function?: { name?: string } }).function?.name ?? ""));
+    },
+    getDefinition(toolName: string) {
+      return inner.getDefinition(toolName);
+    },
+    validate(toolName: string, args: object) {
+      return inner.validate(toolName, args);
+    },
+    async execute(toolName: string, args: object) {
+      if (inner.getDefinition(toolName) && !isAvailable(toolName)) {
+        const gate = availability.get(toolName);
+        return {
+          success: false,
+          error: `Tool "${toolName}" is not available right now — it requires ${gate?.requires ?? "a different studio state"}.`,
+        };
+      }
+      return inner.execute(toolName, args);
+    },
+  };
+}

package/src/services/preview-eval.ts

@@ -0,0 +1,68 @@
+/// <reference lib="dom" />
+/**
+ * Parent-side live expression preview (spec §19.9).
+ *
+ * Evaluates an expression node against the canvas iframe's last dataScope snapshot
+ * (tab.session.canvas.scope) on a structuredClone, so mutating operators are safe — they mutate the
+ * clone, never the live canvas. The engine's trace hook reports every sub-node's value keyed by its
+ * path within the tree; values are formatted to display strings at report time so later mutations
+ * of the clone cannot retroactively change a badge.
+ */
+
+import { evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
+import { toRaw } from "../reactivity";
+// Imported for local use AND re-exported below so existing consumers keep their import site.
+// oxlint-disable-next-line unicorn/prefer-export-from
+import { formatPreviewValue } from "../utils/preview-format";
+
+import type { ExpressionNode } from "@jxsuite/runtime/expression";
+
+export interface ExpressionPreview {
+  /** Path-keyed display values: "" is the root node, "value/target" a nested operand, etc. */
+  values: Map<string, string>;
+  /** Evaluation error message, if the expression threw. */
+  error: string | null;
+  /** Whether the root operator mutates its target (badge renders as an effect, not a value). */
+  mutating: boolean;
+}
+
+// The formatter is shared with the in-iframe live evaluator: it lives in utils/preview-format.ts
+// (dependency-light, safe for the iframe bundle) and is re-exported here so existing consumers
+// Keep their import site.
+export { formatPreviewValue };
+
+/**
+ * Evaluate `node` against a scope snapshot for display. Returns null when no snapshot is available
+ * (canvas not yet rendered) — the editor renders no badges rather than wrong ones.
+ */
+export function previewExpression(
+  node: unknown,
+  scope?: Record<string, unknown> | null,
+): ExpressionPreview | null {
+  if (!scope || !node || typeof node !== "object" || !("operator" in node)) {
+    return null;
+  }
+
+  let state: Record<string, unknown>;
+  try {
+    // Callers hand over tab.session.canvas.scope, which the reactive session tree wraps in a
+    // Proxy — structuredClone rejects proxies, so unwrap to the raw snapshot first.
+    state = structuredClone(toRaw(scope));
+  } catch {
+    // Snapshot values are JSON-safe by construction (serialize-scope), but stay defensive.
+    return null;
+  }
+
+  const values = new Map<string, string>();
+  const expr = node as ExpressionNode;
+  let errorMessage: string | null = null;
+  try {
+    evaluateExpression(expr, state, null, undefined, {
+      report: (path, value) => values.set(path.join("/"), formatPreviewValue(value)),
+    });
+  } catch (error) {
+    errorMessage = error instanceof Error ? error.message : String(error);
+  }
+
+  return { error: errorMessage, mutating: isMutating(expr.operator), values };
+}

package/src/services/project-adoption.ts

@@ -0,0 +1,31 @@
+/**
+ * Project-adoption.ts — a late-bound slot for opening a freshly created project in this window.
+ *
+ * The AI `create_project` tool (services/ai-project-tools.ts) needs to run the full project-open
+ * flow (`openRecentProject` in studio.ts), but services must not import studio.ts — the entry
+ * module imports the services. studio.ts registers the adopter at boot; the tool calls
+ * `adoptProject(root)`.
+ *
+ * @license MIT
+ */
+
+let _adopter: ((root: string) => Promise<void>) | null = null;
+
+/** Register the project-open flow (studio.ts boot). */
+export function setProjectAdopter(fn: (root: string) => Promise<void>): void {
+  _adopter = fn;
+}
+
+/**
+ * Open the project at `root` in this window via the registered flow.
+ *
+ * @param {string} root - Absolute project root.
+ */
+export async function adoptProject(root: string): Promise<void> {
+  if (!_adopter) {
+    throw new Error(
+      "Project adoption is not available in this environment — open the project manually from the welcome screen.",
+    );
+  }
+  await _adopter(root);
+}

package/src/site-context.ts

@@ -8,6 +8,7 @@
 
 import { projectState, requireProjectState, setProjectState } from "./store";
 import { getPlatform } from "./platform";
+import { setWorkspaceProject, workspace } from "./workspace/workspace";
 
 import type {
   JxElement,
@@ -272,6 +273,7 @@ export async function updateSiteConfig(patch: Partial<ProjectConfig>) {
   } as ProjectConfig;
   await platform.writeFile("project.json", JSON.stringify(config, null, 2));
   setProjectState({ ...requireProjectState(), projectConfig: config });
+  setWorkspaceProject(workspace.projectRoot, config);
   if ("extensions" in patch) {
     const { loadFormats, refreshExtensionUi, refreshFormats } =
       await import("./format/format-host");

package/src/store.ts

@@ -37,16 +37,20 @@ export let canvasWrap = null as unknown as HTMLElement;
 export let activityBar = null as unknown as HTMLElement;
 export let leftPanel = null as unknown as HTMLElement;
 export let rightPanel = null as unknown as HTMLElement;
+export let chatPanelEl = null as unknown as HTMLElement;
 export let toolbarEl = null as unknown as HTMLElement;
 export let statusbarEl = null as unknown as HTMLElement;
+export let frontmatterPanelEl = null as unknown as HTMLElement;
 
 export function initShellRefs() {
   canvasWrap = document.querySelector("#canvas-wrap") as HTMLElement;
   activityBar = document.querySelector("#activity-bar") as HTMLElement;
   leftPanel = document.querySelector("#left-panel") as HTMLElement;
   rightPanel = document.querySelector("#right-panel") as HTMLElement;
+  chatPanelEl = document.querySelector("#chat-panel") as HTMLElement;
   toolbarEl = document.querySelector("#toolbar") as HTMLElement;
   statusbarEl = document.querySelector("#statusbar") as HTMLElement;
+  frontmatterPanelEl = document.querySelector("#frontmatter-panel") as HTMLElement;
 }
 
 // ─── Shared containers (mutated in place by owner modules) ───────────────────

package/src/studio.ts

@@ -11,6 +11,7 @@ import { errorMessage } from "@jxsuite/schema/parse";
 
 import {
   canvasWrap,
+  chatPanelEl,
   getNodeAtPath,
   initShellRefs,
   projectState,
@@ -23,14 +24,20 @@ import {
   updateUi,
 } from "./store";
 
-import { activeTab, closeAllTabs, openTab } from "./workspace/workspace";
+import {
+  activeTab,
+  closeAllTabs,
+  openTab,
+  setWorkspaceProject,
+  workspace,
+} from "./workspace/workspace";
 import { mutateUpdateDef, mutateUpdateProperty, transactDoc } from "./tabs/transact";
 import { effect } from "./reactivity";
 
 import { view } from "./view";
 
 import { isEditing } from "./editor/inline-edit";
-import { applyTransform, initCanvasUtils, positionZoomIndicator } from "./canvas/canvas-utils";
+import { applyTransform, initCanvasUtils } from "./canvas/canvas-utils";
 import {
   initCanvasRender,
   renderCanvas,
@@ -113,12 +120,15 @@ import { components as _swc } from "./ui/spectrum";
 import "./ui/panel-resize.js";
 // Built-in schema-form controls (schema-builder, secret) register on import
 import "./ui/form-controls.js";
-import { initLayers } from "./ui/layers";
+import { initLayers, showSaveDiscardDialog } from "./ui/layers";
 import { initShortcuts } from "./editor/shortcuts";
 import { renderActivityBar, mount as mountActivityBar } from "./panels/activity-bar";
 import * as toolbarPanel from "./panels/toolbar";
 import * as overlaysPanel from "./panels/overlays";
+import * as frontmatterPanelMod from "./panels/frontmatter-panel";
 import * as rightPanelMod from "./panels/right-panel";
+import * as chatPanelMod from "./panels/chat-panel";
+import { setProjectAdopter } from "./services/project-adoption";
 import * as leftPanelMod from "./panels/left-panel";
 import * as tabStrip from "./panels/tab-strip";
 import * as tabBar from "./panels/tab-bar";
@@ -127,6 +137,7 @@ import { registerLayersDnD, registerComponentsDnD, registerElementsDnD } from ".
 import { registerCanvasDndBridge } from "./panels/canvas-dnd-bridge";
 import { defaultDef } from "./panels/shared";
 import { registerFunctionCompletions } from "./panels/editors";
+import { closeFormulaWorkspace } from "./panels/formula-workspace";
 import {
   initBlockActionBar,
   isEditChromeTarget,
@@ -142,6 +153,7 @@ import { initWelcome } from "./panels/welcome-screen";
 import { openAddRepoModal } from "./new-project/add-repo-modal";
 import { openNewProjectModal } from "./new-project/new-project-modal";
 import type { DocumentStackEntry, GitDiffState } from "./types";
+import type { Tab } from "./tabs/tab";
 import type { JxPath } from "./state";
 import type { JxMutableNode, ProjectConfig } from "@jxsuite/schema/types";
 
@@ -223,19 +235,41 @@ async function navigateToComponent(componentPath: string) {
   }
 }
 
+/**
+ * Leaving a drilled-in component discards its edits (the pop restores the parent). Because saving
+ * is explicit, prompt when the child is dirty: Save writes it, Discard drops it, Cancel stays.
+ * Returns false to abort navigation.
+ *
+ * @param {Tab} tab
+ */
+async function confirmLeaveDirtyChild(tab: Tab): Promise<boolean> {
+  if (!tab.doc.dirty || !tab.documentPath) {
+    return true;
+  }
+  const name = tab.documentPath.split("/").pop() || "component";
+  const choice = await showSaveDiscardDialog("Unsaved Changes", `"${name}" has unsaved changes.`);
+  if (choice === "cancel") {
+    return false;
+  }
+  if (choice === "save") {
+    try {
+      await getPlatform().writeFile(tab.documentPath, await serializeDocument(tab));
+    } catch (error) {
+      statusMessage(`Save error: ${(error as Error).message}`);
+      return false;
+    }
+  }
+  // "discard": leave without writing — the child's edits are dropped with the popped frame.
+  return true;
+}
+
 async function navigateBack() {
   const tab = activeTab.value;
   if (!tab?.session.documentStack || tab.session.documentStack.length === 0) {
     return;
   }
-  if (tab.doc.dirty && tab.documentPath) {
-    try {
-      const platform = getPlatform();
-      await platform.writeFile(tab.documentPath, await serializeDocument(tab));
-    } catch (error) {
-      const err = error as Error;
-      statusMessage(`Save error: ${err.message}`);
-    }
+  if (!(await confirmLeaveDirtyChild(tab))) {
+    return;
   }
 
   // Pop the stack
@@ -262,14 +296,8 @@ async function navigateToLevel(targetIndex: number) {
   if (!stack || targetIndex < 0 || targetIndex >= stack.length) {
     return;
   }
-  if (tab.doc.dirty && tab.documentPath) {
-    try {
-      const platform = getPlatform();
-      await platform.writeFile(tab.documentPath, await serializeDocument(tab));
-    } catch (error) {
-      const err = error as Error;
-      statusMessage(`Save error: ${err.message}`);
-    }
+  if (!(await confirmLeaveDirtyChild(tab))) {
+    return;
   }
 
   const frame = stack[targetIndex] as DocumentStackEntry;
@@ -393,6 +421,7 @@ initQuickSearch({ openRecentProject: (root: string) => openRecentProject(root) }
 tabStrip.mount(document.querySelector("#tab-strip") as HTMLElement);
 
 tabBar.mount(document.querySelector("#tab-bar") as HTMLElement, {
+  closeFormulaWorkspace: () => closeFormulaWorkspace(),
   closeFunctionEditor: () => closeFunctionEditor(),
   exportFile,
   getCanvasMode,
@@ -442,6 +471,26 @@ document.addEventListener(
   true,
 );
 
+// Unsaved-changes guard: saving is explicit (no idle autosave), so warn before the window unloads
+// While any open tab has unsaved edits. For collab tabs, `dirty` reflects the room-level unsaved
+// State; closing loses in-memory edits that were never flushed to disk.
+export function hasUnsavedTabs(): boolean {
+  for (const tab of workspace.tabs.values()) {
+    if (tab.doc.dirty) {
+      return true;
+    }
+  }
+  return false;
+}
+
+window.addEventListener("beforeunload", (e: BeforeUnloadEvent) => {
+  if (hasUnsavedTabs()) {
+    e.preventDefault();
+    // Legacy browsers require a truthy returnValue to trigger the native confirm prompt.
+    e.returnValue = "";
+  }
+});
+
 initCanvasUtils({
   getCanvasMode,
   getZoom: () => activeTab.value?.session.ui.zoom ?? 1,
@@ -518,10 +567,12 @@ effect(() => {
   if (tab) {
     void tab.doc.mode;
     void tab.session.ui.canvasMode;
+    void tab.session.ui.editingFormula;
     void tab.session.ui.editingFunction;
     void tab.session.ui.featureToggles;
     void tab.session.ui.preview;
     void tab.session.ui.previewParams;
+    void tab.session.ui.previewProps;
     void tab.session.ui.settingsTab;
     void tab.session.ui.showLayout;
     void tab.session.ui.stylebookTab;
@@ -537,6 +588,15 @@ rightPanelMod.mount({
   renderCanvas: () => renderCanvas(),
 });
 
+// Above-canvas frontmatter Properties panel (content-collection docs, edit mode).
+frontmatterPanelMod.mount({ getCanvasMode });
+
+// The persistent AI chat sidebar — mounts once, available with or without a project/document.
+chatPanelMod.mount(chatPanelEl);
+// The assistant's create_project tool adopts freshly scaffolded projects through the same
+// Flow as the recent-projects list.
+setProjectAdopter(openRecentProject);
+
 leftPanelMod.mount({
   cloneRepository: () => cloneRepository({ openRecentProject }),
   defBadgeLabel,
@@ -568,6 +628,8 @@ leftPanelMod.mount({
 registerRenderer("leftPanel", () => leftPanelMod.render());
 registerRenderer("canvas", () => renderCanvas());
 registerRenderer("rightPanel", () => rightPanelMod.render());
+registerRenderer("frontmatterPanel", () => frontmatterPanelMod.render());
+registerRenderer("chatPanel", () => chatPanelMod.render());
 registerRenderer("overlays", () => overlaysPanel.render());
 setStatusbarRenderer(() => renderStatusbar());
 mountStatusbar();
@@ -667,6 +729,7 @@ if (_projectParam) {
             searchQuery: "",
             selectedPath: siteCtx.fileRelPath || null,
           });
+          setWorkspaceProject(siteCtx.sitePath, siteCtx.projectConfig || null);
 
           refreshExtensionUi(platform);
           await autoSyncProjectOnOpen();
@@ -859,6 +922,7 @@ async function openRecentProject(root: string) {
       searchQuery: "",
       selectedPath: null,
     });
+    setWorkspaceProject(root, config);
 
     await autoSyncProjectOnOpen();
     await ensureDependenciesInstalled();
@@ -918,7 +982,6 @@ initShortcuts(() => ({
   openProject,
   panX: view.panX,
   panY: view.panY,
-  positionZoomIndicator,
   saveFile,
   setPan: (x, y) => {
     view.panX = x;
@@ -926,35 +989,3 @@ initShortcuts(() => ({
     view.needsCenter = false;
   },
 }));
-
-// ─── Autosave (registered as update middleware) ──────────────────────────────
-
-const AUTO_SAVE_DELAY = 2000;
-
-function scheduleAutosave() {
-  const tab = activeTab.value;
-  if (!tab?.fileHandle || !tab.doc.dirty) {
-    return;
-  }
-  if (view.autosaveTimer) {
-    clearTimeout(view.autosaveTimer);
-  }
-  view.autosaveTimer = setTimeout(async () => {
-    const t = activeTab.value;
-    if (t?.fileHandle && t.doc.dirty && "createWritable" in t.fileHandle) {
-      try {
-        const writable = await t.fileHandle.createWritable();
-        await writable.write(await serializeDocument(t));
-        await writable.close();
-        t.doc.dirty = false;
-        statusMessage("Auto-saved");
-      } catch {}
-    }
-  }, AUTO_SAVE_DELAY);
-}
-
-effect(() => {
-  if (activeTab.value?.doc.dirty) {
-    scheduleAutosave();
-  }
-});

package/src/tabs/patch-ops.ts

@@ -40,12 +40,26 @@ export type JxPatchOp =
 export type { JxDocOp } from "@jxsuite/collab/ops";
 export type { JxDocOpPair };
 
+/**
+ * A frontmatter key change, replayable in either direction. Frontmatter lives outside the document
+ * tree (`tab.doc.content.frontmatter`, split off by the format host), so these are studio-local and
+ * never enter the shared `JxDocOp` vocabulary the collab bridge and canvas iframe mirror.
+ * `undefined` means the key was/becomes absent.
+ */
+export interface JxFmOp {
+  field: string;
+  before?: unknown;
+  after?: unknown;
+}
+
 /** 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[];
+  /** Replayable frontmatter key changes (content-mode docs) for history undo/redo. */
+  fmOps: JxFmOp[];
   /**
    * 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.
@@ -86,12 +100,14 @@ export function getPatchConsumer(): PatchConsumer | null {
 
 let _recording: JxPatchOp[] | null = null;
 let _docOps: JxDocOpPair[] | null = null;
+let _fmOps: JxFmOp[] | null = null;
 let _invertible = true;
 
 /** Begin recording patch ops for a transaction. */
 export function beginRecording() {
   _recording = [];
   _docOps = [];
+  _fmOps = [];
   _invertible = true;
 }
 
@@ -109,6 +125,13 @@ export function recordDocOp(pair: JxDocOpPair) {
   }
 }
 
+/** Record a replayable frontmatter key change. No-op outside a transaction. */
+export function recordFmOp(op: JxFmOp) {
+  if (_fmOps) {
+    _fmOps.push(op);
+  }
+}
+
 /** Mark the current transaction as non-invertible — history stores a checkpoint instead. */
 export function markNonInvertible() {
   _invertible = false;
@@ -121,11 +144,13 @@ export function markNonInvertible() {
 export function endRecording(): TransactionRecord {
   const record: TransactionRecord = {
     docOps: _docOps ?? [],
+    fmOps: _fmOps ?? [],
     invertible: _invertible,
     ops: _recording ?? [],
   };
   _recording = null;
   _docOps = null;
+  _fmOps = null;
   _invertible = true;
   return record;
 }