cursive-multiplex

cursive-multiplex is a Rust crate that adds a tmux-style tiling window manager to applications built with the cursive terminal UI framework. Its Mux view lets developers nest any other cursive view inside resizable, focusable panes, arranging them side by side or stacked in complex split layouts, then add, remove, resize, and switch between them at runtime.

Under the hood, panes are organized as a binary tree built on the indextree arena crate, with each split node tracking orientation and split ratio. The crate ships configurable keybindings for pane navigation, resizing, and zooming, along with a path-based API for locating panes relative to one another, making it a drop-in building block for CLI dashboards, IDE-style terminal apps, and other multi-pane TUI tools.

What You Get

• A Mux view implementing cursive’s View trait, ready to embed as a fullscreen or nested layer
• Directional pane operations (add_right_of, add_below, add_left_of, add_above) for building split layouts around any existing pane
• Configurable default keybindings for focus movement, pane resizing, and zoom, all overridable via chainable with_*/set_* methods
• A Path API (mux.root().up().down().build()) for locating pane IDs relative to the tree instead of tracking raw indextree IDs manually
• A bounded focus-history buffer that remembers recent focus transitions for undo-style navigation

Common Use Cases

• Building tmux-like split-pane terminal dashboards that host independent cursive views for logs, status, and input side by side
• Adding an IDE-style layout to a cursive CLI tool, with a file browser pane, an editor pane, and an output pane
• Prototyping terminal multiplexer or window-manager behavior without writing raw ANSI cursor/pane math
• Embedding a zoomable focused-pane mode in a terminal dashboard, so a user can temporarily maximize one pane and return to the split layout

Under The Hood

Architecture cursive-multiplex organizes panes as a binary tree built on indextree::Arena, where each Node wraps an optional cursive View plus orientation and split-ratio state, and the root Mux struct implements cursive’s View trait by recursively descending that tree for draw, layout, and event dispatch (rec_draw / rec_layout in lib.rs) based on how many children a node has — zero (leaf pane), one (pass-through), or two (a split). Focus and resize navigation are handled separately in actions.rs via a search-then-traverse pattern that locates the correct sibling pane by walking up to a shared ancestor and back down through the tree, while path.rs exposes a chainable Path builder for resolving a pane’s Id without touching indextree internals directly, and id.rs owns the more delicate logic of detaching a removed node and promoting a sibling into its parent’s slot. The separation into dedicated actions/id/node/path/error modules keeps each concern isolated, though the core Mux struct itself still carries a large flat set of fields — ten separate keybinding Events plus focus/history state — rather than grouping configuration into a sub-struct.

Tech Stack Built for Rust 2018 edition and published to crates.io, the crate depends on cursive_core 0.4 rather than the full cursive package, keeping it backend-agnostic (works with any of cursive’s ncurses/pancurses/termion/crossterm backends); indextree 4.3 supplies the arena-based tree structure that underlies the whole pane hierarchy, thiserror 1 provides typed error enums (AddViewError, RemoveViewError, SwitchError, RenderError) instead of panics for the public API, and log 0.4 wires in optional debug tracing of focus and draw state. Dev-dependencies pull in the full cursive 0.21 framework plus crossbeam, serde_json, and the insta snapshot-testing crate for the example binaries and test suite — a minimal, terminal-UI-focused dependency surface with no async runtime or I/O dependencies of its own.

Code Quality Test coverage is comprehensive for a crate of this size: tests/end2end.rs (679 lines) and tests/geometric.rs (162 lines) exercise pane addition, removal, focus movement, and resizing end-to-end, backed by dozens of insta snapshot files under tests/snapshots that assert exact rendered pane geometry, and lib.rs additionally carries its own #[cfg(test)] unit test module covering removal, switching, zoom, and nesting. A GitHub Actions workflow (test_and_push.yml) runs the suite on every push per the stable/nightly build badges in the README. Error handling favors typed thiserror results at the public boundary, though internal tree-traversal code leans heavily on .unwrap() when navigating parent/sibling relationships, trusting tree invariants rather than defending against corruption. There’s no CONTRIBUTING doc or visible clippy/rustfmt config, but four runnable examples in examples/ double as informal usage documentation.

API Design The public API mirrors how a tmux user already thinks about panes: add_right_of, add_left_of, add_above, and add_below insert a new view directionally relative to an existing pane ID and return a Result<Id, AddViewError> for chaining, while a fluent Path builder (mux.root().up().left().build()) resolves a target pane without exposing indextree internals. Keybindings and the default split ratio are configurable through paired with_/set_ methods, so a caller can override behavior at construction or later, and getting started requires only Mux::new() followed by one add_right_of call. The tradeoff is that most operations surface as Option/Result the caller must handle explicitly, the crate readme itself flags the project as ‘work-in-progress’, and there’s no changelog to track breaking changes across versions.