feat(undo): per-container UndoScope for UndoManager

[edochi]

Summary

Adds an opt-in UndoScope to UndoManager so a manager can be restricted to a set of containers. Ctrl+Z then reverts only edits within that scope, even when a single commit touched containers both inside and outside it. The default is UndoScope::Doc, which is bit-for-bit today's behavior, so the change is purely additive and every existing undo test passes unchanged. Closes #981.

let undo = UndoManager::new(&doc).with_scope(UndoScope::containers([text_a.id()]));
// undo.undo() now reverts only text_a's local edits

Motivation

The use case is a collaborative multi-file workspace held in a single LoroDoc: a LoroTree of file nodes, each file's content a LoroText. We want per-file undo on that unified doc. Today the only per-scope knob is add_exclude_origin_prefix, so per-file undo requires N UndoManager instances cross-excluded by origin string, which is O(N²) to register, can't handle a commit that touches two files at once, relies on set_next_commit_origin carrying through into the reverse op undo() emits internally, and pushes the same boilerplate onto every consumer. UndoScope::Containers reads as a generalization of add_exclude_origin_prefix: same record-time filter path, keyed on ContainerID membership instead of an origin-string prefix.

Design

Two filter points, mirroring how undo already works. At record time, an out-of-scope local commit is not pushed onto the undo stack; it's routed through the same compose_remote_event path that handles real remote peers, so cursor transforms still apply and counter bookkeeping advances cleanly. The scope check is inlined so the optimizer folds the Doc arm to a constant, leaving the default path to pay only a discriminant load. At replay time, a new undo_internal_with_scope masks the computed DiffBatch to in-scope containers before _apply_diff, walking container_remap to mirror its own remap chain; if a commit touched A, B, C and only A is in scope, only A is reverted. That replay-time mask is what makes mixed commits correct, and it has no equivalent in the origin-filter approach. The old undo_internal stays as a thin #[inline] wrapper delegating with scope_filter: None, so no existing caller changes.

pub enum UndoScope {
    Doc,                                  // #[default], current behavior
    Containers(FxHashSet<ContainerID>),
}
impl UndoScope {
    pub fn containers<I: IntoIterator<Item = ContainerID>>(ids: I) -> Self;
}
impl UndoManager {
    pub fn set_scope(&self, scope: UndoScope);
    pub fn with_scope(self, scope: UndoScope) -> Self;  // builder
}

Tests

9 new integration tests in crates/loro-internal/tests/undo.rs (16 total, all passing): default-is-doc-wide regression guard; out-of-scope exclusion and redo symmetry; out-of-scope edits not corrupting the in-scope stack; mixed-commit undo and redo (impossible with the origin workaround); chained mixed commits; three-container scope sets; and scope changed after construction.

Benchmarks

crates/loro-internal/benches/undo.rs (criterion, 1000 commits/iter, n=50), main vs this branch:

Path	main	this branch	Δ/commit
no_manager (baseline)	2.32 µs	2.26 µs	within noise
default_scope (existing hot path)	3.54 µs	3.59 µs	+45 ns (~1.3%)
scoped_one_container (new opt-in)	n/a	3.58 µs	≈ default-scope
replay per undo+redo	5.17 ms	5.15 ms	within noise

The default-path regression is ~45 ns/commit; the opt-in scoped path is indistinguishable from default-scope, and the replay-time mask is free relative to the surrounding checkout-and-diff cost.

Compatibility

Purely additive; UndoScope::Doc is the default and preserves current behavior. Fits a minor bump.

[zxch3n]

Thanks for this PR — the motivation is spot-on (per-file undo on a unified doc is exactly what #981 asks for), and the writeup, tests, and benchmarks are appreciated. The default-Doc path being bit-for-bit unchanged is verified and great.

That said, I have to request changes: the scope predicate currently exists in two places with different semantics, and neither interacts correctly with container_remap or nested containers. This leads to silent data loss in a few scenarios:

1. Remap direction: the replay-time mask walks a diff cid forward through container_remap and tests the final (freshly generated) cid against the user's original-id scope set. So once an undo recreates a scoped container (T → T'), later diffs keyed by T resolve to T', which is never in the scope set — the entry is masked and the undo becomes a silent no-op. The record-time filter has the opposite gap: it checks raw event cids with no remap at all, so new edits to the recreated container (events carry T') are classified out-of-scope and become permanently un-undoable.
2. Nested containers: matching is exact-id only. Scoping a parent map/list tracks nothing when edits land in nested children (their events carry the child's cid). And on redo, a recreated container's child-content diffs are masked out, so the child comes back empty — data loss across a plain undo/redo round-trip within the scoped manager.
3. Ordering vs before_diff: the mask is applied after crate::undo::undo has already run before_diff with the unmasked diff, so the stacks' stored remote DiffBatches (and cursors) get rebased by out-of-scope deltas that are never applied to the doc — positions drift with each scoped undo of a mixed commit.
4. When the mask empties a popped item's diff, perform() treats it as a no-op and cascades into undoing the next older item in the same call, silently destroying stack entries.

I think all of these trace back to one fix: a single shared UndoScope::matches(cid, remap) used by both the record-time filter and the replay-time mask, which accepts any id along the remap chain, plus an explicit decision on whether scope should cover descendants (I'd argue yes — scoping a subtree is the natural mental model for your multi-file use case, and ContainerDiff.path already carries the ancestor chain). The masking should also happen before before_diff fires so the stack transforms see exactly what gets applied.

A few smaller notes, none blocking on their own:

• An out-of-scope local commit advances next_counter past itself, so the counter gap defeats push_with_merge's contiguity check and silently splits an open undo group (or merge-interval window) into multiple undo steps.
• The scope-set snapshot (lock + full FxHashSet clone) sits inside perform's per-span retry loop but is loop-invariant; and the in_scope remap walk clones per hop and runs twice per cid via the two parallel retain calls. A DiffBatch::retain helper would fix both and keep the order/cid_to_events sync invariant inside the type.
• New public set_scope/with_scope on crates/loro could use a couple of wrapper-layer tests in crates/loro/tests/integration_test/undo_test.rs (like #1053 did for pause/resume).

Happy to discuss the descendant-semantics question on #981 first if you'd prefer — it's the one real design decision here. The JS/WASM surface can be a follow-up PR once the Rust semantics settle.