@jxsuite/studio 1.0.0 → 1.2.0

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,
@@ -41,6 +48,7 @@ import { consumePatchedDocument, initCanvasPatcher } from "./canvas/canvas-patch
 import {
   commitActiveEditSession,
   getEditSnapshot,
+  postColorSchemeToLiveHosts,
   setCanvasContextMenuHandler,
   setCanvasSlashHandler,
   setIframePatchEscalation,
@@ -113,12 +121,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 +138,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 +154,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 +236,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 +297,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 +422,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 +472,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 +568,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;
@@ -530,6 +582,12 @@ effect(() => {
   }
   scheduleCanvasRender();
 });
+// Color-scheme preview is a document-level attribute flip inside the iframe — deliberately its
+// Own effect, never part of the ui-effect above: flipping the scheme must not re-render.
+effect(() => {
+  const s = activeTab.value?.session.ui.previewColorScheme;
+  postColorSchemeToLiveHosts(s === "light" || s === "dark" ? s : null);
+});
 
 rightPanelMod.mount({
   getCanvasMode,
@@ -537,6 +595,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 +635,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 +736,7 @@ if (_projectParam) {
             searchQuery: "",
             selectedPath: siteCtx.fileRelPath || null,
           });
+          setWorkspaceProject(siteCtx.sitePath, siteCtx.projectConfig || null);
 
           refreshExtensionUi(platform);
           await autoSyncProjectOnOpen();
@@ -859,6 +929,7 @@ async function openRecentProject(root: string) {
       searchQuery: "",
       selectedPath: null,
     });
+    setWorkspaceProject(root, config);
 
     await autoSyncProjectOnOpen();
     await ensureDependenciesInstalled();
@@ -918,7 +989,6 @@ initShortcuts(() => ({
   openProject,
   panX: view.panX,
   panY: view.panY,
-  positionZoomIndicator,
   saveFile,
   setPan: (x, y) => {
     view.panX = x;
@@ -926,35 +996,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;
 }

package/src/tabs/tab.ts

@@ -4,14 +4,16 @@ import { formatByName, formatForPath } from "../format/format-host";
 import { normalizeArrayChildren } from "../state";
 import type {
   DocumentStackEntry,
+  FormulaEditDef,
   FunctionEditDef,
   GitBranchesResult,
   GitDiffState,
   GitStatusResult,
   InlineEditDef,
+  JsonValue,
 } from "../types";
 import type { JxMutableNode } from "@jxsuite/schema/types";
-import type { JxDocOp } from "./patch-ops";
+import type { JxDocOp, JxFmOp } from "./patch-ops";
 
 export interface TabUi {
   rightTab: string;
@@ -20,13 +22,33 @@ export interface TabUi {
   preview: boolean;
   /** Show elements inherited from the page's layout (pages with an effective layout only). */
   showLayout: boolean;
+  /** Above-canvas frontmatter Properties accordion expanded (content-collection docs, edit mode). */
+  frontmatterOpen: boolean;
   /** Chosen literal values for dynamic route params (e.g. { sku: "mini-trencher" }). */
   previewParams: Record<string, string>;
+  /**
+   * Chosen test values for a component doc's props (state entries), seeded into the canvas render
+   * so a non-instantiated component previews with real data (M6) — the previewParams mirror.
+   */
+  previewProps: Record<string, JsonValue> | null;
   zoom: number;
+  /**
+   * Edit-mode content zoom — browser-page-zoom semantics (content reflows at the zoomed effective
+   * width while the canvas footprint stays fixed), unlike `zoom` which pan/zooms the whole canvas.
+   */
+  editZoom: number;
   activeMedia: string | null;
   activeSelector: string | null;
   editingFunction: FunctionEditDef | null;
+  /** Full-screen formula workspace target ($expression editing); editingFunction wins if both set. */
+  editingFormula: FormulaEditDef | null;
   featureToggles: Record<string, boolean>;
+  /**
+   * Canvas color-scheme preview: follow the OS ("auto") or force a scheme. Drives the
+   * data-color-scheme attribute on the canvas iframe root (spec §9.5) and, in the style sidebar,
+   * which scheme layer edits target.
+   */
+  previewColorScheme: "auto" | "light" | "dark";
   styleSections: Record<string, boolean>;
   inspectorSections: Record<string, boolean>;
   styleShorthands: Record<string, boolean>;
@@ -46,6 +68,18 @@ export interface TabUi {
   pendingInlineEdit: InlineEditDef | null;
 }
 
+/**
+ * A live (iframe-evaluated) expression preview retained per editing target (M6). Stored on
+ * `session.canvas` beside `scope` — plain wire data (path-key → display-string pairs), rebuilt into
+ * an ExpressionPreview by services/live-preview.ts on read.
+ */
+export interface StoredLivePreview {
+  /** Serialized expression + context the values were computed for (staleness check). */
+  key: string;
+  values: [string, string][];
+  error: string | null;
+}
+
 interface HistorySnapshot {
   /** Full document at this state (checkpoint), or null when the ops describe the transition. */
   document: Record<string, unknown> | null;
@@ -57,6 +91,8 @@ interface HistorySnapshot {
   forwardOps?: JxDocOp[] | null;
   /** Replayable ops transforming this state back into the previous one. */
   inverseOps?: JxDocOp[] | null;
+  /** Frontmatter key changes in this transaction (before/after values, replayed both ways). */
+  fmOps?: JxFmOp[] | null;
 }
 
 export interface Tab {
@@ -89,6 +125,9 @@ export interface Tab {
       // 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;
+      // 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;
       error: string | null;
       pendingInlineEdit: InlineEditDef | null;
     };
@@ -109,8 +148,11 @@ function createDefaultUi(canvasMode: string, preview = false) {
     activeMedia: null,
     activeSelector: null,
     canvasMode,
+    editZoom: 1,
+    editingFormula: null,
     editingFunction: null,
     featureToggles: {},
+    frontmatterOpen: true,
     gitBranches: null,
     gitCommitMessage: "",
     gitDiffState: null,
@@ -120,7 +162,9 @@ function createDefaultUi(canvasMode: string, preview = false) {
     inspectorSections: {},
     pendingInlineEdit: null,
     preview,
+    previewColorScheme: "auto" as const,
     previewParams: {},
+    previewProps: null,
     rightTab: "properties",
     settingsTab: "stylebook",
     showLayout: true,
@@ -204,6 +248,7 @@ export function createTab({
     session: reactive({
       canvas: {
         error: null,
+        livePreviews: null,
         pendingInlineEdit: null,
         scope: null,
         status: "idle",

package/src/tabs/transact.ts

@@ -8,16 +8,23 @@ import {
   endRecording,
   getPatchConsumer,
   recordDocOp,
+  recordFmOp,
   recordPatch,
 } from "./patch-ops";
 
-import type { JxDocOp, JxDocOpPair, TransactionRecord } from "./patch-ops";
+import type { JxDocOp, JxDocOpPair, JxFmOp, 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 type {
+  JxAttributeValue,
+  JxEventBinding,
+  JxMutableNode,
+  JxStateObject,
+  JxStyle,
+} from "@jxsuite/schema/types";
 import { ensureNestedStyle, getNestedStyle, isEventBinding } from "@jxsuite/schema/guards";
 
 const HISTORY_LIMIT = 100;
@@ -205,10 +212,14 @@ function pushHistoryEntry(
   selectionBefore: JxPath | null,
 ) {
   const truncated = tab.history.snapshots.slice(0, tab.history.index + 1);
-  const useOps = patchHistoryEnabled() && record.invertible && record.docOps.length > 0;
+  const useOps =
+    patchHistoryEnabled() &&
+    record.invertible &&
+    (record.docOps.length > 0 || record.fmOps.length > 0);
   const needCheckpoint = !useOps || truncated.length % CHECKPOINT_INTERVAL === 0;
   truncated.push({
     document: needCheckpoint ? jsonClone(raw) : null,
+    fmOps: useOps && record.fmOps.length > 0 ? record.fmOps : 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,
@@ -471,14 +482,23 @@ export function undo(tab: Tab) {
   }
   const entry = tab.history.snapshots[tab.history.index]!;
   const inverseOps = patchHistoryEnabled() ? entry.inverseOps : null;
-  if (inverseOps && inverseOps.length > 0) {
+  const fmOps = patchHistoryEnabled() ? entry.fmOps : null;
+  if ((inverseOps && inverseOps.length > 0) || (fmOps && fmOps.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);
+        if (inverseOps) {
+          for (let i = inverseOps.length - 1; i >= 0; i--) {
+            applyDocOp(t, toRaw(inverseOps[i]) as JxDocOp);
+          }
+        }
+        if (fmOps) {
+          for (let i = fmOps.length - 1; i >= 0; i--) {
+            const op = toRaw(fmOps[i]) as JxFmOp;
+            applyFmState(t, op.field, op.before);
+          }
         }
       },
       { origin: "history", skipHistory: true },
@@ -505,12 +525,21 @@ export function redo(tab: Tab) {
   }
   const entry = tab.history.snapshots[tab.history.index + 1]!;
   const forwardOps = patchHistoryEnabled() ? entry.forwardOps : null;
-  if (forwardOps && forwardOps.length > 0) {
+  const fmOps = patchHistoryEnabled() ? entry.fmOps : null;
+  if ((forwardOps && forwardOps.length > 0) || (fmOps && fmOps.length > 0)) {
     transactDoc(
       tab,
       (t) => {
-        for (const op of forwardOps) {
-          applyDocOp(t, toRaw(op) as JxDocOp);
+        if (forwardOps) {
+          for (const op of forwardOps) {
+            applyDocOp(t, toRaw(op) as JxDocOp);
+          }
+        }
+        if (fmOps) {
+          for (const op of fmOps) {
+            const raw = toRaw(op) as JxFmOp;
+            applyFmState(t, raw.field, raw.after);
+          }
         }
       },
       { origin: "history", skipHistory: true },
@@ -746,13 +775,13 @@ export function mutateUpdateStyle(tab: Tab, path: JxPath, prop: string, value: s
  * @param {Tab} tab
  * @param {JxPath} path
  * @param {string} attr
- * @param {string | undefined} value
+ * @param {JxAttributeValue | undefined} value — a literal, `$ref` binding, or `${}` template.
  */
 export function mutateUpdateAttribute(
   tab: Tab,
   path: JxPath,
   attr: string,
-  value?: string | undefined,
+  value?: JxAttributeValue | undefined,
 ) {
   const node = getNodeAtPath(tab.doc.document, path);
   const attrsBefore = cloneValue(node.attributes);
@@ -1196,10 +1225,28 @@ export function mutateRenameSwitchCase(tab: Tab, path: JxPath, oldName: string,
  * @param {JsonValue} value
  */
 export function mutateUpdateFrontmatter(tab: Tab, field: string, value?: JsonValue) {
-  if (value === undefined || value === null || value === "") {
+  const fm = tab.doc.content.frontmatter;
+  const before = Object.hasOwn(fm, field) ? cloneValue(fm[field]) : undefined;
+  const deletes = value === undefined || value === null || value === "";
+  if (deletes) {
+    delete fm[field];
+  } else {
+    fm[field] = value;
+  }
+  const after = deletes ? undefined : cloneValue(value);
+  recordFmOp({ after, before, field });
+  tab.doc.dirty = true;
+}
+
+/**
+ * Restore a frontmatter key to a recorded history state: `undefined` means the key was absent.
+ * 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) {
+  if (value === undefined) {
     delete tab.doc.content.frontmatter[field];
   } else {
     tab.doc.content.frontmatter[field] = value;
   }
-  tab.doc.dirty = true;
 }

package/src/types.ts

@@ -427,6 +427,18 @@ export interface FunctionEditDef {
   parameters?: string[];
 }
 
+/**
+ * Identifies which document position's `$expression` the full-screen formula workspace is editing:
+ * a state entry (`type: "def"` + defName) or an element event binding (`type: "event"` + path +
+ * eventKey). Mirrors FunctionEditDef, the Monaco function editor's target shape.
+ */
+export interface FormulaEditDef {
+  type: "def" | "event";
+  defName?: string;
+  path?: JxPath;
+  eventKey?: string;
+}
+
 export interface GitDiffState {
   filePath: string;
   originalContent: string;