dsh-smooth-stream 0.4.2 → 0.5.0

package/lib/index.js

@@ -1,4 +1,3 @@
-import { settingsNamespace } from "@deepseek-ai/dsh-settings";
 import Schema from "@deepseek-ai/schemastery";
 import { readFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join } from "node:path";
@@ -164,8 +163,8 @@ const STREAM_SETTINGS_NS = "smooth-stream";
 /** Defaults shared by the Host schema and the client-side fallback. */
 const DEFAULT_STREAM_SETTINGS = {
 	enabled: true,
+	controlScroll: true,
 	thinkAutoExpand: true,
-	autoCollapse: true,
 	debugEnabled: false,
 	debugTuning: {
 		revealScale: 1,
@@ -200,8 +199,8 @@ const Config = Schema.object({
 */
 const StreamSettingsSchema = Schema.object({
 	enabled: Schema.boolean().default(DEFAULT_STREAM_SETTINGS.enabled),
+	controlScroll: Schema.boolean().default(DEFAULT_STREAM_SETTINGS.controlScroll),
 	thinkAutoExpand: Schema.boolean().default(DEFAULT_STREAM_SETTINGS.thinkAutoExpand),
-	autoCollapse: Schema.boolean().default(DEFAULT_STREAM_SETTINGS.autoCollapse),
 	debugEnabled: Schema.boolean().default(DEFAULT_STREAM_SETTINGS.debugEnabled),
 	debugTuning: Schema.object({
 		revealScale: Schema.number().min(.25).max(2).default(DEFAULT_STREAM_SETTINGS.debugTuning.revealScale),
@@ -229,7 +228,8 @@ function apply(ctx, config) {
 		httpCtx.effect(() => httpCtx.webServer.tapIndex((html) => injectStreamConfig(html, config)), "dsh-smooth-stream: boot config bridge");
 	});
 	ctx.inject(["settings"], (settingsCtx) => {
-		const scope = settingsCtx.settings.register(settingsNamespace(STREAM_SETTINGS_NS), StreamSettingsSchema, { applies: "live" });
+		const settingsNamespace = STREAM_SETTINGS_NS;
+		const scope = settingsCtx.settings.register(settingsNamespace, StreamSettingsSchema, { applies: "live" });
 		settingsCtx.inject(["connection"], (connectionCtx) => {
 			let upgrade;
 			const view = () => {
@@ -240,8 +240,8 @@ function apply(ctx, config) {
 					installation: installation.kind,
 					writable: connectionCtx.settings.writable,
 					enabled: settings.enabled,
+					controlScroll: settings.controlScroll,
 					thinkAutoExpand: settings.thinkAutoExpand,
-					autoCollapse: settings.autoCollapse,
 					canUpgrade: installation.kind === "npm"
 				};
 			};
@@ -263,11 +263,11 @@ function apply(ctx, config) {
 					value: view()
 				};
 				if (endpoint === STREAM_SETTINGS_RPC.write) {
-					if (typeof payload !== "object" || payload === null || Array.isArray(payload) || typeof payload.enabled !== "boolean" || typeof payload.thinkAutoExpand !== "boolean" || typeof payload.autoCollapse !== "boolean") return {
+					if (typeof payload !== "object" || payload === null || Array.isArray(payload) || typeof payload.enabled !== "boolean" || typeof payload.controlScroll !== "boolean" || typeof payload.thinkAutoExpand !== "boolean") return {
 						ok: false,
 						error: {
 							code: "settings-rejected",
-							message: "enabled, thinkAutoExpand and autoCollapse must be booleans",
+							message: "enabled, controlScroll and thinkAutoExpand must be booleans",
 							details: { ns: STREAM_SETTINGS_NS }
 						}
 					};
@@ -292,8 +292,8 @@ function apply(ctx, config) {
 						};
 						await scope.update({
 							enabled: next.enabled,
+							controlScroll: next.controlScroll,
 							thinkAutoExpand: next.thinkAutoExpand,
-							autoCollapse: next.autoCollapse,
 							...hasDebug ? {
 								debugEnabled: next.debugEnabled,
 								debugTuning: next.debugTuning

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-smooth-stream",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Fluid streaming rendering and silky scrolling for DeepSeek Harness replies, including Markdown, code blocks, tables, and tool results.",
   "license": "MIT",
   "type": "module",
@@ -81,12 +81,18 @@
   "scripts": {
     "benchmark": "node scripts/run-stream-benchmark.mjs",
     "build": "tsdown",
+    "dev:watch": "tsdown --watch",
+    "host:sync": "pnpm build && node scripts/check-lib-fresh.mjs",
     "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",
+    "build:stress": "esbuild repro/stress-120fps.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/stress-120fps.bundle.js",
+    "stress:120fps": "node scripts/stress-test-120fps.mjs",
+    "test:rebound": "node scripts/verify-y-rebound.mjs",
     "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"
+    "test:smooth": "node scripts/verify-y-rebound.mjs && node scripts/probe-tailbob.mjs 1200 20 && node scripts/verify-overflow.mjs --runs 3",
+    "probe:overlap": "node scripts/probe-overlap.mjs",
+    "probe:stability": "node scripts/verify-follow-stability.mjs"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
@@ -139,12 +145,12 @@
   "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-locale": "0.1.2-alpha.3",
     "@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-ui-conversation": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-ui-primitives": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.1.2-alpha.3",
     "@deepseek-ai/dsh-client-ui-settings": "0.1.0-rc.6",
     "@deepseek-ai/dsh-client-ui-settings-plugins": "0.1.0-rc.6",
     "@deepseek-ai/dsh-client-ui-slots": "0.1.0-rc.6",

package/src/client/AgentRowEntrance.module.css

@@ -0,0 +1,43 @@
+/*
+ * Opaque Agent rows (tools, retries, context, etc.) cannot reuse the
+ * assistant's character queue. This is a single compositor-friendly reveal:
+ * the row arrives with a short rise/fade and a left-to-right mask, echoing the
+ * assistant's reading cadence without re-typing status text or countdowns.
+ */
+.surface {
+  min-width: 0;
+}
+
+.surface[data-entrance='active'] {
+  animation: dsh-smooth-stream-agent-row-in 220ms cubic-bezier(0.2, 0.8, 0.2, 1) both;
+  will-change: opacity, transform;
+}
+
+@keyframes dsh-smooth-stream-agent-row-in {
+  0% {
+    opacity: 0;
+    transform: translate3d(0, 4px, 0);
+    clip-path: inset(0 100% 0 0);
+  }
+
+  55% {
+    opacity: 1;
+    clip-path: inset(0 18% 0 0);
+  }
+
+  100% {
+    opacity: 1;
+    transform: translate3d(0, 0, 0);
+    clip-path: inset(0 0 0 0);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .surface[data-entrance='active'] {
+    animation: none;
+    opacity: 1;
+    transform: none;
+    clip-path: none;
+    will-change: auto;
+  }
+}

package/src/client/FollowHost.tsx

@@ -19,7 +19,10 @@ export function FollowHost({
   revealScaleRef,
   predictive = true,
   predictiveRef,
+  controlScroll = true,
   hostRef,
+  className,
+  entranceActive,
   children,
 }: {
   active: boolean
@@ -32,8 +35,13 @@ export function FollowHost({
   revealScaleRef?: { current: number } | undefined
   predictive?: boolean
   predictiveRef?: { current: boolean } | undefined
+  /** False leaves conversation bottom-follow to the Host. */
+  controlScroll?: boolean
   hostRef?: { current: HTMLDivElement | null } | undefined
   children: ReactNode
+  className?: string | undefined
+  /** Optional marker for a generic row's one-shot entrance animation. */
+  entranceActive?: boolean | undefined
 }) {
   const localRootRef = useRef<HTMLDivElement>(null)
   const rootRef = hostRef ?? localRootRef
@@ -48,6 +56,7 @@ export function FollowHost({
     predictiveRef,
     entranceExtentRef,
     revealedCharsRef,
+    controlScroll,
   )
   useEffect(() => {
     if (onGrowth === undefined || typeof ResizeObserver === 'undefined') return
@@ -79,5 +88,13 @@ export function FollowHost({
       if (growthFrame !== null) cancelAnimationFrame(growthFrame)
     }
   }, [onGrowth])
-  return <div ref={rootRef} className={css.follow}>{children}</div>
+  return (
+    <div
+      ref={rootRef}
+      className={className === undefined ? css.follow : `${css.follow} ${className}`}
+      data-entrance={entranceActive === undefined ? undefined : entranceActive ? 'active' : 'idle'}
+    >
+      {children}
+    </div>
+  )
 }

package/src/client/SmoothStreamCard.tsx

@@ -73,29 +73,29 @@ export function SmoothStreamCard(props: SmoothStreamCardProps) {
                 </label>
                 <label className={state.enabled ? css.field : `${css.field} ${css.fieldDisabled}`}>
                   <span className={css.fieldHead}>
-                    <span className={css.label}>{t('thinkAutoExpand')}</span>
+                    <span className={css.label}>{t('controlScroll')}</span>
                     <input
                       type="checkbox"
                       className={css.toggle}
-                      checked={state.thinkAutoExpand}
+                      checked={state.controlScroll}
                       disabled={!state.writable || state.saving || !state.enabled}
-                      onChange={(event) => { props.edit({ thinkAutoExpand: event.target.checked }) }}
+                      onChange={(event) => { props.edit({ controlScroll: event.target.checked }) }}
                     />
                   </span>
-                  <span className={css.hint}>{t('thinkAutoExpandHint')}</span>
+                  <span className={css.hint}>{t('controlScrollHint')}</span>
                 </label>
-                <label className={css.field}>
+                <label className={state.enabled ? css.field : `${css.field} ${css.fieldDisabled}`}>
                   <span className={css.fieldHead}>
-                    <span className={css.label}>{t('autoCollapse')}</span>
+                    <span className={css.label}>{t('thinkAutoExpand')}</span>
                     <input
                       type="checkbox"
                       className={css.toggle}
-                      checked={state.autoCollapse}
-                      disabled={!state.writable || state.saving}
-                      onChange={(event) => { props.edit({ autoCollapse: event.target.checked }) }}
+                      checked={state.thinkAutoExpand}
+                      disabled={!state.writable || state.saving || !state.enabled}
+                      onChange={(event) => { props.edit({ thinkAutoExpand: event.target.checked }) }}
                     />
                   </span>
-                  <span className={css.hint}>{t('autoCollapseHint')}</span>
+                  <span className={css.hint}>{t('thinkAutoExpandHint')}</span>
                 </label>
                 <label className={state.debugAvailable ? css.field : `${css.field} ${css.fieldDisabled}`}>
                   <span className={css.fieldHead}>

package/src/client/TypewriterAssistantNodeView.tsx

@@ -12,7 +12,7 @@ import { DEFAULT_STREAM_SETTINGS } from '../settings.ts'
 import css from './TypewriterAssistantNodeView.module.css'
 
 type AssistantProps = ChatNodeViewProps<'assistant-step'>
-type MarkdownProps = Pick<ComponentProps<typeof MarkdownText>, 'codeLabels' | 'fileMentions' | 'text'>
+type MarkdownProps = Pick<ComponentProps<typeof MarkdownText>, 'labels' | 'fileMentions' | 'text'>
 
 function usePrefersReducedMotion(): boolean {
   const [reduced, setReduced] = useState(
@@ -38,6 +38,7 @@ interface AnimatedMarkdownTextProps extends MarkdownProps {
   onPredictiveChange?: ((predictive: boolean) => void) | undefined
   preset: StreamSmoothingPreset
   shouldHoldBack: () => boolean
+  controlScroll?: boolean
 }
 
 /** Conservative fallback before the streaming Markdown tail has geometry. */
@@ -286,7 +287,7 @@ const StreamAnnouncement = memo(function StreamAnnouncement({
  */
 function AnimatedMarkdownText({
   text,
-  codeLabels,
+  labels,
   fileMentions,
   streaming,
   ownFollow,
@@ -296,6 +297,7 @@ function AnimatedMarkdownText({
   onPredictiveChange,
   preset,
   shouldHoldBack,
+  controlScroll = true,
 }: AnimatedMarkdownTextProps) {
   const reduced = usePrefersReducedMotion()
   const [typing, setTyping] = useState(streaming)
@@ -355,6 +357,7 @@ function AnimatedMarkdownText({
       revealedCharsRef={followRevealedCharsRef}
       revealScaleRef={followRevealScaleRef}
       predictive={streaming}
+      controlScroll={controlScroll}
       hostRef={followRootRef}
     >
       <MarkdownText
@@ -363,7 +366,7 @@ function AnimatedMarkdownText({
         // Rendering `text` early bypasses the drain and teleports the tail.
         text={live ? shown : text}
         streaming={live}
-        codeLabels={codeLabels}
+        labels={labels}
         fileMentions={live ? undefined : fileMentions}
       />
     </FollowHost>
@@ -514,6 +517,7 @@ export const TypewriterAssistantNodeView = memo(function TypewriterAssistantNode
   scrollSpeedPxPerSec: _scrollSpeedPxPerSec = DEFAULT_STREAM_CONFIG.scrollSpeedPxPerSec,
   maxScrollSpeedPxPerSec: _maxScrollSpeedPxPerSec = DEFAULT_STREAM_CONFIG.maxScrollSpeedPxPerSec,
   thinkAutoExpand = DEFAULT_STREAM_SETTINGS.thinkAutoExpand,
+  controlScroll = true,
   node,
   useTurnData,
   openFile,
@@ -527,6 +531,7 @@ export const TypewriterAssistantNodeView = memo(function TypewriterAssistantNode
   scrollSpeedPxPerSec?: number
   maxScrollSpeedPxPerSec?: number
   thinkAutoExpand?: boolean
+  controlScroll?: boolean
 }) {
   const data = node.data
   const streaming = data.status === 'running'
@@ -568,7 +573,10 @@ export const TypewriterAssistantNodeView = memo(function TypewriterAssistantNode
     () => owner === undefined ? undefined : fileMentions(owner),
     [fileMentions, owner],
   )
-  const codeLabels = useMemo(() => ({ copyLabel: t('copy'), copiedLabel: t('copied') }), [t])
+  const markdownLabels = useMemo(() => ({
+    code: { copyLabel: t('copy'), copiedLabel: t('copied') },
+    footnotes: t('markdown.footnotes'),
+  }), [t])
   const imageLoader: ImageLoader = loadImage ?? (async () => {
     throw new Error(t('image.serviceUnavailable'))
   })
@@ -597,7 +605,7 @@ export const TypewriterAssistantNodeView = memo(function TypewriterAssistantNode
           <AnimatedMarkdownText
             key={index}
             text={block.text}
-            codeLabels={codeLabels}
+            labels={markdownLabels}
             fileMentions={mentions}
             streaming={streaming}
             ownFollow={!streaming && index === lastFollow}
@@ -607,6 +615,7 @@ export const TypewriterAssistantNodeView = memo(function TypewriterAssistantNode
             onPredictiveChange={index === lastFollow ? updateTextPrediction : undefined}
             preset={preset}
             shouldHoldBack={shouldHoldBack}
+            controlScroll={controlScroll}
           />,
         )
         break
@@ -663,6 +672,7 @@ export const TypewriterAssistantNodeView = memo(function TypewriterAssistantNode
         revealedCharsRef={rootRevealedCharsRef}
         revealScaleRef={rootRevealScaleRef}
         predictiveRef={rootPredictiveRef}
+        controlScroll={controlScroll}
       >
         <div className={css.body}>
           {rendered}

package/src/client/TypewriterToolNodeView.tsx

@@ -2,6 +2,7 @@ import { createElement, useCallback, useEffect, useLayoutEffect, useRef, useStat
 import { FollowHost } from './FollowHost.tsx'
 import { useProgressiveDomText } from './useProgressiveDomText.ts'
 import { hasRecentConversationFollow } from './teleprompterGlide.ts'
+import entranceCss from './AgentRowEntrance.module.css'
 
 /** Props forwarded through a follow wrap; extra kit seats pass through. */
 export type FollowWrapProps = {
@@ -118,8 +119,12 @@ function liveAgentTailMode(root: HTMLElement): 'turn' | 'handoff' | null {
  * @param Inner - The already-registered row component.
  * @returns A follow-hosted row.
  */
-export function wrapFollowNodeView(Inner: ComponentType<FollowWrapProps>) {
+export function wrapFollowNodeView(
+  Inner: ComponentType<FollowWrapProps>,
+  useControlScroll?: () => boolean,
+) {
   return function TypewriterFollowNodeView(props: FollowWrapProps) {
+    const controlScroll = useControlScroll?.() ?? true
     const speedCpsRef = useRef(35)
     const hostRef = useRef<HTMLDivElement>(null)
     const growing = isGrowingChatNode(props.node)
@@ -215,12 +220,15 @@ export function wrapFollowNodeView(Inner: ComponentType<FollowWrapProps>) {
         onGrowth={followable ? onGrowth : undefined}
         entranceExtentRef={growthExtentRef}
         speedCpsRef={speedCpsRef}
+        controlScroll={controlScroll}
         // Generic Agent rows reveal and spring their measured growth, but do
         // not continuously reserve space for a future Markdown line wrap.
         // Keeping that assistant-only prediction here creates an idle gap
         // above TurnStatus and a visible return when a short Tool row settles.
         predictive={false}
         hostRef={hostRef}
+        className={entranceCss.surface}
+        entranceActive={entering || growthPulse}
       >
         {createElement(Inner, props)}
       </FollowHost>

package/src/client/clientStore.ts

@@ -13,29 +13,88 @@
 
 type ClientRuntimeClient = typeof import('@deepseek-ai/dsh-client-runtime/client')
 
+export interface SnapshotStoreLike<T> {
+  getSnapshot(): T
+  subscribe(listener: (state: T) => void): () => void
+  update(mutator: (draft: T) => void): void
+  set(next: T): void
+}
+
+function fallbackSnapshotStore<T extends object>(init: T): SnapshotStoreLike<T> {
+  let state = init
+  const listeners = new Set<(state: T) => void>()
+  return {
+    getSnapshot: () => state,
+    subscribe: listener => {
+      listeners.add(listener)
+      return () => { listeners.delete(listener) }
+    },
+    update: mutator => {
+      const draft = Object.create(
+        Object.getPrototypeOf(state),
+        Object.getOwnPropertyDescriptors(state),
+      ) as T
+      mutator(draft)
+      state = draft
+      for (const listener of [...listeners]) listener(state)
+    },
+    set: next => {
+      state = next
+      for (const listener of [...listeners]) listener(state)
+    },
+  }
+}
+
 /**
  * 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
+function pickRequire(): NodeRequire | null {
+  if (typeof require === 'function') {
+    try {
+      return require
+    } catch {
+      return null
+    }
+  }
   if (typeof process !== 'undefined' && typeof process.getBuiltinModule === 'function') {
-    const { createRequire } = process.getBuiltinModule('node:module')
-    return createRequire(process.cwd() + '/package.json')
+    try {
+      const { createRequire } = process.getBuiltinModule('node:module')
+      return createRequire(process.cwd() + '/package.json')
+    } catch {
+      return null
+    }
   }
-  throw new TypeError('dsh-smooth-stream: no client module resolver available')
+  return null
 }
 
-let clientStore: ClientRuntimeClient
+let clientStore: Partial<ClientRuntimeClient> | undefined
 
 try {
-  // 0.1.2+ seeds the split store package directly into the module table.
-  clientStore = pickRequire()('@deepseek-ai/dsh-client-store') as ClientRuntimeClient
+  const req = pickRequire()
+  if (req !== null) {
+    try {
+      // 0.1.2+ seeds the split store package directly into the module table.
+      clientStore = req('@deepseek-ai/dsh-client-store') as ClientRuntimeClient
+    } catch {
+      try {
+        // ≤ 0.1.1 owns the store engine on the client-runtime client face.
+        clientStore = req('@deepseek-ai/dsh-client-runtime/client') as ClientRuntimeClient
+      } catch {
+        // Fallback below
+      }
+    }
+  }
 } catch {
-  // ≤ 0.1.1 owns the store engine on the client-runtime client face.
-  clientStore = pickRequire()('@deepseek-ai/dsh-client-runtime/client') as ClientRuntimeClient
+  // Fallback below
+}
+
+export interface SnapshotStore<T> {
+  getSnapshot(): T
+  subscribe(listener: () => void): () => void
+  update(mutator: (draft: T) => void): void
+  set(next: T): void
 }
 
-export const createSnapshotStore = clientStore.createSnapshotStore
-export type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+export const createSnapshotStore = (clientStore?.createSnapshotStore ?? fallbackSnapshotStore) as <T extends object>(init: T) => SnapshotStore<T>

package/src/client/index.ts

@@ -7,7 +7,6 @@ import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client
 import type {} from '@deepseek-ai/dsh-client-ui-settings-plugins/client'
 import type { ChatNodeViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { TypewriterAssistantNodeView } from './TypewriterAssistantNodeView.tsx'
-import { AutoCollapseController } from './auto-collapse-controller.ts'
 import { wrapFollowNodeView, type FollowWrapProps } from './TypewriterToolNodeView.tsx'
 import { SmoothStreamCard } from './SmoothStreamCard.tsx'
 import { SmoothStreamCardController } from './smooth-stream-card-controller.ts'
@@ -88,7 +87,10 @@ function readBootConfig(): StreamConfig {
  * @param ctx - Browser context carrying the slot registry.
  * @returns Restorer that puts the original components back.
  */
-function wrapAgentChatRows(ctx: ClientContext): () => void {
+function wrapAgentChatRows(
+  ctx: ClientContext,
+  useControlScroll: () => boolean,
+): () => void {
   const restores: Array<() => void> = []
   const wrapped = new WeakSet<object>()
 
@@ -99,7 +101,7 @@ function wrapAgentChatRows(ctx: ClientContext): () => void {
       const current = entry.component
       if (!isWrappableComponent(current) || wrapped.has(current)) continue
       const inner = current as ComponentType<FollowWrapProps>
-      const next = wrapFollowNodeView(inner)
+      const next = wrapFollowNodeView(inner, useControlScroll)
       wrapped.add(next)
       entry.component = next
       restores.push(() => {
@@ -154,8 +156,8 @@ class SettingsCell {
     if (
       pending === this.pending
       && next.enabled === this.value.enabled
+      && next.controlScroll === this.value.controlScroll
       && next.thinkAutoExpand === this.value.thinkAutoExpand
-      && next.autoCollapse === this.value.autoCollapse
       && next.debugEnabled === this.value.debugEnabled
       && next.debugTuning === this.value.debugTuning
     ) return
@@ -169,11 +171,6 @@ class SettingsCell {
     return !this.pending && this.value.enabled
   }
 
-  /** Whether finished turns should fold behind a summary row right now. */
-  autoCollapseActive(): boolean {
-    return !this.pending && this.value.autoCollapse
-  }
-
   readonly getSnapshot = (): StreamSettings => this.value
 
   readonly subscribe = (listener: () => void): () => void => {
@@ -196,25 +193,11 @@ class SettingsCell {
 export function apply(ctx: ClientContext): void {
   const config = readBootConfig()
   const settings = new SettingsCell()
-
-  // Auto-collapse works at the DOM level and is independent of the renderer
-  // takeover: it also folds finished turns when the built-in Harness renderer
-  // owns the conversation. The lifecycle rides the guaranteed `slots` service
-  // (this entry's own inject list) and follows the same live settings cell, so
-  // flipping the preference restores every folded row immediately.
-  ctx.inject(['slots'], () => {
-    const autoCollapse = new AutoCollapseController()
-    const syncAutoCollapse = (): void => {
-      if (settings.autoCollapseActive()) autoCollapse.start()
-      else autoCollapse.stop()
-    }
-    const unsubscribe = settings.subscribe(syncAutoCollapse)
-    syncAutoCollapse()
-    return () => {
-      unsubscribe()
-      autoCollapse.stop()
-    }
-  })
+  const useControlScroll = (): boolean => useSyncExternalStore(
+    settings.subscribe,
+    () => settings.getSnapshot().controlScroll,
+    () => settings.getSnapshot().controlScroll,
+  )
 
   // The card talks to the plugin-owned loopback RPC, so the core settings
   // namespace allowlist cannot make it disappear. The stream still applies
@@ -286,6 +269,7 @@ export function apply(ctx: ClientContext): void {
       scrollSpeedPxPerSec: config.scrollSpeedPxPerSec,
       maxScrollSpeedPxPerSec: config.maxScrollSpeedPxPerSec,
       thinkAutoExpand: preferences.thinkAutoExpand,
+      controlScroll: preferences.controlScroll,
     })
   }
   ctx.slots.inject('conversation.chat.node', () => {
@@ -298,7 +282,7 @@ export function apply(ctx: ClientContext): void {
         return
       }
       if (releaseTakeover !== undefined) return
-      const unwrap = wrapAgentChatRows(ctx)
+      const unwrap = wrapAgentChatRows(ctx, useControlScroll)
       const unshadow = ctx.slots.register({
         name: 'conversation.chat.node',
         key: 'assistant-step',

package/src/client/locales.ts

@@ -7,8 +7,8 @@ export const NS = 'settings.smoothStream'
 export type SmoothStreamLocaleKey =
   | 'title' | 'description'
   | 'enabled' | 'enabledHint'
+  | 'controlScroll' | 'controlScrollHint'
   | 'thinkAutoExpand' | 'thinkAutoExpandHint'
-  | 'autoCollapse' | 'autoCollapseHint'
   | 'debugEnabled' | 'debugEnabledHint' | 'debugUnavailable'
   | 'debugPanelTitle' | 'debugPanelToggle' | 'debugPanelClose' | 'debugGuide'
   | 'debugLive' | 'debugIdle' | 'debugUnsaved'
@@ -35,10 +35,10 @@ export const en: Record<SmoothStreamLocaleKey, string> = {
   description: 'How replies are revealed while they stream.',
   enabled: 'Enable smooth streaming',
   enabledHint: 'Let this plugin render and follow streaming replies. Turn off to use the built-in Harness renderer.',
+  controlScroll: 'Take over scrolling',
+  controlScrollHint: 'On by default; smooth-stream writes the conversation scroll position. Turn off to leave bottom-follow to Harness.',
   thinkAutoExpand: 'Auto-expand thinking',
   thinkAutoExpandHint: 'Open the thinking block while it streams. Turn off to keep it collapsed.',
-  autoCollapse: 'Collapse finished work',
-  autoCollapseHint: 'When a reply finishes, fold its thinking, tools, and intermediate output behind one “Processed” summary so only the final answer shows. Click the summary to expand again; works with streaming on or off.',
   debugEnabled: 'Show render diagnostics',
   debugEnabledHint: 'Show live streaming and scroll metrics on the right side of the chat. Tune values there, then save them here.',
   debugUnavailable: 'Live diagnostics require a newer plugin Host.',
@@ -115,10 +115,10 @@ export const zh: Record<SmoothStreamLocaleKey, string> = {
   description: '回复在流式输出时如何逐字展现。',
   enabled: '启用丝滑流式渲染',
   enabledHint: '由本插件渲染并跟随流式回复；关闭后使用 Harness 内置渲染。',
+  controlScroll: '接管滚动',
+  controlScrollHint: '默认开启，由丝滑流式写入会话滚动位置；关闭后贴底滚动交给 Harness。',
   thinkAutoExpand: '自动展开思考',
   thinkAutoExpandHint: '思考块在流式时自动展开；关闭后保持折叠，可手动展开。',
-  autoCollapse: '完成后自动折叠',
-  autoCollapseHint: '回复处理完成后，把思考、工具与过程输出折叠为一行“已处理”摘要，只展示最终回复；点击摘要可再次展开。开启或关闭流式渲染均可用，默认开启。',
   debugEnabled: '显示渲染调试面板',
   debugEnabledHint: '在聊天右侧显示流式渲染和滚动的实时参数，可在面板中调节并在这里保存。',
   debugUnavailable: '当前 Host 版本不支持实时调试，请先更新插件 Host。',

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

@@ -22,8 +22,8 @@ export interface SmoothStreamCardState {
   saving: boolean
   failed: boolean
   enabled: boolean
+  controlScroll: boolean
   thinkAutoExpand: boolean
-  autoCollapse: boolean
   debugEnabled: boolean
   debugTuning: StreamDebugTuning
   debugAvailable: boolean
@@ -52,7 +52,7 @@ export class SmoothStreamCardController {
   private readonly store = createSnapshotStore<SmoothStreamCardState>(this.projection())
   private loaded: StreamSettingsView | undefined
   private loadedDebug: StreamDebugSettingsView | undefined
-  private stagedBase: Pick<StreamSettings, 'enabled' | 'thinkAutoExpand' | 'autoCollapse'> | undefined
+  private stagedBase: Pick<StreamSettings, 'enabled' | 'controlScroll' | 'thinkAutoExpand'> | undefined
   private stagedDebug: Pick<StreamSettings, 'debugEnabled' | 'debugTuning'> | undefined
   private saving = false
   private failed = false
@@ -90,12 +90,12 @@ export class SmoothStreamCardController {
       hooks: { smoothStreamCard: this.store },
       edit: (patch) => {
         if (this.saving) return
-        if (patch.enabled !== undefined || patch.thinkAutoExpand !== undefined || patch.autoCollapse !== undefined) {
+        if (patch.enabled !== undefined || patch.controlScroll !== undefined || patch.thinkAutoExpand !== undefined) {
           this.stagedBase = {
             ...this.baseValues(),
             ...(patch.enabled === undefined ? {} : { enabled: patch.enabled }),
+            ...(patch.controlScroll === undefined ? {} : { controlScroll: patch.controlScroll }),
             ...(patch.thinkAutoExpand === undefined ? {} : { thinkAutoExpand: patch.thinkAutoExpand }),
-            ...(patch.autoCollapse === undefined ? {} : { autoCollapse: patch.autoCollapse }),
           }
         }
         if (this.loadedDebug !== undefined && (patch.debugEnabled !== undefined || patch.debugTuning !== undefined)) {
@@ -140,11 +140,11 @@ export class SmoothStreamCardController {
     }
   }
 
-  private baseValues(): Pick<StreamSettings, 'enabled' | 'thinkAutoExpand' | 'autoCollapse'> {
+  private baseValues(): Pick<StreamSettings, 'enabled' | 'controlScroll' | 'thinkAutoExpand'> {
     return this.stagedBase ?? {
       enabled: this.loaded?.enabled ?? DEFAULT_STREAM_SETTINGS.enabled,
+      controlScroll: this.loaded?.controlScroll ?? DEFAULT_STREAM_SETTINGS.controlScroll,
       thinkAutoExpand: this.loaded?.thinkAutoExpand ?? DEFAULT_STREAM_SETTINGS.thinkAutoExpand,
-      autoCollapse: this.loaded?.autoCollapse ?? DEFAULT_STREAM_SETTINGS.autoCollapse,
     }
   }