feat: add pause()/resume() to UndoManager

.changeset/undo-pause-resume.md

@@ -0,0 +1,10 @@
+---
+"loro-crdt": minor
+"loro-js": minor
+---
+
+Add `pause()`, `resume()`, and `isPaused()` to `UndoManager`. While paused,
+local edits are not recorded as undo steps and checkout events do not clear the
+stacks. Import events (remote changes) are still processed so that the stacks
+remain correctly transformed against concurrent edits. Use this to preserve
+undo/redo history across temporary checkouts such as read-only history previews.

crates/loro-internal/src/undo.rs

@@ -203,6 +203,7 @@ struct UndoManagerInner {
     undo_stack: Stack,
     redo_stack: Stack,
     processing_undo: bool,
+    paused: bool,
     last_undo_time: i64,
     merge_interval_in_ms: i64,
     max_stack_size: usize,
@@ -502,6 +503,7 @@ impl UndoManagerInner {
             undo_stack: Default::default(),
             redo_stack: Default::default(),
             processing_undo: false,
+            paused: false,
             merge_interval_in_ms: 0,
             last_undo_time: 0,
             max_stack_size: usize::MAX,
@@ -607,7 +609,7 @@ impl UndoManager {
                 // TODO: PERF undo can be significantly faster if we can get
                 // the DiffBatch for undo here
                 let lock = inner_clone.lock();
-                if lock.borrow().processing_undo {
+                if lock.borrow().processing_undo || lock.borrow().paused {
                     return;
                 }
                 if let Some(id) = event
@@ -666,6 +668,9 @@ impl UndoManager {
             }
             EventTriggerKind::Checkout => {
                 let lock = inner_clone.lock();
+                if lock.borrow().paused {
+                    return;
+                }
                 let mut inner = lock.borrow_mut();
                 inner.undo_stack.clear();
                 inner.redo_stack.clear();
@@ -977,6 +982,32 @@ impl UndoManager {
         self.inner.lock().borrow_mut().undo_stack.clear();
     }
 
+    /// Pause the UndoManager so that local edits and checkout events are ignored.
+    ///
+    /// While paused, local edits are not recorded as undo steps and checkout
+    /// events do not clear the stacks. Import events (remote changes) are still
+    /// processed so that the stacks remain correctly transformed against
+    /// concurrent edits.
+    ///
+    /// Use this before temporary checkouts (e.g. read-only history preview) that
+    /// should not disturb the undo/redo history. Close any open group (via
+    /// [`Self::group_end`]) before pausing.
+    ///
+    /// Call [`Self::resume`] after returning the document to its original state.
+    pub fn pause(&self) {
+        self.inner.lock().borrow_mut().paused = true;
+    }
+
+    /// Resume the UndoManager after a [`Self::pause`].
+    pub fn resume(&self) {
+        self.inner.lock().borrow_mut().paused = false;
+    }
+
+    /// Returns whether the UndoManager is currently paused.
+    pub fn is_paused(&self) -> bool {
+        self.inner.lock().borrow().paused
+    }
+
     pub fn set_top_undo_meta(&self, meta: UndoItemMeta) {
         self.inner.lock().borrow_mut().undo_stack.set_top_meta(meta);
     }

crates/loro-wasm/src/lib.rs

@@ -5452,6 +5452,31 @@ impl UndoManager {
     pub fn clearUndo(&self) {
         self.undo.lock().clear_undo();
     }
+
+    /// Pause the UndoManager so that local edits and checkout events are ignored.
+    ///
+    /// While paused, local edits are not recorded as undo steps and checkout
+    /// events do not clear the stacks. Import events (remote changes) are still
+    /// processed so that the stacks remain correctly transformed against
+    /// concurrent edits.
+    ///
+    /// Use this before temporary checkouts (e.g. read-only history preview) that
+    /// should not disturb undo/redo history. Close any open group before pausing.
+    ///
+    /// Call `resume()` after returning the document to its original state.
+    pub fn pause(&self) {
+        self.undo.lock().pause();
+    }
+
+    /// Resume the UndoManager after a `pause()`.
+    pub fn resume(&self) {
+        self.undo.lock().resume();
+    }
+
+    /// Returns whether the UndoManager is currently paused.
+    pub fn isPaused(&self) -> bool {
+        self.undo.lock().is_paused()
+    }
 }
 
 /// Use this function to throw an error after the micro task.

crates/loro/src/lib.rs

@@ -3976,6 +3976,32 @@ impl UndoManager {
     pub fn top_redo_value(&self) -> Option<LoroValue> {
         self.0.top_redo_value()
     }
+
+    /// Pause the UndoManager so that local edits and checkout events are ignored.
+    ///
+    /// While paused, local edits are not recorded as undo steps and checkout
+    /// events do not clear the stacks. Import events (remote changes) are still
+    /// processed so that the stacks remain correctly transformed against
+    /// concurrent edits.
+    ///
+    /// Use this before temporary checkouts (e.g. read-only history preview) that
+    /// should not disturb undo/redo history. Close any open group (via
+    /// [`Self::group_end`]) before pausing.
+    ///
+    /// Call [`Self::resume`] after returning the document to its original state.
+    pub fn pause(&self) {
+        self.0.pause();
+    }
+
+    /// Resume the UndoManager after a [`Self::pause`].
+    pub fn resume(&self) {
+        self.0.resume();
+    }
+
+    /// Returns whether the UndoManager is currently paused.
+    pub fn is_paused(&self) -> bool {
+        self.0.is_paused()
+    }
 }
 /// When a undo/redo item is pushed, the undo manager will call the on_push callback to get the meta data of the undo item.
 /// The returned cursors will be recorded for a new pushed undo item.

crates/loro/tests/integration_test/undo_test.rs

@@ -1761,3 +1761,63 @@ fn undo_with_custom_commit_options() -> anyhow::Result<()> {
     assert_eq!(trigger_times.load(atomic::Ordering::SeqCst), 2);
     Ok(())
 }
+
+#[test]
+fn pause_preserves_undo_stacks_across_checkout() -> LoroResult<()> {
+    let doc = LoroDoc::new();
+    doc.set_peer_id(1)?;
+    let mut undo = UndoManager::new(&doc);
+    let text = doc.get_text("text");
+
+    text.insert(0, "Hello")?;
+    doc.commit();
+    text.insert(5, " World")?;
+    doc.commit();
+    assert_eq!(text.to_string(), "Hello World");
+    assert!(undo.can_undo());
+
+    // Pause before checkout so undo stacks survive
+    undo.pause();
+    assert!(undo.is_paused());
+    doc.checkout(&Frontiers::default())?;
+    assert_eq!(text.to_string(), "");
+    doc.attach();
+    assert_eq!(text.to_string(), "Hello World");
+    undo.resume();
+    assert!(!undo.is_paused());
+
+    // Undo stacks should still be intact
+    assert!(undo.can_undo());
+    undo.undo()?;
+    assert_eq!(text.to_string(), "Hello");
+    undo.undo()?;
+    assert_eq!(text.to_string(), "");
+
+    // Redo should also work
+    assert!(undo.can_redo());
+    undo.redo()?;
+    assert_eq!(text.to_string(), "Hello");
+    undo.redo()?;
+    assert_eq!(text.to_string(), "Hello World");
+
+    Ok(())
+}
+
+#[test]
+fn checkout_without_pause_clears_undo_stacks() -> LoroResult<()> {
+    let doc = LoroDoc::new();
+    doc.set_peer_id(1)?;
+    let undo = UndoManager::new(&doc);
+    let text = doc.get_text("text");
+
+    text.insert(0, "Hello")?;
+    doc.commit();
+    assert!(undo.can_undo());
+
+    // Checkout without pausing should still clear stacks (existing behavior)
+    doc.checkout(&Frontiers::default())?;
+    assert!(!undo.can_undo());
+    assert!(!undo.can_redo());
+
+    Ok(())
+}

loro-js/src/runtime/undo.ts

@@ -71,6 +71,7 @@ export class UndoManager {
   #onPush: UndoConfig["onPush"];
   #onPop: UndoConfig["onPop"];
   #applying = false;
+  #paused = false;
   #groupDepth = 0;
   #unsubscribe: () => void;
 
@@ -186,6 +187,18 @@ export class UndoManager {
     this.#redo.length = 0;
   }
 
+  pause(): void {
+    this.#paused = true;
+  }
+
+  resume(): void {
+    this.#paused = false;
+  }
+
+  isPaused(): boolean {
+    return this.#paused;
+  }
+
   destroy(): void {
     this.#unsubscribe();
     this.clear();
@@ -195,13 +208,14 @@ export class UndoManager {
     if (this.#applying) return;
     const targets = new Set(event.events.map(({ target }) => target));
     if (event.by === "checkout") {
-      this.clear();
+      if (!this.#paused) this.clear();
       return;
     }
     if (event.by === "import") {
       for (const target of targets) this.#remoteTargets.add(target);
       return;
     }
+    if (this.#paused) return;
     if (
       event.origin !== undefined &&
       [...this.#excludeOriginPrefixes].some((prefix) => event.origin!.startsWith(prefix))

loro-js/tests/runtime.test.ts

@@ -684,6 +684,39 @@ describe("loro-wasm-compatible runtime", () => {
     expect(text.toString()).toBe("Hello");
   });
 
+  test("pause preserves undo stacks across checkout", () => {
+    const doc = new LoroDoc();
+    doc.setPeerId(1);
+    const undo = new UndoManager(doc, { mergeInterval: 0 });
+    const text = doc.getText("text");
+
+    text.insert(0, "Hello");
+    doc.commit();
+    text.insert(5, " World");
+    doc.commit();
+    expect(text.toString()).toBe("Hello World");
+    expect(undo.canUndo()).toBe(true);
+
+    undo.pause();
+    expect(undo.isPaused()).toBe(true);
+    doc.checkout([]);
+    expect(text.toString()).toBe("");
+    doc.attach();
+    expect(text.toString()).toBe("Hello World");
+    undo.resume();
+    expect(undo.isPaused()).toBe(false);
+
+    expect(undo.canUndo()).toBe(true);
+    expect(undo.undo()).toBe(true);
+    expect(text.toString()).toBe("Hello");
+    expect(undo.undo()).toBe(true);
+    expect(text.toString()).toBe("");
+
+    expect(undo.canRedo()).toBe(true);
+    expect(undo.redo()).toBe(true);
+    expect(text.toString()).toBe("Hello");
+  });
+
   test("round-trips compressed and uncompressed JSON updates", () => {
     const source = new LoroDoc();
     source.setPeerId(19);