oak-editor/crates/oak-undo

oakundo Rust crate

Status: implemented. Ports the C++ oakundo module (src/undo/src) to Rust. Template follows crates/oakplugin.

Scope

Replaces the C++ oakundo module (src/undo/src): undoable commands and the undo/redo history stack. The frozen C ABI (include/undo/*.h) and the engine facade that consumed it are gone (see the root Cargo.toml note on crates/oakengine.bk): every consumer links the crate as a plain rlib and uses the value-typed API below.

Architectural decisions

1. Trait-object commands replace the vtable pattern. In C++ other modules subclass olive::UndoCommand (redo()/undo() overrides) and plug themselves in polymorphically. Rust models the same polymorphism with a boxed [undocommand::Command] trait object: one-off edits arrive as closure commands ([undocommand::UndoCommand::from_closures]) and whole-struct commands implement the trait and are boxed with [undocommand::UndoCommand::new]; composites are [undocommand::MultiUndoCommand]. The former OakUndoCommandVtable callback table, its extern "C" trampolines and the refcounted CHandle layer were deleted with the C ABI — domain logic dispatches through the trait the same way C++ virtual dispatch does.
2. Modified-state callbacks are intentionally omitted. The C++ UndoCommand::redo_and_set_modified pair records/restores a project dirty flag via std::function accessors. The public headers exposed none of this; the stack drives state via done_ on the safe type instead, and the flag callbacks are left as a documented future extension.
3. UndoStack state machine is modeled directly on the C++: two deques — commands_ (done, oldest at front) and undone_commands_ (most-recently-undone at front); push clears any redoable tail, executes redo, and drops the oldest when the cap (200) is exceeded; jump clamps and walks via undo/redo. The fresh stack holds a single "New/Open Project" empty command so can_undo is false at the bottom (per undostack.cpp).
4. No merge semantics. src/undo/src/* defines no merge_with/can_merge; commands are never coalesced. Tests reflect this (no merge tests).

Layout

src/
  lib.rs            crate doc + module map
  error.rs          error codes (mirrors include/undo/error.h values)
  undocommand.rs    UndoCommand / Command trait / MultiUndoCommand
  undostack.rs      UndoStack + empty bottom command
  global.rs         process-wide stack, groups, observers
tests/              contract tests per module

The module has no unsafe code and no extern "C" surface; panics in command callbacks propagate as normal process-internal panics (the process-wide stack recovers a poisoned mutex the same way the former guard* FFI wrappers did).

Dependency policy

Prefer mature third-party crates (MIT/Apache-2.0/BSD, GPL-compatible) over hand-rolling; register each addition (name + reason) here. Large existing C++ libraries (OTIO, OCIO, OIIO, FFmpeg) are NEVER rewritten — they are consumed through their C ABI / bridge layers.