dsh-smooth-stream 0.3.4 → 0.4.0

package/src/client/teleprompterGlide.ts

@@ -27,6 +27,9 @@
  */
 
 import { useEffect, useLayoutEffect, useRef, type RefObject } from 'react'
+import { DEFAULT_STREAM_DEBUG_TUNING, type StreamDebugTuning } from '../settings.ts'
+import { debugRuntime } from './debugRuntime.ts'
+import { PROCESSED_CLASS } from './auto-collapse-controller.ts'
 
 /**
  * Programmatic follow marker retained for hosts that recognize external
@@ -115,7 +118,10 @@ const GESTURE_EVENTS = [
 ] as const
 
 /** Visible runway needed for the current reveal pressure. */
-export function computeFollowReserve(speedCps: number, runwayPx = FOLLOW_STATUS_RUNWAY_PX): number {
+export function computeFollowReserve(
+  speedCps: number,
+  runwayPx = FOLLOW_STATUS_RUNWAY_PX,
+): number {
   const available = Math.max(0, runwayPx)
   if (available <= 0) return 0
   if (speedCps <= FOLLOW_RESERVE_MIN_CPS) return 0
@@ -136,17 +142,18 @@ export function computeFollowRevealScale(
   lagPx: number,
   capacityPx: number,
   constrained = false,
+  tuning: StreamDebugTuning = DEFAULT_STREAM_DEBUG_TUNING,
 ): number {
-  if (constrained) return FOLLOW_REVEAL_MIN_SCALE
+  if (constrained) return tuning.backpressureMinScale
   if (!Number.isFinite(capacityPx)) return 1
-  if (capacityPx <= 0) return lagPx > 0 ? FOLLOW_REVEAL_MIN_SCALE : 1
+  if (capacityPx <= 0) return lagPx > 0 ? tuning.backpressureMinScale : 1
   const ratio = Math.min(1, Math.max(0, lagPx / capacityPx))
-  if (ratio >= FOLLOW_BACKPRESSURE_FULL_RATIO) return FOLLOW_REVEAL_MIN_SCALE
+  if (ratio >= FOLLOW_BACKPRESSURE_FULL_RATIO) return tuning.backpressureMinScale
   const progress = Math.min(1, Math.max(0, (
     ratio - FOLLOW_BACKPRESSURE_START_RATIO
   ) / (FOLLOW_BACKPRESSURE_FULL_RATIO - FOLLOW_BACKPRESSURE_START_RATIO)))
   const eased = progress * progress * (3 - 2 * progress)
-  return 1 - (1 - FOLLOW_REVEAL_MIN_SCALE) * eased
+  return 1 - (1 - tuning.backpressureMinScale) * eased
 }
 
 export interface FollowGlideInput {
@@ -173,7 +180,11 @@ export interface FollowGlideStep {
  * @param input - Current visible lag and carried physics velocity.
  * @returns The position advance, its fraction, and next velocity.
  */
-export function computeFollowStep(dtMs: number, input: FollowGlideInput): FollowGlideStep {
+export function computeFollowStep(
+  dtMs: number,
+  input: FollowGlideInput,
+  tuning: StreamDebugTuning = DEFAULT_STREAM_DEBUG_TUNING,
+): FollowGlideStep {
   if (input.lag <= 0.1 || dtMs <= 0) {
     return { advancePx: 0, lerpStep: 0, velocityPxPerSec: 0 }
   }
@@ -186,8 +197,8 @@ export function computeFollowStep(dtMs: number, input: FollowGlideInput): Follow
   for (let slice = 0; slice < slices; slice += 1) {
     for (let substep = 0; substep < FOLLOW_SPRING_SUBSTEPS; substep += 1) {
       const acceleration = (
-        FOLLOW_SPRING_STIFFNESS * lag - FOLLOW_SPRING_DAMPING * velocity
-      ) / FOLLOW_SPRING_MASS
+      tuning.springStiffness * lag - tuning.springDamping * velocity
+    ) / tuning.springMass
       velocity = Math.max(0, velocity + acceleration * subDt)
       const advance = velocity * subDt
       if (advance >= lag) {
@@ -207,10 +218,14 @@ function resizeProxyOf(port: HTMLElement): HTMLElement | null {
 }
 
 /** Outermost message surfaces; nested tool rows ride their parent. */
-function shiftSurfacesOf(port: HTMLElement): HTMLElement[] {
+/** @internal Test seam: the equal-lag transform set for one scrollport. */
+export function shiftSurfacesOf(port: HTMLElement): HTMLElement[] {
   const transcript = port.querySelector<HTMLElement>('[data-chat-transcript]')
   if (transcript !== null) return [transcript]
-  return [...port.querySelectorAll<HTMLElement>('[data-chat-anchor-key]')]
+  // Fold summary rows are plugin-injected flow children without an anchor
+  // key; they must ride the same lag transform as native rows, otherwise
+  // they visibly detach from their neighbours on every follow frame.
+  return [...port.querySelectorAll<HTMLElement>(`[data-chat-anchor-key], .${PROCESSED_CLASS}`)]
     .filter(row => row.parentElement?.closest('[data-chat-anchor-key]') === null)
 }
 
@@ -267,6 +282,7 @@ interface FollowRunway {
   readonly offset: number
   readonly original: string
   readonly property: 'marginBottom' | 'marginTop'
+  readonly requestedPx: number
 }
 
 /**
@@ -369,7 +385,11 @@ function migrateLegacyRunway(
   if (migrated) invalidatePaintLimit(port)
 }
 
-function ensureRunway(port: HTMLElement, surfaces: readonly HTMLElement[]): void {
+function ensureRunway(
+  port: HTMLElement,
+  surfaces: readonly HTMLElement[],
+  runwayPx = FOLLOW_STATUS_RUNWAY_PX,
+): void {
   const status = turnStatusOf(port)
   const composer = port.querySelector<HTMLElement>('[data-composer-seat]')
   migrateLegacyRunway(port, surfaces, status, composer)
@@ -378,7 +398,7 @@ function ensureRunway(port: HTMLElement, surfaces: readonly HTMLElement[]): void
   // applyVisual keeps every surface in normal flow, so adding status margin
   // would expose the whole runway as empty space below a short/early Think.
   const naturalHeight = Math.max(0, port.scrollHeight - runwayOffsetOf(port))
-  if (port.clientHeight <= 0 || naturalHeight <= port.clientHeight) {
+  if (runwayPx <= 0 || port.clientHeight <= 0 || naturalHeight <= port.clientHeight) {
     restoreRunway(port)
     return
   }
@@ -391,15 +411,17 @@ function ensureRunway(port: HTMLElement, surfaces: readonly HTMLElement[]): void
   }
   const element = target.element
   const current = followRunways.get(port)
-  if (current?.element === element && current.property === target.property) return
+  if (current?.element === element
+    && current.property === target.property
+    && current.requestedPx === runwayPx) return
   restoreRunway(port)
   const beforeHeight = port.scrollHeight
   const original = element.style[target.property]
   element.style[target.property] = original === ''
-    ? `${FOLLOW_STATUS_RUNWAY_PX}px`
-    : `calc(${original} + ${FOLLOW_STATUS_RUNWAY_PX}px)`
+    ? `${runwayPx}px`
+    : `calc(${original} + ${runwayPx}px)`
   const offset = Math.max(0, port.scrollHeight - beforeHeight)
-  followRunways.set(port, { element, offset, property: target.property, original })
+  followRunways.set(port, { element, offset, property: target.property, original, requestedPx: runwayPx })
   invalidatePaintLimit(port)
 }
 
@@ -499,9 +521,10 @@ function applyVisual(
   animatedH: number,
   reservePx: number,
   velocityPxPerSec = 0,
+  runwayPx = FOLLOW_STATUS_RUNWAY_PX,
 ): number {
   const surfaces = shiftSurfacesOf(port)
-  ensureRunway(port, surfaces)
+  ensureRunway(port, surfaces, runwayPx)
   const contentHeight = Math.max(0, port.scrollHeight)
   const runwayOffset = runwayOffsetOf(port)
   const targetHeight = Math.max(0, contentHeight - runwayOffset)
@@ -680,11 +703,12 @@ export function useConversationFollow(
 
     const updateRevealScale = (next: HTMLElement, elapsedMs: number, urgent = false): void => {
       if (revealScaleRef === undefined) return
+      const tuning = debugRuntime.activeTuning()
       const state = followMotionStates.get(next)
       const target = state === undefined
         ? 1
-        : computeFollowRevealScale(state.lagPx, state.capacityPx, state.constrained)
-      const current = Math.min(1, Math.max(FOLLOW_REVEAL_MIN_SCALE, revealScaleRef.current))
+        : computeFollowRevealScale(state.lagPx, state.capacityPx, state.constrained, tuning)
+      const current = Math.min(1, Math.max(tuning.backpressureMinScale, revealScaleRef.current))
       if (target < current || urgent) {
         // Slowing affects only future glyph commits, so it can react at once
         // without producing a visual discontinuity in the current frame.
@@ -699,6 +723,23 @@ export function useConversationFollow(
       if (revealScaleRef !== undefined) revealScaleRef.current = 1
     }
 
+    const reportFollow = (next: HTMLElement, isActive: boolean): void => {
+      const state = followMotionStates.get(next)
+      debugRuntime.reportFollow(next, {
+        lagPx: state?.lagPx ?? Math.max(0, next.scrollHeight - next.clientHeight - next.scrollTop),
+        velocityPxPerSec: state?.velocityPxPerSec ?? 0,
+        reservePx: state?.reservePx ?? 0,
+        capacityPx: state?.capacityPx ?? 0,
+        revealScale: revealScaleRef?.current ?? 1,
+        following,
+        constrained: state?.constrained ?? false,
+        scrollTop: next.scrollTop,
+        scrollHeight: next.scrollHeight,
+        clientHeight: next.clientHeight,
+        active: isActive,
+      })
+    }
+
     const isLeader = (next: HTMLElement): boolean => followLeaders.get(next)?.owner === owner
 
     const hold = (next: HTMLElement): void => {
@@ -717,12 +758,19 @@ export function useConversationFollow(
         clearMotion(next)
         followMotionStates.delete(next)
         releaseRevealScale()
+        debugRuntime.reportFollow(next, null)
       }
     }
 
     const handBackVisual = (next: HTMLElement): void => {
       const shift = currentShiftOf(shiftSurfacesOf(next).at(-1) ?? next)
       const visualTop = Math.max(0, next.scrollTop - Math.max(0, shift))
+      // The predictive runway only has meaning while this follower owns the
+      // floor. Remove it before choosing the reader's landing point; keeping
+      // it through the release paints a transient natural gap + 48px blank
+      // block until the next follow frame restores an equal transform.
+      clearMotion(next)
+      restoreRunway(next)
       const floor = Math.max(0, next.scrollHeight - next.clientHeight)
       // The host keeps its own bottom-follow bit while the reader remains in
       // its 25px slack band. Land one pixel beyond that band so even a light
@@ -760,8 +808,10 @@ export function useConversationFollow(
     const restoreBeforePaint = (): void => {
       if (!following || port === null || !isLeader(port)) return
       invalidatePaintLimit(port)
-      animatedH = applyVisual(port, animatedH, reservePx, velocityPxPerSec)
+      const tuning = debugRuntime.activeTuning()
+      animatedH = applyVisual(port, animatedH, reservePx, velocityPxPerSec, tuning.runwayPx)
       updateRevealScale(port, 0, true)
+      reportFollow(port, activeRef.current)
     }
 
     const bindPort = (next: HTMLElement): void => {
@@ -790,6 +840,7 @@ export function useConversationFollow(
       // frames would open paint room more slowly precisely when it is needed.
       const elapsedMs = Math.max(0.001, now - last)
       const dt = Math.min(FOLLOW_MAX_FRAME_MS, elapsedMs)
+      const tuning = debugRuntime.activeTuning()
       last = now
       const root = rootRef.current
       if (root === null) return
@@ -836,8 +887,9 @@ export function useConversationFollow(
         if (following) {
           hold(nextPort)
           if (isLeader(nextPort)) {
-            animatedH = applyVisual(nextPort, animatedH, reservePx, velocityPxPerSec)
+            animatedH = applyVisual(nextPort, animatedH, reservePx, velocityPxPerSec, tuning.runwayPx)
             updateRevealScale(nextPort, elapsedMs)
+            reportFollow(nextPort, activeRef.current)
             const runwayOffset = runwayOffsetOf(nextPort)
             const entranceLag = Math.max(0, nextPort.scrollHeight - animatedH - runwayOffset)
             if (entranceLag <= FOLLOW_SETTLE_EPSILON_PX) finishEntrance()
@@ -852,7 +904,10 @@ export function useConversationFollow(
       }
 
       const repinSlack = readerReleased ? FOLLOW_REPIN_PX : FOLLOW_SLACK_PX
-      if (!following && !interacting && reportedLag <= repinSlack) {
+      const returnedToFloor = readerReleased
+        && !readerGestureIntent
+        && reportedLag <= FOLLOW_REPIN_PX
+      if (!following && (!interacting || returnedToFloor) && reportedLag <= repinSlack) {
         following = true
         readerReleased = false
         animatedH = extent
@@ -876,6 +931,7 @@ export function useConversationFollow(
 
       if (!activeRef.current || !following) {
         followScrollLedgers.set(nextPort, nextPort.scrollTop)
+        reportFollow(nextPort, activeRef.current)
         return
       }
       hold(nextPort)
@@ -893,14 +949,14 @@ export function useConversationFollow(
       const predictGrowth = predictiveRef?.current ?? predictive
       const reserveTarget = !predictGrowth
         ? 0
-        : computeFollowReserve(speedCpsRef.current, runwayOffset)
-      const reserveStep = 1 - Math.exp(-elapsedMs / FOLLOW_RESERVE_RESPONSE_MS)
+        : computeFollowReserve(speedCpsRef.current, tuning.runwayPx)
+      const reserveStep = 1 - Math.exp(-elapsedMs / tuning.reserveResponseMs)
       reservePx += (reserveTarget - reservePx) * reserveStep
       const step = computeFollowStep(dt, {
         lag,
         speedEma: speedCpsRef.current,
         velocityPxPerSec,
-      })
+      }, tuning)
       if (lag <= 0.1) {
         animatedH = contentHeight - runwayOffset
         velocityPxPerSec = 0
@@ -912,8 +968,9 @@ export function useConversationFollow(
         )
         velocityPxPerSec = step.velocityPxPerSec
       }
-      animatedH = applyVisual(nextPort, animatedH, reservePx, velocityPxPerSec)
+      animatedH = applyVisual(nextPort, animatedH, reservePx, velocityPxPerSec, tuning.runwayPx)
       updateRevealScale(nextPort, elapsedMs)
+      reportFollow(nextPort, true)
       const remainingEntranceLag = Math.max(
         0,
         nextPort.scrollHeight - animatedH - runwayOffsetOf(nextPort),
@@ -943,6 +1000,7 @@ export function useConversationFollow(
         clearVisual(host)
         followLeaders.delete(host)
         releaseRevealScale()
+        debugRuntime.reportFollow(host, null)
         return
       }
       if (preserveReader) {
@@ -950,13 +1008,15 @@ export function useConversationFollow(
         clearVisual(host)
         followLeaders.delete(host)
         releaseRevealScale()
+        debugRuntime.reportFollow(host, null)
         return
       }
 
       // Completion can land the final Tool/command height in this same
       // commit. Preserve the logical extent and drain it after unmount instead
       // of clearing the compositor state before the first settled paint.
-      ensureRunway(host, shiftSurfacesOf(host))
+      const completionTuning = debugRuntime.activeTuning()
+      ensureRunway(host, shiftSurfacesOf(host), completionTuning.runwayPx)
       const completionRunway = runwayOffsetOf(host)
       const completionMinimumLag = Math.max(0, reservePx)
       animatedH = Math.min(
@@ -964,13 +1024,15 @@ export function useConversationFollow(
         host.scrollHeight - completionRunway - completionMinimumLag,
       )
       settleAtFloor(host)
-      animatedH = applyVisual(host, animatedH, reservePx, velocityPxPerSec)
+      animatedH = applyVisual(host, animatedH, reservePx, velocityPxPerSec, completionTuning.runwayPx)
+      reportFollow(host, false)
       const runwayOffset = runwayOffsetOf(host)
       const remainingLag = Math.max(0, host.scrollHeight - animatedH - runwayOffset)
       if (remainingLag <= FOLLOW_SETTLE_EPSILON_PX && reservePx <= FOLLOW_SETTLE_EPSILON_PX) {
         finishAtNaturalFloor(host)
         followLeaders.delete(host)
         releaseRevealScale()
+        debugRuntime.reportFollow(host, null)
         return
       }
 
@@ -996,14 +1058,16 @@ export function useConversationFollow(
           clearVisual(host)
           followLeaders.delete(host)
           releaseRevealScale()
+          debugRuntime.reportFollow(host, null)
           stopSettleListeners()
           return
         }
         const dt = Math.min(FOLLOW_MAX_FRAME_MS, Math.max(0, now - settleLast))
+        const tuning = debugRuntime.activeTuning()
         settleLast = now
         const runwayOffset = runwayOffsetOf(host)
         const lag = Math.max(0, host.scrollHeight - animatedH - runwayOffset)
-        const reserveStep = 1 - Math.exp(-dt / FOLLOW_RESERVE_RESPONSE_MS)
+        const reserveStep = 1 - Math.exp(-dt / tuning.reserveResponseMs)
         reservePx += (0 - reservePx) * reserveStep
         if (lag <= FOLLOW_SETTLE_EPSILON_PX && reservePx <= FOLLOW_SETTLE_EPSILON_PX) {
           animatedH = host.scrollHeight - runwayOffset
@@ -1012,6 +1076,7 @@ export function useConversationFollow(
           finishAtNaturalFloor(host)
           followLeaders.delete(host)
           releaseRevealScale()
+          debugRuntime.reportFollow(host, null)
           stopSettleListeners()
           return
         }
@@ -1019,7 +1084,7 @@ export function useConversationFollow(
           lag,
           speedEma: speedCpsRef.current,
           velocityPxPerSec,
-        })
+        }, tuning)
         // The temporary runway is visually neutral only while an equal lag
         // remains in the transform. Do not let the spring outrun the runway's
         // closing reserve or cleanup would reveal an overshoot and rebound.
@@ -1030,7 +1095,8 @@ export function useConversationFollow(
         )
         velocityPxPerSec = step.velocityPxPerSec
         settleAtFloor(host)
-        animatedH = applyVisual(host, animatedH, reservePx, velocityPxPerSec)
+        animatedH = applyVisual(host, animatedH, reservePx, velocityPxPerSec, tuning.runwayPx)
+        reportFollow(host, false)
         requestAnimationFrame(settleFrame)
       }
       requestAnimationFrame(settleFrame)

package/src/client/useFpsGuard.ts

@@ -9,6 +9,7 @@
  */
 
 import { useCallback, useEffect, useRef } from 'react'
+import { debugRuntime } from './debugRuntime.ts'
 
 const FPS_THRESHOLD = 30
 const FPS_ALPHA = 0.12
@@ -33,6 +34,7 @@ export function useFpsGuard(active: boolean): {
   useEffect(() => {
     if (!active) return
     let rafId = 0
+    let lastDebugReport = 0
     const frame = (now: number) => {
       rafId = requestAnimationFrame(frame)
       const fps = fpsRef.current
@@ -51,11 +53,16 @@ export function useFpsGuard(active: boolean): {
         fps.healthyRun += 1
         if (fps.healthyRun >= RECOVER_FRAMES) fps.degraded = false
       }
+      if (now - lastDebugReport >= 100) {
+        debugRuntime.reportFps(currentFps, fps.emaMs, fps.degraded)
+        lastDebugReport = now
+      }
     }
     rafId = requestAnimationFrame(frame)
     return () => {
       cancelAnimationFrame(rafId)
       fpsRef.current = { emaMs: 0, lastMs: 0, healthyRun: 0, degraded: false }
+      debugRuntime.clearFps()
     }
   }, [active])
 

package/src/client/useProgressiveDomText.ts

@@ -10,6 +10,7 @@
 
 import { useLayoutEffect, type RefObject } from 'react'
 import { computeAdaptiveQueueStep } from './useSmoothStreamContent.ts'
+import { debugRuntime } from './debugRuntime.ts'
 
 interface TextRevealRecord {
   chars: readonly string[]
@@ -17,6 +18,9 @@ interface TextRevealRecord {
   shown: number
 }
 
+/** Last presented text per root, retained across follow lifecycle flips. */
+const ledgerByRoot = new WeakMap<HTMLElement, Map<Text, TextRevealRecord>>()
+
 const SKIP_TEXT_SELECTOR = [
   '[aria-hidden="true"]',
   '[aria-live]',
@@ -55,11 +59,58 @@ export function useProgressiveDomText(
   onSettled?: (() => void) | undefined,
 ): void {
   useLayoutEffect(() => {
-    if (!enabled) return
     const root = rootRef.current
     if (root === null || typeof document === 'undefined') return
 
-    const records = new Map<Text, TextRevealRecord>()
+    let records = ledgerByRoot.get(root)
+    if (!enabled && records === undefined) return
+    if (records === undefined) {
+      records = new Map<Text, TextRevealRecord>()
+      ledgerByRoot.set(root, records)
+    }
+
+    const forEachText = (from: Node, callback: (text: Text) => void): void => {
+      if (from.nodeType === Node.TEXT_NODE) {
+        callback(from as Text)
+        return
+      }
+      const walker = document.createTreeWalker(from, NodeFilter.SHOW_TEXT)
+      let current = walker.nextNode()
+      while (current !== null) {
+        callback(current as Text)
+        current = walker.nextNode()
+      }
+    }
+
+    const settle = (text: Text): void => {
+      if (!revealable(text, root)) return
+      const chars = [...text.data]
+      records.set(text, { chars, full: text.data, shown: chars.length })
+    }
+
+    const snapshotVisible = (): void => {
+      const current = new Set<Text>()
+      forEachText(root, (text) => {
+        if (!revealable(text, root)) return
+        current.add(text)
+        settle(text)
+      })
+      for (const text of records.keys()) {
+        if (!current.has(text)) records.delete(text)
+      }
+    }
+
+    if (!enabled) {
+      snapshotVisible()
+      const observer = typeof MutationObserver === 'undefined'
+        ? null
+        : new MutationObserver(snapshotVisible)
+      observer?.observe(root, { childList: true, characterData: true, subtree: true })
+      return () => {
+        observer?.disconnect()
+      }
+    }
+
     const pending = new Set<Text>()
     const internalWrites = new WeakMap<Text, string>()
     let rafId = 0
@@ -67,11 +118,13 @@ export function useProgressiveDomText(
     let debt = 0
     let stopped = false
     let announcedSettled = false
+    const streamId = `dom-${Math.random().toString(36).slice(2)}`
 
     const announceSettled = (): void => {
       lastFrame = null
       debt = 0
       speedCpsRef.current = 35
+      debugRuntime.reportStream(streamId, null)
       if (announcedSettled) return
       announcedSettled = true
       onSettled?.()
@@ -101,18 +154,22 @@ export function useProgressiveDomText(
     }
 
     const visit = (from: Node, reveal: boolean): void => {
-      if (from.nodeType === Node.TEXT_NODE) {
-        const text = from as Text
-        if (reveal) enqueue(text, text.data, records.get(text))
-        return
-      }
-      const walker = document.createTreeWalker(from, NodeFilter.SHOW_TEXT)
-      let current = walker.nextNode()
-      while (current !== null) {
-        const text = current as Text
-        if (reveal) enqueue(text, text.data, records.get(text))
-        current = walker.nextNode()
-      }
+      forEachText(from, (text) => {
+        if (!revealable(text, root)) return
+        if (reveal) {
+          enqueue(text, text.data, records.get(text))
+          return
+        }
+        settle(text)
+      })
+    }
+
+    const forget = (from: Node): void => {
+      forEachText(from, (text) => {
+        if (root.contains(text)) return
+        records.delete(text)
+        pending.delete(text)
+      })
     }
 
     const scheduleFrame = (): void => {
@@ -140,7 +197,7 @@ export function useProgressiveDomText(
         const record = records.get(node)
         if (record !== undefined) backlog += record.chars.length - record.shown
       }
-      const step = computeAdaptiveQueueStep(backlog, elapsed, debt)
+      const step = computeAdaptiveQueueStep(backlog, elapsed, debt, 1, debugRuntime.activeTuning())
       debt = step.debt
       speedCpsRef.current = step.speedCps
       let remaining = step.revealChars
@@ -149,6 +206,7 @@ export function useProgressiveDomText(
         const record = records.get(node)
         if (record === undefined || !node.isConnected) {
           pending.delete(node)
+          records.delete(node)
           continue
         }
         const amount = Math.min(remaining, record.chars.length - record.shown)
@@ -159,11 +217,31 @@ export function useProgressiveDomText(
         remaining -= amount
         if (shown >= next.chars.length) pending.delete(node)
       }
+      let targetChars = 0
+      let displayedChars = 0
+      let nextBacklog = 0
+      for (const [node, record] of records) {
+        if (!node.isConnected) {
+          records.delete(node)
+          pending.delete(node)
+          continue
+        }
+        targetChars += record.chars.length
+        displayedChars += record.shown
+        if (pending.has(node)) nextBacklog += record.chars.length - record.shown
+      }
+      debugRuntime.reportStream(streamId, {
+        backlog: nextBacklog,
+        speedCps: step.speedCps,
+        targetChars,
+        displayedChars,
+        active: pending.size > 0,
+      })
       if (pending.size === 0) announceSettled()
       else scheduleFrame()
     }
 
-    if (revealInitial) visit(root, true)
+    visit(root, revealInitial)
 
     const observer = typeof MutationObserver === 'undefined'
       ? null
@@ -179,6 +257,7 @@ export function useProgressiveDomText(
               enqueue(node, node.data, records.get(node))
               continue
             }
+            for (const removed of mutation.removedNodes) forget(removed)
             for (const added of mutation.addedNodes) visit(added, true)
           }
           if (pending.size === 0) announceSettled()
@@ -197,10 +276,13 @@ export function useProgressiveDomText(
         // React may have committed a terminal replacement in the same mutation
         // phase that disables this hook. Never overwrite that newer renderer
         // value with the previous controlled source during layout cleanup.
-        if (node.isConnected && node.data === controlled) write(node, record.full)
+        if (node.isConnected && node.data === controlled) {
+          write(node, record.full)
+        }
       }
       pending.clear()
       speedCpsRef.current = 35
+      debugRuntime.reportStream(streamId, null)
     }
   }, [enabled, onSettled, revealInitial, rootRef, speedCpsRef])
 }

package/src/client/useSmoothStreamContent.ts

@@ -14,6 +14,8 @@
  */
 
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
+import { DEFAULT_STREAM_DEBUG_TUNING, type StreamDebugTuning } from '../settings.ts'
+import { debugRuntime } from './debugRuntime.ts'
 
 export type StreamSmoothingPreset = 'realtime' | 'balanced' | 'silky'
 
@@ -117,13 +119,14 @@ export function computeAdaptiveQueueStep(
   dtMs: number,
   debt: number,
   revealScale = 1,
+  tuning: StreamDebugTuning = DEFAULT_STREAM_DEBUG_TUNING,
 ): AdaptiveQueueStep {
   if (backlog <= 0 || dtMs <= 0) return { revealChars: 0, debt: 0, speedCps: 0 }
   const speedCps = Math.min(
-    QUEUE_MAX_SPEED_CPS,
-    QUEUE_BASE_SPEED_CPS + Math.pow(backlog, QUEUE_ACCEL_EXPONENT) * QUEUE_PRESSURE_FACTOR,
+    tuning.maxRevealCps,
+    QUEUE_BASE_SPEED_CPS + Math.pow(backlog, QUEUE_ACCEL_EXPONENT) * tuning.queuePressure,
   )
-  const effectiveScale = clamp(revealScale, 0.05, 1)
+  const effectiveScale = clamp(revealScale * tuning.revealScale, 0.05, 2)
   const accumulated = Math.max(0, debt) + speedCps * effectiveScale * (dtMs / 1000)
   const revealChars = Math.min(backlog, Math.floor(accumulated))
   return { revealChars, debt: revealChars >= backlog ? 0 : accumulated - revealChars, speedCps }
@@ -313,6 +316,7 @@ export function useSmoothStreamContent(
   revealScaleOutRef.current = revealScaleRef
   const inputCompleteRef = useRef(inputComplete)
   inputCompleteRef.current = inputComplete
+  const streamIdRef = useRef(`stream-${Math.random().toString(36).slice(2)}`)
 
   useEffect(() => {
     holdBackRef.current = shouldHoldBack
@@ -374,6 +378,7 @@ export function useSmoothStreamContent(
         settleCpsRef.current = null
         const speedOut = speedOutRef.current
         if (speedOut !== undefined) speedOut.current = seedCps
+        debugRuntime.reportStream(streamIdRef.current, null)
         stopFrameLoop()
         return
       }
@@ -390,6 +395,7 @@ export function useSmoothStreamContent(
 
       const idleMs = now - lastInputTsRef.current
       const producerComplete = inputCompleteRef.current
+      const debugTuning = debugRuntime.activeTuning()
       const inputActive = !producerComplete && idleMs <= config.activeInputWindowMs
       const settling = producerComplete || (!inputActive && idleMs >= config.settleAfterMs)
       if (!producerComplete) settleCpsRef.current = null
@@ -422,7 +428,7 @@ export function useSmoothStreamContent(
           },
           dtSeconds,
         )
-        revealChars = Math.min(step.revealChars, backlog)
+        revealChars = Math.min(Math.round(step.revealChars * debugTuning.revealScale), backlog)
         revealSpeedCps = frameIntervalMs > 0 ? (revealChars * 1000) / frameIntervalMs : 0
       } else {
         const step = computeAdaptiveQueueStep(
@@ -430,12 +436,21 @@ export function useSmoothStreamContent(
           frameIntervalMs,
           queueDebtRef.current,
           revealScaleOutRef.current?.current ?? 1,
+          debugTuning,
         )
         revealChars = step.revealChars
         revealSpeedCps = step.speedCps
         nextQueueDebt = step.debt
       }
 
+      debugRuntime.reportStream(streamIdRef.current, {
+        backlog,
+        speedCps: revealSpeedCps,
+        targetChars: targetCount,
+        displayedChars: displayedCount,
+        active: !producerComplete,
+      })
+
       // 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.
@@ -527,6 +542,7 @@ export function useSmoothStreamContent(
   useEffect(() => {
     return () => {
       stopFrameLoop()
+      debugRuntime.reportStream(streamIdRef.current, null)
     }
   }, [stopFrameLoop])