"use client" import * as React from "react" import { cn } from "@/lib/utils" /** * A word of the reply and the whitespace after it. The word is what gets * counted, held back and faded in: a model's tokens often stop halfway through * a word, and letters that keep landing on a word already on screen read as a * correction rather than as writing. */ interface Word { text: string /** Inside a pair of backticks. */ code: boolean space: string /** Whether the whitespace after it is still inside the backticks. */ spaceCode: boolean } /** * How far behind the stream the text runs. What that buys is a few words in * hand when the stream pauses, so the writing slows through the pause instead * of stopping dead and starting again. */ const RESERVE_SECONDS = 0.45 /** How long a backlog beyond the reserve is given to clear. */ const CATCH_UP_SECONDS = 0.8 /** How far back the estimate of the stream's own rate looks. */ const RATE_WINDOW_SECONDS = 1.5 /** Bounds on that estimate, in words a second. */ const MIN_RATE = 4 const MAX_RATE = 80 /** * Words within this many of the newest keep a `` of their own, and the * rest are joined back into plain text. A word has long finished arriving by * the time it falls this far back, so the join is never seen, and a long reply * stays a few dozen elements instead of one per word. */ const LIVE_WORDS = 96 const REDUCED_MOTION = "(prefers-reduced-motion: reduce)" function subscribeToReducedMotion(onChange: () => void) { const query = window.matchMedia(REDUCED_MOTION) query.addEventListener("change", onChange) return () => query.removeEventListener("change", onChange) } function prefersReducedMotion() { return window.matchMedia(REDUCED_MOTION).matches } function subscribeToVisibility(onChange: () => void) { document.addEventListener("visibilitychange", onChange) return () => document.removeEventListener("visibilitychange", onChange) } function pageIsHidden() { return document.visibilityState === "hidden" } function clamp(value: number, min: number, max: number) { return Math.min(max, Math.max(min, value)) } /** Splits the reply into words, reading backticks as the edges of code. */ function splitWords(text: string, inlineCode: boolean) { const words: Word[] = [] const pattern = inlineCode ? /\s+|`|[^\s`]+/g : /\s+|\S+/g let lead = "" let code = false for (const token of text.match(pattern) ?? []) { if (inlineCode && token === "`") { code = !code } else if (/^\s/.test(token)) { const last = words.at(-1) if (last) { last.space += token last.spaceCode = code } else { lead += token } } else { words.push({ text: token, code, space: "", spaceCode: code }) } } return { lead, words } } const wordClass = cn( // Readable almost at once, but a word arrives in the accent and takes longer // to cool to the body colour, so the newest words show where the writing has // got to. "transition-[opacity,filter,color] duration-[380ms,380ms,700ms] ease-[cubic-bezier(0.2,0,0,1)]", "starting:text-accent starting:opacity-0 starting:blur-[3px]", "motion-reduce:transition-none" ) // Cloned across a line break, so code that wraps keeps its padding and corners // on both lines instead of being cut open at the edge. const codeClass = "rounded-md bg-foreground/[0.06] box-decoration-clone px-1 py-px font-mono text-[0.88em] dark:bg-foreground/[0.09]" /** * The words as nodes: plain text up to `animateFrom`, a fading `` per * word after it, held in the accent from `freshFrom` on, and a `

` around
 * each run inside backticks, whichever side of `animateFrom` it falls on.
 */
function renderWords(
  lead: string,
  words: Word[],
  animateFrom: number,
  freshFrom: number
) {
  const nodes: React.ReactNode[] = []
  let chip: React.ReactNode[] | null = null
  let chips = 0
  let run = lead

  const flush = () => {
    if (run) (chip ?? nodes).push(run)
    run = ""
  }

  const setCode = (code: boolean) => {
    if (code === (chip !== null)) return
    flush()
    if (chip) {
      nodes.push(
        
          {chip}
        
      )
      chip = null
    } else {
      chip = []
    }
  }

  words.forEach((word, index) => {
    setCode(word.code)
    if (index < animateFrom) {
      run += word.text
    } else {
      flush()
      ;(chip ?? nodes).push(
        = freshFrom && "text-accent")}
        >
          {word.text}
        
      )
    }
    if (word.space) {
      setCode(word.spaceCode)
      run += word.space
    }
  })

  setCode(false)
  flush()
  return nodes
}

/**
 * A reply that arrives a piece at a time. Pass the text so far on every
 * render, with `streaming` on until the last token has landed.
 *
 * A stream comes in bursts — a fragment, a pause, half a sentence at once —
 * and showing each burst as it lands makes the reply lurch. Here nothing is
 * shown until its word is whole, and whole words are let out at the rate the
 * stream has been arriving, a moment behind it. Running behind leaves a few
 * words in hand: when words pile up the clock runs faster, and as the reserve
 * thins through a pause it eases off rather than stopping, so the writing
 * keeps one cadence. Once the stream ends, the last words follow at the same
 * rate instead of dropping in together. Each word fades in as it is added,
 * and what is already on screen is never touched again.
 *
 * Text it mounts with is shown at once, unless `revealInitial` asks for it to
 * be written out at `pace`; text that changes other than by growing is shown
 * as it is. The clock only runs where it can be seen: with reduced motion, or
 * in a tab nobody is looking at, whatever has arrived is shown at once. A
 * reply streamed in the background is whole when the reader comes back, and
 * `onRevealed` does not wait for them to.
 *
 * While words are still coming — streamed, or waiting on the clock — a caret
 * sits after the last one and the element is marked busy, so assistive tech
 * can wait for the reply instead of reading it out a word at a time.
 */
function StreamText({
  text,
  streaming = false,
  pace = 16,
  revealInitial = false,
  inlineCode = true,
  freshWords = 2,
  onRevealed,
  className,
  ...props
}: Omit, "children"> & {
  /** The reply so far. Each value should carry on from the one before. */
  text: string
  /** Whether more is still on its way. */
  streaming?: boolean
  /**
   * Words a second: where the clock starts before the stream's own rate is
   * known, and the steady rate for text written out with `revealInitial`.
   */
  pace?: number
  /** Write out the text it mounts with as well, for a reply already in hand. */
  revealInitial?: boolean
  /** Set runs inside `backticks` as code. */
  inlineCode?: boolean
  /** How many of the newest words hold the accent while more are coming. */
  freshWords?: number
  /** Called once the reply is finished and every word of it is on screen. */
  onRevealed?: () => void
}) {
  const { lead, words } = React.useMemo(
    () => splitWords(text, inlineCode),
    [text, inlineCode]
  )

  // With more on the way, a last word that nothing follows yet may be half a
  // word, so it waits.
  const endsMidWord = (inlineCode ? /[^\s`]$/ : /\S$/).test(text)
  const ready = streaming && endsMidWord ? words.length - 1 : words.length

  const reducedMotion = React.useSyncExternalStore(
    subscribeToReducedMotion,
    prefersReducedMotion,
    () => false
  )
  // A hidden page gets no animation frames, so a clock that waited for them
  // would hold the whole reply back until the reader returned.
  const hidden = React.useSyncExternalStore(
    subscribeToVisibility,
    pageIsHidden,
    () => false
  )
  const unwatched = reducedMotion || hidden

  // How many words are out, how many were there before anything could
  // animate, and whether this is still text in hand being written out. All
  // follow their inputs by being adjusted while rendering, which is how React
  // has a component compare a value with the one it had before.
  const [previous, setPrevious] = React.useState(text)
  const [shown, setShown] = React.useState(
    revealInitial && !unwatched ? 0 : ready
  )
  const [quiet, setQuiet] = React.useState(revealInitial ? 0 : ready)
  const [typing, setTyping] = React.useState(revealInitial)

  if (text !== previous) {
    setPrevious(text)
    setTyping(false)
    if (!text.startsWith(previous)) {
      setShown(ready)
      setQuiet(ready)
    }
  }

  // Out of sight, everything that has arrived is out. When the page is seen
  // again the clock carries on from there, so nothing already shown goes back.
  if (unwatched && shown < ready) {
    setShown(ready)
  }

  const shownRef = React.useRef(shown)
  const clock = React.useRef({
    frame: 0,
    last: 0,
    budget: 0,
    /** The stream's arrival rate so far, in words a second. */
    rate: pace,
    /** When words last arrived, and how many had by then. */
    arrived: 0,
    received: ready,
  })

  React.useEffect(() => {
    shownRef.current = shown
  }, [shown])

  React.useEffect(() => {
    const state = clock.current

    // Every time more words are ready, fold how quickly they came into the
    // estimate of the stream's rate. A reset starts the estimate over.
    if (ready < state.received) {
      state.received = ready
      state.arrived = 0
      state.rate = pace
    } else if (ready > state.received) {
      const now = performance.now()
      if (state.arrived) {
        const seconds = Math.max(0.05, (now - state.arrived) / 1000)
        const sample = (ready - state.received) / seconds
        const weight = 1 - Math.exp(-seconds / RATE_WINDOW_SECONDS)
        state.rate = clamp(
          state.rate + (sample - state.rate) * weight,
          MIN_RATE,
          MAX_RATE
        )
      }
      state.arrived = now
      state.received = ready
    }

    if (unwatched || shownRef.current >= ready) return

    // The clock runs only while words are waiting. It keeps its last tick and
    // its part-spent budget across restarts, so a new burst landing mid-run
    // neither stalls it nor makes it skip ahead.
    const tick = (now: number) => {
      const seconds = state.last
        ? Math.min(0.1, (now - state.last) / 1000)
        : 1 / 60
      state.last = now

      const backlog = ready - shownRef.current
      if (backlog <= 0) {
        state.frame = 0
        state.last = 0
        state.budget = 0
        return
      }

      let rate: number
      if (typing) {
        rate = pace
      } else if (streaming) {
        const reserve = state.rate * RESERVE_SECONDS
        rate = Math.max(
          state.rate * clamp(backlog / reserve, 0.4, 3),
          (backlog - reserve) / CATCH_UP_SECONDS
        )
      } else {
        rate = Math.max(state.rate, backlog / CATCH_UP_SECONDS)
      }

      state.budget += rate * seconds
      const step = Math.floor(state.budget)
      if (step > 0) {
        state.budget -= step
        shownRef.current = Math.min(ready, shownRef.current + step)
        setShown(shownRef.current)
      }

      state.frame = requestAnimationFrame(tick)
    }

    state.frame = requestAnimationFrame(tick)
    return () => {
      cancelAnimationFrame(state.frame)
      state.frame = 0
    }
  }, [ready, streaming, typing, pace, unwatched])

  const visible = Math.min(shown, words.length)
  const busy = streaming || visible < words.length

  const onRevealedRef = React.useRef(onRevealed)
  const wasBusy = React.useRef(busy)

  React.useEffect(() => {
    onRevealedRef.current = onRevealed
  })

  React.useEffect(() => {
    if (wasBusy.current && !busy) onRevealedRef.current?.()
    wasBusy.current = busy
  }, [busy])

  return (
    
      {renderWords(
        lead,
        words.slice(0, visible),
        Math.max(quiet, visible - LIVE_WORDS),
        busy ? visible - freshWords : visible
      )}
      {busy ? (
        // Sat on the last line's baseline and a little shorter than a capital,
        // so it reads as the end of the text rather than a character in it.
        
      ) : null}
    
  )
}

export { StreamText }

Stream Text

01Preview

02Installation