Skip to content

0.0.11 plan — developer ergonomics and core usability

Status: in progress. The maintainer started it on 2026-09-23 and directed that everything unfinished from 0.0.10 lands here. It tracks milestone 2.

Goal: Make rs-rich the crate a Rust CLI author reaches for first. That means errors, logs, clap help, structured data and test output rendered well with little code. Close the parity divergences the 0.0.10 fuzzer found first, so the new surface sits on a core that matches upstream.

Why this theme: 0.0.10 finished the visible core gaps (Progress, theme stack) and proved the differential harness. Milestone 2 collects what Rust users ask for that Python rich cannot give them directly: type-driven rendering, compile-time checked markup, and integrations with clap, tracing, anyhow and thiserror. All of it builds on core through public APIs, so almost none of it touches the faithful mirror.

Carried over from 0.0.10

Moved to milestone 2 on 2026-09-23:

Issue What remains
#6 Progress RenderableColumn, Live-driven Progress (auto-refresh, track()), the pulse bar
#9 Markdown Inline styling inside table cells
#34 Differential fuzzing Keep the nightly run green once #442–#449 are fixed; add Tree/Columns generators
#126 Image transforms Alpha and checkerboard background modes
#144 Art in the CLI Route the remaining art modes and adjustments through first-class CLI workflows
#498 (new) #125 remainder: Atkinson dithering, perceptual distance, Braille/Sixel/GIF colour modes
#499 (new) --theme-file for upstream theme files (#3 follow-on)

146, #149, #151, #199 and the #198 tracker were delivered in 0.0.10 and closed.

Workstreams

Each workstream lands as its own pull request (or a short stack), with evidence in the PR and an entry under Delivered. Placement follows AGENTS.md: upstream behaviour lives in core, new renderables live in rich-ext, and CLI commands only compose them.

1. Core parity fixes (#442–#449, #34) — core

Fix the eight divergence families the differential fuzzer found against rich 15.0.0:

  • 442 Padding with empty content, and content style

  • 443 Align of the rendered block (Constrain + Segment.set_shape)

  • 444 right-aligned Rule with a multi-character fill

  • 445 Table header alignment and empty-header styling

  • 446 printed Text drops overflow, no_wrap and justify, as upstream's Text.join does

  • 447 full justify with tabs

  • 448 emoji matching across a consumed colon

  • 449 zero-width Panel body rows

Acceptance: - Each repro from the issue becomes a corpus case, and a golden where it is deterministic. - diff_rich.py --corpus matches rich 15.0.0 on all of them. - Existing goldens stay byte-identical, unless the fix is the golden's own subject. - The nightly 20,000-case run is green, or files new issues.

2. Core carry-over ports (#6, #9, #10) — core, then ext

  • 6: RenderableColumn (the ProgressColumn model gains renderable cells),

    Live-driven auto-refresh, track() over iterators, and the pulse bar with upstream's frame arithmetic. Goldens use the injected clock.

  • 9: table cells hold styled Text, so Markdown tables keep inline emphasis, code

    and links. Goldens against rich 15.0.0.

  • 10: a RichHandler-style log sink (upstream logging.py, _log_render.py) on

    top of the 0.0.9 log and tracing adapters.

3. Diagnostics and error adapters (#210, #386, #387, #239, #212, #329) — ext

  • A first-class Diagnostic renderable with severity, code, primary and secondary spans, labels, notes, help and suggestions. It extends the 0.0.10 Diagnostic::from_error.
  • Feature-gated anyhow and thiserror adapters that map chains and sources.
  • Semantic OSC 8 hyperlinks for paths, path:line:col and frames, with a plain fallback.
  • A stack-trace normaliser for Rust panics and backtraces. Python, Java and JS traces are pluggable adapters.
  • A grouped diagnostics dashboard (#329).

4. Structured data and serde rendering (#37, #211, #384, #394–#400, #402) — ext, then CLI

  • A serde-backed object explorer (Serialize to a tree or table, with depth and length limits), plus zero-boilerplate helpers (print_json, print_table, tree views).
  • YAML, TOML, XML, INI and dotenv renderers and inspectors.
  • Flatten and unflatten views, path/value search, and a pluggable selection-expression abstraction whose parser backends are optional.
  • CLI: rich inspect, and stdin format detection with explicit override and a plain fallback (#402).

5. Macros and derive (#36, #280–#285, #385) — new rs-rich-macros crate plus ext

  • #[derive(Rich)] and table derive attributes.
  • richf!, with compile-time checked markup, style names and theme keys.
  • Checked format templates, rich_dbg!, rich_eprintln! and rich_trace!.
  • Convenience macros (rich_table!, rich_panel!, rich_tree!).

A proc-macro must be its own crate, so this adds rs-rich-macros 0.0.1, re-exported from rich-ext behind a macros feature. Generated code uses public APIs only.

6. clap and CLI authoring (#38, #407, #403, #408, #409, #413) — ext behind a clap feature

  • Help, usage and errors rendered through rich, with grouped options, examples and env/config hints.
  • Shell completions with rich metadata.
  • Markdown and man-page generation.
  • A config-reference renderer and a precedence visualiser. The CLI eats its own dog food: rich --help and rich config explain.

7. Tracing and logging polish (#286, #285) — ext

  • A polished tracing layer with span trees, fields, source links and Live-safe output. It extends the 0.0.9 adapter.

8. Diff, snapshot and test tooling (#208, #217, #223, #236, #237, #306, #308–#313, #225, #230)

  • A common diff engine: unified and side-by-side views for text, ANSI and render snapshots, and syntax-aware source diffs.
  • assert_rich_eq! helpers (in ext's testing feature).
  • Git diff and test-result renderers (JUnit XML, cargo test JSON).
  • Tooling:
  • multi-width screenshot tests
  • layout stress tests
  • render linting
  • "explain" traces
  • a render profiler
  • deterministic render fuzzing
  • a compatibility-matrix runner
  • benchmark capture and comparison
  • CLI: rich diff.

9. Capabilities and accessibility (#209, #218, #229, #422, #307, #219)

  • A reusable terminal-capability API that rich doctor consumes, with deterministic overrides.
  • Graceful degradation levels.
  • Accessible semantic text, render-target policies (reduced motion, monochrome, screen reader) and a theme contrast checker.
  • rich ansi explain.

10. Workflow renderables (#388–#393, #259, #429, #425–#427, #224)

  • Command execution and nested task trees.
  • Transfer progress helpers, built on the #6 work.
  • Retry countdowns, transient notifications and completion summaries.
  • Streaming tables, table sort and group, and semantic formatters, badges and size bars.
  • Redaction transforms, applied before export.

11. CLI viewers (#401, #410, #411, #412, #424)

  • rich view, a universal pager that uses workstream 4's detection.
  • Hex, Unicode and env/PATH inspectors.
  • rich capture -- <cmd> with SVG, HTML and recording export.

12. Art and CLI carry-over (#126, #144, #498, #499)

  • Alpha and checkerboard backgrounds.
  • Atkinson dithering, perceptual distance and the remaining colour modes.
  • --theme-file.

16 (the roadmap epic) is tracking only.

Order of work

  1. Workstream 1 first. It is small, verifiable against the oracle, and every later renderer sits on it. It is the only planned core change besides workstream 2.
  2. Workstream 2 (#6, #9) in core, then #10.
  3. Workstreams 3 and 5 together: diagnostics and macros share source-span types.
  4. Workstreams 4 and 6: structured data, then clap, which reuses the renderers.
  5. Workstreams 8 and 9: the diff engine and capability API are shared foundations for 10 and 11.
  6. Workstreams 7, 10, 11 and 12 in any order.
  7. Release test, as in 0.0.10.

Milestone 2 is roughly eight times the size of 0.0.10. If it has to ship in slices, cut after step 4 as 0.0.11 and move the rest to a point release. Record that cut here.

Decision (2026-09-23): the maintainer chose to keep the full milestone. There is no cut: every workstream ships in 0.0.11.

Decisions (defaults, open to the maintainer)

  • New crate rs-rich-macros for proc-macros. A proc-macro cannot live in ext. It starts at its own 0.0.1.
  • Optional dependencies stay feature-gated in ext:
  • clap
  • anyhow and thiserror (adapters only)
  • serde (already present for testing)
  • toml (already a CLI dependency)
  • a maintained YAML crate (serde_yml or saphyr, not the deprecated serde_yaml)
  • quick-xml

A default build of rs-rich gains no dependencies. - No rs-rich-assert crate for now. The assertion helpers live in ext's testing feature. They split out only if dev-dependency weight becomes a complaint.

Package impact

Package Proposed Reason
rs-rich 0.0.7 Parity fixes (#442–#449), #6 remainder, #9 table cells
rs-rich-ext 0.0.9 Core pin, plus diagnostics, serde, clap, diff, capability and workflow renderables
rs-rich-art 0.0.9 Core pin; alpha/checkerboard, Atkinson, perceptual distance
rs-rich-cli 0.0.11 Pins; inspect, diff, view, capture, ansi explain, --theme-file
rs-rich-macros 0.0.1 (new) Derive and checked-markup macros

Publication order: core, then macros, then ext and art, then CLI. Push one tag at a time and wait for each release run; see the 0.0.10 tag-order incident.

Delivered

Workstream Pull request Merged as
1. Core parity fixes (#442–#449), with the cohort version bump #497 7c75447
2. Markdown styled table cells and constructor options (#9) #501 0f9cbc0
2. Progress pulse, format columns, live display and track() (#6) #502 b4cb2e2
2. LogRender port, RichHandler, JSON float repr (#10) #503 e4a91ef
2. Progress grid, expand, column options, transient, disable, file reading (#6) #504 0bc8b2c
3. Diagnostics, hyperlinks, stack traces, dashboard, error adapters (#210, #212, #239, #329, #386, #387) #505 dd63a5c
5. rs-rich-macros 0.0.1: checked markup, derive, print and convenience macros (#36, #280–#285, #385) #505 dd63a5c
4. Structured data, serde helpers, rich inspect, --format (#37, #211, #384, #394–#400, #402) (this PR)
6. CLI authoring: help, errors, completions, docs, config reference and precedence, clap (#38, #403, #407–#409, #413) (this PR)

Review focus

  1. Parity fixes change only the divergent cases: the full golden suite and the differential corpus stay green.
  2. No new dependency reaches a default build of rs-rich. Check cargo tree -e normal for core.
  3. Macros expand to public APIs only and produce readable compile errors (trybuild tests).
  4. Every renderer has a plain, non-colour fallback and deterministic tests.