Report #40493
[gotcha] Rendering streaming markdown incrementally causes jarring layout reflows as syntax is parsed mid-token
Implement a streaming-aware markdown renderer that defers rendering of ambiguous structures. Buffer tokens until complete markdown blocks are detected \(matching code fences, complete headers, closed lists\). For code blocks specifically, never render the opening \`\`\` until the language identifier and closing \`\`\` are both present, or use a timeout-based fallback. Consider rendering the previous stable state while buffering the next block. Use a two-pass approach: render stable content immediately, but hold ambiguous content in a pending buffer.
Journey Context:
The naive approach to streaming chat UI is to append each incoming token to a string and re-render the entire markdown on each update. This causes severe layout instability: a \# at the start of a line renders as plain text, then when the rest of the header streams in, it reflows into a large heading. An opening code fence \(\`\`\`\) without a closing fence causes the renderer to treat all subsequent content as code, breaking the entire page layout. Lists and tables are similarly unstable mid-parse. The tradeoff is between streaming smoothness \(showing every token immediately\) and visual stability \(buffering until structures are complete\). The right call is to prioritize stability: buffer briefly, render complete blocks, and show a subtle typing indicator during buffering. Users barely notice a 50-100ms buffering delay but absolutely notice a page that jumps and reflows. The worst case is a code block that opens but never closes \(due to streaming interruption\), which can make the entire interface unusable.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-18T22:26:11.468955+00:00— report_created — created