@pixerate/editor 0.6.1 → 0.8.0

package/dist/history/index.js

@@ -0,0 +1,232 @@
+// src/history/HistoryManager.ts
+var HistoryManager = class {
+  undoStack = [];
+  redoStack = [];
+  maxDepth;
+  isApplying = false;
+  batchDepth = 0;
+  currentBatch = null;
+  listeners = /* @__PURE__ */ new Set();
+  onStateChange;
+  cachedState;
+  constructor(options = {}) {
+    this.maxDepth = options.maxDepth ?? 50;
+    this.onStateChange = options.onStateChange;
+    this.cachedState = this.computeState();
+  }
+  computeState() {
+    const canUndo = this.undoStack.length > 0;
+    const canRedo = this.redoStack.length > 0;
+    return {
+      canUndo,
+      canRedo,
+      undoName: canUndo ? this.undoStack[this.undoStack.length - 1].name : "",
+      redoName: canRedo ? this.redoStack[this.redoStack.length - 1].name : "",
+      undoCount: this.undoStack.length,
+      redoCount: this.redoStack.length
+    };
+  }
+  /**
+   * Returns a snapshot of the current history state.
+   * Cached to maintain referential equality across renders for useSyncExternalStore.
+   */
+  getState() {
+    return this.cachedState;
+  }
+  notify() {
+    this.cachedState = this.computeState();
+    const state = this.cachedState;
+    this.onStateChange?.(state);
+    this.listeners.forEach((listener) => {
+      try {
+        listener(state);
+      } catch (err) {
+        console.error("[HistoryManager] Error in state listener:", err);
+      }
+    });
+  }
+  /**
+   * Executes a command and pushes it onto the undo stack.
+   * Clears the redo stack.
+   */
+  execute(command) {
+    if (this.isApplying) {
+      command.execute();
+      return;
+    }
+    if (this.batchDepth > 0 && this.currentBatch) {
+      command.execute();
+      this.currentBatch.push({
+        ...command,
+        timestamp: command.timestamp ?? Date.now()
+      });
+      return;
+    }
+    command.execute();
+    this.undoStack.push({
+      ...command,
+      timestamp: command.timestamp ?? Date.now()
+    });
+    if (this.undoStack.length > this.maxDepth) {
+      this.undoStack.shift();
+    }
+    this.redoStack = [];
+    this.notify();
+  }
+  /**
+   * Executes a command, coalescing it with the previous command if they share
+   * the same `tag` and occurred within `windowMs` (default: 300ms).
+   * Useful for high-frequency interactions like slider scrubs or node drags.
+   */
+  executeMerged(command, options = {}) {
+    const windowMs = options.windowMs ?? 300;
+    const now = Date.now();
+    if (command.tag && this.undoStack.length > 0 && this.batchDepth === 0 && !this.isApplying) {
+      const top = this.undoStack[this.undoStack.length - 1];
+      const elapsed = top.timestamp ? now - top.timestamp : Infinity;
+      if (top.tag === command.tag && elapsed <= windowMs) {
+        command.execute();
+        const initialUndo = top.undo;
+        this.undoStack[this.undoStack.length - 1] = {
+          name: command.name,
+          tag: command.tag,
+          timestamp: now,
+          execute: command.execute,
+          undo: initialUndo,
+          redo: command.redo ?? command.execute
+        };
+        this.redoStack = [];
+        this.notify();
+        return;
+      }
+    }
+    this.execute({ ...command, timestamp: now });
+  }
+  /**
+   * Batches multiple commands executed within `fn` into a single atomic undo entry.
+   */
+  batch(name, fn) {
+    if (this.isApplying) {
+      fn();
+      return;
+    }
+    if (this.batchDepth > 0) {
+      fn();
+      return;
+    }
+    this.batchDepth++;
+    this.currentBatch = [];
+    try {
+      fn();
+    } finally {
+      this.batchDepth--;
+      const batchCommands = this.currentBatch;
+      this.currentBatch = null;
+      if (batchCommands && batchCommands.length > 0) {
+        const compoundCommand = {
+          name,
+          timestamp: Date.now(),
+          execute: () => {
+            for (let i = 0; i < batchCommands.length; i++) {
+              (batchCommands[i].redo ?? batchCommands[i].execute)();
+            }
+          },
+          undo: () => {
+            for (let i = batchCommands.length - 1; i >= 0; i--) {
+              batchCommands[i].undo();
+            }
+          },
+          redo: () => {
+            for (let i = 0; i < batchCommands.length; i++) {
+              (batchCommands[i].redo ?? batchCommands[i].execute)();
+            }
+          }
+        };
+        this.undoStack.push(compoundCommand);
+        if (this.undoStack.length > this.maxDepth) {
+          this.undoStack.shift();
+        }
+        this.redoStack = [];
+        this.notify();
+      }
+    }
+  }
+  /**
+   * Reverts the most recent command on the undo stack.
+   * Returns true if a command was undone, false otherwise.
+   */
+  undo() {
+    if (this.undoStack.length === 0 || this.isApplying || this.batchDepth > 0) {
+      return false;
+    }
+    this.isApplying = true;
+    try {
+      const command = this.undoStack.pop();
+      command.undo();
+      this.redoStack.push(command);
+      return true;
+    } finally {
+      this.isApplying = false;
+      this.notify();
+    }
+  }
+  /**
+   * Re-applies the most recent undone command on the redo stack.
+   * Returns true if a command was redone, false otherwise.
+   */
+  redo() {
+    if (this.redoStack.length === 0 || this.isApplying || this.batchDepth > 0) {
+      return false;
+    }
+    this.isApplying = true;
+    try {
+      const command = this.redoStack.pop();
+      (command.redo ?? command.execute)();
+      this.undoStack.push(command);
+      return true;
+    } finally {
+      this.isApplying = false;
+      this.notify();
+    }
+  }
+  /**
+   * Clears both undo and redo stacks.
+   */
+  clear() {
+    this.undoStack = [];
+    this.redoStack = [];
+    this.notify();
+  }
+  /**
+   * Subscribes to history state changes.
+   * The listener is immediately invoked with the current state.
+   * Returns an unsubscribe function.
+   */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    listener(this.getState());
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /**
+   * Utility helper to create a Command from before/after state snapshots.
+   */
+  static createSnapshotCommand(options) {
+    return {
+      name: options.name,
+      tag: options.tag,
+      execute: () => options.apply(options.after),
+      undo: () => options.apply(options.before),
+      redo: () => options.apply(options.after)
+    };
+  }
+};
+function createHistoryManager(options = {}) {
+  return new HistoryManager(options);
+}
+export {
+  HistoryManager,
+  createHistoryManager
+};
+//# sourceMappingURL=index.js.map

package/dist/history/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/history/HistoryManager.ts"],"sourcesContent":["import {\n  Command,\n  HistoryManagerOptions,\n  HistoryState,\n  MergedExecutionOptions,\n  SnapshotCommandOptions,\n} from \"./types\";\n\n/**\n * UI-agnostic History and Undo/Redo manager supporting command closures,\n * snapshot diffs, transaction batching, and high-frequency event coalescing.\n */\nexport class HistoryManager {\n  private undoStack: Command[] = [];\n  private redoStack: Command[] = [];\n  private readonly maxDepth: number;\n  private isApplying = false;\n  private batchDepth = 0;\n  private currentBatch: Command[] | null = null;\n  private listeners: Set<(state: HistoryState) => void> = new Set();\n  private onStateChange?: (state: HistoryState) => void;\n  private cachedState: HistoryState;\n\n  constructor(options: HistoryManagerOptions = {}) {\n    this.maxDepth = options.maxDepth ?? 50;\n    this.onStateChange = options.onStateChange;\n    this.cachedState = this.computeState();\n  }\n\n  private computeState(): HistoryState {\n    const canUndo = this.undoStack.length > 0;\n    const canRedo = this.redoStack.length > 0;\n    return {\n      canUndo,\n      canRedo,\n      undoName: canUndo ? this.undoStack[this.undoStack.length - 1].name : \"\",\n      redoName: canRedo ? this.redoStack[this.redoStack.length - 1].name : \"\",\n      undoCount: this.undoStack.length,\n      redoCount: this.redoStack.length,\n    };\n  }\n\n  /**\n   * Returns a snapshot of the current history state.\n   * Cached to maintain referential equality across renders for useSyncExternalStore.\n   */\n  public getState(): HistoryState {\n    return this.cachedState;\n  }\n\n  private notify(): void {\n    this.cachedState = this.computeState();\n    const state = this.cachedState;\n    this.onStateChange?.(state);\n    this.listeners.forEach((listener) => {\n      try {\n        listener(state);\n      } catch (err) {\n        console.error(\"[HistoryManager] Error in state listener:\", err);\n      }\n    });\n  }\n\n  /**\n   * Executes a command and pushes it onto the undo stack.\n   * Clears the redo stack.\n   */\n  public execute(command: Command): void {\n    if (this.isApplying) {\n      command.execute();\n      return;\n    }\n\n    if (this.batchDepth > 0 && this.currentBatch) {\n      command.execute();\n      this.currentBatch.push({\n        ...command,\n        timestamp: command.timestamp ?? Date.now(),\n      });\n      return;\n    }\n\n    command.execute();\n\n    this.undoStack.push({\n      ...command,\n      timestamp: command.timestamp ?? Date.now(),\n    });\n\n    if (this.undoStack.length > this.maxDepth) {\n      this.undoStack.shift();\n    }\n\n    this.redoStack = [];\n    this.notify();\n  }\n\n  /**\n   * Executes a command, coalescing it with the previous command if they share\n   * the same `tag` and occurred within `windowMs` (default: 300ms).\n   * Useful for high-frequency interactions like slider scrubs or node drags.\n   */\n  public executeMerged(\n    command: Command,\n    options: MergedExecutionOptions = {},\n  ): void {\n    const windowMs = options.windowMs ?? 300;\n    const now = Date.now();\n\n    if (\n      command.tag &&\n      this.undoStack.length > 0 &&\n      this.batchDepth === 0 &&\n      !this.isApplying\n    ) {\n      const top = this.undoStack[this.undoStack.length - 1];\n      const elapsed = top.timestamp ? now - top.timestamp : Infinity;\n\n      if (top.tag === command.tag && elapsed <= windowMs) {\n        command.execute();\n        // Replace top with merged command keeping the original initial undo\n        const initialUndo = top.undo;\n        this.undoStack[this.undoStack.length - 1] = {\n          name: command.name,\n          tag: command.tag,\n          timestamp: now,\n          execute: command.execute,\n          undo: initialUndo,\n          redo: command.redo ?? command.execute,\n        };\n        this.redoStack = [];\n        this.notify();\n        return;\n      }\n    }\n\n    this.execute({ ...command, timestamp: now });\n  }\n\n  /**\n   * Batches multiple commands executed within `fn` into a single atomic undo entry.\n   */\n  public batch(name: string, fn: () => void): void {\n    if (this.isApplying) {\n      fn();\n      return;\n    }\n\n    if (this.batchDepth > 0) {\n      // Already inside a batch; execute directly\n      fn();\n      return;\n    }\n\n    this.batchDepth++;\n    this.currentBatch = [];\n\n    try {\n      fn();\n    } finally {\n      this.batchDepth--;\n      const batchCommands = this.currentBatch;\n      this.currentBatch = null;\n\n      if (batchCommands && batchCommands.length > 0) {\n        const compoundCommand: Command = {\n          name,\n          timestamp: Date.now(),\n          execute: () => {\n            for (let i = 0; i < batchCommands.length; i++) {\n              (batchCommands[i].redo ?? batchCommands[i].execute)();\n            }\n          },\n          undo: () => {\n            for (let i = batchCommands.length - 1; i >= 0; i--) {\n              batchCommands[i].undo();\n            }\n          },\n          redo: () => {\n            for (let i = 0; i < batchCommands.length; i++) {\n              (batchCommands[i].redo ?? batchCommands[i].execute)();\n            }\n          },\n        };\n\n        this.undoStack.push(compoundCommand);\n        if (this.undoStack.length > this.maxDepth) {\n          this.undoStack.shift();\n        }\n        this.redoStack = [];\n        this.notify();\n      }\n    }\n  }\n\n  /**\n   * Reverts the most recent command on the undo stack.\n   * Returns true if a command was undone, false otherwise.\n   */\n  public undo(): boolean {\n    if (this.undoStack.length === 0 || this.isApplying || this.batchDepth > 0) {\n      return false;\n    }\n\n    this.isApplying = true;\n    try {\n      const command = this.undoStack.pop()!;\n      command.undo();\n      this.redoStack.push(command);\n      return true;\n    } finally {\n      this.isApplying = false;\n      this.notify();\n    }\n  }\n\n  /**\n   * Re-applies the most recent undone command on the redo stack.\n   * Returns true if a command was redone, false otherwise.\n   */\n  public redo(): boolean {\n    if (this.redoStack.length === 0 || this.isApplying || this.batchDepth > 0) {\n      return false;\n    }\n\n    this.isApplying = true;\n    try {\n      const command = this.redoStack.pop()!;\n      (command.redo ?? command.execute)();\n      this.undoStack.push(command);\n      return true;\n    } finally {\n      this.isApplying = false;\n      this.notify();\n    }\n  }\n\n  /**\n   * Clears both undo and redo stacks.\n   */\n  public clear(): void {\n    this.undoStack = [];\n    this.redoStack = [];\n    this.notify();\n  }\n\n  /**\n   * Subscribes to history state changes.\n   * The listener is immediately invoked with the current state.\n   * Returns an unsubscribe function.\n   */\n  public subscribe(listener: (state: HistoryState) => void): () => void {\n    this.listeners.add(listener);\n    listener(this.getState());\n    return () => {\n      this.listeners.delete(listener);\n    };\n  }\n\n  /**\n   * Utility helper to create a Command from before/after state snapshots.\n   */\n  public static createSnapshotCommand<T>(\n    options: SnapshotCommandOptions<T>,\n  ): Command {\n    return {\n      name: options.name,\n      tag: options.tag,\n      execute: () => options.apply(options.after),\n      undo: () => options.apply(options.before),\n      redo: () => options.apply(options.after),\n    };\n  }\n}\n\n/**\n * Creates and initializes a new HistoryManager instance.\n */\nexport function createHistoryManager(\n  options: HistoryManagerOptions = {},\n): HistoryManager {\n  return new HistoryManager(options);\n}\n"],"mappings":"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","names":[]}

package/dist/index.cjs

@@ -33,11 +33,13 @@ __export(src_exports, {
   ColorHighlighter: () => ColorHighlighter,
   DataSourceBinder: () => DataSourceBinder,
   DependencyGraph: () => DependencyGraph,
+  DirtyTracker: () => DirtyTracker,
   EditorController: () => EditorController,
   FontSize: () => FontSize,
   FormulaEvaluator: () => FormulaEvaluator,
   FormulaParser: () => FormulaParser,
   GradientText: () => GradientText,
+  HistoryManager: () => HistoryManager,
   INSTRUCTION_REGEX: () => INSTRUCTION_REGEX,
   Image: () => Image2,
   LoadingNode: () => LoadingNode,
@@ -50,9 +52,12 @@ __export(src_exports, {
   TemplateSuggestions: () => TemplateSuggestions,
   VARIABLE_REGEX: () => VARIABLE_REGEX,
   colNameToIndex: () => colNameToIndex,
+  createDirtyTracker: () => createDirtyTracker,
   createEditor: () => createEditor,
+  createHistoryManager: () => createHistoryManager,
   createMentionExtension: () => createMentionExtension,
   createRichTextPreset: () => createRichTextPreset,
+  defaultIsEqual: () => defaultIsEqual,
   escapeHtml: () => escapeHtml,
   extractCellDependencies: () => extractCellDependencies,
   extractInstructionNames: () => extractInstructionNames,
@@ -2443,6 +2448,7 @@ var EditorController = class {
   onMarkdownChange;
   onTokensChange;
   onSelectionChange;
+  baselineContent;
   constructor(options = {}) {
     const {
       element,
@@ -2480,6 +2486,7 @@ var EditorController = class {
     if (plainTextMode) {
       this.enforcePlainTextClipboard();
     }
+    this.baselineContent = this.getCurrentContentString();
   }
   enforcePlainTextClipboard() {
     this.editor.setOptions({
@@ -2553,6 +2560,23 @@ var EditorController = class {
   replaceRange(from, to, text) {
     this.editor.chain().focus().deleteRange({ from, to }).insertContentAt(from, text).run();
   }
+  getCurrentContentString() {
+    if (this.plainTextMode) return this.getPlainText();
+    if (this.markdownMode) return this.getMarkdown();
+    return this.editor.getHTML();
+  }
+  isDirty() {
+    return this.getCurrentContentString() !== this.baselineContent;
+  }
+  setCheckpoint(content) {
+    this.baselineContent = content !== void 0 ? content : this.getCurrentContentString();
+  }
+  resetDirty() {
+    this.setCheckpoint();
+  }
+  getBaselineContent() {
+    return this.baselineContent;
+  }
   destroy() {
     this.editor.destroy();
   }
@@ -3835,16 +3859,311 @@ var SpreadsheetController = class {
     this.onDocumentChange?.(this.document);
   }
 };
+
+// src/dirty.ts
+function defaultIsEqual(a, b) {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== "object" || a === null || typeof b !== "object" || b === null) {
+    return false;
+  }
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!defaultIsEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  if (Array.isArray(a) !== Array.isArray(b)) {
+    return false;
+  }
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+  for (const key of keysA) {
+    if (!Object.prototype.hasOwnProperty.call(b, key)) return false;
+    if (!defaultIsEqual(a[key], b[key])) return false;
+  }
+  return true;
+}
+var DirtyTracker = class {
+  baseline;
+  isEqual;
+  constructor(initialBaseline, options) {
+    this.baseline = initialBaseline;
+    if (typeof options === "function") {
+      this.isEqual = options;
+    } else {
+      this.isEqual = options?.isEqual ?? defaultIsEqual;
+    }
+  }
+  /**
+   * Returns current baseline value.
+   */
+  getBaseline() {
+    return this.baseline;
+  }
+  /**
+   * Sets a new baseline value without triggering any dirty state.
+   */
+  setBaseline(value) {
+    this.baseline = value;
+  }
+  /**
+   * Checks whether the given value differs from the baseline.
+   */
+  isDirty(current) {
+    return !this.isEqual(this.baseline, current);
+  }
+  /**
+   * Resets the baseline to the provided current value (or clears dirty status).
+   */
+  reset(current) {
+    this.baseline = current;
+  }
+};
+function createDirtyTracker(initialBaseline, options) {
+  return new DirtyTracker(initialBaseline, options);
+}
+
+// src/history/HistoryManager.ts
+var HistoryManager = class {
+  undoStack = [];
+  redoStack = [];
+  maxDepth;
+  isApplying = false;
+  batchDepth = 0;
+  currentBatch = null;
+  listeners = /* @__PURE__ */ new Set();
+  onStateChange;
+  cachedState;
+  constructor(options = {}) {
+    this.maxDepth = options.maxDepth ?? 50;
+    this.onStateChange = options.onStateChange;
+    this.cachedState = this.computeState();
+  }
+  computeState() {
+    const canUndo = this.undoStack.length > 0;
+    const canRedo = this.redoStack.length > 0;
+    return {
+      canUndo,
+      canRedo,
+      undoName: canUndo ? this.undoStack[this.undoStack.length - 1].name : "",
+      redoName: canRedo ? this.redoStack[this.redoStack.length - 1].name : "",
+      undoCount: this.undoStack.length,
+      redoCount: this.redoStack.length
+    };
+  }
+  /**
+   * Returns a snapshot of the current history state.
+   * Cached to maintain referential equality across renders for useSyncExternalStore.
+   */
+  getState() {
+    return this.cachedState;
+  }
+  notify() {
+    this.cachedState = this.computeState();
+    const state = this.cachedState;
+    this.onStateChange?.(state);
+    this.listeners.forEach((listener) => {
+      try {
+        listener(state);
+      } catch (err) {
+        console.error("[HistoryManager] Error in state listener:", err);
+      }
+    });
+  }
+  /**
+   * Executes a command and pushes it onto the undo stack.
+   * Clears the redo stack.
+   */
+  execute(command) {
+    if (this.isApplying) {
+      command.execute();
+      return;
+    }
+    if (this.batchDepth > 0 && this.currentBatch) {
+      command.execute();
+      this.currentBatch.push({
+        ...command,
+        timestamp: command.timestamp ?? Date.now()
+      });
+      return;
+    }
+    command.execute();
+    this.undoStack.push({
+      ...command,
+      timestamp: command.timestamp ?? Date.now()
+    });
+    if (this.undoStack.length > this.maxDepth) {
+      this.undoStack.shift();
+    }
+    this.redoStack = [];
+    this.notify();
+  }
+  /**
+   * Executes a command, coalescing it with the previous command if they share
+   * the same `tag` and occurred within `windowMs` (default: 300ms).
+   * Useful for high-frequency interactions like slider scrubs or node drags.
+   */
+  executeMerged(command, options = {}) {
+    const windowMs = options.windowMs ?? 300;
+    const now = Date.now();
+    if (command.tag && this.undoStack.length > 0 && this.batchDepth === 0 && !this.isApplying) {
+      const top = this.undoStack[this.undoStack.length - 1];
+      const elapsed = top.timestamp ? now - top.timestamp : Infinity;
+      if (top.tag === command.tag && elapsed <= windowMs) {
+        command.execute();
+        const initialUndo = top.undo;
+        this.undoStack[this.undoStack.length - 1] = {
+          name: command.name,
+          tag: command.tag,
+          timestamp: now,
+          execute: command.execute,
+          undo: initialUndo,
+          redo: command.redo ?? command.execute
+        };
+        this.redoStack = [];
+        this.notify();
+        return;
+      }
+    }
+    this.execute({ ...command, timestamp: now });
+  }
+  /**
+   * Batches multiple commands executed within `fn` into a single atomic undo entry.
+   */
+  batch(name, fn) {
+    if (this.isApplying) {
+      fn();
+      return;
+    }
+    if (this.batchDepth > 0) {
+      fn();
+      return;
+    }
+    this.batchDepth++;
+    this.currentBatch = [];
+    try {
+      fn();
+    } finally {
+      this.batchDepth--;
+      const batchCommands = this.currentBatch;
+      this.currentBatch = null;
+      if (batchCommands && batchCommands.length > 0) {
+        const compoundCommand = {
+          name,
+          timestamp: Date.now(),
+          execute: () => {
+            for (let i = 0; i < batchCommands.length; i++) {
+              (batchCommands[i].redo ?? batchCommands[i].execute)();
+            }
+          },
+          undo: () => {
+            for (let i = batchCommands.length - 1; i >= 0; i--) {
+              batchCommands[i].undo();
+            }
+          },
+          redo: () => {
+            for (let i = 0; i < batchCommands.length; i++) {
+              (batchCommands[i].redo ?? batchCommands[i].execute)();
+            }
+          }
+        };
+        this.undoStack.push(compoundCommand);
+        if (this.undoStack.length > this.maxDepth) {
+          this.undoStack.shift();
+        }
+        this.redoStack = [];
+        this.notify();
+      }
+    }
+  }
+  /**
+   * Reverts the most recent command on the undo stack.
+   * Returns true if a command was undone, false otherwise.
+   */
+  undo() {
+    if (this.undoStack.length === 0 || this.isApplying || this.batchDepth > 0) {
+      return false;
+    }
+    this.isApplying = true;
+    try {
+      const command = this.undoStack.pop();
+      command.undo();
+      this.redoStack.push(command);
+      return true;
+    } finally {
+      this.isApplying = false;
+      this.notify();
+    }
+  }
+  /**
+   * Re-applies the most recent undone command on the redo stack.
+   * Returns true if a command was redone, false otherwise.
+   */
+  redo() {
+    if (this.redoStack.length === 0 || this.isApplying || this.batchDepth > 0) {
+      return false;
+    }
+    this.isApplying = true;
+    try {
+      const command = this.redoStack.pop();
+      (command.redo ?? command.execute)();
+      this.undoStack.push(command);
+      return true;
+    } finally {
+      this.isApplying = false;
+      this.notify();
+    }
+  }
+  /**
+   * Clears both undo and redo stacks.
+   */
+  clear() {
+    this.undoStack = [];
+    this.redoStack = [];
+    this.notify();
+  }
+  /**
+   * Subscribes to history state changes.
+   * The listener is immediately invoked with the current state.
+   * Returns an unsubscribe function.
+   */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    listener(this.getState());
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /**
+   * Utility helper to create a Command from before/after state snapshots.
+   */
+  static createSnapshotCommand(options) {
+    return {
+      name: options.name,
+      tag: options.tag,
+      execute: () => options.apply(options.after),
+      undo: () => options.apply(options.before),
+      redo: () => options.apply(options.after)
+    };
+  }
+};
+function createHistoryManager(options = {}) {
+  return new HistoryManager(options);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ColorHighlighter,
   DataSourceBinder,
   DependencyGraph,
+  DirtyTracker,
   EditorController,
   FontSize,
   FormulaEvaluator,
   FormulaParser,
   GradientText,
+  HistoryManager,
   INSTRUCTION_REGEX,
   Image,
   LoadingNode,
@@ -3857,9 +4176,12 @@ var SpreadsheetController = class {
   TemplateSuggestions,
   VARIABLE_REGEX,
   colNameToIndex,
+  createDirtyTracker,
   createEditor,
+  createHistoryManager,
   createMentionExtension,
   createRichTextPreset,
+  defaultIsEqual,
   escapeHtml,
   extractCellDependencies,
   extractInstructionNames,