@jcy2387/dsh-conversation-ui 0.1.0-rc.12

package/src/client/turnProcessFold.ts

@@ -0,0 +1,224 @@
+import { useCallback, useLayoutEffect, useSyncExternalStore } from 'react'
+
+export interface TurnFoldAddress {
+  readonly sessionId: string
+  readonly turn: number
+}
+
+interface TurnFoldEntry {
+  collapsed: boolean
+  completed: boolean
+  label: string | undefined
+  readonly boundaries: Map<string, number>
+  readonly members: Map<string, number>
+  readonly listeners: Set<() => void>
+}
+
+interface TurnProcessFoldState {
+  readonly collapsed: boolean
+  readonly completed: boolean
+  readonly boundary: boolean
+  readonly controls: string
+  readonly hasMembers: boolean
+  readonly label: string | undefined
+  readonly toggle: () => void
+}
+
+const entries = new Map<string, TurnFoldEntry>()
+
+function addressKey(address: TurnFoldAddress): string {
+  return `${address.sessionId}\u0000${address.turn}`
+}
+
+function entryFor(key: string): TurnFoldEntry {
+  const current = entries.get(key)
+  if (current !== undefined) return current
+  const created: TurnFoldEntry = {
+    collapsed: false,
+    completed: false,
+    label: undefined,
+    boundaries: new Map(),
+    members: new Map(),
+    listeners: new Set(),
+  }
+  entries.set(key, created)
+  return created
+}
+
+function notify(entry: TurnFoldEntry): void {
+  for (const listener of entry.listeners) listener()
+}
+
+function discardUnused(key: string, entry: TurnFoldEntry): void {
+  if (entry.listeners.size === 0 && entry.boundaries.size === 0 && entry.members.size === 0) entries.delete(key)
+}
+
+function subscribe(key: string, listener: () => void): () => void {
+  const entry = entryFor(key)
+  entry.listeners.add(listener)
+  return () => {
+    entry.listeners.delete(listener)
+    discardUnused(key, entry)
+  }
+}
+
+function orderedMembers(entry: TurnFoldEntry): readonly string[] {
+  return [...entry.members]
+    .sort(([leftId, leftOrder], [rightId, rightOrder]) => leftOrder - rightOrder || leftId.localeCompare(rightId))
+    .map(([id]) => id)
+}
+
+function orderedBoundaries(entry: TurnFoldEntry): readonly string[] {
+  return [...entry.boundaries]
+    .sort(([leftId, leftOrder], [rightId, rightOrder]) => leftOrder - rightOrder || leftId.localeCompare(rightId))
+    .map(([id]) => id)
+}
+
+function complete(key: string, label: string): void {
+  const entry = entryFor(key)
+  if (entry.completed) {
+    if (entry.label === label) return
+    entry.label = label
+    notify(entry)
+    return
+  }
+  entry.completed = true
+  entry.label = label
+  entry.collapsed = true
+  notify(entry)
+}
+
+function registerMember(key: string, memberId: string, memberOrder: number): () => void {
+  const entry = entryFor(key)
+  entry.members.set(memberId, memberOrder)
+  notify(entry)
+  return () => {
+    entry.members.delete(memberId)
+    notify(entry)
+    discardUnused(key, entry)
+  }
+}
+
+function registerBoundary(key: string, boundaryId: string, boundaryOrder: number): () => void {
+  const entry = entryFor(key)
+  entry.boundaries.set(boundaryId, boundaryOrder)
+  notify(entry)
+  return () => {
+    entry.boundaries.delete(boundaryId)
+    notify(entry)
+    discardUnused(key, entry)
+  }
+}
+
+function hash(value: string): string {
+  let result = 2_166_136_261
+  for (let index = 0; index < value.length; index += 1) {
+    result ^= value.charCodeAt(index)
+    result = Math.imul(result, 16_777_619)
+  }
+  return (result >>> 0).toString(36)
+}
+
+/** Stable DOM id for one flat Chat node controlled by a Turn disclosure. */
+export function turnProcessMemberId(address: TurnFoldAddress, nodeKey: string): string {
+  return `dsh-turn-process-${address.turn}-${hash(`${address.sessionId}\u0000${nodeKey}`)}`
+}
+
+/** Stable DOM/store identity for the user-anchored Turn disclosure. */
+export function turnProcessBoundaryId(sessionId: string, nodeKey: string): string {
+  return `dsh-turn-boundary-${hash(`${sessionId}\u0000${nodeKey}`)}`
+}
+
+/**
+ * Share one collapse state across flat Chat siblings belonging to the same
+ * Session Turn. A successful final node marks the Turn complete; process
+ * members contribute their DOM ids to the disclosure's `aria-controls` list.
+ */
+export function useTurnProcessFold(
+  address: TurnFoldAddress | undefined,
+  options: {
+    readonly boundaryId?: string | undefined
+    readonly boundaryOrder?: number | undefined
+    readonly completedLabel?: string | undefined
+    readonly memberId?: string | undefined
+    readonly memberOrder?: number | undefined
+  } = {},
+): TurnProcessFoldState {
+  const key = address === undefined ? undefined : addressKey(address)
+  const subscribeToKey = useCallback((listener: () => void) => (
+    key === undefined ? () => {} : subscribe(key, listener)
+  ), [key])
+  const collapsed = useSyncExternalStore(
+    subscribeToKey,
+    () => key === undefined ? false : entries.get(key)?.collapsed ?? false,
+    () => false,
+  )
+  const completed = useSyncExternalStore(
+    subscribeToKey,
+    () => key === undefined ? false : entries.get(key)?.completed ?? false,
+    () => false,
+  )
+  const controls = useSyncExternalStore(
+    subscribeToKey,
+    () => {
+      if (key === undefined) return ''
+      const entry = entries.get(key)
+      return entry === undefined ? '' : orderedMembers(entry).join(' ')
+    },
+    () => '',
+  )
+  const boundaryId = useSyncExternalStore(
+    subscribeToKey,
+    () => {
+      if (key === undefined) return undefined
+      const entry = entries.get(key)
+      if (entry === undefined) return undefined
+      return orderedBoundaries(entry)[0] ?? orderedMembers(entry)[0]
+    },
+    () => undefined,
+  )
+  const hasMembers = useSyncExternalStore(
+    subscribeToKey,
+    () => key !== undefined && (entries.get(key)?.members.size ?? 0) > 0,
+    () => false,
+  )
+  const label = useSyncExternalStore(
+    subscribeToKey,
+    () => key === undefined ? undefined : entries.get(key)?.label,
+    () => undefined,
+  )
+
+  useLayoutEffect(() => {
+    if (key === undefined || options.boundaryId === undefined || options.boundaryOrder === undefined) return
+    return registerBoundary(key, options.boundaryId, options.boundaryOrder)
+  }, [key, options.boundaryId, options.boundaryOrder])
+
+  useLayoutEffect(() => {
+    if (key === undefined || options.memberId === undefined || options.memberOrder === undefined) return
+    return registerMember(key, options.memberId, options.memberOrder)
+  }, [key, options.memberId, options.memberOrder])
+
+  useLayoutEffect(() => {
+    if (key === undefined || options.completedLabel === undefined) return
+    complete(key, options.completedLabel)
+  }, [key, options.completedLabel])
+
+  const toggle = useCallback(() => {
+    if (key === undefined) return
+    const entry = entryFor(key)
+    if (!entry.completed || entry.members.size === 0) return
+    entry.collapsed = !entry.collapsed
+    notify(entry)
+  }, [key])
+
+  return {
+    collapsed,
+    completed,
+    boundary: (options.boundaryId !== undefined && boundaryId === options.boundaryId)
+      || (options.memberId !== undefined && boundaryId === options.memberId),
+    controls,
+    hasMembers,
+    label,
+    toggle,
+  }
+}

package/src/client/useConversationContent.ts

@@ -0,0 +1,471 @@
+/**
+ * Stream-smoothing reveal hook.
+ *
+ * Buffers the model's chunked text and reveals it at a cadence that tracks
+ * the observed arrival rate, so a long reply never dumps whole paragraphs at
+ * once and a fast stream never stutters. Port of lobe-ui's smoother: EMA
+ * arrival cps + chunk size, backlog pressure, commit-interval widening with
+ * tail length, and a flush-speed settle drain once the input idles. The
+ * reveal decision is the pure {@link computeRevealStep} for unit tests.
+ *
+ * `shouldHoldBack` is the performance guard's veto: while it returns true the
+ * loop keeps measuring but skips the DOM commit, so an offscreen reply never
+ * competes with visible frames when the frame rate is degraded.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+export type ConversationSmoothingPreset = 'realtime' | 'balanced' | 'silky'
+
+export interface ConversationSmoothingPresetConfig {
+  readonly activeInputWindowMs: number
+  readonly defaultCps: number
+  readonly emaAlpha: number
+  readonly flushCps: number
+  readonly largeAppendChars: number
+  readonly maxActiveCps: number
+  readonly maxCps: number
+  readonly maxFlushCps: number
+  readonly minCommitIntervalMs: number
+  readonly minCps: number
+  readonly settleAfterMs: number
+  readonly settleDrainMaxMs: number
+  readonly settleDrainMinMs: number
+  readonly targetBufferMs: number
+}
+
+export const PRESET_CONFIG: Record<ConversationSmoothingPreset, ConversationSmoothingPresetConfig> = {
+  balanced: {
+    activeInputWindowMs: 220,
+    defaultCps: 80,
+    emaAlpha: 0.35,
+    flushCps: 180,
+    largeAppendChars: 120,
+    maxActiveCps: 360,
+    maxCps: 240,
+    maxFlushCps: 480,
+    minCommitIntervalMs: 16,
+    minCps: 24,
+    settleAfterMs: 280,
+    settleDrainMaxMs: 420,
+    settleDrainMinMs: 120,
+    targetBufferMs: 40,
+  },
+  realtime: {
+    activeInputWindowMs: 140,
+    defaultCps: 120,
+    emaAlpha: 0.45,
+    flushCps: 240,
+    largeAppendChars: 180,
+    maxActiveCps: 480,
+    maxCps: 320,
+    maxFlushCps: 640,
+    minCommitIntervalMs: 16,
+    minCps: 32,
+    settleAfterMs: 200,
+    settleDrainMaxMs: 280,
+    settleDrainMinMs: 100,
+    targetBufferMs: 24,
+  },
+  silky: {
+    activeInputWindowMs: 280,
+    defaultCps: 64,
+    emaAlpha: 0.28,
+    flushCps: 140,
+    largeAppendChars: 100,
+    maxActiveCps: 280,
+    maxCps: 180,
+    maxFlushCps: 400,
+    minCommitIntervalMs: 16,
+    minCps: 20,
+    settleAfterMs: 360,
+    settleDrainMaxMs: 520,
+    settleDrainMinMs: 160,
+    targetBufferMs: 56,
+  },
+}
+
+const MAX_COMMIT_INTERVAL_MS = 16
+/** Demo queue divisor: each frame reveals about `backlog / 8` characters. */
+export const QUEUE_REVEAL_DIVISOR = 8
+const QUEUE_FRAME_MS = 16.67
+/** Hard cap on how far display may trail a live stream, in characters. */
+export const LIVE_LAG_CHAR_CEILING = 32
+const CATCHUP_SECONDS = 0.15
+
+export const clamp = (value: number, min: number, max: number): number => {
+  return Math.min(max, Math.max(min, value))
+}
+
+/**
+ * Demo per-frame reveal: drain `backlog / 8` characters, at least 1, scaled
+ * by frame time. A small queue types one glyph per frame; a burst raises the
+ * step so the display does not fall behind.
+ * @param backlog - Unrevealed characters.
+ * @param dtMs - Frame delta in ms.
+ * @returns Characters to reveal this frame.
+ */
+export function computeQueueReveal(backlog: number, dtMs: number): number {
+  if (backlog <= 0 || dtMs <= 0) return 0
+  return Math.min(backlog, Math.max(1, Math.ceil((backlog / QUEUE_REVEAL_DIVISOR) * (dtMs / QUEUE_FRAME_MS))))
+}
+
+const graphemeSegmenter = typeof Intl.Segmenter === 'function'
+  ? new Intl.Segmenter(undefined, { granularity: 'grapheme' })
+  : undefined
+
+/** Split text into user-perceived characters without tearing emoji or combining marks. */
+export function splitGraphemes(text: string): string[] {
+  if (graphemeSegmenter === undefined) return [...text]
+  return [...graphemeSegmenter.segment(text)].map(item => item.segment)
+}
+
+/** Counts user-perceived characters, not UTF-16 units or Unicode code points. */
+export const countChars = (text: string): number => splitGraphemes(text).length
+
+/**
+ * Drain rate for backlog beyond the tail-lag ceiling: the displayed text may
+ * trail the stream by at most `backlogCharCeiling` characters for at most
+ * `backlogSecondCeiling` seconds. The constants are a smoothness invariant
+ * (bounded lag is the reason the reveal never stalls mid-reply), so they are
+ * not config fields; the preset multiplier is how a deployment tunes them.
+ */
+export const BACKLOG_CHAR_CEILING = 300
+export const BACKLOG_SECOND_CEILING = 2
+
+export interface SettleDrainInput {
+  readonly backlog: number
+  readonly inputActive: boolean
+  readonly settling: boolean
+}
+
+/** Pure settle-drain decision shared by the frame loop and its tests. */
+export function computeSettleDrain(config: ConversationSmoothingPresetConfig, input: SettleDrainInput): number {
+  if (input.inputActive || !input.settling) return 0
+  // A settled stream must drain fast enough to finish the reply promptly:
+  // lag beyond the ceiling drains within the second ceiling.
+  const overflow = Math.max(0, input.backlog - BACKLOG_CHAR_CEILING)
+  const overflowCps = (overflow * 1000) / BACKLOG_SECOND_CEILING
+  const drainTargetMs = clamp(input.backlog * 8, config.settleDrainMinMs, config.settleDrainMaxMs)
+  const settleCps = (input.backlog * 1000) / drainTargetMs
+  return clamp(Math.max(settleCps, overflowCps), config.flushCps, config.maxFlushCps)
+}
+
+/**
+ * Drain rate multiplier once the input ends: leftover backlog reveals at
+ * this multiple of the steady rate, so the end never drags.
+ */
+export const SETTLE_DRAIN_MULTIPLIER = 1.8
+
+export interface RevealStepInput {
+  readonly backlog: number
+  readonly chunkSizeEma: number
+  readonly arrivalCpsEma: number
+  readonly emaCps: number
+  readonly inputActive: boolean
+  readonly settling: boolean
+  /** Fixed reveal rate; overrides the arrival-tracking cadence entirely. */
+  readonly steadyCps?: number | undefined
+}
+
+export interface RevealStepResult {
+  readonly revealChars: number
+  readonly targetLagChars: number
+}
+
+/** Pure per-frame reveal decision shared by the loop and its tests. */
+export function computeRevealStep(config: ConversationSmoothingPresetConfig, input: RevealStepInput, dtSeconds: number): RevealStepResult {
+  // Track the faster of the two EMAs and do not clamp to the old low maxCps
+  // ceiling — that cap is why a fast model left hundreds of chars unrevealed.
+  const trackedCps = Math.max(input.emaCps, input.arrivalCpsEma)
+  const baseCps = clamp(trackedCps, config.minCps, config.maxFlushCps)
+  const targetLagChars = input.inputActive
+    ? Math.max(2, Math.round((baseCps * config.targetBufferMs) / 1000))
+    : 0
+
+  let currentCps: number
+  if (input.steadyCps !== undefined) {
+    currentCps = input.inputActive || input.settling
+      ? clamp(
+        input.steadyCps * (input.inputActive ? 1 : SETTLE_DRAIN_MULTIPLIER),
+        config.minCps,
+        config.maxFlushCps,
+      )
+      : 0
+  } else if (input.inputActive) {
+    const overflow = Math.max(0, input.backlog - LIVE_LAG_CHAR_CEILING)
+    const catchup = overflow > 0 ? overflow / CATCHUP_SECONDS : 0
+    currentCps = clamp(baseCps * 1.08 + catchup, config.minCps, config.maxFlushCps)
+  } else if (input.settling) {
+    currentCps = computeSettleDrain(config, input)
+  } else {
+    const idleFlushCps = Math.max(config.flushCps, baseCps * 1.8, input.arrivalCpsEma * 0.8)
+    currentCps = clamp(idleFlushCps, config.flushCps, config.maxFlushCps)
+  }
+
+  const minRevealChars = input.inputActive ? 1 : 2
+  return { revealChars: Math.max(minRevealChars, Math.round(currentCps * dtSeconds)), targetLagChars }
+}
+
+export interface UseConversationContentOptions {
+  enabled?: boolean
+  preset?: ConversationSmoothingPreset
+  /** Performance guard veto: while true, reveal commits are held back. */
+  shouldHoldBack?: (() => boolean) | undefined
+  /**
+   * Fixed reveal rate in chars/s. When set, the reveal runs at this steady
+   * pace while the input streams (instead of tracking the arrival rate) and
+   * drains the leftover backlog at {@link SETTLE_DRAIN_MULTIPLIER} once the
+   * input ends.
+   */
+  steadyCps?: number | undefined
+  /**
+   * Seed for the arrival-rate EMA. When omitted, the preset's `defaultCps`
+   * is used. The live rate then tracks observed arrival; this is not a cap.
+   */
+  defaultCps?: number | undefined
+  /** Written each commit with the live arrival-rate EMA for the follow lerp. */
+  speedCpsRef?: { current: number } | undefined
+}
+
+/**
+ * Smooth a chunked content stream into a reveal-paced display string.
+ *
+ * @param content - The full accumulated input so far.
+ * @param options - Preset, guard, and steady-rate wiring.
+ * @returns The displayed content, revealed at the smoothed cadence.
+ */
+export function useConversationContent(
+  content: string,
+  { enabled = true, preset = 'balanced', shouldHoldBack, steadyCps, defaultCps, speedCpsRef }: UseConversationContentOptions = {},
+): string {
+  const config = PRESET_CONFIG[preset]
+  const seedCps = defaultCps ?? config.defaultCps
+  const [displayedContent, setDisplayedContent] = useState(content)
+
+  const displayedContentRef = useRef(content)
+  const displayedCountRef = useRef(countChars(content))
+  const targetContentRef = useRef(content)
+  const targetCharsRef = useRef(splitGraphemes(content))
+  const targetCountRef = useRef(countChars(content))
+
+  const emaCpsRef = useRef(seedCps)
+  const lastInputTsRef = useRef(0)
+  const lastInputCountRef = useRef(countChars(content))
+  const chunkSizeEmaRef = useRef(1)
+  const arrivalCpsEmaRef = useRef(seedCps)
+
+  const rafRef = useRef<number | null>(null)
+  const lastFrameTsRef = useRef<number | null>(null)
+  const wakeTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const holdBackRef = useRef(shouldHoldBack)
+  const speedOutRef = useRef(speedCpsRef)
+  speedOutRef.current = speedCpsRef
+
+  useEffect(() => {
+    holdBackRef.current = shouldHoldBack
+  }, [shouldHoldBack])
+
+  const clearWakeTimer = useCallback(() => {
+    if (wakeTimerRef.current !== null) {
+      clearTimeout(wakeTimerRef.current)
+      wakeTimerRef.current = null
+    }
+  }, [])
+
+  const stopFrameLoop = useCallback(() => {
+    if (rafRef.current !== null) {
+      cancelAnimationFrame(rafRef.current)
+      rafRef.current = null
+    }
+    lastFrameTsRef.current = null
+  }, [])
+
+  const stopScheduling = useCallback(() => {
+    stopFrameLoop()
+    clearWakeTimer()
+  }, [clearWakeTimer, stopFrameLoop])
+
+  const startFrameLoopRef = useRef<() => void>(() => {})
+
+  const scheduleFrameWake = useCallback(
+    (delayMs: number) => {
+      clearWakeTimer()
+      wakeTimerRef.current = setTimeout(
+        () => {
+          wakeTimerRef.current = null
+          startFrameLoopRef.current()
+        },
+        Math.max(1, Math.ceil(delayMs)),
+      )
+    },
+    [clearWakeTimer],
+  )
+
+  const syncImmediate = useCallback(
+    (nextContent: string) => {
+      stopScheduling()
+      const chars = splitGraphemes(nextContent)
+      const now = performance.now()
+      targetContentRef.current = nextContent
+      targetCharsRef.current = chars
+      targetCountRef.current = chars.length
+      displayedContentRef.current = nextContent
+      displayedCountRef.current = chars.length
+      setDisplayedContent(nextContent)
+      emaCpsRef.current = seedCps
+      chunkSizeEmaRef.current = 1
+      arrivalCpsEmaRef.current = seedCps
+      lastInputTsRef.current = now
+      lastInputCountRef.current = chars.length
+    },
+    [seedCps, stopScheduling],
+  )
+
+  const startFrameLoop = useCallback(() => {
+    clearWakeTimer()
+    if (rafRef.current !== null) return
+
+    const tick = () => {
+      const targetCount = targetCountRef.current
+      const displayedCount = displayedCountRef.current
+      const backlog = targetCount - displayedCount
+
+      if (backlog <= 0) {
+        stopFrameLoop()
+        return
+      }
+
+      const now = performance.now()
+      if (lastFrameTsRef.current === null) {
+        lastFrameTsRef.current = now
+        rafRef.current = requestAnimationFrame(tick)
+        return
+      }
+
+      const commitIntervalMs = Math.min(MAX_COMMIT_INTERVAL_MS, config.minCommitIntervalMs)
+      const frameIntervalMs = Math.max(0, now - lastFrameTsRef.current)
+      if (frameIntervalMs < commitIntervalMs) {
+        rafRef.current = requestAnimationFrame(tick)
+        return
+      }
+
+      const dtSeconds = Math.max(0.001, Math.min(frameIntervalMs / 1000, 0.12))
+      lastFrameTsRef.current = now
+
+      const idleMs = now - lastInputTsRef.current
+      const inputActive = idleMs <= config.activeInputWindowMs
+      const settling = !inputActive && idleMs >= config.settleAfterMs
+
+      let revealChars: number
+      if (steadyCps !== undefined) {
+        const step = computeRevealStep(
+          config,
+          {
+            backlog,
+            chunkSizeEma: chunkSizeEmaRef.current,
+            arrivalCpsEma: arrivalCpsEmaRef.current,
+            emaCps: emaCpsRef.current,
+            inputActive,
+            settling,
+            steadyCps,
+          },
+          dtSeconds,
+        )
+        revealChars = Math.min(step.revealChars, backlog)
+      } else {
+        // Same rAF queue drain as the silky markdown demo.
+        revealChars = computeQueueReveal(backlog, frameIntervalMs)
+      }
+
+      // Performance guard: while degraded and the reply is offscreen, skip
+      // the DOM commit — the backlog keeps accumulating and flushes when the
+      // guard clears or the reply scrolls into view.
+      if (holdBackRef.current?.() === true) {
+        rafRef.current = requestAnimationFrame(tick)
+        return
+      }
+
+      const speedOut = speedOutRef.current
+      if (speedOut !== undefined && frameIntervalMs > 0) {
+        const instantCps = (revealChars * 1000) / frameIntervalMs
+        speedOut.current = speedOut.current * 0.92 + instantCps * 0.08
+      }
+
+      const nextCount = displayedCount + revealChars
+      const segment = targetCharsRef.current.slice(displayedCount, nextCount).join('')
+      if (segment) {
+        const nextDisplayed = displayedContentRef.current + segment
+        displayedContentRef.current = nextDisplayed
+        displayedCountRef.current = nextCount
+        setDisplayedContent(nextDisplayed)
+      } else {
+        displayedContentRef.current = targetContentRef.current
+        displayedCountRef.current = targetCount
+        setDisplayedContent(targetContentRef.current)
+      }
+
+      rafRef.current = requestAnimationFrame(tick)
+    }
+
+    rafRef.current = requestAnimationFrame(tick)
+  }, [config, scheduleFrameWake, stopFrameLoop, clearWakeTimer, steadyCps])
+
+  useEffect(() => {
+    startFrameLoopRef.current = startFrameLoop
+  }, [startFrameLoop])
+
+  useEffect(() => {
+    if (!enabled) {
+      syncImmediate(content)
+      return
+    }
+
+    const prevTargetContent = targetContentRef.current
+    if (content === prevTargetContent) return
+
+    const now = performance.now()
+    const appendOnly = content.startsWith(prevTargetContent)
+
+    if (!appendOnly) {
+      syncImmediate(content)
+      return
+    }
+
+    const appended = content.slice(prevTargetContent.length)
+    const appendedChars = splitGraphemes(appended)
+    const appendedCount = appendedChars.length
+
+    targetContentRef.current = content
+    targetCharsRef.current.push(...appendedChars)
+    targetCountRef.current += appendedCount
+
+    const hadSample = lastInputTsRef.current > 0
+    const deltaChars = targetCountRef.current - lastInputCountRef.current
+    const deltaMs = Math.max(1, now - lastInputTsRef.current)
+
+    // Skip the first sample: lastInputTs starts at 0, so the interval would
+    // be "time since page load" (or 1ms under fake timers) and poison the EMA.
+    if (hadSample && deltaChars > 0) {
+      const instantCps = (deltaChars * 1000) / deltaMs
+      const normalizedInstantCps = clamp(instantCps, config.minCps, config.maxFlushCps * 3)
+      const chunkEmaAlpha = 0.45
+      chunkSizeEmaRef.current = chunkSizeEmaRef.current * (1 - chunkEmaAlpha) + appendedCount * chunkEmaAlpha
+      arrivalCpsEmaRef.current = arrivalCpsEmaRef.current * (1 - chunkEmaAlpha) + normalizedInstantCps * chunkEmaAlpha
+      emaCpsRef.current = emaCpsRef.current * (1 - config.emaAlpha) + normalizedInstantCps * config.emaAlpha
+    }
+
+    lastInputTsRef.current = now
+    lastInputCountRef.current = targetCountRef.current
+
+    startFrameLoop()
+  }, [content, enabled, config, startFrameLoop, syncImmediate])
+
+  useEffect(() => {
+    return () => {
+      stopScheduling()
+    }
+  }, [stopScheduling])
+
+  return displayedContent
+}