dsh-smooth-stream 0.4.1 → 0.4.2

package/lib/index.js

@@ -174,7 +174,7 @@ const DEFAULT_STREAM_SETTINGS = {
 		springStiffness: 130,
 		springDamping: 24,
 		springMass: 1,
-		runwayPx: 48,
+		runwayPx: 72,
 		reserveResponseMs: 180,
 		backpressureMinScale: .55
 	}

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "dsh-smooth-stream",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Fluid streaming rendering and silky scrolling for DeepSeek Harness replies, including Markdown, code blocks, tables, and tool results.",
   "license": "MIT",
   "type": "module",
+  "packageManager": "pnpm@11.23.0",
   "engines": {
     "node": "^22.19.0 || >=24.0.0"
   },
@@ -77,21 +78,29 @@
       ]
     }
   },
-  "dependencies": {
-    "@deepseek-ai/dsh-settings": "0.1.0-rc.6"
+  "scripts": {
+    "benchmark": "node scripts/run-stream-benchmark.mjs",
+    "build": "tsdown",
+    "build:repro": "esbuild repro/main.tsx --bundle --format=esm --platform=browser --loader:.css=local-css --alias:@deepseek-ai/dsh-client-runtime=./repro/shims/client-runtime.ts --alias:@deepseek-ai/dsh-client-runtime/client=./repro/shims/client-runtime.ts --alias:@deepseek-ai/dsh-client-ui-primitives=./repro/shims/primitives.tsx --outfile=repro/bundle.js",
+    "prepare": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --pretty false",
+    "test:smooth": "node scripts/probe-tailbob.mjs 1200 20 && node scripts/verify-overflow.mjs --runs 3",
+    "probe:overlap": "node scripts/probe-overlap.mjs"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-connection": "*",
     "@deepseek-ai/dsh-client-locale": "*",
     "@deepseek-ai/dsh-client-runtime": "*",
     "@deepseek-ai/dsh-client-ui-attachment": "*",
-    "@deepseek-ai/dsh-client-connection": "*",
     "@deepseek-ai/dsh-client-ui-conversation": "*",
     "@deepseek-ai/dsh-client-ui-primitives": "*",
     "@deepseek-ai/dsh-client-ui-settings": "*",
     "@deepseek-ai/dsh-client-ui-settings-plugins": "*",
     "@deepseek-ai/dsh-client-ui-slots": "*",
     "@deepseek-ai/dsh-host-webserver": "*",
+    "@deepseek-ai/dsh-settings": "*",
     "@deepseek-ai/schemastery": "*",
     "react": "^18.2.0"
   },
@@ -129,10 +138,11 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-client-connection": "0.1.0-rc.6",
     "@deepseek-ai/dsh-client-locale": "0.1.0-rc.6",
     "@deepseek-ai/dsh-client-runtime": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-store": "0.1.2-alpha.3",
     "@deepseek-ai/dsh-client-ui-attachment": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-connection": "0.1.0-rc.6",
     "@deepseek-ai/dsh-client-ui-conversation": "0.1.0-rc.6",
     "@deepseek-ai/dsh-client-ui-primitives": "0.1.0-rc.6",
     "@deepseek-ai/dsh-client-ui-settings": "0.1.0-rc.6",
@@ -148,17 +158,11 @@
     "esbuild": "^0.28.2",
     "jsdom": "^26.1.0",
     "lightningcss": "^1.30.1",
+    "playwright-core": "^1.62.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "tsdown": "^0.22.2",
     "typescript": "^5.9.2",
     "vitest": "^4.1.8"
-  },
-  "scripts": {
-    "benchmark": "node scripts/run-stream-benchmark.mjs",
-    "build": "tsdown",
-    "build:repro": "esbuild repro/main.tsx --bundle --format=esm --platform=browser --loader:.css=local-css --outfile=repro/bundle.js",
-    "test": "vitest run",
-    "typecheck": "tsc -p tsconfig.json --pretty false"
   }
-}
+}

package/src/client/AnimatedDisclosure.tsx

@@ -27,6 +27,13 @@ export interface AnimatedDisclosureProps {
   leadingClassName?: string | undefined
   titleClassName?: string | undefined
   chevronClassName?: string | undefined
+  /**
+   * When false the body snaps between states with no grid-track transition.
+   * The auto-close at stream end uses this: the conversation follower's
+   * settle spring absorbs the height step through the compositor instead,
+   * which glides identically without twelve frames of layout animation.
+   */
+  bodyTransition?: boolean
 }
 
 /**
@@ -46,6 +53,7 @@ export function AnimatedDisclosure({
   leadingClassName,
   titleClassName,
   chevronClassName,
+  bodyTransition = true,
 }: AnimatedDisclosureProps) {
   const toggleFromKeyboard = (event: KeyboardEvent<HTMLDivElement>) => {
     if (event.key !== 'Enter' && event.key !== ' ') return
@@ -77,7 +85,12 @@ export function AnimatedDisclosure({
         <span className={cx(css.disclosureTitle, titleClassName)}>{title}</span>
         {!open && collapsedContent}
       </div>
-      <div className={css.disclosureContent} data-disclosure-content data-collapsed={open ? undefined : ''}>
+      <div
+        className={css.disclosureContent}
+        data-disclosure-content
+        data-collapsed={open ? undefined : ''}
+        data-no-transition={bodyTransition ? undefined : ''}
+      >
         {children}
       </div>
     </div>

package/src/client/FollowHost.tsx

@@ -15,6 +15,7 @@ export function FollowHost({
   onGrowth,
   entranceExtentRef,
   speedCpsRef,
+  revealedCharsRef,
   revealScaleRef,
   predictive = true,
   predictiveRef,
@@ -27,6 +28,7 @@ export function FollowHost({
   onGrowth?: ((deltaPx: number) => void) | undefined
   entranceExtentRef?: { current: number | null } | undefined
   speedCpsRef: { current: number }
+  revealedCharsRef?: { current: number } | undefined
   revealScaleRef?: { current: number } | undefined
   predictive?: boolean
   predictiveRef?: { current: boolean } | undefined
@@ -45,22 +47,37 @@ export function FollowHost({
     onEntranceSettled,
     predictiveRef,
     entranceExtentRef,
+    revealedCharsRef,
   )
   useEffect(() => {
     if (onGrowth === undefined || typeof ResizeObserver === 'undefined') return
     const root = rootRef.current
     if (root === null) return
     let previousHeight: number | null = null
+    let pendingGrowth = 0
+    let growthFrame: number | null = null
+    const flushGrowth = (): void => {
+      growthFrame = null
+      if (pendingGrowth <= 0) return
+      const delta = pendingGrowth
+      pendingGrowth = 0
+      onGrowth(delta)
+    }
     const observer = new ResizeObserver(entries => {
-      const nextHeight = entries[0]?.contentRect.height ?? root.getBoundingClientRect().height
-      if (!Number.isFinite(nextHeight)) return
+      const measuredHeight = entries[0]?.contentRect.height
+      if (measuredHeight === undefined || !Number.isFinite(measuredHeight)) return
+      const nextHeight = measuredHeight
       if (previousHeight !== null && nextHeight > previousHeight + 0.5) {
-        onGrowth(nextHeight - previousHeight)
+        pendingGrowth += nextHeight - previousHeight
+        if (growthFrame === null) growthFrame = requestAnimationFrame(flushGrowth)
       }
       previousHeight = nextHeight
     })
     observer.observe(root)
-    return () => { observer.disconnect() }
+    return () => {
+      observer.disconnect()
+      if (growthFrame !== null) cancelAnimationFrame(growthFrame)
+    }
   }, [onGrowth])
   return <div ref={rootRef} className={css.follow}>{children}</div>
 }

package/src/client/TypewriterAssistantNodeView.module.css

@@ -178,6 +178,13 @@
     visibility 0s var(--ds-transition-duration, 0.2s);
 }
 
+/* Auto-close at stream end snaps instead of animating: the follower's settle
+ * spring already absorbs the height step through the compositor, so a grid
+ * animation would double-animate the same collapse for a dozen frames. */
+.disclosureContent[data-no-transition] {
+  transition: none;
+}
+
 .disclosureContent > * {
   min-height: 0;
   overflow: hidden;
@@ -227,6 +234,22 @@
   min-width: 0;
 }
 
+/*
+ * Inline code is allowed to wrap inside list items. The Harness markdown
+ * theme uses `inline-flex` for its single-line code treatment, but an
+ * inline-flex box can expose multiple painted line boxes without contributing
+ * their full height to a trimmed list-item line box in Chromium. Keep the
+ * code's font and padding while using normal inline layout so every wrapped
+ * line participates in the parent list item's geometry.
+ */
+.root :not(pre) > code {
+  display: inline;
+  line-height: inherit;
+  white-space: normal;
+  overflow-wrap: anywhere;
+  vertical-align: baseline;
+}
+
 /*
  * Trim the half-leading above and below each text block so line boxes hug
  * the font's ascent/descent edges. `text` edges are used instead of
@@ -234,7 +257,11 @@
  * trimming would clip ideographic glyphs.
  */
 @supports (text-box-trim: trim-both) {
-  .root :is(p, h1, h2, h3, h4, h5, h6, li, blockquote) {
+  /* List-item line boxes must retain their full leading. A wrapped inline
+   * code element is an inline-flex formatting context; Chromium's
+   * text-box-trim can shrink the li's layout box below the code's painted
+   * second line, letting the following item start inside that line. */
+  .root :is(p, h1, h2, h3, h4, h5, h6, blockquote) {
     text-box-trim: trim-both;
     text-box-edge: text;
   }

package/src/client/TypewriterAssistantNodeView.tsx

@@ -3,6 +3,7 @@ import { IconThinkOutline14, JsonBlock, MarkdownText } from '@deepseek-ai/dsh-cl
 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'
 import { AnimatedDisclosure } from './AnimatedDisclosure.tsx'
+import { notifyFollowCommit } from './teleprompterGlide.ts'
 import { useSmoothStreamContent, type StreamSmoothingPreset } from './useSmoothStreamContent.ts'
 import { useFpsGuard } from './useFpsGuard.ts'
 import { FollowHost } from './FollowHost.tsx'
@@ -32,6 +33,7 @@ interface AnimatedMarkdownTextProps extends MarkdownProps {
   /** True on the last text block: that block owns conversation follow. */
   ownFollow: boolean
   followSpeedCpsRef?: { current: number } | undefined
+  followRevealedCharsRef?: { current: number } | undefined
   followRevealScaleRef?: { current: number } | undefined
   onPredictiveChange?: ((predictive: boolean) => void) | undefined
   preset: StreamSmoothingPreset
@@ -289,6 +291,7 @@ function AnimatedMarkdownText({
   streaming,
   ownFollow,
   followSpeedCpsRef,
+  followRevealedCharsRef,
   followRevealScaleRef,
   onPredictiveChange,
   preset,
@@ -308,7 +311,9 @@ function AnimatedMarkdownText({
     preset,
     shouldHoldBack,
     speedCpsRef,
+    revealedCharsRef: followRevealedCharsRef,
     revealScaleRef: followRevealScaleRef,
+    onRevealCommit: () => { notifyFollowCommit(followRootRef.current) },
   })
   const shown = reduced ? text : displayed
   const live = typing && !reduced
@@ -347,11 +352,15 @@ function AnimatedMarkdownText({
     <FollowHost
       active={live && ownFollow}
       speedCpsRef={speedCpsRef}
+      revealedCharsRef={followRevealedCharsRef}
       revealScaleRef={followRevealScaleRef}
       predictive={streaming}
       hostRef={followRootRef}
     >
       <MarkdownText
+        // `shown` stays authoritative through the completion drain: the
+        // settled parse swaps in only when the queue has actually emptied.
+        // Rendering `text` early bypasses the drain and teleports the tail.
         text={live ? shown : text}
         streaming={live}
         codeLabels={codeLabels}
@@ -416,13 +425,19 @@ function AnimatedReasoning({
 }) {
   const reduced = usePrefersReducedMotion()
   const [expanded, setExpanded] = useState(running && thinkAutoExpand)
+  const [autoClosed, setAutoClosed] = useState(false)
   const summaryRef = useRef<HTMLSpanElement>(null)
+  const commitAnchorRef = useRef<HTMLDivElement>(null)
+  // The running→false flip is the AUTO-close: it collapses instantly and the
+  // follower's settle spring absorbs the height step. A later manual toggle
+  // keeps the CSS glide.
   const displayed = useSmoothStreamContent(text, {
     enabled: running && !reduced,
     preset,
     shouldHoldBack,
     speedCpsRef: followSpeedCpsRef,
     revealScaleRef: followRevealScaleRef,
+    onRevealCommit: () => { notifyFollowCommit(commitAnchorRef.current) },
   })
   const shown = running && !reduced ? displayed : text
   const summary = running ? latestLine(shown) : firstLine(text)
@@ -430,7 +445,14 @@ function AnimatedReasoning({
   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)
+    if (thinkAutoExpand) {
+      setExpanded(running)
+      setAutoClosed(!running)
+    }
+    // A commit that changes this block's height must hand the follower its
+    // correction in the SAME task, before the grown-but-uncompensated frame
+    // can reach a paint.
+    notifyFollowCommit(commitAnchorRef.current)
   }, [running, thinkAutoExpand])
 
   useEffect(() => {
@@ -441,7 +463,7 @@ function AnimatedReasoning({
 
   // Preserve FollowHost's layout wrapper without mounting a second scroll owner.
   return (
-    <div className={css.follow}>
+    <div className={css.follow} ref={commitAnchorRef}>
       <div className={css.think} data-variant="think" data-state={running ? 'running' : 'ok'}>
         {running && <span className={css.visuallyHidden}>{t('row.running')}</span>}
         <AnimatedDisclosure
@@ -452,7 +474,15 @@ function AnimatedReasoning({
           icon={<IconThinkOutline14 size={14} />}
           title="Think"
           open={expanded}
-          onToggle={() => { setExpanded(value => !value) }}
+          onToggle={() => {
+            setAutoClosed(false)
+            setExpanded(value => !value)
+          }}
+          // The auto-close at stream end snaps (no grid-track animation): the
+          // follower's settle spring absorbs the height step through the
+          // compositor, so animating the track too would double-animate the
+          // collapse. Manual toggles while streaming keep the glide.
+          bodyTransition={!autoClosed}
           collapsedContent={(
             <>
               <span className={css.thinkSeparator} aria-hidden />
@@ -503,6 +533,7 @@ export const TypewriterAssistantNodeView = memo(function TypewriterAssistantNode
   const reduced = usePrefersReducedMotion()
   const { ref: guardRef, shouldHoldBack } = useFpsGuard(streaming)
   const rootSpeedRef = useRef(35)
+  const rootRevealedCharsRef = useRef(0)
   const rootRevealScaleRef = useRef(1)
   const reasoningTailIndex = streaming && data.blocks[data.blocks.length - 1]?.kind === 'reasoning'
     ? data.blocks.length - 1
@@ -571,6 +602,7 @@ export const TypewriterAssistantNodeView = memo(function TypewriterAssistantNode
             streaming={streaming}
             ownFollow={!streaming && index === lastFollow}
             followSpeedCpsRef={index === lastFollow ? rootSpeedRef : undefined}
+            followRevealedCharsRef={index === lastFollow ? rootRevealedCharsRef : undefined}
             followRevealScaleRef={index === lastFollow ? rootRevealScaleRef : undefined}
             onPredictiveChange={index === lastFollow ? updateTextPrediction : undefined}
             preset={preset}
@@ -628,6 +660,7 @@ export const TypewriterAssistantNodeView = memo(function TypewriterAssistantNode
       <FollowHost
         active={streaming && !reduced}
         speedCpsRef={rootSpeedRef}
+        revealedCharsRef={rootRevealedCharsRef}
         revealScaleRef={rootRevealScaleRef}
         predictiveRef={rootPredictiveRef}
       >

package/src/client/auto-collapse-controller.ts

@@ -27,6 +27,8 @@
  * flowing when background tabs suspend rAF.
  */
 
+import { hasRecentConversationFollow } from './teleprompterGlide.ts'
+
 const STYLE_ID = 'dshss-auto-collapse-style'
 /** Class of the injected per-turn summary row; the follow engine's generalized
  * surface walk picks it up as an ordinary foreign flow sibling. */
@@ -174,6 +176,7 @@ export class AutoCollapseController {
   /** True between start() and stop(); the preference toggle re-enters both. */
   private running = false
   private lastPassError = ''
+  private followDeferredAt: number | null = null
 
   private flow: HTMLElement | null = null
   /** Stable segment key → summary row + gesture state. */
@@ -233,6 +236,7 @@ export class AutoCollapseController {
 
   stop(): void {
     this.running = false
+    this.followDeferredAt = null
     if (this.raf !== 0) cancelAnimationFrame(this.raf)
     this.raf = 0
     if (this.timer !== 0) clearTimeout(this.timer)
@@ -270,13 +274,26 @@ export class AutoCollapseController {
     }, AUDIT_TICK_MS)
   }
 
-  /** Body-level observations only need to wake us up near the active flow. */
+  /** Only mutations inside the active flow can affect collapse geometry. */
   private shouldSchedule(records: MutationRecord[]): boolean {
     if (records.length === 0 || this.flow === null || !this.flow.isConnected) return true
-    return records.some(record => (
-      nodeWithin(record.target, this.flow as HTMLElement)
-      || nodeWithin(this.flow as HTMLElement, record.target)
-    ))
+    const flow = this.flow
+    return records.some(record => {
+      // The harness Tooltip renders its `position: fixed` bubble as a Fragment
+      // sibling INSIDE the message row (not a body portal), so hovering a copy
+      // button mounts/unmounts a node within the flow. It never affects
+      // collapse geometry, but treating it as relevant made hovering re-run
+      // the collapse pass against a streaming flow, racing the follower and
+      // producing visible flicker/jitter. Ignore purely-fixed additions and
+      // removals; keep every layout-affecting mutation.
+      const changed = [...record.addedNodes, ...record.removedNodes]
+      if (changed.length > 0 && changed.every(node => isFloatingOverlayNode(node))) return false
+      if (record.target === flow || nodeWithin(record.target, flow)) return true
+      // Child-list additions/removals can target an ancestor only when the
+      // changed node itself is inside the flow; inspect added/removed nodes so
+      // a body-level tooltip mutation remains ignored.
+      return changed.some(node => nodeWithin(node, flow))
+    })
   }
 
   /** Walk each record to its flow child so reply-cache invalidation stays
@@ -389,49 +406,94 @@ export class AutoCollapseController {
       this.syncProcessedRow(state)
     }
 
-    // Every layout-affecting decision below lands synchronously: one pass,
-    // one reflow, no deferred or animated geometry.
-    for (const [key, state] of [...this.segmentStates]) {
-      if (completedKeys.has(key)) continue
-      state.row?.remove()
-      this.segmentStates.delete(key)
+    // Start the deadline only after a completed segment actually exists.
+    // Opening it during a long-running stream exhausts the full two seconds
+    // before completion and lets the fold collide with the final reveal drain.
+    const portNow = flow.closest<HTMLElement>('[data-conversation-scroll]')
+    if (
+      completedKeys.size > 0
+      && portNow !== null
+      && hasRecentConversationFollow(portNow, 140)
+    ) {
+      const now = Date.now()
+      this.followDeferredAt ??= now
+      if (now - this.followDeferredAt < 2000) {
+        this.schedule()
+        return
+      }
     }
+    this.followDeferredAt = null
 
-    const desiredHidden = new Set<HTMLElement>()
-    for (const segment of segments) {
-      const state = this.segmentStates.get(segment.key)
-      const collapse = state !== undefined && !state.expanded
-      if (collapse) {
-        for (const seat of segment.hideSeats) this.hideElement(seat, desiredHidden)
-        for (const row of segment.finalThinkRows) this.hideElement(row, desiredHidden)
-        // The final answer itself always shows; its thinking rows were hidden
-        // above, everything else about it is restored defensively.
-        if (segment.finalStep !== null) this.restoreElement(segment.finalStep)
-      } else {
-        for (const seat of segment.hideSeats) this.restoreElement(seat)
-        for (const row of segment.finalThinkRows) this.restoreElement(row)
-        if (segment.finalStep !== null) this.restoreElement(segment.finalStep)
+    // Every layout-affecting decision below lands synchronously: one pass,
+    // one reflow, no deferred or animated geometry.
+    //
+    // Folding moves flow height in one commit. A reader pinned to the floor
+    // would see the whole column translate unless scrollTop re-pins to the
+    // new floor in the same frame — the host's own ResizeObserver snap fires
+    // only for RESIZES it observes and can lose the race to paint. Capture
+    // the pin state before the mutations and restore it after.
+    const port = flow.closest<HTMLElement>('[data-conversation-scroll]')
+    const beforeFloor = Math.max(0, (port?.scrollHeight ?? 0) - (port?.clientHeight ?? 0))
+    const pinnedToFloor = port !== null && beforeFloor - port.scrollTop <= 30
+    // Anchor on the LAST VISIBLE MESSAGE SURFACE rather than the scroll floor:
+    // the floor moves with every height change above AND below the fold point,
+    // while the reader's eye is on the answer text. Compensating by this
+    // surface's viewport delta pins exactly what the reader is looking at,
+    // whatever the fold removed or inserted around it.
+    const anchorBefore = lastVisibleAnchorTop(flow)
+
+    const applyMutations = (): void => {
+      for (const [key, state] of [...this.segmentStates]) {
+        if (completedKeys.has(key)) continue
+        state.row?.remove()
+        this.segmentStates.delete(key)
       }
-    }
 
-    // Segments whose work is already invisible (hidden by the host or another
-    // extension) withdraw their summary row instead of pointing at nothing,
-    // but keep owning whatever they still hold so the sweep below leaves it.
-    for (const segment of segments) {
-      if (!hasVisibleSegmentWork(segment)) {
+      const desiredHidden = new Set<HTMLElement>()
+      for (const segment of segments) {
         const state = this.segmentStates.get(segment.key)
-        if (state !== undefined && state.row !== null) {
-          state.row.remove()
-          state.row = null
+        const collapse = state !== undefined && !state.expanded
+        if (collapse) {
+          for (const seat of segment.hideSeats) this.hideElement(seat, desiredHidden)
+          for (const row of segment.finalThinkRows) this.hideElement(row, desiredHidden)
+          // The final answer itself always shows; its thinking rows were hidden
+          // above, everything else about it is restored defensively.
+          if (segment.finalStep !== null) this.restoreElement(segment.finalStep)
+        } else {
+          for (const seat of segment.hideSeats) this.restoreElement(seat)
+          for (const row of segment.finalThinkRows) this.restoreElement(row)
+          if (segment.finalStep !== null) this.restoreElement(segment.finalStep)
+        }
+      }
+
+      // Segments whose work is already invisible (hidden by the host or another
+      // extension) withdraw their summary row instead of pointing at nothing,
+      // but keep owning whatever they still hold so the sweep below leaves it.
+      for (const segment of segments) {
+        if (!hasVisibleSegmentWork(segment)) {
+          const state = this.segmentStates.get(segment.key)
+          if (state !== undefined && state.row !== null) {
+            state.row.remove()
+            state.row = null
+          }
         }
+        for (const seat of segment.hideSeats) this.retainDisplayControl(seat, desiredHidden)
+        for (const row of segment.finalThinkRows) this.retainDisplayControl(row, desiredHidden)
+        if (segment.finalStep !== null) this.retainDisplayControl(segment.finalStep, desiredHidden)
       }
-      for (const seat of segment.hideSeats) this.retainDisplayControl(seat, desiredHidden)
-      for (const row of segment.finalThinkRows) this.retainDisplayControl(row, desiredHidden)
-      if (segment.finalStep !== null) this.retainDisplayControl(segment.finalStep, desiredHidden)
+
+      this.restoreUnusedDisplays(desiredHidden)
+      for (const state of this.segmentStates.values()) this.placeProcessedRow(flow, state)
     }
+    applyMutations()
 
-    this.restoreUnusedDisplays(desiredHidden)
-    for (const state of this.segmentStates.values()) this.placeProcessedRow(flow, state)
+    if (port !== null && pinnedToFloor && anchorBefore !== null) {
+      const anchorAfter = lastVisibleAnchorTop(flow)
+      if (anchorAfter !== null) {
+        const delta = anchorAfter - anchorBefore
+        if (Math.abs(delta) > 0.5) port.scrollTop += delta
+      }
+    }
 
     for (const key of [...this.runningSince.keys()]) {
       if (!liveSegmentKeys.has(key)) this.runningSince.delete(key)
@@ -622,6 +684,24 @@ function nodeWithin(node: Node, ancestor: Node): boolean {
   return false
 }
 
+/**
+ * Whether a mutation-added/removed node is a `position: fixed` overlay (the
+ * harness Tooltip bubble / a popover) that never affects the flow's collapse
+ * geometry. The primitives Tooltip mounts its fixed bubble as a Fragment
+ * sibling inside the message row — `position: fixed` arrives from its CSS
+ * module class, not inline style — so it appears within `[data-chat-flow]`
+ * even though it is viewport-fixed and layout-neutral. Matching on the
+ * tooltip's structural role instead of computed style keeps the filter
+ * reliable before the node has been laid out.
+ */
+function isFloatingOverlayNode(node: Node): boolean {
+  if (!(node instanceof HTMLElement)) return false
+  if (node.getAttribute('role') === 'tooltip') return true
+  if (node.style.position === 'fixed') return true
+  if (node.style.position === 'absolute' && node.parentElement?.getAttribute('role') === 'tooltip') return true
+  return false
+}
+
 /** Top-level message order, excluding this plugin's own summary rows. */
 function flowItems(flow: HTMLElement): HTMLElement[] {
   return [...flow.children].filter((el): el is HTMLElement => (
@@ -862,6 +942,21 @@ function hasBodyText(el: HTMLElement): boolean {
  * tails only carry an end timestamp, which is diffed against the opening user
  * row's timestamp.
  */
+
+/**
+ * Viewport-top of the last visible anchored message row, or null when none is
+ * rendered. Used to pin the reader's visual anchor across a fold commit.
+ */
+function lastVisibleAnchorTop(flow: HTMLElement): number | null {
+  const rows = flow.querySelectorAll<HTMLElement>('[data-chat-anchor-key]')
+  for (let index = rows.length - 1; index >= 0; index -= 1) {
+    const row = rows[index]!
+    if (row.getClientRects().length === 0) continue
+    return row.getBoundingClientRect().top
+  }
+  return null
+}
+
 function parseTurnDuration(boundary: HTMLElement): number | undefined {
   const text = boundary.textContent ?? ''
   const zh = text.match(/用时\s*(\d+)分(\d+)秒|用时\s*(\d+)秒/)

package/src/client/clientStore.ts

@@ -0,0 +1,41 @@
+/**
+ * Kernel compatibility for the client store engine.
+ *
+ * DSH 0.1.2 split the snapshot store out of `@deepseek-ai/dsh-client-runtime`
+ * into a bare `@deepseek-ai/dsh-client-store` module-table seed, while ≤ 0.1.1
+ * kernels keep it on the client-runtime client face. The client module table
+ * only answers what the booting kernel actually ships, so the face must be
+ * probed at runtime: a static require of either specifier kills the whole
+ * loader tree on the other generation (issue #17: a top-level
+ * `require("@deepseek-ai/dsh-client-runtime/client")` took down the web UI on
+ * DSH Desktop 2.0.4 / kernel 0.1.2-alpha.1).
+ */
+
+type ClientRuntimeClient = typeof import('@deepseek-ai/dsh-client-runtime/client')
+
+/**
+ * Runtime require: the module-loader factory scopes its own resolver over the
+ * booting kernel's table; under Node (vitest) there is no global require, so
+ * fall back to `createRequire`.
+ */
+function pickRequire(): NodeRequire {
+  if (typeof require === 'function') return require
+  if (typeof process !== 'undefined' && typeof process.getBuiltinModule === 'function') {
+    const { createRequire } = process.getBuiltinModule('node:module')
+    return createRequire(process.cwd() + '/package.json')
+  }
+  throw new TypeError('dsh-smooth-stream: no client module resolver available')
+}
+
+let clientStore: ClientRuntimeClient
+
+try {
+  // 0.1.2+ seeds the split store package directly into the module table.
+  clientStore = pickRequire()('@deepseek-ai/dsh-client-store') as ClientRuntimeClient
+} catch {
+  // ≤ 0.1.1 owns the store engine on the client-runtime client face.
+  clientStore = pickRequire()('@deepseek-ai/dsh-client-runtime/client') as ClientRuntimeClient
+}
+
+export const createSnapshotStore = clientStore.createSnapshotStore
+export type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'

package/src/client/debugRuntime.ts

@@ -6,7 +6,7 @@
  * while panel edits are staged through the settings-card controller.
  */
 
-import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import { createSnapshotStore, type SnapshotStore } from './clientStore.ts'
 import {
   DEFAULT_STREAM_DEBUG_TUNING,
   type StreamDebugTuning,

package/src/client/smooth-stream-card-controller.ts

@@ -1,6 +1,6 @@
 /** Staged form state for the plugin-owned smooth-stream settings RPC. */
 
-import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import { createSnapshotStore, type SnapshotStore } from './clientStore.ts'
 import {
   DEFAULT_STREAM_DEBUG_TUNING,
   DEFAULT_STREAM_SETTINGS,