dsh-smooth-stream 0.4.3 → 0.6.0

package/lib/index.js

@@ -163,8 +163,9 @@ 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,
+	motionPreference: "auto",
 	thinkAutoExpand: true,
-	autoCollapse: true,
 	debugEnabled: false,
 	debugTuning: {
 		revealScale: 1,
@@ -199,8 +200,13 @@ const Config = Schema.object({
 */
 const StreamSettingsSchema = Schema.object({
 	enabled: Schema.boolean().default(DEFAULT_STREAM_SETTINGS.enabled),
+	controlScroll: Schema.boolean().default(DEFAULT_STREAM_SETTINGS.controlScroll),
+	motionPreference: Schema.union([
+		Schema.const("auto"),
+		Schema.const("force-smooth"),
+		Schema.const("force-reduced")
+	]).default(DEFAULT_STREAM_SETTINGS.motionPreference),
 	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),
@@ -240,8 +246,9 @@ function apply(ctx, config) {
 					installation: installation.kind,
 					writable: connectionCtx.settings.writable,
 					enabled: settings.enabled,
+					controlScroll: settings.controlScroll,
+					motionPreference: settings.motionPreference,
 					thinkAutoExpand: settings.thinkAutoExpand,
-					autoCollapse: settings.autoCollapse,
 					canUpgrade: installation.kind === "npm"
 				};
 			};
@@ -263,11 +270,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 }
 						}
 					};
@@ -281,6 +288,14 @@ function apply(ctx, config) {
 					};
 					try {
 						const next = payload;
+						if (next.motionPreference !== void 0 && next.motionPreference !== "auto" && next.motionPreference !== "force-smooth" && next.motionPreference !== "force-reduced") return {
+							ok: false,
+							error: {
+								code: "settings-rejected",
+								message: "motionPreference must be one of auto | force-smooth | force-reduced",
+								details: { ns: STREAM_SETTINGS_NS }
+							}
+						};
 						const hasDebug = next.debugEnabled !== void 0 || next.debugTuning !== void 0;
 						if (hasDebug && (typeof next.debugEnabled !== "boolean" || !validDebugTuning(next.debugTuning))) return {
 							ok: false,
@@ -292,8 +307,9 @@ function apply(ctx, config) {
 						};
 						await scope.update({
 							enabled: next.enabled,
+							controlScroll: next.controlScroll,
+							...next.motionPreference === void 0 ? {} : { motionPreference: next.motionPreference },
 							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.3",
+  "version": "0.6.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.module.css

@@ -157,6 +157,40 @@
   outline-offset: 2px;
 }
 
+.choiceRow {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px 14px;
+  margin: 2px 0 0;
+  padding: 0;
+}
+
+.choice {
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-secondary);
+  cursor: pointer;
+}
+
+.choiceInput {
+  width: 14px;
+  height: 14px;
+  accent-color: var(--dsw-alias-brand-primary);
+  cursor: pointer;
+}
+
+.choice:has(.choiceInput:disabled) {
+  cursor: default;
+  opacity: 0.55;
+}
+
+.choiceInput:disabled {
+  cursor: default;
+}
+
 .hint {
   margin: 0;
   font-size: 12px;

package/src/client/SmoothStreamCard.tsx

@@ -73,29 +73,58 @@ 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}>
+                {/* Motion preference is a radio group, so this row is a div:
+                    nesting the choice labels inside a field <label> would be
+                    illegal HTML (label within label) and browsers route the
+                    inner click away, so React never sees onChange. */}
+                <div className={state.enabled ? css.field : `${css.field} ${css.fieldDisabled}`}>
+                  <span className={css.fieldHead}>
+                    <span className={css.label}>{t('motionPreference')}</span>
+                  </span>
+                  <span className={css.hint}>{t('motionPreferenceHint')}</span>
+                  <span className={css.choiceRow} role="radiogroup" aria-label={t('motionPreference')}>
+                    {([
+                      ['auto', 'motionAuto', 'motionAutoHint'],
+                      ['force-smooth', 'motionForceSmooth', 'motionForceSmoothHint'],
+                      ['force-reduced', 'motionForceReduced', 'motionForceReducedHint'],
+                    ] as const).map(([value, label, hint]) => (
+                      <label key={value} className={css.choice} title={t(hint)}>
+                        <input
+                          type="radio"
+                          className={css.choiceInput}
+                          name="smooth-stream-motion"
+                          checked={state.motionPreference === value}
+                          disabled={!state.writable || state.saving || !state.enabled}
+                          onChange={() => { props.edit({ motionPreference: value }) }}
+                        />
+                        {t(label)}
+                      </label>
+                    ))}
+                  </span>
+                </div>
+                <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

@@ -1,4 +1,4 @@
-import { memo, useEffect, useLayoutEffect, useMemo, useRef, useState, type ComponentProps, type ReactNode } from 'react'
+import { memo, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type ComponentProps, type ReactNode, type RefObject } 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'
@@ -8,11 +8,11 @@ import { useSmoothStreamContent, type StreamSmoothingPreset } from './useSmoothS
 import { useFpsGuard } from './useFpsGuard.ts'
 import { FollowHost } from './FollowHost.tsx'
 import { DEFAULT_STREAM_CONFIG, type StreamMode } from '../config.ts'
-import { DEFAULT_STREAM_SETTINGS } from '../settings.ts'
+import { DEFAULT_STREAM_SETTINGS, type StreamMotionPreference } 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(
@@ -28,8 +28,25 @@ function usePrefersReducedMotion(): boolean {
   return reduced
 }
 
+/**
+ * Resolve whether the reveal engine should stay off for this view. The OS
+ * preference wins only in `auto` mode: `force-smooth` keeps the engine on
+ * machines where a system-wide reduce-motion switch (or a forced browser
+ * flag) would otherwise silently bypass smoothing, and `force-reduced`
+ * disables it even when the OS asks for motion. Credit: three-state design
+ * proposed by @Zn-Dk in #21/#22.
+ */
+function useMotionReduced(preference: StreamMotionPreference): boolean {
+  const system = usePrefersReducedMotion()
+  if (preference === 'force-smooth') return false
+  if (preference === 'force-reduced') return true
+  return system
+}
+
 interface AnimatedMarkdownTextProps extends MarkdownProps {
   streaming: boolean
+  /** Whether the resolved reduced-motion gate keeps the reveal engine off. */
+  motionReduced: boolean
   /** True on the last text block: that block owns conversation follow. */
   ownFollow: boolean
   followSpeedCpsRef?: { current: number } | undefined
@@ -38,6 +55,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,9 +304,10 @@ const StreamAnnouncement = memo(function StreamAnnouncement({
  */
 function AnimatedMarkdownText({
   text,
-  codeLabels,
+  labels,
   fileMentions,
   streaming,
+  motionReduced,
   ownFollow,
   followSpeedCpsRef,
   followRevealedCharsRef,
@@ -296,8 +315,9 @@ function AnimatedMarkdownText({
   onPredictiveChange,
   preset,
   shouldHoldBack,
+  controlScroll = true,
 }: AnimatedMarkdownTextProps) {
-  const reduced = usePrefersReducedMotion()
+  const reduced = motionReduced
   const [typing, setTyping] = useState(streaming)
   const localSpeedCpsRef = useRef(35)
   const followRootRef = useRef<HTMLDivElement>(null)
@@ -348,6 +368,14 @@ function AnimatedMarkdownText({
     if (typing && !streaming && shown.length === text.length) setTyping(false)
   }, [shown, streaming, text, typing])
 
+  // A row can mount before the projection flips its assistant step to
+  // `running`, which would freeze `typing` at false forever and leave the
+  // reveal engine off for the whole reply. Re-arm on the rising edge so late
+  // stream starts are still smoothed. (Adopted from #22 by @Zn-Dk.)
+  useEffect(() => {
+    if (streaming) setTyping(true)
+  }, [streaming])
+
   return (
     <FollowHost
       active={live && ownFollow}
@@ -355,6 +383,7 @@ function AnimatedMarkdownText({
       revealedCharsRef={followRevealedCharsRef}
       revealScaleRef={followRevealScaleRef}
       predictive={streaming}
+      controlScroll={controlScroll}
       hostRef={followRootRef}
     >
       <MarkdownText
@@ -363,7 +392,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>
@@ -384,6 +413,61 @@ function imageLabels(t: AssistantProps['t']): MessageImageLabels {
   }
 }
 
+/**
+ * Apply searchable hidden state without unmounting a stable subtree — the
+ * Host's completion fold hides the answer-inline reasoning this way, so the
+ * takeover renderer must reproduce it to stay inside the contract: the row
+ * disappears into the Host's process summary and comes back on find-in-page.
+ * (Mirrors the Harness chat kit's `useSearchableHidden`.)
+ */
+function useSearchableHidden(
+  hidden: boolean,
+  reveal: () => void,
+): RefObject<HTMLDivElement> {
+  const ref = useRef<HTMLDivElement>(null)
+  useLayoutEffect(() => {
+    const element = ref.current
+    if (element === null) return
+    if (hidden && element.contains(element.ownerDocument.activeElement)) {
+      reveal()
+      return
+    }
+    if (hidden) element.setAttribute('hidden', 'until-found')
+    else element.removeAttribute('hidden')
+  }, [hidden, reveal])
+  useEffect(() => {
+    const element = ref.current
+    if (element === null) return
+    element.addEventListener('beforematch', reveal)
+    return () => { element.removeEventListener('beforematch', reveal) }
+  }, [reveal])
+  return ref
+}
+
+/**
+ * One answer-inline reasoning block wrapped in the Host's fold contract. The
+ * Host computes the fold decision (turn closed, compact transcript, this node
+ * is the answer) and delivers it through the `turnProcess` owner prop; when
+ * folded the block hides into the Host's "thought" summary row instead of
+ * staying mounted above the answer.
+ */
+function FoldableReasoning({
+  hidden,
+  reveal,
+  children,
+}: {
+  hidden: boolean
+  reveal: () => void
+  children: ReactNode
+}) {
+  const ref = useSearchableHidden(hidden, reveal)
+  return (
+    <div ref={ref} data-turn-process-inline={hidden || undefined}>
+      {children}
+    </div>
+  )
+}
+
 function firstLine(text: string): string {
   const newline = text.indexOf('\n')
   return newline === -1 ? text : text.slice(0, newline)
@@ -409,6 +493,7 @@ function AnimatedReasoning({
   running,
   preset,
   thinkAutoExpand,
+  motionReduced,
   shouldHoldBack,
   followSpeedCpsRef,
   followRevealScaleRef,
@@ -418,12 +503,13 @@ function AnimatedReasoning({
   running: boolean
   preset: StreamSmoothingPreset
   thinkAutoExpand: boolean
+  motionReduced: boolean
   shouldHoldBack: () => boolean
   followSpeedCpsRef?: { current: number } | undefined
   followRevealScaleRef?: { current: number } | undefined
   t: AssistantProps['t']
 }) {
-  const reduced = usePrefersReducedMotion()
+  const reduced = motionReduced
   const [expanded, setExpanded] = useState(running && thinkAutoExpand)
   const [autoClosed, setAutoClosed] = useState(false)
   const summaryRef = useRef<HTMLSpanElement>(null)
@@ -514,11 +600,14 @@ 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,
+  motionPreference = DEFAULT_STREAM_SETTINGS.motionPreference,
   node,
   useTurnData,
   openFile,
   loadImage,
   fileMentions,
+  turnProcess,
   t,
 }: AssistantProps & {
   mode?: StreamMode
@@ -527,10 +616,22 @@ export const TypewriterAssistantNodeView = memo(function TypewriterAssistantNode
   scrollSpeedPxPerSec?: number
   maxScrollSpeedPxPerSec?: number
   thinkAutoExpand?: boolean
+  controlScroll?: boolean
+  motionPreference?: StreamMotionPreference
 }) {
   const data = node.data
   const streaming = data.status === 'running'
-  const reduced = usePrefersReducedMotion()
+  const reduced = useMotionReduced(motionPreference)
+  // The Host's completion-fold decision for THIS node's inline reasoning:
+  // only the answer step folds, only in compact-transcript mode, and only
+  // once the turn has closed (foldable implies it). Mirrors the built-in
+  // assistant renderer so the takeover keeps the official behavior.
+  const reasoningHidden = turnProcess !== undefined
+    && turnProcess.foldable
+    && turnProcess.spec.answerStep === data.step
+    && turnProcess.spec.inlineReasoning
+    && !turnProcess.open
+  const revealProcess = useCallback(() => { turnProcess?.setOpen(true) }, [turnProcess])
   const { ref: guardRef, shouldHoldBack } = useFpsGuard(streaming)
   const rootSpeedRef = useRef(35)
   const rootRevealedCharsRef = useRef(0)
@@ -568,7 +669,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,9 +701,10 @@ export const TypewriterAssistantNodeView = memo(function TypewriterAssistantNode
           <AnimatedMarkdownText
             key={index}
             text={block.text}
-            codeLabels={codeLabels}
+            labels={markdownLabels}
             fileMentions={mentions}
             streaming={streaming}
+            motionReduced={reduced}
             ownFollow={!streaming && index === lastFollow}
             followSpeedCpsRef={index === lastFollow ? rootSpeedRef : undefined}
             followRevealedCharsRef={index === lastFollow ? rootRevealedCharsRef : undefined}
@@ -607,22 +712,25 @@ export const TypewriterAssistantNodeView = memo(function TypewriterAssistantNode
             onPredictiveChange={index === lastFollow ? updateTextPrediction : undefined}
             preset={preset}
             shouldHoldBack={shouldHoldBack}
+            controlScroll={controlScroll}
           />,
         )
         break
       case 'reasoning':
         rendered.push(
-          <AnimatedReasoning
-            key={index}
-            text={block.text}
-            running={streaming && index === last}
-            preset={preset}
-            thinkAutoExpand={thinkAutoExpand}
-            shouldHoldBack={shouldHoldBack}
-            followSpeedCpsRef={reasoningOwnsSpeed && index === last ? rootSpeedRef : undefined}
-            followRevealScaleRef={reasoningOwnsSpeed && index === last ? rootRevealScaleRef : undefined}
-            t={t}
-          />,
+          <FoldableReasoning key={index} hidden={reasoningHidden} reveal={revealProcess}>
+            <AnimatedReasoning
+              text={block.text}
+              running={streaming && index === last}
+              preset={preset}
+              thinkAutoExpand={thinkAutoExpand}
+              motionReduced={reduced}
+              shouldHoldBack={shouldHoldBack}
+              followSpeedCpsRef={reasoningOwnsSpeed && index === last ? rootSpeedRef : undefined}
+              followRevealScaleRef={reasoningOwnsSpeed && index === last ? rootRevealScaleRef : undefined}
+              t={t}
+            />
+          </FoldableReasoning>,
         )
         break
       case 'image': {
@@ -663,6 +771,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>