dsh-smooth-stream 0.3.2 → 0.3.3

package/src/client/useProgressiveDomText.ts

@@ -0,0 +1,206 @@
+/**
+ * Progressive text reveal for opaque Agent renderers.
+ *
+ * Slot renderers own arbitrary React trees, so the generic integration cannot
+ * clone or classify their business components. This hook leaves that tree and
+ * all of its event handlers in place, and only paces visible Text node data
+ * while the row belongs to the live Agent turn. No clip, mask, overlay, or
+ * duplicate accessibility tree is introduced.
+ */
+
+import { useLayoutEffect, type RefObject } from 'react'
+import { computeAdaptiveQueueStep } from './useSmoothStreamContent.ts'
+
+interface TextRevealRecord {
+  chars: readonly string[]
+  full: string
+  shown: number
+}
+
+const SKIP_TEXT_SELECTOR = [
+  '[aria-hidden="true"]',
+  '[aria-live]',
+  '[contenteditable="true"]',
+  'script',
+  'style',
+  'textarea',
+].join(',')
+
+function revealable(node: Text, root: HTMLElement): boolean {
+  if (node.data.trim() === '') return false
+  const parent = node.parentElement
+  return parent !== null
+    && root.contains(parent)
+    && parent.closest(SKIP_TEXT_SELECTOR) === null
+}
+
+function commonPrefix(left: readonly string[], right: readonly string[]): number {
+  const limit = Math.min(left.length, right.length)
+  let index = 0
+  while (index < limit && left[index] === right[index]) index += 1
+  return index
+}
+
+/**
+ * Pace text inside a renderer whose React component is intentionally opaque.
+ * Initial content is revealed only for a genuinely new row; later mutations
+ * stay paced until `enabled` becomes false, at which point the full renderer
+ * content is restored synchronously before paint.
+ */
+export function useProgressiveDomText(
+  rootRef: RefObject<HTMLElement | null>,
+  enabled: boolean,
+  revealInitial: boolean,
+  speedCpsRef: { current: number },
+  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>()
+    const pending = new Set<Text>()
+    const internalWrites = new WeakMap<Text, string>()
+    let rafId = 0
+    let lastFrame: number | null = null
+    let debt = 0
+    let stopped = false
+    let announcedSettled = false
+
+    const announceSettled = (): void => {
+      lastFrame = null
+      debt = 0
+      speedCpsRef.current = 35
+      if (announcedSettled) return
+      announcedSettled = true
+      onSettled?.()
+    }
+
+    const write = (node: Text, value: string): void => {
+      if (node.data === value) return
+      internalWrites.set(node, value)
+      node.data = value
+    }
+
+    const enqueue = (node: Text, full: string, preserve: TextRevealRecord | undefined): void => {
+      if (!revealable(node, root)) return
+      const chars = [...full]
+      const preserved = preserve === undefined
+        ? 0
+        : Math.min(preserve.shown, commonPrefix(preserve.chars, chars))
+      const record = { chars, full, shown: preserved }
+      records.set(node, record)
+      if (preserved < chars.length) {
+        pending.add(node)
+        announcedSettled = false
+      } else {
+        pending.delete(node)
+      }
+      write(node, chars.slice(0, preserved).join(''))
+    }
+
+    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()
+      }
+    }
+
+    const scheduleFrame = (): void => {
+      if (stopped || pending.size === 0 || rafId !== 0) return
+      rafId = requestAnimationFrame(frame)
+    }
+
+    const frame = (now: number): void => {
+      rafId = 0
+      if (stopped) return
+      if (pending.size === 0) {
+        announceSettled()
+        return
+      }
+      announcedSettled = false
+      if (lastFrame === null) {
+        lastFrame = now
+        scheduleFrame()
+        return
+      }
+      const elapsed = Math.max(0, now - lastFrame)
+      lastFrame = now
+      let backlog = 0
+      for (const node of pending) {
+        const record = records.get(node)
+        if (record !== undefined) backlog += record.chars.length - record.shown
+      }
+      const step = computeAdaptiveQueueStep(backlog, elapsed, debt)
+      debt = step.debt
+      speedCpsRef.current = step.speedCps
+      let remaining = step.revealChars
+      for (const node of [...pending]) {
+        if (remaining <= 0) break
+        const record = records.get(node)
+        if (record === undefined || !node.isConnected) {
+          pending.delete(node)
+          continue
+        }
+        const amount = Math.min(remaining, record.chars.length - record.shown)
+        const shown = record.shown + amount
+        const next = { ...record, shown }
+        records.set(node, next)
+        write(node, next.chars.slice(0, shown).join(''))
+        remaining -= amount
+        if (shown >= next.chars.length) pending.delete(node)
+      }
+      if (pending.size === 0) announceSettled()
+      else scheduleFrame()
+    }
+
+    if (revealInitial) visit(root, true)
+
+    const observer = typeof MutationObserver === 'undefined'
+      ? null
+      : new MutationObserver((mutations) => {
+          for (const mutation of mutations) {
+            if (mutation.type === 'characterData') {
+              const node = mutation.target as Text
+              const expected = internalWrites.get(node)
+              if (expected === node.data) {
+                internalWrites.delete(node)
+                continue
+              }
+              enqueue(node, node.data, records.get(node))
+              continue
+            }
+            for (const added of mutation.addedNodes) visit(added, true)
+          }
+          if (pending.size === 0) announceSettled()
+          else scheduleFrame()
+        })
+    observer?.observe(root, { childList: true, characterData: true, subtree: true })
+    if (pending.size === 0) announceSettled()
+    else scheduleFrame()
+
+    return () => {
+      stopped = true
+      cancelAnimationFrame(rafId)
+      observer?.disconnect()
+      for (const [node, record] of records) {
+        const controlled = record.chars.slice(0, record.shown).join('')
+        // 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)
+      }
+      pending.clear()
+      speedCpsRef.current = 35
+    }
+  }, [enabled, onSettled, revealInitial, rootRef, speedCpsRef])
+}

package/src/client/useSmoothStreamContent.ts

@@ -13,7 +13,7 @@
  * competes with visible frames when the frame rate is degraded.
  */
 
-import { useCallback, useEffect, useRef, useState } from 'react'
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
 
 export type StreamSmoothingPreset = 'realtime' | 'balanced' | 'silky'
 
@@ -26,7 +26,6 @@ export interface StreamSmoothingPresetConfig {
   readonly maxActiveCps: number
   readonly maxCps: number
   readonly maxFlushCps: number
-  readonly minCommitIntervalMs: number
   readonly minCps: number
   readonly settleAfterMs: number
   readonly settleDrainMaxMs: number
@@ -44,7 +43,6 @@ export const PRESET_CONFIG: Record<StreamSmoothingPreset, StreamSmoothingPresetC
     maxActiveCps: 360,
     maxCps: 240,
     maxFlushCps: 480,
-    minCommitIntervalMs: 16,
     minCps: 24,
     settleAfterMs: 280,
     settleDrainMaxMs: 420,
@@ -60,7 +58,6 @@ export const PRESET_CONFIG: Record<StreamSmoothingPreset, StreamSmoothingPresetC
     maxActiveCps: 480,
     maxCps: 320,
     maxFlushCps: 640,
-    minCommitIntervalMs: 16,
     minCps: 32,
     settleAfterMs: 200,
     settleDrainMaxMs: 280,
@@ -76,7 +73,6 @@ export const PRESET_CONFIG: Record<StreamSmoothingPreset, StreamSmoothingPresetC
     maxActiveCps: 280,
     maxCps: 180,
     maxFlushCps: 400,
-    minCommitIntervalMs: 16,
     minCps: 20,
     settleAfterMs: 360,
     settleDrainMaxMs: 520,
@@ -85,10 +81,11 @@ export const PRESET_CONFIG: Record<StreamSmoothingPreset, StreamSmoothingPresetC
   },
 }
 
-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
+/** Pressure curve from the reference stream renderer. */
+export const QUEUE_BASE_SPEED_CPS = 90
+export const QUEUE_ACCEL_EXPONENT = 1.25
+export const QUEUE_PRESSURE_FACTOR = 0.85
+export const QUEUE_MAX_SPEED_CPS = 600
 /** 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
@@ -98,16 +95,38 @@ export const clamp = (value: number, min: number, max: number): number => {
 }
 
 /**
- * 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.
+ * Reference pressure-buffer reveal for a frame that starts without debt.
  * @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))))
+  return computeAdaptiveQueueStep(backlog, dtMs, 0).revealChars
+}
+
+export interface AdaptiveQueueStep {
+  readonly revealChars: number
+  readonly debt: number
+  readonly speedCps: number
+}
+
+/** Float-debt queue integration from `ultimate_stream_physics_scroller.html`. */
+export function computeAdaptiveQueueStep(
+  backlog: number,
+  dtMs: number,
+  debt: number,
+  revealScale = 1,
+): 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,
+  )
+  const effectiveScale = clamp(revealScale, 0.05, 1)
+  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 }
 }
 
 /** Counts user-perceived characters (code points), not UTF-16 units. */
@@ -148,6 +167,20 @@ export function computeSettleDrain(config: StreamSmoothingPresetConfig, input: S
   return clamp(Math.max(settleCps, overflowCps), config.flushCps, config.maxFlushCps)
 }
 
+/** Fixed velocity that closes a producer-complete queue within its deadline. */
+export function computeCompletionDrain(
+  config: StreamSmoothingPresetConfig,
+  backlog: number,
+): number {
+  if (backlog <= 0) return 0
+  const drainTargetMs = clamp(backlog * 8, config.settleDrainMinMs, config.settleDrainMaxMs)
+  const deadlineCps = (backlog * 1000) / drainTargetMs
+  return Math.max(
+    deadlineCps,
+    computeSettleDrain(config, { backlog, inputActive: false, settling: true }),
+  )
+}
+
 /**
  * Drain rate multiplier once the input ends: leftover backlog reveals at
  * this multiple of the steady rate, so the end never drags.
@@ -206,14 +239,16 @@ export function computeRevealStep(config: StreamSmoothingPresetConfig, input: Re
 
 export interface UseSmoothStreamContentOptions {
   enabled?: boolean
+  /** The producer has completed; drain queued text without live backpressure. */
+  inputComplete?: boolean
   preset?: StreamSmoothingPreset
   /** 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.
+   * drains an inferred idle backlog at {@link SETTLE_DRAIN_MULTIPLIER}.
+   * Explicit producer completion still uses the bounded completion drain.
    */
   steadyCps?: number | undefined
   /**
@@ -223,6 +258,8 @@ export interface UseSmoothStreamContentOptions {
   defaultCps?: number | undefined
   /** Written each commit with the live arrival-rate EMA for the follow lerp. */
   speedCpsRef?: { current: number } | undefined
+  /** Live multiplier from the follow spring when safe visual lag is filling. */
+  revealScaleRef?: { current: number } | undefined
 }
 
 /**
@@ -234,42 +271,53 @@ export interface UseSmoothStreamContentOptions {
  */
 export function useSmoothStreamContent(
   content: string,
-  { enabled = true, preset = 'balanced', shouldHoldBack, steadyCps, defaultCps, speedCpsRef }: UseSmoothStreamContentOptions = {},
+  {
+    enabled = true,
+    inputComplete = false,
+    preset = 'balanced',
+    shouldHoldBack,
+    steadyCps,
+    defaultCps,
+    speedCpsRef,
+    revealScaleRef,
+  }: UseSmoothStreamContentOptions = {},
 ): 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([...content])
-  const targetCountRef = useRef(countChars(content))
+  // A fast provider can fill the first Host render with a large batch. Start
+  // an enabled stream behind that batch so it still enters the reveal queue;
+  // disabled (settled/history) content must remain immediate.
+  const initialContent = enabled ? '' : content
+  const [displayedContent, setDisplayedContent] = useState(initialContent)
+
+  const displayedContentRef = useRef(initialContent)
+  const displayedCountRef = useRef(countChars(initialContent))
+  const targetContentRef = useRef(initialContent)
+  const targetCharsRef = useRef([...initialContent])
+  const targetCountRef = useRef(countChars(initialContent))
 
   const emaCpsRef = useRef(seedCps)
   const lastInputTsRef = useRef(0)
-  const lastInputCountRef = useRef(countChars(content))
+  const lastInputCountRef = useRef(countChars(initialContent))
   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 queueDebtRef = useRef(0)
+  const settleCpsRef = useRef<number | null>(null)
   const holdBackRef = useRef(shouldHoldBack)
   const speedOutRef = useRef(speedCpsRef)
   speedOutRef.current = speedCpsRef
+  const revealScaleOutRef = useRef(revealScaleRef)
+  revealScaleOutRef.current = revealScaleRef
+  const inputCompleteRef = useRef(inputComplete)
+  inputCompleteRef.current = inputComplete
 
   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)
@@ -278,30 +326,11 @@ export function useSmoothStreamContent(
     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()
+      stopFrameLoop()
       const chars = [...nextContent]
       const now = performance.now()
       targetContentRef.current = nextContent
@@ -309,6 +338,10 @@ export function useSmoothStreamContent(
       targetCountRef.current = chars.length
       displayedContentRef.current = nextContent
       displayedCountRef.current = chars.length
+      queueDebtRef.current = 0
+      settleCpsRef.current = null
+      const speedOut = speedOutRef.current
+      if (speedOut !== undefined) speedOut.current = seedCps
       setDisplayedContent(nextContent)
       emaCpsRef.current = seedCps
       chunkSizeEmaRef.current = 1
@@ -316,46 +349,66 @@ export function useSmoothStreamContent(
       lastInputTsRef.current = now
       lastInputCountRef.current = chars.length
     },
-    [seedCps, stopScheduling],
+    [seedCps, stopFrameLoop],
   )
 
+  // Producer completion is authoritative. Publish the accumulated source in
+  // the same commit instead of leaving a visible typewriter tail after the
+  // Agent has already stopped; the conversation follower still glides any
+  // resulting layout height before paint.
+  useLayoutEffect(() => {
+    if (!enabled || !inputComplete || displayedContentRef.current === content) return
+    syncImmediate(content)
+  }, [content, enabled, inputComplete, syncImmediate])
+
   const startFrameLoop = useCallback(() => {
-    clearWakeTimer()
     if (rafRef.current !== null) return
 
-    const tick = () => {
+    const tick = (now: number) => {
       const targetCount = targetCountRef.current
       const displayedCount = displayedCountRef.current
       const backlog = targetCount - displayedCount
 
       if (backlog <= 0) {
+        queueDebtRef.current = 0
+        settleCpsRef.current = null
+        const speedOut = speedOutRef.current
+        if (speedOut !== undefined) speedOut.current = seedCps
         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
+      const producerComplete = inputCompleteRef.current
+      const inputActive = !producerComplete && idleMs <= config.activeInputWindowMs
+      const settling = producerComplete || (!inputActive && idleMs >= config.settleAfterMs)
+      if (!producerComplete) settleCpsRef.current = null
 
       let revealChars: number
-      if (steadyCps !== undefined) {
+      let revealSpeedCps: number
+      let nextQueueDebt = 0
+      if (producerComplete) {
+        // Backpressure protects live layout. Once input has ended, retaining
+        // that scale only makes a completed response keep typing onscreen.
+        // Keep one drain velocity for the whole completion tail. Recomputing
+        // it from the shrinking backlog creates an exponential slow tail.
+        const settleCps = settleCpsRef.current ?? computeCompletionDrain(config, backlog)
+        settleCpsRef.current = settleCps
+        const accumulated = Math.max(0, queueDebtRef.current) + settleCps * dtSeconds
+        revealChars = Math.min(backlog, Math.floor(accumulated))
+        revealSpeedCps = settleCps
+        nextQueueDebt = revealChars >= backlog ? 0 : accumulated - revealChars
+      } else if (steadyCps !== undefined) {
         const step = computeRevealStep(
           config,
           {
@@ -370,9 +423,17 @@ export function useSmoothStreamContent(
           dtSeconds,
         )
         revealChars = Math.min(step.revealChars, backlog)
+        revealSpeedCps = frameIntervalMs > 0 ? (revealChars * 1000) / frameIntervalMs : 0
       } else {
-        // Same rAF queue drain as the silky markdown demo.
-        revealChars = computeQueueReveal(backlog, frameIntervalMs)
+        const step = computeAdaptiveQueueStep(
+          backlog,
+          frameIntervalMs,
+          queueDebtRef.current,
+          revealScaleOutRef.current?.current ?? 1,
+        )
+        revealChars = step.revealChars
+        revealSpeedCps = step.speedCps
+        nextQueueDebt = step.debt
       }
 
       // Performance guard: while degraded and the reply is offscreen, skip
@@ -383,10 +444,14 @@ export function useSmoothStreamContent(
         return
       }
 
+      queueDebtRef.current = nextQueueDebt
+
       const speedOut = speedOutRef.current
-      if (speedOut !== undefined && frameIntervalMs > 0) {
-        const instantCps = (revealChars * 1000) / frameIntervalMs
-        speedOut.current = speedOut.current * 0.92 + instantCps * 0.08
+      if (speedOut !== undefined) speedOut.current = revealSpeedCps
+
+      if (revealChars <= 0) {
+        rafRef.current = requestAnimationFrame(tick)
+        return
       }
 
       const nextCount = displayedCount + revealChars
@@ -406,7 +471,7 @@ export function useSmoothStreamContent(
     }
 
     rafRef.current = requestAnimationFrame(tick)
-  }, [config, scheduleFrameWake, stopFrameLoop, clearWakeTimer, steadyCps])
+  }, [config, stopFrameLoop, steadyCps])
 
   useEffect(() => {
     startFrameLoopRef.current = startFrameLoop
@@ -436,6 +501,7 @@ export function useSmoothStreamContent(
     targetContentRef.current = content
     targetCharsRef.current.push(...appendedChars)
     targetCountRef.current += appendedCount
+    settleCpsRef.current = null
 
     const hadSample = lastInputTsRef.current > 0
     const deltaChars = targetCountRef.current - lastInputCountRef.current
@@ -460,9 +526,9 @@ export function useSmoothStreamContent(
 
   useEffect(() => {
     return () => {
-      stopScheduling()
+      stopFrameLoop()
     }
-  }, [stopScheduling])
+  }, [stopFrameLoop])
 
   return displayedContent
 }

package/src/config.ts

@@ -7,12 +7,12 @@
 
 import type { StreamSmoothingPreset } from './client/useSmoothStreamContent.ts'
 
-/** Streaming render direction of the assistant node view. */
+/** Legacy render-mode value retained so existing overlays remain valid. */
 export type StreamMode = 'typewriter' | 'teleprompter'
 
 /** Plugin configuration validated by the Host schema and bridged to the browser half. */
 export interface StreamConfig {
-  /** Render direction: horizontal per-character reveal or uniform upward glide. */
+  /** Compatibility field; both values use the current adaptive reveal engine. */
   readonly mode: StreamMode
   /** Smoothing preset for the reveal cadence. */
   readonly preset: StreamSmoothingPreset
@@ -26,10 +26,7 @@ export interface StreamConfig {
    * smooth-damp, not a cruise speed.
    */
   readonly scrollSpeedPxPerSec: number
-  /**
-   * Follow velocity ceiling in CSS pixels per second, so a huge first lag
-   * does not teleport. Ordinary wraps stay well below this.
-   */
+  /** Unused at runtime; retained so existing overlays continue to load. */
   readonly maxScrollSpeedPxPerSec: number
 }