dsh-smooth-stream 0.1.0

package/src/client/index.ts

@@ -0,0 +1,122 @@
+import { createElement, type ComponentType } from 'react'
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-client-locale/client'
+import type { ChatNodeViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { TypewriterAssistantNodeView } from './TypewriterAssistantNodeView.tsx'
+import { wrapFollowNodeView, type FollowWrapProps } from './TypewriterToolNodeView.tsx'
+import { DEFAULT_STREAM_CONFIG, STREAM_BOOT_GLOBAL, type StreamConfig } from '../config.ts'
+
+/** Cordis services required by the browser half. */
+export const inject = ['slots']
+
+type AssistantProps = ChatNodeViewProps<'assistant-step'>
+
+const STREAM_MODES: readonly string[] = ['typewriter', 'teleprompter']
+const STREAM_PRESETS: readonly string[] = ['realtime', 'balanced', 'silky']
+
+/** Human-authored rows stay on the built-in renderer; `assistant-step` is replaced. */
+const SKIP_WRAP = new Set(['assistant-step', 'user', 'steering', 'command-input'])
+
+/**
+ * Read the Host-bridged boot config. The inline script is produced by this
+ * plugin's Host half from a schema-validated value, so only the structural
+ * guarantees that could break between the two halves are re-checked: the
+ * global is absent when the client runs without its Host entry (defaults
+ * apply), and any present-but-malformed value fails loudly instead of
+ * rendering a half-configured view.
+ * @returns The resolved configuration for the assistant node view.
+ */
+function readBootConfig(): StreamConfig {
+  const raw = (globalThis as Record<string, unknown>)[STREAM_BOOT_GLOBAL]
+  if (raw === undefined) {
+    console.info('[dsh-smooth-stream] no host config bridge; using defaults')
+    return DEFAULT_STREAM_CONFIG
+  }
+  if (
+    typeof raw !== 'object' || raw === null
+    || !STREAM_MODES.includes((raw as StreamConfig).mode)
+    || !STREAM_PRESETS.includes((raw as StreamConfig).preset)
+    || typeof (raw as StreamConfig).revealCharsPerSec !== 'number'
+    || typeof (raw as StreamConfig).scrollSpeedPxPerSec !== 'number'
+    || typeof (raw as StreamConfig).maxScrollSpeedPxPerSec !== 'number'
+  ) {
+    throw new Error(`[dsh-smooth-stream] malformed ${STREAM_BOOT_GLOBAL} boot global: ${JSON.stringify(raw)}`)
+  }
+  return raw as StreamConfig
+}
+
+/**
+ * Wrap every keyed Chat row except `assistant-step` in place. A second
+ * register with the same `children` table throws because the child slot is
+ * already declared, and only the winning entry receives `renderSlot`;
+ * swapping `entry.component` keeps the original children, locale, and inject
+ * seats. `assistant-step` is replaced below so text and Think use the
+ * typewriter reveal.
+ * @param ctx - Browser context carrying the slot registry.
+ * @returns Restorer that puts the original components back.
+ */
+function wrapGrowingChatRows(ctx: ClientContext): () => void {
+  const restores: Array<() => void> = []
+  const wrapped = new WeakSet<object>()
+
+  const wrapAll = (): void => {
+    for (const entry of ctx.slots.entries('conversation.chat.node')) {
+      const key = entry.options.key
+      if (key === undefined || SKIP_WRAP.has(key)) continue
+      const current = entry.component
+      if (typeof current !== 'function' || wrapped.has(current)) continue
+      const inner = current as ComponentType<FollowWrapProps>
+      const next = wrapFollowNodeView(inner)
+      wrapped.add(next)
+      entry.component = next
+      restores.push(() => {
+        if (entry.component === next) entry.component = inner
+      })
+    }
+  }
+
+  wrapAll()
+  const off = ctx.on('slots/changed', (key: string) => {
+    if (key === 'conversation.chat.node') wrapAll()
+  })
+  return () => {
+    off()
+    for (const restore of restores) restore()
+  }
+}
+
+/**
+ * Register the typewriter renderer after the conversation package declares the
+ * keyed Chat node seat. A lower priority shadows the built-in assistant row;
+ * every other growing row is wrapped in place so Tool cards, retries, and
+ * workflow runs share conversation follow. The Host-bridged configuration
+ * selects the render direction, smoothing preset, and glide speed.
+ * @param ctx - Browser context carrying the shared slot registry.
+ */
+export function apply(ctx: ClientContext): void {
+  const config = readBootConfig()
+  const configured = function StreamConfiguredView(props: AssistantProps) {
+    return createElement(TypewriterAssistantNodeView, {
+      ...props,
+      mode: config.mode,
+      preset: config.preset,
+      revealCharsPerSec: config.revealCharsPerSec,
+      scrollSpeedPxPerSec: config.scrollSpeedPxPerSec,
+      maxScrollSpeedPxPerSec: config.maxScrollSpeedPxPerSec,
+    })
+  }
+  ctx.slots.inject('conversation.chat.node', () => {
+    const unwrap = wrapGrowingChatRows(ctx)
+    const unshadow = ctx.slots.register({
+      name: 'conversation.chat.node',
+      key: 'assistant-step',
+      priority: -100,
+      locale: 'conversation',
+      registrant: 'dsh-smooth-stream',
+    }, configured)
+    return () => {
+      unshadow()
+      unwrap()
+    }
+  })
+}

package/src/client/teleprompterGlide.ts

@@ -0,0 +1,426 @@
+/**
+ * Conversation-port follow while an assistant reply streams.
+ *
+ * The demo's damped-spring lerp is driven from a float `animatedH` — the
+ * smoothed content height — never from the rounded `scrollTop` the browser
+ * reports back. A wrap raises the content height by a line; if the engine
+ * were allowed to snap `scrollTop` to the new floor, the previous line would
+ * hop up in one frame. This overlay:
+ *
+ * - owns follow via `data-follow-owned` so ChatView does not snap;
+ * - sets `overflow-anchor: none` so CSS scroll-anchoring does not snap;
+ * - restores `animatedH` in a ResizeObserver (before paint) so a layout
+ *   pass cannot flash a snapped frame;
+ * - while the port has scroll room, writes the interpolated lag as
+ *   `translate3d` on `[data-chat-transcript]` (message rows only), so the
+ *   turn-status chrome stays pinned at the floor;
+ * - before the port has scroll room (content shorter than the viewport), the
+ *   same lag is a content-height lag written as a negative translate on
+ *   `[data-chat-turn-status]`, so the status label descends smoothly with
+ *   each wrap instead of hopping a line at a time.
+ *
+ * Handing the port back to the reader (unpin, or the owner going inactive)
+ * first writes the effective visual top (`engine - lag`) into `scrollTop`
+ * before clearing the transform, so the frame stays continuous. That write
+ * also lands in ChatView's observed-top ledger as reader input beyond
+ * `FOLLOW_THRESHOLD`, releasing its native snap-follow instead of fighting
+ * the gesture for the port.
+ *
+ * Unpin is a real gesture (wheel / touch / pointer / key) that leaves the
+ * floor; a `scrollTop` delta from our own write must not release the pin.
+ */
+
+import { useEffect, useRef, type RefObject } from 'react'
+
+/**
+ * Matches ChatView's `FOLLOW_OWNED_ATTR`. The overlay writes the last
+ * programmatic `scrollTop` here so ChatView yields snap-follow and does not
+ * treat the write as reader input.
+ */
+const FOLLOW_OWNED_ATTR = 'data-follow-owned'
+
+/** Demo `1 - exp(-dt / 18)` time constant, in ms. */
+export const FOLLOW_LERP_DT_MS = 18
+
+/** Floor / ceiling of the per-frame lerp fraction before the dt term. */
+export const FOLLOW_LERP_MIN = 0.05
+export const FOLLOW_LERP_MAX = 0.25
+
+/** Lag (px) at which the lag term of the lerp saturates. */
+export const FOLLOW_LERP_LAG_REF_PX = 160
+
+/** Reveal cps at which the speed factor is 1. */
+export const FOLLOW_SPEED_REF_CPS = 35
+
+export const FOLLOW_SPEED_FACTOR_MIN = 0.7
+export const FOLLOW_SPEED_FACTOR_MAX = 2.2
+
+/** Reader-return / still-pinned boundary, matching ChatView + the demo. */
+export const FOLLOW_SLACK_PX = 25
+
+/**
+ * Upward wheel/touch distance that releases the pin. The engine `scrollTop`
+ * is held on the floor while following, so a small trackpad tick never
+ * appears as `reportedLag` and cannot be judged against {@link FOLLOW_SLACK_PX}.
+ */
+export const FOLLOW_UNPIN_GESTURE_PX = 8
+
+/** How long a gesture keeps `isUserInteracting` so the next scroll can unpin. */
+export const FOLLOW_GESTURE_MS = 800
+
+const GESTURE_EVENTS = ['wheel', 'touchmove', 'pointerdown', 'keydown'] as const
+
+export interface FollowGlideInput {
+  /** How far the interpolated top trails the floor, in px. */
+  readonly lag: number
+  /** Observed reveal rate in chars/s; 0 uses {@link FOLLOW_SPEED_REF_CPS}. */
+  readonly speedEma: number
+}
+
+export interface FollowGlideStep {
+  /** Pixels to advance `animatedH` this frame (fractional). */
+  readonly advancePx: number
+  /** Applied lerp fraction, for tests. */
+  readonly lerpStep: number
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value))
+}
+
+/**
+ * One spring-lerp frame from the silky markdown demo.
+ * @param dtMs - Frame delta in ms.
+ * @param input - Current lag (from the float top, not the rounded engine top) and reveal-speed EMA.
+ * @returns The fractional advance and the lerp fraction.
+ */
+export function computeFollowStep(dtMs: number, input: FollowGlideInput): FollowGlideStep {
+  if (input.lag <= 0.1 || dtMs <= 0) return { advancePx: 0, lerpStep: 0 }
+  const speed = input.speedEma > 0 ? input.speedEma : FOLLOW_SPEED_REF_CPS
+  const speedFactor = clamp(speed / FOLLOW_SPEED_REF_CPS, FOLLOW_SPEED_FACTOR_MIN, FOLLOW_SPEED_FACTOR_MAX)
+  const baseLerp = clamp((input.lag / FOLLOW_LERP_LAG_REF_PX) * speedFactor, FOLLOW_LERP_MIN, FOLLOW_LERP_MAX)
+  const lerpStep = baseLerp * (1 - Math.exp(-dtMs / FOLLOW_LERP_DT_MS))
+  return { advancePx: input.lag * lerpStep, lerpStep }
+}
+
+/** The message-rows box the lag transform rides on, when the host has one. */
+function shiftRootOf(port: HTMLElement): HTMLElement | null {
+  return port.querySelector('[data-chat-transcript]')
+}
+
+/**
+ * Row wrappers that carry only messages/tools. Hosts without a transcript
+ * box keep the turn-status chrome as a sibling of the rows inside
+ * `[data-chat-flow]`, so shifting that whole flow would drag the chrome
+ * along; shifting the rows individually leaves every non-message sibling
+ * (turn status, steering bubbles) pinned while the text glides.
+ *
+ * Only the outermost rows are shifted: a tool call nests its subcalls as
+ * descendant `[data-chat-anchor-key]` rows, and writing the lag on each of
+ * them would double (or further multiply) the shift, tearing the subcalls
+ * away from their parent every frame. Descendants ride the parent's
+ * transform instead.
+ */
+function shiftRowsOf(port: HTMLElement): HTMLElement[] {
+  return [...port.querySelectorAll<HTMLElement>('[data-chat-anchor-key]')]
+    .filter(row => row.parentElement?.closest('[data-chat-anchor-key]') === null)
+}
+
+/** Element whose resize signals flow growth for the before-paint restore. */
+function resizeProxyOf(port: HTMLElement): HTMLElement | null {
+  return port.querySelector('[data-chat-transcript]') ?? port.querySelector('[data-chat-flow]')
+}
+
+/** True when the glide expresses its lag as transforms instead of engine top. */
+function hasShiftSurface(port: HTMLElement): boolean {
+  return shiftRootOf(port) !== null || shiftRowsOf(port).length > 0
+}
+
+function setShift(element: HTMLElement, px: number, negative = false): void {
+  const value = negative ? -px : px
+  if (Math.abs(value) > 0.01) {
+    element.style.transform = `translate3d(0, ${value}px, 0)`
+    element.style.willChange = 'transform'
+  } else {
+    element.style.transform = ''
+    element.style.willChange = ''
+  }
+}
+
+/**
+ * The running-turn label. Before the port scrolls (content shorter than the
+ * viewport) the content-height lag has no `scrollTop` room to ride, so it is
+ * expressed as a negative translate on this sibling: the label descends
+ * smoothly with each wrap instead of hopping down a line at a time.
+ */
+function chromeShiftOf(port: HTMLElement): HTMLElement | null {
+  return port.querySelector<HTMLElement>('[data-chat-turn-status]')
+}
+
+/**
+ * Render the single smoothed extent `animatedH`. Before the port scrolls
+ * (content shorter than the viewport) `animatedH` is clamped to the content
+ * height and the content-height lag rides a negative translate on the
+ * turn-status label; once the port has scroll room the engine is pinned at
+ * the floor and the lag rides `[data-chat-transcript]` (or each message row
+ * when the host has no transcript box) so the chrome stays put. Without any
+ * shift surface the engine itself carries the interpolated top.
+ */
+function applyVisual(port: HTMLElement, animatedH: number): void {
+  const contentHeight = Math.max(0, port.scrollHeight)
+  const floor = Math.max(0, contentHeight - port.clientHeight)
+  const extent = Math.min(contentHeight, Math.max(0, animatedH))
+  const lag = contentHeight - extent
+  port.style.overflowAnchor = 'none'
+  port.style.scrollBehavior = 'auto'
+  const shiftRoot = shiftRootOf(port)
+  if (shiftRoot !== null) {
+    if (floor <= 0) {
+      port.scrollTop = 0
+      port.setAttribute(FOLLOW_OWNED_ATTR, String(port.scrollTop))
+      const chrome = chromeShiftOf(port)
+      if (chrome !== null) setShift(chrome, lag, true)
+      setShift(shiftRoot, 0)
+      return
+    }
+    port.scrollTop = floor
+    port.setAttribute(FOLLOW_OWNED_ATTR, String(port.scrollTop))
+    setShift(shiftRoot, lag)
+    return
+  }
+  const rows = shiftRowsOf(port)
+  if (rows.length > 0) {
+    if (floor <= 0) {
+      port.scrollTop = 0
+      port.setAttribute(FOLLOW_OWNED_ATTR, String(port.scrollTop))
+      const chrome = chromeShiftOf(port)
+      if (chrome !== null) setShift(chrome, lag, true)
+      for (const row of rows) setShift(row, 0)
+      return
+    }
+    port.scrollTop = floor
+    port.setAttribute(FOLLOW_OWNED_ATTR, String(port.scrollTop))
+    for (const row of rows) setShift(row, lag)
+    return
+  }
+  port.scrollTop = Math.min(floor, Math.max(0, extent))
+  port.setAttribute(FOLLOW_OWNED_ATTR, String(port.scrollTop))
+}
+
+function clearVisual(port: HTMLElement): void {
+  port.removeAttribute(FOLLOW_OWNED_ATTR)
+  port.style.overflowAnchor = ''
+  port.style.scrollBehavior = ''
+  const shiftRoot = shiftRootOf(port)
+  if (shiftRoot !== null) {
+    shiftRoot.style.transform = ''
+    shiftRoot.style.willChange = ''
+  } else {
+    for (const row of shiftRowsOf(port)) {
+      row.style.transform = ''
+      row.style.willChange = ''
+    }
+  }
+  const chrome = chromeShiftOf(port)
+  if (chrome !== null) {
+    chrome.style.transform = ''
+    chrome.style.willChange = ''
+  }
+}
+
+/** Live follow hosts per conversation port so one unmount does not clear another. */
+const followOwners = new WeakMap<HTMLElement, number>()
+
+function acquireFollow(port: HTMLElement): void {
+  followOwners.set(port, (followOwners.get(port) ?? 0) + 1)
+}
+
+function releaseFollow(port: HTMLElement): number {
+  const next = (followOwners.get(port) ?? 1) - 1
+  if (next <= 0) {
+    followOwners.delete(port)
+    return 0
+  }
+  followOwners.set(port, next)
+  return next
+}
+
+/**
+ * Own the conversation scrollport's bottom-follow while `active` is true.
+ *
+ * @param rootRef - An element inside the conversation scrollport.
+ * @param active - True while the reply is still revealing.
+ * @param speedCpsRef - Live reveal-rate EMA from the smoother.
+ */
+export function useConversationFollow(
+  rootRef: RefObject<HTMLElement | null>,
+  active: boolean,
+  speedCpsRef: { current: number },
+): void {
+  const activeRef = useRef(active)
+  useEffect(() => {
+    activeRef.current = active
+  }, [active])
+
+  useEffect(() => {
+    if (!active) return
+    let rafId = 0
+    let last = performance.now()
+    let following = true
+    let primed = false
+    let animatedH = 0
+    let interacting = false
+    let interactTimer: ReturnType<typeof setTimeout> | null = null
+    let port: HTMLElement | null = null
+    let resize: ResizeObserver | null = null
+    let holding: HTMLElement | null = null
+    let awayPx = 0
+
+    const hold = (next: HTMLElement): void => {
+      if (holding === next) return
+      if (holding !== null) releaseFollow(holding)
+      acquireFollow(next)
+      holding = next
+    }
+
+    const drop = (next: HTMLElement): void => {
+      if (holding === next) {
+        releaseFollow(next)
+        holding = null
+      }
+      clearVisual(next)
+    }
+
+    /**
+     * Give the reader the visual position the glide was showing before the
+     * transforms go away. While transforms carry the lag, the engine sits at
+     * the floor and the effective visual top is `engine - lag`; writing that
+     * keeps the handover frame-continuous, and the write shows up in
+     * ChatView's ledger as reader movement, disarming its snap-follow.
+     * Without a shift surface the engine already holds the interpolated top,
+     * so there is nothing to compensate.
+     */
+    const handBackVisual = (next: HTMLElement): void => {
+      if (!hasShiftSurface(next)) return
+      const floor = Math.max(0, next.scrollHeight - next.clientHeight)
+      if (floor <= 0) return
+      const lag = Math.max(0, next.scrollHeight - animatedH)
+      next.scrollTop = Math.min(floor, Math.max(0, next.scrollTop - lag))
+    }
+
+    const markGesture = (event: Event): void => {
+      interacting = true
+      if (event instanceof WheelEvent && event.deltaY < 0) awayPx += -event.deltaY
+      else if (event.type === 'touchmove' || event.type === 'keydown') awayPx += FOLLOW_UNPIN_GESTURE_PX
+      if (interactTimer !== null) clearTimeout(interactTimer)
+      interactTimer = setTimeout(() => {
+        interacting = false
+        interactTimer = null
+        awayPx = 0
+      }, FOLLOW_GESTURE_MS)
+    }
+
+    const restoreBeforePaint = (): void => {
+      if (!following || port === null) return
+      applyVisual(port, animatedH)
+    }
+
+    const bindPort = (next: HTMLElement): void => {
+      if (port === next) return
+      if (port !== null) {
+        for (const name of GESTURE_EVENTS) port.removeEventListener(name, markGesture)
+        resize?.disconnect()
+      }
+      port = next
+      for (const name of GESTURE_EVENTS) {
+        port.addEventListener(name, markGesture, { passive: true })
+      }
+      if (typeof ResizeObserver !== 'undefined') {
+        resize = new ResizeObserver(restoreBeforePaint)
+        resize.observe(port)
+        const proxy = resizeProxyOf(port)
+        if (proxy !== null) resize.observe(proxy)
+      }
+    }
+
+    const frame = (now: number) => {
+      rafId = requestAnimationFrame(frame)
+      const dt = Math.min(50, now - last)
+      last = now
+      const root = rootRef.current
+      if (root === null) return
+      const nextPort = root.closest<HTMLElement>('[data-conversation-scroll]')
+      if (nextPort === null) return
+      bindPort(nextPort)
+
+      const floor = Math.max(0, nextPort.scrollHeight - nextPort.clientHeight)
+      const reportedLag = floor - nextPort.scrollTop
+      // Visual extent (content-height equivalent of the reader's scroll top):
+      // content shorter than the viewport has no scrollTop to derive from, so
+      // the extent is just the content height.
+      const extent = Math.min(nextPort.scrollHeight, Math.max(0, nextPort.scrollHeight - reportedLag))
+
+      if (!primed) {
+        animatedH = extent
+        following = reportedLag <= FOLLOW_SLACK_PX
+        if (following) {
+          hold(nextPort)
+          applyVisual(nextPort, animatedH)
+        }
+        primed = true
+        return
+      }
+
+      if (!following && !interacting && reportedLag <= FOLLOW_SLACK_PX) {
+        following = true
+        animatedH = extent
+        hold(nextPort)
+      } else if (following && interacting && awayPx >= FOLLOW_UNPIN_GESTURE_PX) {
+        following = false
+        awayPx = 0
+        // Compensate before the transform clears, or the flow (turn-status
+        // chrome included) jumps up by the whole lag in one frame.
+        handBackVisual(nextPort)
+        animatedH = nextPort.scrollHeight
+        drop(nextPort)
+      }
+
+      if (!activeRef.current || !following) return
+      hold(nextPort)
+
+      const lag = nextPort.scrollHeight - animatedH
+      const step = computeFollowStep(dt, {
+        lag,
+        speedEma: speedCpsRef.current,
+      })
+      if (lag <= 0.1) {
+        animatedH = nextPort.scrollHeight
+      } else {
+        animatedH = Math.min(nextPort.scrollHeight, animatedH + step.advancePx)
+      }
+      applyVisual(nextPort, animatedH)
+    }
+
+    rafId = requestAnimationFrame(frame)
+    return () => {
+      cancelAnimationFrame(rafId)
+      if (interactTimer !== null) clearTimeout(interactTimer)
+      resize?.disconnect()
+      if (port !== null) {
+        for (const name of GESTURE_EVENTS) port.removeEventListener(name, markGesture)
+      }
+      const root = rootRef.current
+      const host = root?.closest<HTMLElement>('[data-conversation-scroll]') ?? port
+      if (host === null) return
+      if (following) {
+        // Same handback as an unpin: land on the effective visual top rather
+        // than the floor, so the owner change (stream close, unmount) does
+        // not snap the flow up by the remaining lag.
+        handBackVisual(host)
+      }
+      const remaining = holding === host ? releaseFollow(host) : (followOwners.get(host) ?? 0)
+      holding = null
+      if (remaining === 0) clearVisual(host)
+    }
+  }, [active, rootRef, speedCpsRef])
+}

package/src/client/useFpsGuard.ts

@@ -0,0 +1,84 @@
+/**
+ * Performance guard for the streaming reveal.
+ *
+ * Feeds an EMA-smoothed frame-rate monitor from a rAF loop while streaming
+ * and tracks whether the reply is on-screen. The returned `shouldHoldBack`
+ * predicate is true only while the frame rate is below the threshold AND the
+ * reply is offscreen — exactly the spec's "skip offscreen DOM updates when
+ * FPS < 30" rule. The smoother consumes the predicate as its commit veto.
+ */
+
+import { useCallback, useEffect, useRef } from 'react'
+
+const FPS_THRESHOLD = 30
+const FPS_ALPHA = 0.12
+const RECOVER_FRAMES = 6
+const MAX_FRAME_MS = 100
+
+interface MutableFps {
+  emaMs: number
+  lastMs: number
+  healthyRun: number
+  degraded: boolean
+}
+
+export function useFpsGuard(active: boolean): {
+  ref: (element: HTMLElement | null) => void
+  shouldHoldBack: () => boolean
+} {
+  const fpsRef = useRef<MutableFps>({ emaMs: 0, lastMs: 0, healthyRun: 0, degraded: false })
+  const visibleRef = useRef(true)
+  const elementRef = useRef<HTMLElement | null>(null)
+
+  useEffect(() => {
+    if (!active) return
+    let rafId = 0
+    const frame = (now: number) => {
+      rafId = requestAnimationFrame(frame)
+      const fps = fpsRef.current
+      if (fps.lastMs === 0) {
+        fps.lastMs = now
+        return
+      }
+      const delta = Math.min(MAX_FRAME_MS, Math.max(1, now - fps.lastMs))
+      fps.lastMs = now
+      fps.emaMs = fps.emaMs === 0 ? delta : fps.emaMs + FPS_ALPHA * (delta - fps.emaMs)
+      const currentFps = 1000 / fps.emaMs
+      if (currentFps < FPS_THRESHOLD) {
+        fps.healthyRun = 0
+        fps.degraded = true
+      } else if (fps.degraded) {
+        fps.healthyRun += 1
+        if (fps.healthyRun >= RECOVER_FRAMES) fps.degraded = false
+      }
+    }
+    rafId = requestAnimationFrame(frame)
+    return () => {
+      cancelAnimationFrame(rafId)
+      fpsRef.current = { emaMs: 0, lastMs: 0, healthyRun: 0, degraded: false }
+    }
+  }, [active])
+
+  const ref = useCallback((element: HTMLElement | null) => {
+    elementRef.current = element
+  }, [])
+
+  useEffect(() => {
+    const element = elementRef.current
+    if (element === null || typeof IntersectionObserver === 'undefined') return
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) visibleRef.current = entry.isIntersecting
+      },
+      { rootMargin: '120px 0px' },
+    )
+    observer.observe(element)
+    return () => observer.disconnect()
+  })
+
+  const shouldHoldBack = useCallback(() => {
+    return active && fpsRef.current.degraded && !visibleRef.current
+  }, [active])
+
+  return { ref, shouldHoldBack }
+}