feat: v0.20.0 — features + perf + breaking + v0.19.x patch sweep

.github/workflows/ci.yml

@@ -38,7 +38,12 @@ jobs:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
-      - run: cargo test --all-features
+      # `--test-threads=1` is required because `tests/v020_perf_alloc.rs`
+      # uses a global allocation counter; CI's higher parallelism than a
+      # local laptop causes other parallel tests to contaminate the count
+      # and trip its single-thread budget. Single-threaded execution adds
+      # ~10s but keeps the perf-budget asserts meaningful.
+      - run: cargo test --all-features -- --test-threads=1
 
   clippy:
     name: Clippy

.github/workflows/release.yml

@@ -21,7 +21,10 @@ jobs:
           components: clippy, rustfmt
       - uses: Swatinem/rust-cache@v2
       - run: cargo check --all-features
-      - run: cargo test --all-features
+      # See ci.yml — perf-alloc tests use a global counter, so CI's higher
+      # parallelism contaminates measurements. Single-threaded keeps the
+      # budget asserts honest.
+      - run: cargo test --all-features -- --test-threads=1
       - run: cargo clippy --all-features -- -D warnings
       - run: cargo fmt -- --check
 

.gitignore

@@ -7,3 +7,4 @@ SESSION-SUMMARY.md
 assets/blackpink/
 CLAUDE.md
 .research/
+.claude/worktrees/

Cargo.toml

@@ -3,7 +3,7 @@ members = [".", "crates/slt-wasm"]
 
 [package]
 name = "superlighttui"
-version = "0.19.3"
+version = "0.20.0"
 edition = "2021"
 description = "Super Light TUI - A lightweight, ergonomic terminal UI library"
 license = "MIT"
@@ -15,6 +15,14 @@ keywords = ["tui", "terminal", "cli", "ui", "immediate-mode"]
 categories = ["command-line-interface"]
 rust-version = "1.81"
 exclude = ["examples/", ".github/", "assets/", "AUDIT-REPORT.md", "CLAUDE.md"]
+# Disable cargo's `examples/*.rs` auto-discovery: only the binaries listed
+# below as `[[example]]` are exposed via `cargo run --example`. Source
+# demos that compose into a tour (v020_*, cookbook_*, most demo_*,
+# anim, async_demo, inline, error_boundary_demo) stay in examples/ but
+# are reached only via `#[path = ...] mod` includes from the tour
+# binaries. See `docs/DEMO_GUIDE.md` for the archetype rules and the
+# v0.20 release notes for why these were merged into tours.
+autoexamples = false
 
 [lib]
 name = "slt"
@@ -50,6 +58,7 @@ tree-sitter-yaml = { version = "0.7", optional = true }
 criterion = { version = "0.5", features = ["html_reports"] }
 insta = "1"
 proptest = "1"
+serde_json = "1"
 
 [features]
 crossterm = ["dep:crossterm"]
@@ -97,90 +106,84 @@ full = ["crossterm", "async", "serde", "image", "qrcode", "kitty-compress"]
 all-features = true
 rustdoc-args = ["--cfg", "docsrs"]
 
-[[example]]
-name = "hello"
-path = "examples/hello.rs"
+# ── Tour binaries (6) — integrated demos covering v0.20 features and
+#    domain showcases. Each tour bundles 4–10 source demos via the
+#    DEMO_GUIDE.md archetype rules. Run these for end-to-end review.
 
 [[example]]
-name = "counter"
-path = "examples/counter.rs"
+name = "v020_tour"
+path = "examples/v020_tour.rs"
 
 [[example]]
-name = "demo"
-path = "examples/demo.rs"
+name = "cookbook_tour"
+path = "examples/cookbook_tour.rs"
 
 [[example]]
-name = "anim"
-path = "examples/anim.rs"
+name = "showcase_tour"
+path = "examples/showcase_tour.rs"
 
 [[example]]
-name = "inline"
-path = "examples/inline.rs"
+name = "canvas_tour"
+path = "examples/canvas_tour.rs"
 
 [[example]]
-name = "async_demo"
-path = "examples/async_demo.rs"
-required-features = ["async"]
+name = "text_tour"
+path = "examples/text_tour.rs"
 
 [[example]]
-name = "demo_dashboard"
-path = "examples/demo_dashboard.rs"
+name = "system_tour"
+path = "examples/system_tour.rs"
+required-features = ["async"]
 
-[[example]]
-name = "demo_cli"
-path = "examples/demo_cli.rs"
+# ── Standalone — entry / how-to-start (3)
 
 [[example]]
-name = "demo_spreadsheet"
-path = "examples/demo_spreadsheet.rs"
+name = "hello"
+path = "examples/hello.rs"
 
 [[example]]
-name = "demo_website"
-path = "examples/demo_website.rs"
+name = "counter"
+path = "examples/counter.rs"
 
 [[example]]
-name = "demo_infoviz"
-path = "examples/demo_infoviz.rs"
+name = "demo"
+path = "examples/demo.rs"
 
-[[example]]
-name = "cookbook_dashboard"
-path = "examples/cookbook_dashboard.rs"
+# ── Standalone — performance measurement (2)
 
 [[example]]
-name = "cookbook_file_picker"
-path = "examples/cookbook_file_picker.rs"
+name = "perf_interactive"
+path = "examples/perf_interactive.rs"
 
 [[example]]
-name = "cookbook_login"
-path = "examples/cookbook_login.rs"
+name = "perf_regression"
+path = "examples/perf_regression.rs"
 
-[[example]]
-name = "cookbook_modal_toast"
-path = "examples/cookbook_modal_toast.rs"
+# ── Standalone — development tools (3)
 
 [[example]]
-name = "cookbook_table"
-path = "examples/cookbook_table.rs"
+name = "debug_selection"
+path = "examples/debug_selection.rs"
 
 [[example]]
-name = "demo_fire"
-path = "examples/demo_fire.rs"
+name = "test_mouse"
+path = "examples/test_mouse.rs"
 
 [[example]]
-name = "demo_game"
-path = "examples/demo_game.rs"
+name = "demo_key_test"
+path = "examples/demo_key_test.rs"
 
-[[example]]
-name = "demo_kitty_image"
-path = "examples/demo_kitty_image.rs"
+# ── v0.20 non-interactive reports (2) — kept standalone because they
+#    print to stdout rather than render a TUI, so they don't compose
+#    into v020_tour.
 
 [[example]]
-name = "demo_cjk"
-path = "examples/demo_cjk.rs"
+name = "v020_perf_audit"
+path = "examples/v020_perf_audit.rs"
 
 [[example]]
-name = "demo_overlay_anchor"
-path = "examples/demo_overlay_anchor.rs"
+name = "v020_test_utils"
+path = "examples/v020_test_utils.rs"
 
 [[bench]]
 name = "benchmarks"

README.md

@@ -134,7 +134,7 @@ The same closure runs across several entry points. Pick one based on UI shape, n
 
 ```toml
 [dependencies]
-superlighttui = { version = "0.19", features = ["async", "image"] }
+superlighttui = { version = "0.20", features = ["async", "image"] }
 ```
 
 | Feature | What it adds |
@@ -258,6 +258,7 @@ For composition advice, see [Patterns Guide].
 | [Animation Guide] | Tween, spring, keyframes, sequence, stagger |
 | [Theming Guide] | Theme struct, presets, ThemeBuilder, custom themes |
 | [Design Principles] | API constraints and design philosophy |
+| [API Design] | Five consistency rules for new widgets and PR review checklist |
 
 ## Representative Examples
 
@@ -276,6 +277,46 @@ For composition advice, see [Patterns Guide].
 
 The full categorized index lives in [Examples Guide].
 
+### v0.20 Demo Catalog
+
+Run any v020 demo directly:
+
+| Demo | Issue | Showcases |
+|---|---|---|
+| `v020_showcase` | (integration) | All v0.20 features on one screen |
+| `v020_regression_panel` | (integration) | v0.19 + v0.20 cumulative regression check |
+| `v020_dx_shortcuts` | #209/#210/#220/#221 | on_hover, animate_bool, fill, center_in |
+| `v020_use_state_keyed` | #215 | Dynamic-string-keyed state |
+| `v020_use_effect` | #216 | Dependency-tracked effects |
+| `v020_named_focus` | #217 | register_focusable_named, focus_by_name |
+| `v020_theme_subtree` | #226 | Per-subtree theme override |
+| `v020_modal_trap` | #225 | Modal tab_trap focus containment |
+| `v020_spacing_scale` | #227 | compact / comfortable / spacious presets |
+| `v020_split_pane` | #223 | split_pane / vsplit_pane with drag handle |
+| `v020_gauge` | #224 | gauge / line_gauge builder APIs |
+| `v020_gutter_highlights` | #235 | scrollable_with_gutter, GutterOpts |
+| `v020_breadcrumb_response` | #213 | Builder breadcrumb API |
+| `v020_progress_response` | #212 | progress / spinner returning Response |
+| `v020_static_log` | #233 | ui.static_log() append-only scrollback |
+| `v020_keymap_help` | #236 | WidgetKeyHelp + auto help overlay |
+| `v020_ctrl_c_passthrough` | #238 | RunConfig::handle_ctrl_c opt-out |
+| `v020_widthspec` | #237 | WidthSpec / HeightSpec sampler |
+| `v020_perf_audit` | #204/205/206/228 | Allocation + timing report (stdout) |
+| `v020_test_utils` | #229–232 | record_frames / sequence / snapshot_format / negative asserts (stdout) |
+
+Or use the launcher script:
+
+```bash
+# Interactive picker
+./scripts/ghostty_demos.sh
+
+# All v0.20 demos at once (each in its own Ghostty window)
+./scripts/ghostty_demos.sh --features
+
+# Just the integration demos
+./scripts/ghostty_demos.sh --showcase
+```
+
 ## Custom Widgets And Backends
 
 - Implement `Widget` when you want reusable high-level building blocks.
@@ -316,6 +357,7 @@ The release process expects format, check, clippy, tests, examples, and backend
 [Patterns Guide]: docs/PATTERNS.md
 [Architecture Guide]: docs/ARCHITECTURE.md
 [Design Principles]: docs/DESIGN_PRINCIPLES.md
+[API Design]: docs/API_DESIGN.md
 [Animation Guide]: docs/ANIMATION.md
 [Theming Guide]: docs/THEMING.md
 [Features Guide]: docs/FEATURES.md

_typos.toml

@@ -9,6 +9,11 @@
 "Pn" = "Pn"
 "flate" = "flate"
 "flate2" = "flate2"
+# Intentional truncation-test prefixes used in tests/widgets.rs to verify
+# label-clipping behaviour. They look like typos because they ARE bare
+# truncations — that's the point of the assertions.
+"Pytho" = "Pytho"
+"Memor" = "Memor"
 
 [files]
 extend-exclude = [

benches/benchmarks.rs

@@ -394,7 +394,7 @@ fn bench_flush_full_redraw_200x60(c: &mut Criterion) {
     let mut group = c.benchmark_group("flush");
     group.bench_function("full_redraw_200x60", |b| {
         let area = Rect::new(0, 0, 200, 60);
-        let prev = Buffer::empty(area);
+        let mut prev = Buffer::empty(area);
         let mut curr = Buffer::empty(area);
         fill_realistic(&mut curr, 1);
         // Sanity: make sure we actually have a non-trivial diff workload.
@@ -403,10 +403,13 @@ fn bench_flush_full_redraw_200x60(c: &mut Criterion) {
         let mut sink: Vec<u8> = Vec::with_capacity(256 * 1024);
         b.iter(|| {
             sink.clear();
-            slt::__bench_flush_buffer_diff(
+            // Issue #171: use the mutable bench entry point so the per-row
+            // hash refresh is part of the measured cost (matches what
+            // `Terminal::flush` does in production).
+            slt::__bench_flush_buffer_diff_mut(
                 &mut sink,
-                black_box(&curr),
-                black_box(&prev),
+                black_box(&mut curr),
+                black_box(&mut prev),
                 ColorDepth::TrueColor,
             )
             .expect("flush into Vec<u8> cannot fail");
@@ -437,10 +440,45 @@ fn bench_flush_sparse_change_200x60(c: &mut Criterion) {
         let mut sink: Vec<u8> = Vec::with_capacity(64 * 1024);
         b.iter(|| {
             sink.clear();
-            slt::__bench_flush_buffer_diff(
+            slt::__bench_flush_buffer_diff_mut(
+                &mut sink,
+                black_box(&mut curr),
+                black_box(&mut prev),
+                ColorDepth::TrueColor,
+            )
+            .expect("flush into Vec<u8> cannot fail");
+            black_box(sink.len());
+        });
+    });
+    group.finish();
+}
+
+/// 0%-dirty (static) flush baseline for issue #171's GO/NO-GO decision.
+///
+/// Two identical buffers — `flush_buffer_diff` walks every cell, finds no
+/// difference, and emits nothing. This is the worst case for the per-cell
+/// scan because every cell pays the comparison cost while no output is
+/// produced. If this bench stays under 50 µs on 200×60 we do **not**
+/// implement the per-row hash skip (issue #171 NO-GO).
+#[cfg(feature = "crossterm")]
+fn bench_flush_static_200x60(c: &mut Criterion) {
+    let mut group = c.benchmark_group("flush");
+    group.bench_function("static_200x60", |b| {
+        let area = Rect::new(0, 0, 200, 60);
+        let mut prev = Buffer::empty(area);
+        let mut curr = Buffer::empty(area);
+        fill_realistic(&mut prev, 1);
+        fill_realistic(&mut curr, 1);
+        // Sanity: 0% dirty — diff must be empty.
+        debug_assert!(curr.diff(&prev).is_empty());
+
+        let mut sink: Vec<u8> = Vec::with_capacity(1024);
+        b.iter(|| {
+            sink.clear();
+            slt::__bench_flush_buffer_diff_mut(
                 &mut sink,
-                black_box(&curr),
-                black_box(&prev),
+                black_box(&mut curr),
+                black_box(&mut prev),
                 ColorDepth::TrueColor,
             )
             .expect("flush into Vec<u8> cannot fail");
@@ -458,6 +496,7 @@ fn bench_flush_group(c: &mut Criterion) {
     {
         bench_flush_full_redraw_200x60(c);
         bench_flush_sparse_change_200x60(c);
+        bench_flush_static_200x60(c);
     }
     let _ = c;
 }