Demo Showcase Overview
The ftui-demo-showcase crate is two things at once:
- A human-facing reference app that exercises every major subsystem —
run
cargo run -p ftui-demo-showcaseand explore. - The canonical snapshot-test target —
cargo test -p ftui-demo-showcasecompares the rendered frames against blessed baselines, andBLESS=1 cargo test -p ftui-demo-showcaseupdates them.
This page is the orientation for both uses. If you want to run the app, see quick run. If you want the exhaustive screen list, see screen catalog. If you want the snapshot workflow, see snapshot testing.
The showcase is the primary way to see what FrankenTUI does. The
harness examples (cargo run -p ftui-harness --example minimal) are
smaller and easier to read, but they only demonstrate one thing at a
time. The showcase demonstrates everything.
Why both a demo and a snapshot target
Most TUI projects ship a demo app and a separate test suite. That’s twice the work and twice the drift: the demo ages out of date, the tests don’t cover anything the human would actually look at, and a subtle rendering bug slips between the two.
The showcase collapses them. Every screen is:
- Interactive, so humans can drive it and feel the behavior.
- Snapshot-tested, so a blessed baseline captures the rendered frames at canonical tick counts and input fixtures.
- Deterministic, because design decisions
forbid hidden I/O inside
view().
A regression in any subsystem shows up as a diff in the blessed
snapshot. A visual improvement shows up as a diff too — the human
confirms it, runs BLESS=1, and commits the new baseline.
Mental model
Screen categories
There are 46 screens, grouped into ten categories. Each screen demonstrates one or more subsystems. The screen catalog has the exhaustive table; what follows is the shape.
| Category | Screens | What they show |
|---|---|---|
| Overview | dashboard, widget_gallery, advanced_features | Full-system demos with animated panels, sparklines, markdown streaming |
| Layout | layout_lab, layout_inspector, intrinsic_sizing, responsive_demo | Flex/Grid solvers, pane workspaces, constraint visualization |
| Text | shakespeare, markdown_rich_text, markdown_live_editor, advanced_text_editor | Rope editor, syntax highlighting, streaming markdown |
| Data | table_theme_gallery, data_viz, virtualized_search, log_search | Themed tables, charts, Fenwick-backed virtualization |
| Input | forms_input, form_validation, command_palette_lab, mouse_playground | Bayesian fuzzy search, gesture recognition, focus management |
| Visual FX | visual_effects, theme_studio, mermaid_showcase, mermaid_mega_showcase | Gray-Scott reaction-diffusion, metaballs, Clifford attractors, fractal zooms |
| System | terminal_capabilities, performance, performance_hud, determinism_lab | Capability probing, frame budgets, conformal risk gating |
| Diagnostics | explainability_cockpit, voi_overlay, snapshot_player, accessibility_panel | Evidence ledgers, VOI sampling visualization, a11y tree |
| Workflow | file_browser, kanban_board, async_tasks, notifications, drag_drop | File picker, task boards, notification toasts, drag handles |
| Advanced | inline_mode_story, hyperlink_playground, i18n_demo, macro_recorder, quake | Inline scrollback, OSC 8 links, locale switching, event recording |
| 3D / Code | 3d_data, code_explorer, widget_builder, action_timeline | 3D data views, AST browsing, widget composition, timeline aggregation |
How to navigate
Run the showcase and navigate with arrow keys / Enter / Escape:
cargo run -p ftui-demo-showcaseJump directly to a screen via env var:
FTUI_HARNESS_VIEW=dashboard cargo run -p ftui-demo-showcase
FTUI_HARNESS_VIEW=visual_effects cargo run -p ftui-demo-showcase
FTUI_HARNESS_VIEW=command_palette_lab cargo run -p ftui-demo-showcaseSee quick run for the full env-var
reference (mouse, focus, log redirection, auto-exit, etc.) and
screen catalog for every
FTUI_HARNESS_VIEW value.
How to snapshot-test
# Run the snapshot tests — fails if any screen diverges from baseline.
cargo test -p ftui-demo-showcase
# Update baselines after an intentional change.
BLESS=1 cargo test -p ftui-demo-showcase
# Review pending changes interactively.
cargo insta reviewSee snapshot testing for the full workflow including review, commit, and CI gating.
Determinism
Every screen in the showcase is expected to produce byte-identical output run-to-run under the deterministic fixture set:
E2E_DETERMINISTIC=1 E2E_SEED=42 ./scripts/demo_showcase_e2e.shIf you see a run-to-run diff that isn’t caused by a terminal-capability difference, it’s a determinism bug — file it.
Pitfalls
Don’t edit screens to be “less deterministic for realism”. The
screens are tests. If a visual effect needs randomness, seed it from
the frame index, not SystemTime::now(). The VFX effects screen is
the reference for deterministic randomness.
Don’t add new screens without a snapshot-test entry. Every screen is a test target. If you add a screen and don’t add a test, regressions in that subsystem won’t be caught.
Don’t assume the showcase covers every edge case. Snapshot tests
catch visual regressions at canonical tick counts; they don’t cover
every interactive path. For fuller coverage, add harness tests in
ftui-harness or integration tests in tests/.