0.0.4 development plan¶
Status: implementation complete; source prepared for 0.0.4. Diagnostics (#62), GIF rendering (#65), CSV/wrapping (#74) and opt-in syntax parsing reuse (#45) are included with independent reviews, tests and actual CLI evidence. See release preparation for results, package decisions and publication gates. This is not a publication notice. Track release runs separately from development progress.
The reproducible development baseline records the pre-change measurements and performance targets.
Goal and scope¶
Make large inputs cheaper to render, improve the remaining input diagnostics, and add explicit GIF half-block rendering. Preserve default upstream behavior, per-crate versioning, redirected-output safety and the existing release path.
| Order | Work | Deliverable and acceptance |
|---|---|---|
| 0 | Baseline and scope audit; supports #35 | Reproduce the remaining cases on current main. Record release-build timings, peak RSS, output hashes and environment before optimizing. Reconcile historical issue text with the 0.0.3 closeout. |
| 1 | #62 — diagnostics | Clean image-extension punctuation and lead with one actionable image hint. Reproduce BOM/headerless UTF-16 separately and specify an upstream-compatible diagnostic or explicit encoding option before changing decoding. |
| 2 | #65 — GIF blocks | Add an explicit half-block rendering path through rich-art and the CLI, with a documented capability/fallback matrix and real playback evidence. |
| 3 | #74 — CSV memory and wrapping | Reduce retained data/allocations while preserving measured column widths, Unicode wrapping, output and early-pipe exit behavior. Treat CSV and long-line wrapping as separate PRs under the same issue. |
| 4 | #45 — syntax performance | Profile startup, parsing/highlighting, style conversion and output allocation; optimize the measured dominant costs without dropping grammars or changing rendering semantics. |
The performance baseline is a prerequisite for orders 3 and 4. Diagnostics and GIF work can proceed independently once their input/output contracts are agreed. Do not close a grouped issue until all its remaining acceptance cases are met; split deferred portions into explicit follow-ups instead.
Implementation boundaries¶
Diagnostics. Keep the default UTF-8 replacement behavior until the pinned
upstream behavior has been checked. Do not silently auto-detect encodings or
turn previously accepted text into errors. Treat headerless UTF-16 detection as
heuristic; avoid false-positive warnings on arbitrary binary or valid UTF-8 data.
If encoding support is needed beyond diagnostics, design it as explicit extension
behavior and document the option, supported encodings and error policy first.
Put new encoding support in rich-ext, with CLI wiring and policy at the input
boundary, rather than changing the faithful core's default decoding behavior.
GIFs. Implement rendering in rich-art; keep CLI policy at the CLI boundary.
Prototype an explicit selector before committing its spelling. Preserve current
ASCII behavior for existing invocations and keep image-diff options compatible.
Define behavior for truecolor/limited-color terminals, NO_COLOR, redirected
stdout, --loop 0, finite loops and interruption. Redirected output must still
emit one frame and no cursor/animation controls. Sixel and other new graphics
protocols are outside this scope. Update unsupported-option validation alongside
any newly supported options.
CSV and wrapping. Global column measurement conflicts with one-pass streaming. Evaluate two-pass reading for seekable files and temporary spooling for stdin before considering an API or layout change. Preserve dialect/header inference, quoted multiline fields, row order and width allocation. Measure undecorated, decorated, aligned, paged and exported paths separately. Any spooling design must handle disk errors, cleanup and early consumer exit. Optimize wrapping against ASCII, CJK, combining marks and grapheme clusters without changing parity.
Syntax. The current implementation already caches syntax/theme sets with
OnceLock within a process; do not assume a missing cache is the diagnosis.
Measure cold CLI startup separately from repeated library rendering. Retain the
documented syntect/Pygments divergence; check layout and surrounding text against
the pinned upstream oracle and highlighted output against the pre-change Rust
baseline. New default behavior does not belong in the faithful core.
Measurement and verification¶
Use one host and toolchain, optimized builds, fixed terminal dimensions and an explicit color environment. Record fixture hashes, exact commands, warmup policy, at least five measured runs, median/range, output size and peak RSS. Separate process startup from in-process throughput. Choose numerical improvement targets from the reproduced baseline before implementation; do not adopt historical issue timings as current measurements or make unsupported speed guarantees.
| Area | Required cases |
|---|---|
| Diagnostics | Files, stdin and supported URL input; misleading extensions, actual images, malformed UTF-8, UTF-8 BOM, UTF-16 with/without BOM; stderr ordering, unchanged stdout and exit codes where applicable. |
| GIFs | Truecolor and limited/no-color output, PTY versus pipe, odd frame heights, transparency/disposal, finite/infinite repeats, interruption and first-frame-only redirection. |
| CSV | 10k/50k/100k-row fixtures; files and stdin; quoted multiline records; narrow/wide terminals; plain/decorated/aligned/paged/exported output; broken pipes. Record memory growth instead of claiming constant memory without evidence. |
| Wrapping/syntax | Short files, roughly 46 KB and 199 KB source fixtures, progressively larger single lines and mixed Unicode. Use timeouts for pathological inputs and preserve output hashes or reviewed parity fixtures. |
Every implementation PR includes focused regression tests and the normal CI gate: formatting, Clippy, workspace tests, feature matrix, declared MSRV, native Windows coverage and pinned Python Rich goldens. Keep the Rich library oracle separate from the rich-cli oracle. Do not silently update fixtures to accept different behavior. Add minimized regressions for newly discovered defects.
Attach actual CLI screenshots to both the PR and chat. For GIFs, include a short playback recording or sequential real captures as well as a still. Performance claims need raw measurements alongside screenshots. Preserve original terminal output and exports, exact reproduction commands and commit-pinned evidence links. Require independent sub-agent review and address findings before merge.
Delivery, documentation and versions¶
Use small PRs: baseline, diagnostics, GIF rendering, CSV memory, wrapping and
syntax optimization. Land planning separately from implementation. Each code PR
updates applicable CLI help/reference, tutorials, troubleshooting, known issues,
benchmarks and the docs site. Build MkDocs with --strict; verify the live pages
and image links after docs deployment. Add changelog entries under Unreleased
with affected crate names. Close issues using demonstrated acceptance results.
| Package | Prepared version and reason |
|---|---|
| rs-rich-cli | 0.0.4: input diagnostics, GIF selection and CSV changes. |
| rs-rich-art | 0.0.4: GIF half-block rendering and updated core dependency. |
| rs-rich | 0.0.4: CSV ownership extension point, wrapping optimization and optional syntax cache. |
| rs-rich-ext | 0.0.4: explicit decoding and updated core dependency. |
All four change for their own code and dependency requirements. Internal caret
requirements and the lockfile move with these independently owned versions;
this does not impose a lockstep version policy. Once the integrated source and
packages pass all gates, the coordinated v0.0.4 scope selects all four.
Preparation creates neither a tag nor an upload, and does not alter 0.0.3.
Before shipping, rerun package dry runs and clean-consumer verification through the protected release workflow. Use annotated tags on the verified main commit. Keep verification-only recovery distinct from uploads, and never blindly rerun a partially published release.
Outside this release¶
Theme-stack/progress/legacy-console expansions, a new syntax engine, terminal graphics protocols, default escape sanitization (#64), and broad differential fuzzing (#34) remain separate projects. Targeted parity tests and useful benchmark additions are included, but do not imply completion of the broader #15/#35 infrastructure issues. Review dependency-update PRs separately against the feature and MSRV gates; do not bundle unrelated upgrades into performance changes.