dsh-smooth-stream 0.3.2 → 0.3.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-smooth-stream",
-  "version": "0.3.2",
-  "description": "DeepSeek Harness (dsh) plugin: silky streaming reveal, no flicker. dsh 丝滑流式渲染插件。",
+  "version": "0.3.4",
+  "description": "Fluid streaming rendering and silky scrolling for DeepSeek Harness replies, including Markdown, code blocks, tables, and tool results.",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -23,6 +23,11 @@
     "cordis",
     "streaming",
     "smooth-streaming",
+    "fluid-streaming",
+    "streaming-renderer",
+    "markdown-streaming",
+    "smooth-scrolling",
+    "smooth-scroll",
     "smooth-stream",
     "typewriter",
     "typewriter-effect",
@@ -74,6 +79,7 @@
   },
   "scripts": {
     "build": "tsdown",
+    "build:repro": "esbuild repro/main.tsx --bundle --format=esm --platform=browser --loader:.css=local-css --outfile=repro/bundle.js",
     "prepare": "tsdown",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --pretty false"
@@ -146,6 +152,7 @@
     "@types/node": "^22.20.0",
     "@types/react": "~18.3.1",
     "@types/react-dom": "~18.3.0",
+    "esbuild": "^0.28.2",
     "jsdom": "^26.1.0",
     "lightningcss": "^1.30.1",
     "react": "^18.3.1",

package/src/client/FollowHost.tsx

@@ -1,21 +1,66 @@
-import { useRef, type ReactNode } from 'react'
+import { useEffect, useRef, type ReactNode } from 'react'
 import { useConversationFollow } from './teleprompterGlide.ts'
 import css from './TypewriterAssistantNodeView.module.css'
 
 /**
  * Document-flow host that owns conversation-port follow while `active`.
- * Shared by assistant blocks and every other growing Chat row.
+ * Shared by assistant blocks and every other Agent Chat row. `onGrowth` lets
+ * generic wrapped renderers re-arm one glide when their DOM grows without
+ * requiring a business-kind-specific lifecycle predicate.
  */
 export function FollowHost({
   active,
+  entrance = false,
+  onEntranceSettled,
+  onGrowth,
+  entranceExtentRef,
   speedCpsRef,
+  revealScaleRef,
+  predictive = true,
+  predictiveRef,
+  hostRef,
   children,
 }: {
   active: boolean
+  entrance?: boolean
+  onEntranceSettled?: (() => void) | undefined
+  onGrowth?: ((deltaPx: number) => void) | undefined
+  entranceExtentRef?: { current: number | null } | undefined
   speedCpsRef: { current: number }
+  revealScaleRef?: { current: number } | undefined
+  predictive?: boolean
+  predictiveRef?: { current: boolean } | undefined
+  hostRef?: { current: HTMLDivElement | null } | undefined
   children: ReactNode
 }) {
-  const rootRef = useRef<HTMLDivElement>(null)
-  useConversationFollow(rootRef, active, speedCpsRef)
+  const localRootRef = useRef<HTMLDivElement>(null)
+  const rootRef = hostRef ?? localRootRef
+  useConversationFollow(
+    rootRef,
+    active || entrance,
+    speedCpsRef,
+    revealScaleRef,
+    predictive,
+    entrance,
+    onEntranceSettled,
+    predictiveRef,
+    entranceExtentRef,
+  )
+  useEffect(() => {
+    if (onGrowth === undefined || typeof ResizeObserver === 'undefined') return
+    const root = rootRef.current
+    if (root === null) return
+    let previousHeight: number | null = null
+    const observer = new ResizeObserver(entries => {
+      const nextHeight = entries[0]?.contentRect.height ?? root.getBoundingClientRect().height
+      if (!Number.isFinite(nextHeight)) return
+      if (previousHeight !== null && nextHeight > previousHeight + 0.5) {
+        onGrowth(nextHeight - previousHeight)
+      }
+      previousHeight = nextHeight
+    })
+    observer.observe(root)
+    return () => { observer.disconnect() }
+  }, [onGrowth])
   return <div ref={rootRef} className={css.follow}>{children}</div>
 }

package/src/client/TypewriterAssistantNodeView.module.css

@@ -223,6 +223,7 @@
  * (see useConversationFollow).
  */
 .follow {
+  contain: layout style;
   min-width: 0;
 }
 

package/src/client/TypewriterAssistantNodeView.tsx

@@ -1,4 +1,4 @@
-import { memo, useEffect, useMemo, useRef, useState, type ComponentProps, type ReactNode } from 'react'
+import { memo, useEffect, useLayoutEffect, useMemo, useRef, useState, type ComponentProps, type ReactNode } from 'react'
 import { IconThinkOutline14, JsonBlock, MarkdownText } from '@deepseek-ai/dsh-client-ui-primitives'
 import { ImageGallery, type ImageLoader, type MessageImageLabels } from '@deepseek-ai/dsh-client-ui-attachment'
 import type { ChatNodeViewProps, TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
@@ -29,13 +29,248 @@ function usePrefersReducedMotion(): boolean {
 
 interface AnimatedMarkdownTextProps extends MarkdownProps {
   streaming: boolean
-  announce: boolean
   /** True on the last text block: that block owns conversation follow. */
   ownFollow: boolean
+  followSpeedCpsRef?: { current: number } | undefined
+  followRevealScaleRef?: { current: number } | undefined
+  onPredictiveChange?: ((predictive: boolean) => void) | undefined
   preset: StreamSmoothingPreset
   shouldHoldBack: () => boolean
 }
 
+/** Conservative fallback before the streaming Markdown tail has geometry. */
+const PREDICTIVE_WRAP_FALLBACK_CHARS = 32
+const STREAM_ANNOUNCEMENT_INTERVAL_MS = 800
+const STREAM_ANNOUNCEMENT_MAX_CHARS = 320
+
+interface PendingTextGeometry {
+  root: HTMLElement
+  visibleText: string
+  fontSize: number
+  wrapThresholdWidth: number | null
+}
+
+function approximateInlineWidth(text: string, emPx: number): number {
+  let width = 0
+  for (const char of text) {
+    if (/\s/u.test(char)) width += emPx * 0.33
+    else if (/^[\x00-\x7f]$/u.test(char)) width += emPx * 0.56
+    else width += emPx
+  }
+  return width
+}
+
+function measurePendingTextGeometry(root: HTMLElement, visibleText: string): PendingTextGeometry {
+  if (
+    typeof document.createTreeWalker !== 'function'
+    || typeof NodeFilter === 'undefined'
+  ) {
+    return { root, visibleText, fontSize: 14, wrapThresholdWidth: null }
+  }
+  const rootRect = root.getBoundingClientRect()
+  const rootWidth = Math.max(0, rootRect.width, rootRect.right - rootRect.left, root.clientWidth)
+  if (rootWidth <= 0) return { root, visibleText, fontSize: 14, wrapThresholdWidth: null }
+
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT)
+  let tail: Text | null = null
+  for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
+    if ((node.textContent ?? '').length > 0) tail = node as Text
+  }
+  const parent = tail?.parentElement ?? root
+  const fontSize = Number.parseFloat(getComputedStyle(parent).fontSize) || 14
+  if (tail === null || typeof document.createRange !== 'function') {
+    return { root, visibleText, fontSize, wrapThresholdWidth: rootWidth }
+  }
+
+  try {
+    const length = tail.textContent?.length ?? 0
+    if (length <= 0) return { root, visibleText, fontSize, wrapThresholdWidth: rootWidth }
+    const range = document.createRange()
+    range.setStart(tail, Math.max(0, length - 1))
+    range.setEnd(tail, length)
+    const tailRect = range.getBoundingClientRect()
+    const contentRight = rootRect.right
+    if (!Number.isFinite(tailRect.right) || tailRect.right <= rootRect.left || contentRight <= rootRect.left) {
+      return { root, visibleText, fontSize, wrapThresholdWidth: rootWidth }
+    }
+    const remainingWidth = Math.max(0, contentRight - tailRect.right)
+    return {
+      root,
+      visibleText,
+      fontSize,
+      wrapThresholdWidth: remainingWidth + fontSize * 0.35,
+    }
+  } catch {
+    return { root, visibleText, fontSize, wrapThresholdWidth: rootWidth }
+  }
+}
+
+/** Whether buffered source can reach a new visual line before it drains. */
+function pendingTextCanGrow(
+  root: HTMLElement | null,
+  visibleText: string,
+  pending: string,
+  geometryRef: { current: PendingTextGeometry | null },
+): boolean {
+  if (pending === '') return false
+  if (/[\r\n]/u.test(pending)) return true
+  const pendingChars = [...pending]
+  if (root === null) return pendingChars.length >= PREDICTIVE_WRAP_FALLBACK_CHARS
+
+  let geometry = geometryRef.current
+  if (geometry?.root !== root || geometry.visibleText !== visibleText) {
+    geometry = measurePendingTextGeometry(root, visibleText)
+    geometryRef.current = geometry
+  }
+  if (geometry.wrapThresholdWidth === null) {
+    return pendingChars.length >= PREDICTIVE_WRAP_FALLBACK_CHARS
+  }
+  return approximateInlineWidth(pending, geometry.fontSize) >= geometry.wrapThresholdWidth
+}
+
+function announcementChunkEnd(source: string, start: number): number {
+  const hardEnd = Math.min(source.length, start + STREAM_ANNOUNCEMENT_MAX_CHARS)
+  if (hardEnd === source.length) return hardEnd
+  const softStart = start + Math.floor(STREAM_ANNOUNCEMENT_MAX_CHARS * 0.6)
+  for (let index = hardEnd - 1; index >= softStart; index -= 1) {
+    if (/[\s.,;:!?]/u.test(source[index] ?? '')) return index + 1
+  }
+  return hardEnd
+}
+
+/** Pace screen-reader updates independently from visual reveal frames. */
+interface StreamAnnouncementState {
+  text: string
+  revision: number
+  present: boolean
+}
+
+/** A commit-driven live region isolated from the visible Markdown subtree. */
+const StreamAnnouncement = memo(function StreamAnnouncement({
+  text,
+  active,
+}: {
+  text: string
+  active: boolean
+}) {
+  const [announcement, setAnnouncement] = useState<StreamAnnouncementState>({
+    text: '',
+    revision: 0,
+    present: active,
+  })
+  const sourceRef = useRef(text)
+  const activeRef = useRef(active)
+  const announcedOffsetRef = useRef(active ? 0 : text.length)
+  const drainSourceRef = useRef<string | null>(null)
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  useEffect(() => {
+    const clearTimer = (): void => {
+      if (timerRef.current === null) return
+      clearTimeout(timerRef.current)
+      timerRef.current = null
+    }
+
+    const publishNext = (source: string): boolean => {
+      const start = Math.min(announcedOffsetRef.current, source.length)
+      const end = announcementChunkEnd(source, start)
+      if (end <= start) return false
+      announcedOffsetRef.current = end
+      setAnnouncement(previous => ({
+        text: source.slice(start, end),
+        revision: previous.revision + 1,
+        present: true,
+      }))
+      return end < source.length
+    }
+
+    const hideAfterLinger = (): void => {
+      timerRef.current = setTimeout(() => {
+        timerRef.current = null
+        if (activeRef.current) return
+        drainSourceRef.current = null
+        setAnnouncement(previous => ({ ...previous, present: false }))
+      }, STREAM_ANNOUNCEMENT_INTERVAL_MS)
+    }
+
+    const drainNext = (): void => {
+      const source = drainSourceRef.current
+      if (source === null) return
+      if (!publishNext(source)) {
+        hideAfterLinger()
+        return
+      }
+      timerRef.current = setTimeout(() => {
+        timerRef.current = null
+        if (activeRef.current) return
+        drainNext()
+      }, STREAM_ANNOUNCEMENT_INTERVAL_MS)
+    }
+
+    const scheduleLive = (): void => {
+      if (timerRef.current !== null || announcedOffsetRef.current >= sourceRef.current.length) return
+      timerRef.current = setTimeout(() => {
+        timerRef.current = null
+        if (!activeRef.current) return
+        const source = sourceRef.current
+        if (publishNext(source)) scheduleLive()
+      }, STREAM_ANNOUNCEMENT_INTERVAL_MS)
+    }
+
+    const wasActive = activeRef.current
+    const previousSource = sourceRef.current
+    const continuingDrain = !active && !wasActive && drainSourceRef.current !== null
+    if (
+      !continuingDrain
+      && (!text.startsWith(previousSource) || announcedOffsetRef.current > text.length)
+    ) {
+      announcedOffsetRef.current = 0
+    }
+    sourceRef.current = text
+    activeRef.current = active
+
+    if (active) {
+      if (!wasActive) {
+        clearTimer()
+        drainSourceRef.current = null
+        setAnnouncement(previous => ({
+          text: '',
+          revision: previous.revision + 1,
+          present: true,
+        }))
+      }
+      scheduleLive()
+      return
+    }
+
+    if (!wasActive) {
+      if (drainSourceRef.current === null) announcedOffsetRef.current = text.length
+      return
+    }
+
+    clearTimer()
+    drainSourceRef.current = text
+    drainNext()
+  }, [active, text])
+
+  useEffect(() => () => {
+    if (timerRef.current !== null) clearTimeout(timerRef.current)
+    timerRef.current = null
+  }, [])
+
+  if (!active && !announcement.present) return null
+  const activating = active && !activeRef.current
+  return (
+    <span
+      className={css.visuallyHidden}
+      aria-live="polite"
+      aria-atomic="true"
+    >
+      <span key={announcement.revision}>{activating ? '' : announcement.text}</span>
+    </span>
+  )
+})
+
 /**
  * Smooth streaming text arm. While the reply runs, the accumulated source is
  * revealed through the smoother at a rate that tracks the model's arrival
@@ -52,40 +287,78 @@ function AnimatedMarkdownText({
   codeLabels,
   fileMentions,
   streaming,
-  announce,
   ownFollow,
+  followSpeedCpsRef,
+  followRevealScaleRef,
+  onPredictiveChange,
   preset,
   shouldHoldBack,
 }: AnimatedMarkdownTextProps) {
   const reduced = usePrefersReducedMotion()
   const [typing, setTyping] = useState(streaming)
-  const speedCpsRef = useRef(35)
+  const localSpeedCpsRef = useRef(35)
+  const followRootRef = useRef<HTMLDivElement>(null)
+  const predictionSourceRef = useRef<string | null>(null)
+  const predictionStateRef = useRef(false)
+  const predictionGeometryRef = useRef<PendingTextGeometry | null>(null)
+  const speedCpsRef = followSpeedCpsRef ?? localSpeedCpsRef
   const displayed = useSmoothStreamContent(text, {
     enabled: typing && !reduced,
+    inputComplete: !streaming,
     preset,
     shouldHoldBack,
     speedCpsRef,
+    revealScaleRef: followRevealScaleRef,
   })
   const shown = reduced ? text : displayed
   const live = typing && !reduced
 
+  useEffect(() => {
+    const root = followRootRef.current
+    if (root === null || typeof ResizeObserver === 'undefined') return
+    const observer = new ResizeObserver(() => {
+      if (predictionGeometryRef.current?.root === root) predictionGeometryRef.current = null
+    })
+    observer.observe(root)
+    return () => { observer.disconnect() }
+  }, [])
+
+  useLayoutEffect(() => {
+    if (onPredictiveChange === undefined) return
+    const pending = text.slice(shown.length)
+    const sourceChanged = predictionSourceRef.current !== text
+    const next = !live || !streaming || pending === ''
+      ? false
+      : sourceChanged
+        ? pendingTextCanGrow(followRootRef.current, shown, pending, predictionGeometryRef)
+        : predictionStateRef.current
+    predictionSourceRef.current = text
+    predictionStateRef.current = next
+    onPredictiveChange(next)
+  }, [live, onPredictiveChange, shown, streaming, text])
+
   // The stream closed: keep revealing the remaining queue, then swap to the
   // settled parse exactly once. The markdown tree stays mounted until then.
   useEffect(() => {
     if (typing && !streaming && shown.length === text.length) setTyping(false)
   }, [shown, streaming, text, typing])
 
-  if (live) {
-    return (
-      <>
-        {announce && <span className={css.visuallyHidden} aria-live="polite">{text}</span>}
-        <FollowHost active={ownFollow} speedCpsRef={speedCpsRef}>
-          <MarkdownText text={shown} streaming codeLabels={codeLabels} />
-        </FollowHost>
-      </>
-    )
-  }
-  return <MarkdownText text={text} codeLabels={codeLabels} fileMentions={fileMentions} />
+  return (
+    <FollowHost
+      active={live && ownFollow}
+      speedCpsRef={speedCpsRef}
+      revealScaleRef={followRevealScaleRef}
+      predictive={streaming}
+      hostRef={followRootRef}
+    >
+      <MarkdownText
+        text={live ? shown : text}
+        streaming={live}
+        codeLabels={codeLabels}
+        fileMentions={live ? undefined : fileMentions}
+      />
+    </FollowHost>
+  )
 }
 
 function imageLabels(t: AssistantProps['t']): MessageImageLabels {
@@ -129,6 +402,7 @@ function AnimatedReasoning({
   thinkAutoExpand,
   shouldHoldBack,
   followSpeedCpsRef,
+  followRevealScaleRef,
   t,
 }: {
   text: string
@@ -137,6 +411,7 @@ function AnimatedReasoning({
   thinkAutoExpand: boolean
   shouldHoldBack: () => boolean
   followSpeedCpsRef?: { current: number } | undefined
+  followRevealScaleRef?: { current: number } | undefined
   t: AssistantProps['t']
 }) {
   const reduced = usePrefersReducedMotion()
@@ -147,11 +422,12 @@ function AnimatedReasoning({
     preset,
     shouldHoldBack,
     speedCpsRef: followSpeedCpsRef,
+    revealScaleRef: followRevealScaleRef,
   })
   const shown = running && !reduced ? displayed : text
   const summary = running ? latestLine(shown) : firstLine(text)
 
-  useEffect(() => {
+  useLayoutEffect(() => {
     // Only the running state owns disclosure while auto-expand is on; with it
     // off, a manual toggle is never wrestled back by the stream.
     if (thinkAutoExpand) setExpanded(running)
@@ -224,12 +500,30 @@ export const TypewriterAssistantNodeView = memo(function TypewriterAssistantNode
 }) {
   const data = node.data
   const streaming = data.status === 'running'
+  const reduced = usePrefersReducedMotion()
   const { ref: guardRef, shouldHoldBack } = useFpsGuard(streaming)
   const rootSpeedRef = useRef(35)
-  const reasoningOwnsSpeed = streaming && data.blocks[data.blocks.length - 1]?.kind === 'reasoning'
-  useEffect(() => {
+  const rootRevealScaleRef = useRef(1)
+  const reasoningTailIndex = streaming && data.blocks[data.blocks.length - 1]?.kind === 'reasoning'
+    ? data.blocks.length - 1
+    : -1
+  const reasoningOwnsSpeed = reasoningTailIndex !== -1
+  const rootPredictiveRef = useRef(false)
+  const previousReasoningTailRef = useRef(-1)
+  if (reasoningTailIndex !== previousReasoningTailRef.current) {
+    // Think growth is already paced by its own text reveal. Opening additional
+    // speculative runway here exposes that runway as an empty gap above the
+    // fixed turn status, especially when reasoning arrives in fast bursts.
+    // The follower still smooths real height growth within the measured gap
+    // and catches up any unsafe remainder in the same frame.
+    rootPredictiveRef.current = false
     if (!reasoningOwnsSpeed) rootSpeedRef.current = 35
-  }, [reasoningOwnsSpeed])
+    previousReasoningTailRef.current = reasoningTailIndex
+  }
+  const updateTextPrediction = useMemo(
+    () => (predictive: boolean): void => { rootPredictiveRef.current = predictive },
+    [],
+  )
   const turn = node.location.kind === 'turn' || node.location.kind === 'step'
     ? node.location.turn
     : undefined
@@ -251,6 +545,10 @@ export const TypewriterAssistantNodeView = memo(function TypewriterAssistantNode
     || data.status === 'interrupted'
     || data.blocks.some(block => block.kind !== 'tool-call')
   if (!hasVisible) return null
+  const announcementText = data.blocks
+    .filter(block => block.kind === 'text')
+    .map(block => block.text)
+    .join('\n')
 
   const rendered: ReactNode[] = []
   const last = data.blocks.length - 1
@@ -271,8 +569,10 @@ export const TypewriterAssistantNodeView = memo(function TypewriterAssistantNode
             codeLabels={codeLabels}
             fileMentions={mentions}
             streaming={streaming}
-            announce={index === last}
             ownFollow={!streaming && index === lastFollow}
+            followSpeedCpsRef={index === lastFollow ? rootSpeedRef : undefined}
+            followRevealScaleRef={index === lastFollow ? rootRevealScaleRef : undefined}
+            onPredictiveChange={index === lastFollow ? updateTextPrediction : undefined}
             preset={preset}
             shouldHoldBack={shouldHoldBack}
           />,
@@ -288,6 +588,7 @@ export const TypewriterAssistantNodeView = memo(function TypewriterAssistantNode
             thinkAutoExpand={thinkAutoExpand}
             shouldHoldBack={shouldHoldBack}
             followSpeedCpsRef={reasoningOwnsSpeed && index === last ? rootSpeedRef : undefined}
+            followRevealScaleRef={reasoningOwnsSpeed && index === last ? rootRevealScaleRef : undefined}
             t={t}
           />,
         )
@@ -323,7 +624,13 @@ export const TypewriterAssistantNodeView = memo(function TypewriterAssistantNode
 
   return (
     <div ref={guardRef} className={css.root} data-streaming={streaming || undefined}>
-      <FollowHost active={streaming} speedCpsRef={rootSpeedRef}>
+      <StreamAnnouncement text={announcementText} active={streaming && !reduced} />
+      <FollowHost
+        active={streaming && !reduced}
+        speedCpsRef={rootSpeedRef}
+        revealScaleRef={rootRevealScaleRef}
+        predictiveRef={rootPredictiveRef}
+      >
         <div className={css.body}>
           {rendered}
           {data.status === 'interrupted' && <span className={css.stopped}>{t('message.stopped')}</span>}