clankerdiff-ratatui

Ratatui adapters for syntax highlighting, Markdown parsing, diff previews, and review widgets.

Streaming Markdown

Keep a MarkdownStream, StreamingMarkdownState, and SyntaxHighlighter per logical rendering context. Append only new source bytes, then call MarkdownRenderer::render_stream_layout. The returned MarkdownLayout shares row handles; state.update_since(last_revision) supplies the suffix to replace. Apply its first_changed_row, replacement, and reset fields together, then retain its revision. A missed revision returns a replacement sufficient to reconstruct the current live content.

The default StreamingMarkdownPolicy::Reflowable matches a fresh render of the current source. For native terminal scrollback, construct the state with StreamingMarkdownPolicy::Terminal:

1. Render and apply the row update.
2. Write the chosen leading rows to native history through the host's terminal writer.
3. Only after that write succeeds, call state.commit_rows(revision, end_exclusive) with an absolute layout row index. Do not count host-added padding or separators as Markdown rows.
4. On write failure, leave those rows uncommitted and retry through the host's writer.

Commits are monotonic and validate the layout revision and range. Committed rows retain their handles, source metadata, text, and styles. Resize and theme changes affect only the uncommitted suffix; checkpoints retain partial-row and tab-expansion progress. Later delimiters or reference definitions may intentionally make terminal history differ from a new full-document render. One-shot equality is not a promise that arbitrary Markdown or incomplete syntax has an eternally stable prefix.

Call stream.finish() and render its final update before sealing an item. Preserve the terminal state rather than replacing it with a one-shot render. state.reset() clears rendering caches, not acknowledged history. Replacing or switching a source after a commit returns MarkdownStreamError::CommittedSourceReplaced; create a separate item/state for replacement content.

Use MarkdownRows and row updates on the hot path. materialize() and render_stream_lines() are convenience boundaries for hosts that require flat arrays, not a requirement for streaming. take_stats() exposes parser, highlighter, and row work. blocks_visited counts semantic blocks visited during layout, targets_visited counts target-map entries inspected or updated, chunks_visited counts rendered/cached line chunks visited, and row_store_updates counts individual row insertions and persistent range splice/truncate operations. A range operation shares its prefix and costs logarithmic tree work; the counter does not claim to count the persistent collection's internal node copies. rows_reused describes logical output reuse, not rows traversed. source_bytes_copied counts explicit source retention and synthetic reference-prefix/tail copies (not allocator reallocations or semantic-node allocations); prefix_bytes_copied identifies the reference-prefix portion. These counters supplement actual parser input bytes rather than substituting appended bytes for parsing work.

Completed blocks and committed rows use persistent row storage. In Rendered presentation, ordinary appends visit changed blocks and code lines rather than rebuilding the completed prefix. SourceLines retains cached rows but may still traverse source-line prefixes; the rendered transcript's prefix-work bounds do not apply to that alternate presentation. Continuous structural tails, including long paragraphs, lists, quotes, and nested fences, may still require reparsing their entire unsettled block for CommonMark correctness. Their actual work is counted; the concrete prose/top-level-fence workload budgets are not a universal linear-time guarantee for arbitrary Markdown.

The upstream just package-check recipe packages and verifies the seven portable libraries together, then runs tests/consumer-fixture from a temporary directory against a temporary registry of those exact archives. It does not publish or read sibling application sources. Archive checksums, file lists, resolved versions, and the consumer lockfile are saved under target/package-check. Temporary registry patches are used only for this pre-publication check; just published-consumer-check runs the same fixture against the versions in the workspace manifests with crates.io dependencies only and no patches. Run that gate after the release workflow publishes the coordinated versions.

Run cargo run -p clankerdiff-ratatui --example terminal_markdown for a complete host-side write/acknowledgement example, including a failed write, revision validation, completion, and late reference resolution. streaming_markdown demonstrates reflowable rendering; chat_embedding and the review examples show library embedding without a second application event loop.