oak-editor/crates/oak-node

oaknode Rust crate (implementation)

Status: all FFI headers implemented. Phase 1 (core engine: graph arena, values, keyframes, project, factory, ~55 FFI exports), Phase 2 (sequence/track/block/footage/colormanager + traverser + serializer, the folder/group/keyframe/dragger FFI families, the undo/XML bridges with test stubs, and the contract tests) and Phase 3 (the multicam grid family and the deferred bridge exports: markers/work-area/frame cache accessors, viewer params, sequence/footage stream params via the videoparams/audioparams C ABIs, and the colormanager compliant transform) are complete; cargo test --features test-stubs is green (84 tests, 1 ignored byte-exact golden). The remaining todo!()s are the concrete node-type behaviors under src/nodes/ (registered in the factory, bodies deferred) — the multicam node behavior and the effect/generator nodes. The crate template (FFI discipline, testing layers) follows crates/oakplugin/README.md.

Scope

Replaces the C++ oaknode module (src/node/src, ~40k lines): the node graph engine, project/folder/sequence/track/block hierarchy, footage, color manager, keyframes, evaluation (traverser), project serialization, and the undo bridge.

Public contract: include/node/*.h (14 headers, ~280 functions) — frozen, implemented verbatim by src/ffi.rs.

Key architectural decisions (C++ → Rust mapping)

1. Inheritance → arena + trait objects. The C++ design is deep inheritance (Node → ViewerOutput/Track/Block/… and ~50 effect nodes). Rust: a slab-allocated Graph arena of NodeEntry { core: NodeCore, behavior: Box<dyn NodeBehavior> }, addressed by generational NodeId. No reference cycles exist by construction (edges are IDs, not pointers).
2. Cross-module inheritance disappears. C++ RenderProcessor : NodeTraverser (render subclassing a node class) becomes a plain evaluation API: traverser::evaluate(...) -> NodeValueTable is a function, and oakrender supplies backend hooks via a trait (RenderHooks) instead of overriding virtuals.
3. Value system. olive::Variant/type-erasure becomes a closed NodeValue enum (value.rs). C ABI marshalling lives only in ffi.rs.
4. Undo. Commands are created through the oakundo C ABI (bridge::undo); the C++ UndoCommand subclass hierarchy becomes vtable commands whose userdata is a Rust closure.
5. Serialization. XML read/write goes through the oakcommon C ABI (bridge::common) until oakcommon itself is rewritten.
6. Threading. The C++ code relied on Qt's event thread + called_on_owner_thread() assertions. Rust replaces this with Mutex<Graph> interior mutability plus explicit &mut Graph phases for structural edits; the threading contract is documented per function.

Layout

COVERAGE.md maps every method of the C++ olive::Node (260 declaration lines, ~150 unique methods) to its Rust home — trait / core / graph / ops / bridge / drop-with-reason. Review that first.

src/
  lib.rs         crate doc + module map
  error.rs       error codes (mirrors include/node/error.h)
  handle.rs      refcounted-handle scaffolding (same pattern as plugin)
  value.rs       NodeValue / NodeValueTable / ValueHint
  id.rs          NodeId, generational arena ids
  node.rs        NodeCore + NodeBehavior trait (the virtual surface)
  graph.rs       Graph arena, edges, topological order
  input.rs       Input descriptors, flags, array inputs, hints
  keyframe.rs    NodeKeyframe + track interpolation
  project.rs     Project, settings, folder tree
  sequence.rs    Sequence (ViewerOutput equivalent)
  track.rs       Track, TrackList
  block.rs       Block/ClipBlock/GapBlock/TransitionBlock
  footage.rs     Footage (probe via oakcodec C ABI)
  colormanager.rs ColorManager (OCIO via oakrender C ABI for now)
  traverser.rs   Evaluation engine (iterative, hook-based)
  serializer.rs  XML project load/save (bridge::common)
  factory.rs     Node type registry (id -> constructor)
  nodes/         The concrete built-in node types
  bridge/        C ABI imports: common.rs, undo.rs, render.rs, codec.rs
  ffi.rs         include/node/*.h export layer
tests/           contract + golden tests (see README test section)

Hard rules for the implementer

1. Every extern "C" body goes through handle::guard*; no panic crosses FFI.
2. Graph is the only owner of nodes; the public API never hands out references into the arena, only NodeId-carrying handles.
3. Behavior parity with C++ is proven by the C ABI test-suite (src/node/tests, unchanged) plus the golden tests in tests/.
4. Where C++ behavior is genuinely load-bearing but ugly (e.g. Block length-change side effects on Track), port the behavior, not the aesthetics; leave a // CPP-PARITY: comment with the C++ file:line.

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.