| name | streaming-render |
| description | Smoothly render LLM token streams in the UI using a requestAnimationFrame char-drain loop with adaptive speed and clean cancellation. Read before touching SSE / streaming services. |
| user-invocable | true |
Streaming render
LLM SSE chunks arrive in irregular bursts (50 chars at once, then nothing for
300ms). Painting deltas as they arrive makes text "jump" and tear, and forces a
re-render per token.
DO
- Enqueue incoming characters into an output queue; drain the queue on
requestAnimationFrame, emitting at most one UI update per frame (≤60fps).
- Make the drain speed adaptive to backpressure: target speed grows when the
queue is long (
targetSpeed = max(baseSpeed, queue.length)) so the text never
lags far behind the model, and eases back down as it empties.
- Use a time accumulator (
accumulatedTime += frameDuration), not
setInterval — robust against a variable frame rate (it decouples how many
chars to emit from how often rAF fires). Note: requestAnimationFrame is
paused entirely in backgrounded tabs (HTML spec / MDN), so the stream does
not advance there; on refocus the first frame carries a huge dt, and since
charsToProcess is clamped to queue.length the backlog is emitted in one
frame (caught by the flush/clamp, but not a "smooth" catch-up).
- Flush the whole queue on finish and on abort, then
cancelAnimationFrame.
Without an explicit flush, aborting leaves characters stranded.
DON'T
- Don't call
signal.set/update (or setState) once per raw SSE chunk.
- Don't drive the typewriter with
setInterval.
- Don't forget cleanup: every started rAF loop must be cancellable.
Where
The reusable mechanism is packages/client/src/core/streaming/smooth-stream.ts
(createSmoothMessage). The Angular AiStreamService should feed its raw deltas
through it instead of appending directly to the streamText signal.
