chore: import upstream snapshot with attribution

apps/sim/hooks/use-smooth-text.ts

@@ -0,0 +1,207 @@
+import { useEffect, useRef, useState } from 'react'
+
+/**
+ * Time-based paced reveal of a growing string. A per-frame loop earns a
+ * character budget from elapsed time and releases text one word/punctuation
+ * boundary at a time — so words appear individually, evenly spaced on the
+ * timeline, instead of the old fixed-interval tick that dumped a multi-word
+ * chunk every 24ms and read as blocky.
+ *
+ * The rate is a proportional controller: drain the current backlog over
+ * {@link DRAIN_HORIZON_MS}. It therefore converges on the stream's real
+ * arrival rate — a fast stream reveals fast, a slow one trickles — instead of
+ * racing ahead at a fixed cap, emptying the backlog, and stalling until the
+ * next network burst (the old burst–pause rhythm).
+ */
+const SNAP = /[\s.,!?;:)\]]/
+
+/** Reveal the backlog over roughly this horizon (a small jitter buffer). */
+const DRAIN_HORIZON_MS = 400
+/** Floor so a near-empty backlog still trickles out instead of freezing. */
+const MIN_CPS = 45
+/** Cap so a huge backlog (resume, giant paste) sweeps in over ~a second. */
+const MAX_CPS = 2400
+
+/** Chars/second that drains `remaining` over the horizon, clamped. */
+function drainRate(remaining: number): number {
+  return Math.min(MAX_CPS, Math.max(MIN_CPS, (remaining * 1000) / DRAIN_HORIZON_MS))
+}
+
+/**
+ * The furthest word/punctuation boundary within `start + budget`, or `start`
+ * when the budget doesn't yet cover the next whole word (the budget carries
+ * over to later frames). Words longer than the 24-char lookahead are released
+ * whole once the budget covers the lookahead, so an unbroken token (a URL, a
+ * long identifier) cannot dam the reveal.
+ */
+function nextIndex(text: string, start: number, budget: number): number {
+  const limit = Math.min(text.length, start + Math.floor(budget))
+  for (let i = limit; i > start; i--) {
+    if (SNAP.test(text[i - 1] ?? '')) return i
+  }
+  if (limit >= Math.min(text.length, start + 24)) return limit
+  return start
+}
+
+/**
+ * Content already longer than this when streaming begins is assumed to be
+ * pre-existing (an in-progress resume, restored history, or an in-place edit
+ * of an existing document), so it is shown immediately rather than replayed
+ * from the first character. Consumers gating reveal animations should use the
+ * same threshold so pacing and animation agree on what counts as "new".
+ */
+export const RESUME_SKIP_THRESHOLD = 60
+
+interface SmoothTextOptions {
+  /**
+   * When a content update is not a continuation of the previous string (the new
+   * value does not start with the old one — e.g. an in-place patch/rewrite
+   * rather than an append), show it in full immediately instead of re-revealing
+   * a prefix. Keeps diff/patch previews correct while still pacing ordinary
+   * append streams. Defaults to `false`, which keeps the original
+   * pull-back-on-shrink behavior used by the chat.
+   */
+  snapOnNonAppend?: boolean
+}
+
+/**
+ * Paces a growing string so it reveals word-by-word at a steady cadence
+ * regardless of how bursty the upstream stream is — a React port of opencode's
+ * paced text rendering. Returns the portion of `content` that should be
+ * displayed now.
+ *
+ * Content that is already complete at mount (history, or a resume past
+ * {@link RESUME_SKIP_THRESHOLD}) is returned in full and never animates. When a
+ * live stream ends mid-reveal the remaining tail keeps draining at the paced
+ * cadence rather than snapping — so the reveal stays smooth right to the end and
+ * the caller can hold its streaming render until `useSmoothText` reports the
+ * full string, avoiding a flash on the streaming→static handoff.
+ *
+ * @remarks
+ * The re-arm effect runs on every committed render with a cheap
+ * `rafRef === null` guard instead of keying on a `hasBacklog` dependency.
+ * The frame chain self-terminates whenever the reveal catches up, and a chain
+ * keyed on the `hasBacklog` boolean could die for good: when the final frame's
+ * `setRevealed` and a new chunk land in the same React commit, `hasBacklog`
+ * stays `true` across commits, the effect never re-fires, and the reveal
+ * freezes mid-stream until remount. Re-arming per render closes that
+ * interleaving while still avoiding per-chunk loop teardown (no cleanup on
+ * content changes), so it cannot trip React's max-update-depth guard either.
+ * If upstream sanitization rewrites earlier text and shrinks the string, the
+ * cursor is pulled back to the new end so regrowth stays paced instead of
+ * jumping past it.
+ */
+export function useSmoothText(
+  content: string,
+  isStreaming: boolean,
+  options?: SmoothTextOptions
+): string {
+  const snapOnNonAppend = options?.snapOnNonAppend ?? false
+
+  const [revealed, setRevealed] = useState(() =>
+    isStreaming && content.length <= RESUME_SKIP_THRESHOLD ? 0 : content.length
+  )
+
+  const contentRef = useRef(content)
+  const revealedRef = useRef(revealed)
+  const rafRef = useRef<number | null>(null)
+  /** Fractional character budget carried between frames (see the frame loop). */
+  const budgetRef = useRef(0)
+  const lastFrameAtRef = useRef(0)
+  const prevContentRef = useRef(content)
+  const prevIsStreamingRef = useRef(isStreaming)
+
+  let effectiveRevealed = revealed
+
+  if (
+    isStreaming &&
+    !prevIsStreamingRef.current &&
+    content.length > RESUME_SKIP_THRESHOLD &&
+    revealed < content.length
+  ) {
+    effectiveRevealed = content.length
+    revealedRef.current = content.length
+    setRevealed(content.length)
+  }
+
+  if (
+    snapOnNonAppend &&
+    content !== prevContentRef.current &&
+    !content.startsWith(prevContentRef.current) &&
+    effectiveRevealed < content.length
+  ) {
+    effectiveRevealed = content.length
+    revealedRef.current = content.length
+    setRevealed(content.length)
+  }
+
+  contentRef.current = content
+
+  const hasBacklog = effectiveRevealed < content.length
+
+  // Advance the previous-input trackers on commit, never during render. A concurrent render can be
+  // started and then thrown away before it commits (interrupted by a higher-priority update); a
+  // render-phase write persists on that discarded attempt, so the retried render would read a stale
+  // `prev` and skip the snap. Updating them in a committed effect keeps `prev` in lockstep with the
+  // render that actually committed, so the snap decision is identical across discarded attempts.
+  useEffect(() => {
+    prevContentRef.current = content
+    prevIsStreamingRef.current = isStreaming
+  }, [content, isStreaming])
+
+  useEffect(() => {
+    /**
+     * Per-frame reveal: each frame earns `drainRate * dt` characters of budget
+     * (fractional remainder carried in `budgetRef`), and the cursor advances to
+     * the furthest word boundary the budget covers — releasing words one at a
+     * time, evenly spaced in real time, rather than a fixed-size chunk per
+     * tick. Frames whose budget doesn't yet cover the next word update nothing.
+     */
+    const run = (now: number) => {
+      rafRef.current = null
+      const text = contentRef.current
+      const target = text.length
+
+      if (revealedRef.current > target) {
+        revealedRef.current = target
+        budgetRef.current = 0
+        setRevealed(target)
+      }
+      const current = revealedRef.current
+      if (current >= target) return
+
+      // Clamp dt so a background tab's paused rAF doesn't bank a giant budget.
+      const dt = Math.min(now - lastFrameAtRef.current, 100)
+      lastFrameAtRef.current = now
+      budgetRef.current += (drainRate(target - current) * dt) / 1000
+
+      const next = nextIndex(text, current, budgetRef.current)
+      if (next > current) {
+        budgetRef.current -= next - current
+        revealedRef.current = next
+        setRevealed(next)
+      }
+      if (revealedRef.current < target) {
+        rafRef.current = requestAnimationFrame(run)
+      }
+    }
+
+    if (hasBacklog && rafRef.current === null) {
+      lastFrameAtRef.current = performance.now()
+      rafRef.current = requestAnimationFrame(run)
+    }
+  })
+
+  useEffect(
+    () => () => {
+      if (rafRef.current !== null) {
+        cancelAnimationFrame(rafRef.current)
+        rafRef.current = null
+      }
+    },
+    []
+  )
+
+  if (effectiveRevealed >= content.length) return content
+  return content.slice(0, effectiveRevealed)
+}