Streaming markdown
Markdown that renders correctly while it streams: held-back partial markers, open code fences that grow, tables that wait for whole rows, a caret, and stop or error states.
oxyn add streaming-markdownrsx! {
StreamingMarkdown {
text: reply,
elapsed_ms: now - started,
first_token_ms: 600,
on_cite: move |n: u32| sources.highlight(n),
}
}Rendered from Rust at build time · goes live when visible
When to use
- Agent answers are documents: headings, lists, tables, math, and above all code the user will copy, run or apply.
- While streaming, the renderer must never flash raw syntax, never reflow what the user is reading, and never hand the user a half-written code block as if it were done (copy disabled until the fence closes; Run and Apply only on complete blocks).
- Every product renders markdown with copy buttons (note 04: "Markdown/code/table rendering w/ copy — All"); the differentiators are the code block's actions — Conductor's Run button on bash snippets with inline output, Claude desktop's "Fix this one / Apply fixes", ChatGPT code blocks with Preview (notes 03, 04, 08) — and the streaming Discipline Codex and MonoCode document in source (mutable tail, per-block repair; note 08).
- A code block explicitly says to use a separate text-stream component for code still arriving (note 12): we make that one component with two phases instead.
When not to use
- Streamed text arriving: use Text Reveal instead.
- Feedback on a reply: use Response feedback instead.
- Cited sources under an answer: use Source cards instead.
Installation
Streaming markdown is free and MIT. The oxyn CLI copies its code, and the components it needs, into src/oxyn/ of your Dioxus or GPUI project, so it is yours to change.
cargo install --git https://github.com/ismailqureshi72/Oxyn oxyn-cli
oxyn init
oxyn add streaming-markdownuse crate::oxyn::{StreamingMarkdown, Markdown, STATUS_INDICATOR_CSS};Rather depend on the crate? cargo add oxyn-dioxus oxyn-core --git https://github.com/ismailqureshi72/Oxyn, then use oxyn_dioxus::{StreamingMarkdown, Markdown, STATUS_INDICATOR_CSS};
Usage
rsx! {
StreamingMarkdown {
text: reply,
elapsed_ms: now - started,
first_token_ms: 600,
on_cite: move |n: u32| sources.highlight(n),
}
}Examples
Streaming
Headings, lists, code, a table and citations arriving.
Code
rsx! {
StreamingMarkdown {
text: reply,
elapsed_ms: now - started,
first_token_ms: 600,
on_cite: move |n: u32| sources.highlight(n),
}
}Stopped
Stopped mid-reply: what arrived stays.
Code
rsx! {
StreamingMarkdown {
text: reply,
elapsed_ms: now - started,
phase: "stopped",
first_token_ms: 600,
on_cite: move |n: u32| sources.highlight(n),
}
}Error
Connection dropped with Retry.
Code
rsx! {
StreamingMarkdown {
text: reply,
elapsed_ms: now - started,
phase: "error",
first_token_ms: 600,
on_cite: move |n: u32| sources.highlight(n),
}
}Instant
Everything at once (Oxyn plus).
Code
rsx! {
StreamingMarkdown {
text: reply,
elapsed_ms: now - started,
first_token_ms: 600,
on_cite: move |n: u32| sources.highlight(n),
}
}API reference
StreamingMarkdown
| Prop | Type | Default | Description |
|---|---|---|---|
textrequired | String | — | Full text the model will send. |
elapsed_ms | u64 | u64::MAX | Milliseconds since the stream started. |
cps | f32 | 140.0 | Characters per second (0 = instant). |
first_token_ms | u64 | Default::default() | Delay before the first token (waiting shimmer). |
phase | String | "streaming" | `streaming` · `stopped` · `error` (stops at what arrived). |
caret | bool | true | Show the caret. |
reveal | String | "fade" | `fade` · `none`. |
active_cite | Option<u32> | Default::default() | Highlighted citation. |
on_cite | EventHandler<u32> | — | A citation chip was pressed. |
Markdown
| Prop | Type | Default | Description |
|---|---|---|---|
textrequired | String | — | Source. |
caret | bool | Default::default() | Streaming caret at the end. |
active_cite | Option<u32> | Default::default() | Highlighted citation. |
on_cite | EventHandler<u32> | — | A citation chip was pressed. |
Read from the Rust signature and doc comments.
Keyboard interactions
| Key | Action |
|---|---|
| Tab | Citation chips, links, code copy |
Accessibility
- The container is aria-busy while streaming; the caret is aria-hidden.
- Partial markers (**, `, [1) are held back so screen readers never hear them.
- Citation chips are buttons named “Source n”.
From the spec
- Rendered markdown uses real semantics: headings are headings (levels offset by the host so an answer's
#is not the page's h1 — proposed default offset +2), lists are lists, tables have header cells and a caption ("Table, 84 rows, 5 columns"), task-list checkboxes are read-only checkboxes. - Code block: a
region/grouplabelled "Rust code, 312 lines" (Arc labels its block "hello.ts source code", note 12); thepreis focusable for keyboard scrolling; Copy "Copy code" → "Copied"; Wrap is a toggle button (aria-pressed); Show all hasaria-expanded+aria-controls; Run "Run snippet" / "Stop snippet"; Apply "Apply to auth.rs". - Streaming:
aria-busy="true"on the message while open; code blocks inStreamingexpose "Code block, writing" and their actions as disabled with the reason as description. - Announcements (polite, composer live region): "Snippet finished, exit 0" / "Snippet failed, exit 1" (assertive), "Applied to auth.rs, 12 additions, 3 deletions", "Apply conflict" (assertive).
- Contrast: syntax themes are checked so every token colour ≥ 4.5:1 on the code background in both themes (Codex corrects pale custom theme colours automatically, note 08 — we apply the same contrast floor at token load); inline code background ≥ 3:1 is not required, text contrast is.
- Math: exposes its LaTeX source as the accessible name until a MathML path exists on that platform.
- Diagrams: the source code is the accessible alternative ("Diagram, flowchart. Show source").
- Reduced motion: §5 last row.
- Keyboard: inside a focused code block, ⌘/Ctrl+C with no selection copies the whole block (proposed);
wtoggles wrap when the block is focused (proposed, listed in the ? help).
Motion & interaction
- Fence opens: code chrome (header + 1-line body) fades in 120 ms; the block reserves 1 line, then grows per committed line (line-commit 80 ms fade, text-reveal §4). No per-token effects in code.
- Language label: "…" → "rust" crossfade 120 ms when the info string completes.
- Streaming window: at 40 lines the block stops growing; the header line count rolls (
dur.digit.roll); a 24 px top fade mask indicates hidden earlier lines. - Complete: final highlight pass applies; actions fade in 120 ms (stagger 30 ms); copy icon enables (opacity 40 % → 100 %). If the block was windowed it collapses to 20 lines (200 ms, anchored).
- Copy: copy ✓ morph (message-bubble §4 timings: 160 ms, hold 1500 ms); label "Copy" → "Copied" rolls (Arc rolls its toggle labels, note 12).
- Wrap toggle: lines re-wrap without animation (animating re-wrap is unreadable); the toggle icon swaps; the scroll position inside the block keeps the first visible line.
- Show all / Collapse: height spring (
dur.collapse), chevron rotates 180°, label rolls. - Run: ▶ → ■ morph (160 ms
spring.snap, same as send control); output panel unfolds (200 ms); exit chip enters withdur.row.enter; success ✓ holds then rests; failure tone fades 200 ms, no shake. - Apply: button → 12 px loader → ✓ "Applied +12 −3" (diff numbers roll); Undo stays 10 s with a shrinking 2 px underline as its timer (proposed).
- Diagram render: code view crossfades to the diagram (200 ms); height change anchored.
- Table: column widths that grow while streaming animate with
spring.snap160 ms (text-reveal); "Show all rows" unfolds 200 ms.
Timing
| Transition | Duration | Delay | Easing / spring | Stagger | Frame rate |
|---|---|---|---|---|---|
| Code chrome enter | 120 ms | 0 | ease.out | — | 60 Hz |
| Line commit (code) | 80 ms fade | — | linear | — | 30 Hz (text-reveal) |
| Tail-line re-highlight | ≤ 1 per 100 ms | — | none (instant colour) | — | — |
| Language label swap | 120 ms | on info-string end | ease.out | — | 60 Hz |
| Line count roll | 280 ms (dur.digit.roll) | — | ease.out | 30 ms right → left | 30 Hz |
| Actions enter on complete | 120 ms | 0 | ease.out | 30 ms | 60 Hz |
| Window → collapsed (on complete) | 200 ms | 0 | spring.snap | — | 60 Hz |
| Show all / collapse | 200 ms | 0 | spring.snap | — | 60 Hz |
| Copy ✓ / hold / revert | 160 / 1500 / 160 ms | 0 | ease.out | — | 60 Hz |
| Run ▶ → ■ | 160 ms | 0 | spring.snap | — | 60 Hz |
| Output panel unfold | 200 ms | 0 | ease.out | — | 60 Hz |
| Applied ✓ + diff stats roll | 160 ms + 280 ms | 0 | spring.snap / ease.out | — | 60 Hz |
| Undo timer underline | 10 000 ms | 0 | linear | — | 15 Hz |
| Diagram code → render | 200 ms | on close + render time | ease.in-out | — | 60 Hz |
| Table column grow | 160 ms | — | spring.snap | — | 60 Hz |
| Reduced motion | everything above → 0–80 ms opacity crossfades; heights snap; digits swap; Undo timer shown as static "Undo (10 s)" text counting at 1 Hz; code lines appear per line without fade | — | linear | none | on change |
Responsive behaviour
- Tables and code scroll horizontally inside their own frames.
Edge cases (spec)
- Huge outputs (> 100 KB per message): settled blocks virtualise (messages.md §4.1); highlight caps §3.3; the in-flight reveal budget stays at 64 units (text-reveal).
- Fence inside a fence / tilde fences / 4+ backticks: follow CommonMark fence-length rules; the repair pass never closes a fence early (MonoCode's
remendskips fences, note 08). - Code with very long lines: no wrap by default; horizontal scroll inside the block; wrap toggle persists per session (proposed); a 12 px fade on the overflowing edge.
- Tabs and mixed indentation: tab width 4 (token); visible-whitespace off.
- RTL: prose mirrors; code blocks, inline code, math and tables of numbers stay LTR (bidi isolates); list bullets move to the right; the code header's actions stay trailing in reading direction.
- CJK: prose line-breaking follows the platform; code font fallback must include CJK glyphs at mono width ×2 (cell alignment in terminal surface).
- Tiny widths (< 320 px): code header shows icon-only Copy; line numbers hidden; tables become "Show table" disclosure that opens a full-width sheet.
- Dense IDE panels:
markdown/compact+code-block/file; Apply / Open in editor are primary. - Touch: code blocks scroll horizontally with the finger without scrolling the transcript (axis lock after 8 px); Copy 44 px hit area.
- Slow networks: a fence open for >
stall_softkeeps the "Writing" header and loader; the composer status handles "Still working". - Very fast streams: whole blocks arrive at once (text-reveal CatchUp) — the code block goes
Opening → Completein one frame: chrome and body appear together, no window phase. - Interrupted mid-fence:
Truncated(§2.3); copying works; Run/Apply disabled with the reason. - Unknown / unsafe languages for Run: Run hidden; never infer runnable from content.
- Math: rendered on close; render failure → raw LaTeX in mono with a dim "Couldn't render" note. The math layout engine for GPUI is an open question (see Gaps in §10).
- Images in markdown: placeholder box (text-reveal §5); broken image → alt text in a bordered box; remote images can be blocked by host policy ("Image blocked · Load").
- Malicious markdown: links with mismatched text/destination show the real domain in the hover tooltip; raw HTML off by default.
Notes for AI
- Import
StreamingMarkdown,Markdownfromoxyn_dioxusand includeSTATUS_INDICATOR_CSSplus the token stylesheet once. - A GPUI version exists:
MarkdownElinoxyn_gpui. - Props to set first:
text,text. - It reads a clock (
now) for live timers; pass one clock for the whole page rather than one per component. - Keep its states and timings as they ship; restyle it through the CSS variables rather than by hand.