Fenced code blocks don't render incrementally during streaming

[Aventerica89]

Fenced code blocks don't render incrementally during streaming

Description

When streaming AI responses token-by-token, fenced code blocks (triple backtick) appear to render all at once rather than incrementally as the markdown string grows. Text outside code blocks streams smoothly with visible character-by-character rendering, but the moment a code fence opens, the content inside appears to buffer until the block is complete, then dumps visually.

Environment

• streamdown: 2.5.0
• @streamdown/code: 1.1.1
• React 18
• Using <Streamdown animated isAnimating plugins={{ cjk, code, math, mermaid }}>

Reproduction

1. Pass a growing markdown string to <Streamdown> that includes a fenced code block
2. The string updates token-by-token (verified via console.log — length increments: 4, 8, 24, 26, 34, 58... smoothly up to 860+)
3. Prose text before and after the code fence streams beautifully with the animated caret
4. The code block content appears all at once or in large chunks

Minimal usage:

<Streamdown animated isAnimating plugins={{ cjk, code, math, mermaid }}>
  {streamingMarkdownString}
</Streamdown>

Where streamingMarkdownString grows incrementally and contains:

Some text before...

```typescript
// This content appears to dump all at once
function example() {
  return "hello";
}
```

What we investigated

1. Transport is not the issue

Console logging confirms the raw string updates smoothly, token-by-token. The buffering is in the rendering layer, not the data transport.

2. parseMarkdownIntoBlocks uses marked's Lexer.lex()

parseMarkdownIntoBlocks calls Lexer.lex(markdown, { gfm: true }) and iterates tokens. When the lexer encounters a fenced code block, it emits a single code token only after the closing fence is found. While the fence is open (no closing backticks yet), the raw content likely falls into a different token type or gets merged differently.

Key question: Does marked's Lexer.lex() emit a code-type token for a partial fence (no closing backticks), or does it fall back to a paragraph token? If it treats unclosed fences as paragraphs, the block would render as text during streaming and then suddenly swap to a code block when the closing fence arrives — which is exactly what we observe.

3. isIncomplete infrastructure exists

The Streamdown component checks for unclosed code fences (via hasIncompleteCodeFence) on the last block and passes isIncomplete={true} to the Block component. The useIsCodeFenceIncomplete hook exposes this. However, if marked's lexer doesn't produce a code-type token for the unclosed fence, the isIncomplete flag may not trigger the code block rendering path.

4. chatbot.ai-sdk.dev achieves smooth code block streaming

The reference chatbot at chatbot.ai-sdk.dev (which uses Streamdown via MessageResponse) renders code blocks incrementally during streaming. This suggests either a configuration difference or that AI SDK's useChat delivers data in a way that interacts with Streamdown differently than a custom WebSocket stream.

5. parseIncompleteMarkdown prop

We noticed this prop defaults to false. Does remend processing affect how unclosed code fences are rendered during streaming? Does enabling parseIncompleteMarkdown={true} change the behavior?

Our setup (not using AI SDK)

We're NOT using AI SDK's useChat. We have a custom WebSocket streaming pipeline that delivers text tokens from a container running Claude CLI. The growing markdown string is accumulated in a Zustand store and passed as children to Streamdown. The string IS raw markdown with fences.

Questions

1. Does parseMarkdownIntoBlocks produce incremental block updates for unclosed code fences?
2. Is there a prop or configuration we're missing to enable incremental code block rendering?
3. Does chatbot.ai-sdk.dev use any additional configuration beyond what's in its open-source MessageResponse wrapper?
4. Could remend preprocessing be the key — does it close unclosed fences before the lexer sees them?

[mvanhorn]

I've submitted PR #474 to fix this.

Root cause: The animate plugin unconditionally skips all code and pre elements (via SKIP_TAGS). When using animated isAnimating, prose gets word-by-word fade-in animation, but code block content renders instantly with no animation. This creates the visual impression of "buffering" - code appears to dump all at once while surrounding text streams smoothly.

Fix: Added setAnimateCodeBlocks to the animate plugin API. When a block has an incomplete (unclosed) code fence, the Block component tells the plugin to include code/pre in its animation pass. Once the fence closes, it reverts to the default skip behavior so syntax highlighting works normally.

[Aventerica89]

Update: Root Cause Identified (Source Code Analysis)

After extensive debugging, we've traced the root cause to HighlightedCodeBlockBody in the Streamdown core package.

Key Finding: Removing @streamdown/code plugin has ZERO effect

We tested removing the code plugin entirely during streaming (plugins without code when isAnimating=true). No change — code blocks still dump complete. This proves the issue is NOT in the Shiki async highlighting path.

Root Cause: useEffect-based state sync in HighlightedCodeBlockBody

HighlightedCodeBlockBody is loaded via lazy() and is part of the core Streamdown package (not the code plugin). Once the lazy import resolves on the first code block render, the Suspense fallback (which renders raw tokens directly via CodeBlockBody) never shows again.

Inside HighlightedCodeBlockBody:

1. useState(raw) — only sets initial value
2. useEffect(() => { if (!codePlugin) { setResult(raw); return; } ... }) — state sync is async (fires after render)
3. During render, result still holds the previous raw value
4. CodeBlockBody memo: prevProps.result === nextProps.result — same stale reference → bails out
5. Under rapid streaming (~50ms between tokens), useEffect can never catch up
6. When streaming stops → final useEffect commits → full content appears → "dump"

Why text/tables work

They go through synchronous rendering paths (no lazy(), no Suspense, no useEffect state sync). Their memo comparisons check className + node.position, and their rendered output updates immediately.

Suggested Fix

In HighlightedCodeBlockBody, when no code plugin is registered, bypass the useEffect and use raw directly:

// Option 1: Synchronous derivation
const effectiveResult = codePlugin ? result : raw;
// Pass effectiveResult to CodeBlockBody instead of result

// Option 2: Bypass entirely when no plugin
if (!codePlugin) {
  return <CodeBlockBody result={raw} ... />;
}

Or more fundamentally: ensure raw is always displayed synchronously as the fallback during streaming, regardless of whether the async highlight has completed.

Environment

• Streamdown v2.5.0
• React 18.3.0
• parseIncompleteMarkdown enabled
• Data flow: WebSocket → Zustand store → growing string as children prop (NOT using AI SDK's useChat)

[Aventerica89]

Thanks @mvanhorn for the quick PR! The animate plugin fix makes sense — skipping code/pre during animation definitely contributes to the visual discontinuity.

I wanted to flag that we've identified what appears to be a second, independent layer of the problem in HighlightedCodeBlockBody (details in my comment above). Even with the @streamdown/code plugin removed entirely, code blocks still dump their content all at once during streaming.

The root cause is the useEffect-based state sync: useState(raw) only captures the initial value, and the useEffect that syncs subsequent raw updates fires after render. Under rapid streaming (~50ms between tokens), result stays stale and CodeBlockBody's memo bails out on every render. The full content only appears when the final useEffect commits after streaming stops.

Your PR would fix the animation smoothing layer, but the underlying content update pipeline would still buffer. Would it make sense to address both in the same PR, or would a separate PR for the HighlightedCodeBlockBody sync path be preferred?

Happy to submit one if that's helpful.