intuiTUIve: what the demos are missing¶

Status: working list, updated after each round.

We rebuild well-known ratatui apps on intuiTUIve to learn what the framework lacks. Each clone is built only from intuiTUIve's own components, from its core or its plugins: no framework changes during the round, and no custom widget in the example to stand in for a missing one. What the clone needs and cannot get goes on this list. Gaps chosen from it are added to the framework, the clones are rebuilt on them, and we repeat until each clone uses intuiTUIve components only. Then we pick more apps.

Each round also looks beyond what the clone strictly needs. Whoever builds a clone reports, under Components that would help, the components that would make it shorter or more faithful: the ones the original app leans on, and the ones comparable libraries (ratatui and its crates, Bubble Tea and Bubbles, Textual) offer. Each entry gives what it would replace, an API sketch, core or plugin, and how much it would help.

A whole-framework comparison with Textual, widget by widget, with its gaps filed as issues, is in the Textual parity audit.

Where a gap belongs:

• core: rs-rich-intuituive itself (layout, widgets, keys, popups);
• plugin: a crate or feature beside it (rs-rich-ext's charts, rs-rich-ratatui, or a new one).

Core components are generic. A core component must be reusable by other components: no domain types, names or parameters (no paths, files, samples, sound cards, or one app's or one data source's shapes). Anything only one domain could use is a plugin: an off-by-default feature module (files, pcm/audio, watch, art) or another crate. Where a domain component has a generic shape underneath, the generic part goes in core and the plugin builds on it: files::miller is the core's miller_of over a directory tree, files::tasks the core's jobs running file operations, files::finder the core's finder_of over a walk, files::preview the core's preview_of keyed by a path, and files::path_crumb the core's breadcrumb over a path's parts.

This is a gate, not a preference. A proposal for core that is not generic is not accepted into core: it is reshaped as a generic core piece plus a plugin built on it, or kept as a plugin. So every gap report and every Components that would help entry that proposes a domain component must also propose the generic core shape under it (or say why there is none, and mark it plugin). The tables below predate the rule where they name a domain shape as core; such an entry is read as its generic shape.

Round 1: Yazi and scope-tui¶

The clones are examples/files.rs (Yazi, the file manager) and examples/scope.rs (scope-tui 0.3.5, the oscilloscope). How each compares with its original is in the porting guide.

Keys and input¶

Lists and tables¶

Layout, popups and chrome¶

Charts¶

Data, sources and the outside world¶

Bugs found¶

Round 2: scope-tui¶

The round-1 gaps were added (PR #752) and the clones rebuilt on them, with no framework changes during the round.

scope¶

examples/scope.rs now uses no workaround from round 1. Checked side by side with scope-tui 0.3.5 (built with app,file) on the same PCM file at 80x24, 100x32 and 160x45: the header's cells start in the same columns and are cut the same way at every size, the vectorscope's reference lines break where the trace crosses them as ratatui's do, and the legend box matches. What still differs is deliberate and listed in the porting guide.

Round-1 gaps now closed¶

Also from the round-1 work: the hand-written ? modal is replaced by the framework's help (cx.help()), fed by .bind(keys, description, ..).

New gaps and bugs¶

No bugs were found in the round-1 additions themselves.

Friction with the new APIs¶

• Two shapes for "the newest value from elsewhere". latest gives Signal<Option<T>> (None before the first), audio::input a Signal<Matrix> that starts as empty rows. The example needs a match per source to take a buffer. One shape (Option) for both would let a source be one value.
• dsp::spectrum stops at the Nyquist frequency. scope-tui plots every bin, the mirrored half too, so the example uses fft and magnitude instead. Fine as it is; a spectrum_full would only save three lines.
• legend_style("") reads as "no style" only once you know it; ratatui's legend takes the chart's own style. A Chart::style(..) that the legend takes by default would say it directly.
• style_from_color_name lives in rs-rich-ratatui, which brings ratatui-core. Fine for the example (a dev-dependency); an app that only wants to read ratatui's colour names on its command line pays for the conversions too. It could sit in rs-rich-ext with rs-rich-ratatui re-exporting it.
• Solver::Ratatui and cell were drop-in. No friction: the header is shorter than round 1's and exact.
• Frames per second count frames drawn. latest drops what the app had no time for, as intended; with a debug build at 80x24 the example shows 19–20 fps where scope-tui shows 21–22, because scope-tui counts every buffer it reads.

Components that would help¶

Patterns written by hand from several built-ins, components from other ecosystems an audio or visualisation app would use, and plugins that would make the clone more capable. Value is for this kind of app.

Round 2: files (Yazi)¶

examples/files.rs rebuilt on what round 1's gaps added (PR #752). It uses intuiTUIve's own components and plugins only, with no framework change in the round. Built with default features it follows the disk only through what it does itself and describes images; the crate's watch and art features (which CI's tapes job now builds the examples with) add the watcher and image previews. Local times come from rs-rich-ext's local-time feature, turned on for the examples and tests through a dev-dependency, so files needs no required-features.

Round-1 gaps now closed, and where files.rs uses them¶

Kept on purpose: the empty-list end of visual mode, the trash never moved into itself, and tab clicks going through switch_tab (all tested).

New gaps and bugs¶

Friction with the new APIs¶

• bind vs bind_sequence: in bind("k up", ..) a space separates alternatives, in bind_sequence("g g", ..) keys pressed in turn. Easy to mix up when moving a binding between the two tables; a sequence with one key silently becomes a bind. A "g>g" or ["g", "g"] form would read unambiguously.
• The comma: "\",\" s" for ,s is hard to read; "comma s" would be kinder.
• Pop-up title styles: popup.title styles every pop-up's title, but Yazi's confirm titles are blue and its input titles plain. Prompts set .title_style("default") by hand; cx.confirm cannot take a style.
• selected_style_for was not needed for Yazi's coloured bar: row_style plus a reverse highlight already gives it. Its doc example suggests it for that case; it earns its keep only for a different look per row (the preview's underline here could equally be theme_styles).
• rule() joins the border only with no padding between it and the panel, so the help pads its field and list one by one instead of the column; a rule().inset(..) or padding that rules ignore would help.
• popup_at with Origin::At(rect) puts the box below the rect and then clamps it on screen; at 80 columns an 80-wide rename box slides to the left edge, away from the row (Yazi does the same, but a w: Size::Percent or "shrink before moving" option would keep it under the row).
• notify has no width or wrap control: the 48-cell box wraps a one-line error at 80 columns.
• list_lazy's closures re-read the same memos for len, item, trailing, marker and row_style; a list_of(memo, |entry, i| Row { text, trailing, marker, style }) would read the data once per row.

Components that would help¶

Round 2's gaps in the core: widgets, pop-ups and the clock¶

The core items of round 2 above, and those the plugin work (files, audio, charts) asked for, were added; the clones are rebuilt on them in the next round.

New gaps and bugs¶

Components that would help¶

Round 3: files (Yazi)¶

examples/files.rs rebuilt on round 3's additions: the files plugin (intuituive::files, rs-rich-ext's listing, open, file_ops, trash, git, archive) and the core's bars, tabs and dialogs. No framework change in the round. It went from 2,756 lines to 1,450: what is left is Yazi's keymap, what each key does, tabs, the selection and visual mode, the help and the spotter. It now needs the crate's files feature (required-features = ["files"], so a default build and --all-targets skip it); archive, watch and art add to it, and CI's tapes job builds it with all four.

A rule from this round on: a core entry below names a component that another, unrelated component could reuse, with nothing about files, paths or Yazi in its name or parameters. What is about files is a plugin entry (the files feature); where a file component has a generic shape underneath, both are proposed: the generic core piece and the plugin built on it.

Round-2 gaps now closed, and where files.rs uses them¶

Newly faithful, and tested: the system's trash; file jobs in the background and a task manager; quitting asks while tasks run; git signs; type colours sniffed from content; archive listings and extraction; the finder's streaming walk; 50-wide prompts; Yazi's confirm sizes; a click in the parent column goes into that directory (Yazi's cd; round 2 went to the parent, hovering it, and its test now says so). One assertion changed for the worse: a binary file previews as a hex dump, not Yazi's file classification (below).

Not used, on purpose: key_hints (Yazi has no footer), notify_width (the default fits Yazi's errors at 80 columns), Miller::navigation (see friction).

New gaps and bugs¶

Friction with the new APIs¶

• Miller::navigation's descriptions are its own ("Move up", "Go to the top"), not Yazi's ("Previous file"), and its key set is fixed (no shift+pageup). The help and the which-key pop-up show descriptions, so the example binds the moves itself with m.arrow, m.page, …. A table form (navigation_with(&[(Move::Up, "k up", "Previous file")])) would let a clone keep its wording.
• Two ways to reach a column: Miller's lists are built inside view_with, so anything not in MillerOptions (an on_mouse, list options, a name) has to go on the whole view. Every option a clone needs has to be added to MillerOptions by hand; a MillerOptions::current(|list| list.option(..)) hook would end that.
• Which signals are public is uneven: cwd, cursor, find, preview_top are fields, current.filter is a field of a field, row_rects() and column_rect() are methods, remembered a lookup, the preview cursor private. A clone reads all of them; one style (all methods returning signals) would be easier to find.
• Tasks report twice: a failed job stays in tasks_panel and the app notifies too, so the title shows twice ("Move src to src: src: can't go inside itself"). An option for the panel's line without the title, or Tasks::on_fail(|job, cx| ..) app-wide, would replace the done closure each call repeats.
• files::preview does not use the core's resource_for / stale_after that round 3 added for it: it keeps its own generation counter and a spawned sleep. The first-frame bug above would be one fix in one place if it did.
• required-features for an example that a test includes by path: tests/files.rs needs #![cfg(feature = "files")] by hand; without it a default cargo test fails to compile the test, not skips it.

Components that would help¶

Round 3: scope-tui¶

examples/scope.rs rebuilt on what round 2's gaps added (the audio plugin rounded out, rs-rich-ext's dsp generators and chart options, and the core's clock, key and bar components), with no framework change in the round and no hand-made stand-in left in the example. Its hand-rolled test signal, PCM reader, Frame numbering, trigger search, note table, 29 reference datasets, polled fps counter and the 24 modifier bindings are gone; it is 1,323 lines where round 2's was 1,340, while doing more of what scope-tui does (audio --timeout, audio --list's configurations, PulseAudio's sources and --server-buffer). tests/scope.rs counts frames exactly on the app's clock and checks the new behaviour (24 tests; 25 with audio).

Round-2 gaps now closed, and where scope.rs uses them¶

Not used, on purpose: live (scope-tui draws every buffer it reads, with no cap), audio::wav/record, audio::picker, meter, sparkline, big_text, Spectrogram, status_bar and key_hints: scope-tui has none of them, and extras are added only where scope-tui has them.

New gaps and bugs¶

Friction with the new APIs¶

• One on_write arm per kind of source. latest_every and latest give Signal<Option<Matrix>>, a capture Signal<Option<Frame>>, so the example writes the same on_write + rate three times. With on_write seeing every write, Frame::number is no longer needed to count; a generic latest_iter(iter, pace) (below) and an audio source enum would make a source one value again.
• on_write clones each value (here a 2×2048 matrix per buffer, which take then clones again into the history). A borrowing on_write_ref(signal, |&T, cx| ..) would save both.
• dsp::note_hz is not scope-tui's table. It is equal temperament with octave 4 by default; scope-tui doubles octave-0 pitches rounded to the hundredth and defaults to octave 0. The example adds the 0; about one note in ten (E2, F1, B1, … at 48 kHz) gives a buffer one sample off. More correct, less faithful; a test pins E2.
• Axis::grid styles with Axis::style, the axis line's style too. scope-tui's axes have no lines, so it fits here; an app with a styled axis and fainter grid lines would want Axis::grid_style.
• Chart::style("none") reads well once known; "none" as a magic string is easy to miss next to "".
• bind_scaled's help prints alt ×0.2, where scope-tui's docs say ⅕; fine, but a label per variant (("alt", 0.2, "⅕")) would let an app say it its way.
• audio::open made App::try_new unnecessary. Opening before the app is the cleaner shape; try_new stays for builders that only fail inside.
• Driver::advance's 50 ms step is documented, but nothing says a latest thread is not a "thing due" (see the first bug); the latest_every doc example steps driver.update by hand, which hides it. Round 2's "19–20 fps where scope-tui shows 21–22" was put down to a debug build; it is this cap.
• The help cuts long rows. bind_scaled appends (shift ×10, ctrl ×5, alt ×0.2), 30 cells, and the help box (75 wide at 110 columns) cuts a row rather than wrapping it, so PgUp's description had to shrink to "threshold or avg up".

Components that would help¶

Patterns written by hand from several built-ins, what scope-tui leans on, and what comparable audio and visualisation TUIs and libraries offer (cava, ratatui and its crates, Bubble Tea and Bubbles, Textual). Core entries are generic: another, unrelated component could use them.

Round 4: files (Yazi)¶

examples/files.rs rebuilt on round 4's additions: the runtime's settled layouts, the core's tab_set, history, multi_select, list_search, cursor_by, on_context, seg_gauge, facts, fuzzy_list, tabs(..).fit() and help_with, and the files plugin's tabs, selection, Yank, find_next, hovered_caps, BinaryPreview::FileType, open_with_tasks, Tasks::on_fail and summary, frecency, finder_with, spot, bulk_rename, shell and search. No framework change in the round. It went from 1,449 lines to 1,198 while gaining Yazi's search (s, S, Ctrl+S), shell (;, :), bulk rename (r on a selection), a frecency Z kept between sessions, per-tab history and a progress gauge: what is left is Yazi's keymap as a table, what each key does, the create and rename prompts, the opener choice, the confirms, the header and the status line's segments. Its tests went from 766 lines to 992 (36 tests to 47). The example still needs files only (required-features = ["files"]); the tape's keys did not change, so it was not re-recorded.

Round-3 gaps now closed, and where files.rs uses them¶

Newly faithful, and tested: per-tab history; file's classification of binaries; the cursor kept through a sort or a filter; find as you type staying on a hovered match; Ctrl+A, Ctrl+R and V; a selection yanked; s/S search listings that Esc ends; ; and :; bulk rename; frecency-ranked Z across sessions; Yazi's help in Vim key notation; fitted tab titles; a progress gauge shown while tasks run, red once one fails.

Not used, on purpose: bind_when and when (Yazi's manager keymap is the same in every state: visual mode, a search and one tab all keep it; a binding hidden while it does nothing would leave Yazi's help); the MillerOptions::current/parent/preview hooks (nothing needed past MillerOptions); Miller::visited() (frecency().follow(m) already sees every directory, and lasts the session where there is no state directory); Miller::navigation and the core's navigation_with (see the gaps: unreachable from files::Miller).

New gaps and bugs¶

Friction with the new APIs¶

• Prompts repeat their look. Yazi's inputs have plain titles; each prompt_with takes input_look(), and ShellOptions::prompt has to be given it again. An app-wide default (App::prompt_defaults(PromptOptions)) would let a clone set it once. Core.
• The menu from the keyboard needs row_rects. on_context says "then below the hovered row" but leaves it to the app: menu matches cx.pointer() and row_rects().get(cursor) to choose between context_menu and open_menu. A context_menu_at(cx, fallback_rect), or an on_context that passes the item's rect, would do it.
• selection and Yank mark in two ways. The selection is drawn by the columns because selection(m) stores itself in the Miller (made before view_with, or it is not marked); the yank is a MillerOptions::markers closure. Either way works, but the order dependence is silent: selection after view_with marks nothing.
• Visual mode before an action. Miller::targets() counts a visual range but does not end it, so every action calls end_visual() first (Fm::targets), as Yazi ends visual mode on y, x, d.
• The parent column's marks are re-derived by path inside files::Miller because selection_markers reads the visual range by index of the current column; the files agent's "marks by key" (a MultiSelect::mark(&key) marker any list showing the same keys can use, no cursor) would make that one call.
• files::Miller's state is still half fields, half methods (m.cwd, m.find, m.current.filter but m.searching(), m.visited(), m.row_rects()); the core Miller moved to methods in round 4, the plugin did not.
• tests/files.rs still needs #![cfg(feature = "files")] by hand for an example it includes by path.

Components that would help¶

Round 4: scope-tui¶

examples/scope.rs rebuilt on round 4's runtime, widgets and sound pieces, with no framework change in the round and no hand-made stand-in left in the example. Its hand-checked in_mode handlers, the page dispatcher, ten flag closures, the clamped debounce steps, the quoted punctuation keys, the hand-paced file thread, the per-channel VecDeque history and the equal-temperament tune are gone; it is 1,274 lines where round 3's was 1,323, and more faithful: each scope's keys apply, and are listed, only while it shows (p is peaks in one and the phase difference in another), --tune picks scope-tui's buffer sizes sample for sample, and the frame rate is the buffers' rate, as scope-tui's (-b 2048 23 fps, -b 1024 47, -b 4096 12, on the app's clock and in a terminal). tests/scope.rs (853 lines, was 741) runs on the app's clock with no hand stepping and checks the new behaviour (29 tests; 30 with audio).

Round-3 gaps now closed, and where scope.rs uses them¶

Not used, on purpose, as in round 3: live, audio::record/wav, audio::picker, the viz plugin's meter, sparkline, hold, spectrogram and bar_spectrum, chart::Persistence, digits, dsp::peak_hz/nearest_note, smoothed, status_bar and key_hints: scope-tui has none of them. Not reproduced, also on purpose: scope-tui 0.3.5's file source reads buffer × channels bytes a buffer, half a buffer of s16 frames a channel (its trace fills half the width), and paces -l by whole milliseconds of that; and its spectroscope keeps its averaging history only while it shows. The clone reads a whole buffer a channel at its time, and averages the last buffers shown in any scope.

New gaps and bugs¶

Friction with the new APIs¶

• A field picker kept in a variable does not compile. let average = |s: &mut Spectroscope| &mut s.average; passed to two bind_steps fails with "lifetime may not live long enough": a closure's return does not take its argument's lifetime. The clone writes fn depth and fn average. A field!(Spectroscope, average) macro, or the docs saying "use a fn", would save the detour.
• A name for a memo and a field picker clash quietly. average the memo and average the fn gave a type error naming Memo<usize>; not the API's fault, but recent(signal, n) taking a closure (|| spec.with(..)) as a Count would make the memo unnecessary.
• Empty descriptions hide bindings. "" is still the way to keep a binding out of the help, as "none" was for the legend's style; Textual's Binding(show=False) names it: .hidden().
• modes wants &dyn Fn(Node) -> Node. The pages are closures kept in variables (oscilloscope_keys), which reads well; the type (ModePage) only shows when inference fails.
• One key, two scopes, one handler each. scope-tui hands a key to the app and then to the scope showing (Esc resets the view and stops the trigger); a binding's key runs one handler, so the oscilloscope's Esc calls the shared reset itself and the general Esc is bind_when(mode != Oscilloscope). Fine, but a "fall through" binding (.and_then_parent(), Bubble Tea's message passed on) would say it directly.
• Headings in the help have no hook for tests. A test finds a section by │name at the box's edge, since a description may hold the same word ("oscilloscope, vectorscope, spectroscope").
• Capture::simulated for a demo signal. It fits (a source with a status, the same arm as a sound card), but its name says tests; a Capture::generated(iter, period) alias, or the one source type below, would read better.

Components that would help¶

What scope-tui leans on, what the sound and chart work left open, and what comparable audio and visualisation TUIs and libraries offer (cava, ratatui and its crates, Bubble Tea and Bubbles, Textual). Core entries are generic: another, unrelated component could use them.

Plugins¶

The user's decision for this round: visualisation and recording are plugins, not core. The viz feature is the home of the views of sound and signal data: meter, sparkline, the peak hold (PeakHold, hold), the spectrogram and the bar spectrum, and later persistence and an oscilloscope view. The wav feature is the home of recording (audio::record, wav_writer). The core keeps only what any app could use under them: recent, smoothed, latest_with_state, latest_iter, digits, rate.

Round 5: nine new apps¶

Round 5 cloned apps unlike a file manager and an audio scope, each built on intuiTUIve as round 4 left it (no framework change during the round), each with its own report in docs/design/gaps/:

None draws a widget of its own except the game's playfield and the raycaster's 3D view. The round-5 core and plugin work (below the round-4 sections' backlog) landed alongside; the clones do not use it yet.

Gaps shared across apps¶

What several clones hit independently leads round 6. Each is generic core unless marked.

Bugs found: keys typed while the terminal ignores the start-up query are lost for up to 3 s (blocks); tables and lists treat Shift+↑/↓ as ↑/↓ (top); an .auto() switch ignores its page's .fixed()/.min_size() (top); Driver::event does not settle as press does (top); a full-size layer paints over a fill beneath it (blocks); upstream's Text.markup is not ported (csv); the app loop handles one input event per frame, so queued keys spread out over slow frames: drain pending input before drawing (raycast); rs-rich-ext's Screen style table and the painter's code cache only grow, so a full-screen truecolour framebuffer leaks styles every frame, and interning hashes with SipHash (33 of 41 ms a frame at 160x50): compact styles between frames, a fast hash and a put_rgb path (sprites, raycast).

Sprites landed during the round (Sprite, stage, pixels/PixelBuf, sprite sheets behind art, micro assets behind micro); blocks and raycast use them from round 6.

Real Doom (rs-rich-doom)¶

rs-rich-doom (GPL-2.0, a separate repo: the engine is GPL) runs doomgeneric on an intuiTUIve latest thread and draws its 320x200 frames in half blocks, Braille, Kitty, Sixel or iTerm2 at 33–35 fps (release, 80x24 and 160x50), with sound effects through cpal. What it needed from rs-rich, beyond the raycaster's list:

Round 7: the nine apps rebuilt on round 6¶

Each clone was rebuilt on round 6's components, without library edits. Each report in gaps/ has a "Round 2" section with the details.

blocks grew by 40 lines. Its model is unchanged; the extra lines are the repeat rates and the sprite builder.

Bugs found¶

Each has a minimal failing test in its report. All four are fixed in 0.0.21 (2a36216), their tests in crates/rich-intuituive/tests/round7_bugs.rs, the workarounds gone.

Performance¶

view_of made csv's million-row filter slower: 3.3 s → 15.4 s in the unoptimised test build. About 8 s goes on reading each row through TableSource::row(i), and about 7 s on building a Text per row for the regex. Needed:

• a bulk read for passes;
• a compiled matcher on &str in rs-rich-ext.

Both are in 0.0.21 (ee8c474): TableSource::rows and rich_ext::transform::Pattern; the filter takes 3.8 s.

Gaps shared across apps¶