@drscrewdriver/dsh-better-display 0.3.3-fork.1

package/src/client/Blocks.tsx

@@ -0,0 +1,213 @@
+import { Component, Fragment, memo, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import type { ReactNode } from 'react';
+import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
+import type { AssistantBlock, UserMessageNode } from '@deepseek-ai/dsh-client-ui-conversation/client';
+import { JsonBlock, MarkdownText, writeClipboard } from '@deepseek-ai/dsh-client-ui-primitives';
+import { ComposerFillContext, McpAppFrame } from './McpAppFrame.js';
+import { formatMessageClock } from './message-chrome.js';
+import { markdownLabels, truncatedJsonLabel } from './primitive-labels.js';
+import type { BlockRenderProps, ReaderBlockOwner } from './types.js';
+import { useStreamingText } from './streaming.js';
+import { MotionMarkdown, MotionPlainText } from './word-motion.js';
+import css from './Reader.module.css';
+
+const IMAGE_TYPES = new Set(['image/png', 'image/jpeg', 'image/webp', 'image/gif']);
+
+export class BlockBoundary extends Component<{ children: ReactNode }, { failed: boolean; detail: string }> {
+  state = { failed: false, detail: '' };
+  // Temporary diagnostic: surface the reason inline so a recurrence is reportable
+  // without a console. Remove once the reported block crash is identified.
+  static getDerivedStateFromError(error: unknown) {
+    const err = error as { message?: unknown } | undefined;
+    return { failed: true, detail: String(err?.message ?? error).slice(0, 160) };
+  }
+  render() {
+    return this.state.failed
+      ? <div className={css.notice}>此内容暂时无法在阅读页显示；原对话中的记录未受影响。<span data-reader-block-error style={{ opacity: .65 }}>（{this.state.detail}）</span></div>
+      : this.props.children;
+  }
+}
+
+export const ImageBlock = memo(function ImageBlock({ attachment, loadImage }: {
+  attachment: ImageAttachmentRef; loadImage: BlockRenderProps['loadImage'];
+}) {
+  const [attempt, setAttempt] = useState(0);
+  const [url, setUrl] = useState<string | null>(null);
+  const [error, setError] = useState(false);
+  const [decoded, setDecoded] = useState(false);
+  const dialog = useRef<HTMLDialogElement>(null);
+  const opener = useRef<HTMLButtonElement>(null);
+  useEffect(() => {
+    let active = true;
+    let owned: string | null = null;
+    const timeout = setTimeout(() => { if (active) { setError(true); active = false; } }, 20000);
+    setError(false); setDecoded(false); setUrl(null);
+    void loadImage(attachment).then(result => {
+      if (!active) return;
+      clearTimeout(timeout);
+      if (!IMAGE_TYPES.has(result.mediaType)) throw new Error('Unsupported image media type');
+      const bytes = Uint8Array.from(result.data);
+      owned = URL.createObjectURL(new Blob([bytes.buffer], { type: result.mediaType }));
+      setUrl(owned);
+    }).catch(() => { clearTimeout(timeout); if (active) setError(true); });
+    return () => { active = false; clearTimeout(timeout); if (owned) URL.revokeObjectURL(owned); };
+  }, [attachment.attachmentId, attempt, loadImage]);
+  const width = Number.isFinite(attachment.width) && attachment.width > 0 ? attachment.width : 4;
+  const height = Number.isFinite(attachment.height) && attachment.height > 0 ? attachment.height : 3;
+  return <figure className={css.imageFigure} data-reader-image data-image-state={error ? 'error' : decoded ? 'ready' : 'loading'}>
+    <div className={css.imageFrame} style={{ aspectRatio: `${width} / ${height}` }}>
+      {!error && url && <button ref={opener} type="button" className={css.imageOpen} aria-label={`放大图片${attachment.name ? `：${attachment.name}` : ''}`} onClick={() => dialog.current?.showModal()}>
+        <img src={url} alt={attachment.name ?? '会话图片'} width={width} height={height} onLoad={() => setDecoded(true)} onError={() => setError(true)} data-ready={decoded} />
+      </button>}
+      {(!decoded || error) && <div className={css.imagePlaceholder}>
+        <span>{error ? '图片未能加载' : '正在加载图片'}</span>
+        {error && <button type="button" className={css.textButton} onClick={() => setAttempt(value => value + 1)}>重试</button>}
+      </div>}
+    </div>
+    {attachment.name && <figcaption>{attachment.name}</figcaption>}
+    <dialog ref={dialog} className={css.imageDialog} aria-label="图片预览" onClose={() => opener.current?.focus()} onClick={event => { if (event.target === dialog.current) dialog.current?.close(); }}>
+      <button type="button" autoFocus className={css.dialogClose} aria-label="关闭图片预览" onClick={() => dialog.current?.close()}>×</button>
+      {url && <img src={url} alt={attachment.name ?? '会话图片'} />}
+    </dialog>
+  </figure>;
+});
+
+export function contentBlocks(content: UserMessageNode['content']): AssistantBlock[] {
+  return content.map(block => {
+    if (block.type === 'text') return { kind: 'text', text: block.text };
+    if (block.type === 'image') return { kind: 'image', attachment: block.attachment };
+    return { kind: 'other', block };
+  });
+}
+
+type TextPresentation = { startedAt?: number; interrupted?: boolean; liveText?: boolean };
+
+function ReadingMarkdown({ text, streaming, holdFormatting, startedAt, interrupted = false, liveText = false, kind = 'body', fileMentions }: { text: string; streaming: boolean; holdFormatting: boolean; kind?: 'body' | 'reasoning'; fileMentions?: BlockRenderProps['fileMentions'] } & TextPresentation) {
+  const root = useRef<HTMLDivElement>(null);
+  const presentation = useStreamingText(text, streaming, { startedAt, interrupted: interrupted || !liveText, selected: holdFormatting });
+  // Native Markdown changes block keys for its full final parse. Keep the last
+  // committed mode while this answer is selected, then finish formatting on
+  // deselection. Business status and the source text still update normally.
+  const committedMode = useRef(streaming);
+  const effectiveMode = holdFormatting ? committedMode.current : presentation.formatStreaming;
+  useLayoutEffect(() => { committedMode.current = effectiveMode; }, [effectiveMode]);
+  return <div ref={root} className={css.readingText} data-reader-text data-reader-text-kind={kind} data-received-length={text.length} data-shown-length={presentation.text.length}
+    data-presentation-pending={presentation.pending || undefined} data-motion-style="opacity-blur" data-ud-motion="reader-text-arrival" data-ud-motion-type="reveal" data-ud-motion-no-flash="true">
+    <MotionMarkdown text={presentation.text} streaming={effectiveMode} enabled={liveText && presentation.reveal && effectiveMode} revision={presentation.revision} fileMentions={fileMentions} />
+  </div>;
+}
+
+function ReadingReasoning({ text, streaming, holdFormatting, startedAt, interrupted = false, liveText = false }: { text: string; streaming: boolean; holdFormatting: boolean } & TextPresentation) {
+  const presentation = useStreamingText(text, streaming, { startedAt, interrupted: interrupted || !liveText, selected: holdFormatting });
+  return <div className={css.readingText} data-reader-text data-reader-text-kind="reasoning" data-received-length={text.length} data-shown-length={presentation.text.length}
+    data-presentation-pending={presentation.pending || undefined} data-motion-style="opacity-blur" data-ud-motion="reader-text-arrival" data-ud-motion-type="reveal" data-ud-motion-no-flash="true">
+    <MotionPlainText text={presentation.text} enabled={liveText && presentation.reveal} revision={presentation.revision} />
+  </div>;
+}
+
+function fallback(block: AssistantBlock, streaming: boolean, source: ReaderBlockOwner['source'], loadImage: BlockRenderProps['loadImage'], fillComposer: BlockRenderProps['fillComposer'], holdFormatting: boolean, presentation: TextPresentation, fileMentions?: BlockRenderProps['fileMentions']): ReactNode {
+  switch (block.kind) {
+    case 'text': return source === 'user' ? <MarkdownText text={block.text} labels={markdownLabels} /> : <ReadingMarkdown text={block.text} streaming={streaming} holdFormatting={holdFormatting} {...presentation} fileMentions={fileMentions} />;
+    case 'image': return <ImageBlock attachment={block.attachment} loadImage={loadImage} />;
+    case 'reasoning': return <ReadingReasoning text={block.text} streaming={streaming} holdFormatting={holdFormatting} {...presentation} />;
+    case 'tool-call': return <JsonBlock label={`工具参数 · ${block.name}`} payload={block.argsRaw} truncatedLabel={truncatedJsonLabel} />;
+    case 'other': {
+      const raw = block.block;
+      if (raw && typeof raw === 'object') {
+        const item = raw as Record<string, unknown>;
+        if ((item.type === 'mcp-app' || item.type === 'mcpapp' || item.type === 'ui') && typeof item.html === 'string') {
+          return <McpAppFrame html={item.html} title={typeof item.title === 'string' ? item.title : undefined} fillComposer={fillComposer} />;
+        }
+      }
+      return <div className={css.unknown}>
+        <p>此内容类型尚未接入阅读页，原始内容已保留。</p>
+        <JsonBlock label="查看原始内容" payload={block.block} truncatedLabel={truncatedJsonLabel} />
+      </div>;
+    }
+  }
+}
+
+export const Blocks = memo(function Blocks({ blocks, streaming = false, source = 'assistant', holdFormatting = false, startedAt, interrupted, liveText, renderSlotChain, loadImage, fillComposer, fileMentions }: BlockRenderProps & TextPresentation & {
+  blocks: readonly AssistantBlock[]; streaming?: boolean; source?: ReaderBlockOwner['source']; holdFormatting?: boolean;
+}) {
+  return <ComposerFillContext.Provider value={fillComposer}>
+    <div className={css.blocks} data-streaming={streaming || undefined}>
+      {blocks.map((block, index) => <BlockBoundary key={block.kind === 'image' ? `image:${block.attachment.attachmentId}:${index}` : `${index}:${block.kind}`}>
+        <Fragment>{renderSlotChain('dsh-better-display.block', { block, streaming, source }, { fallback: fallback(block, streaming, source, loadImage, fillComposer, holdFormatting, { startedAt, interrupted, liveText }, fileMentions) })}</Fragment>
+      </BlockBoundary>)}
+    </div>
+  </ComposerFillContext.Provider>;
+});
+
+import { TurnMetrics } from './TurnMetrics.js';
+
+function CopyGlyph() {
+  return <svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><rect x="5" y="5" width="8" height="8" rx="1.5" /><path d="M3 10H2.8A.8.8 0 0 1 2 9.2V2.8a.8.8 0 0 1 .8-.8h6.4a.8.8 0 0 1 .8.8V3" /></svg>;
+}
+
+function useCopyReceipt() {
+  const [receipt, setReceipt] = useState('');
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(() => () => { if (timer.current) clearTimeout(timer.current); }, []);
+  const copy = async (text: string) => {
+    const accepted = await writeClipboard(text);
+    setReceipt(accepted ? '已复制' : '未能复制，请手动选择文字');
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = setTimeout(() => setReceipt(''), 2000);
+  };
+  return { receipt, copy };
+}
+
+function MessageClock({ time }: { time: number }) {
+  return <time className={css.messageClock} dateTime={new Date(time).toISOString()}>{formatMessageClock(time)}</time>;
+}
+
+export function CopyAnswer({ blocks, onFork, metrics, extraActions }: { blocks: readonly AssistantBlock[]; onFork?: () => void; metrics?: BlockRenderProps['metrics']; extraActions?: ReactNode }) {
+  const { receipt, copy } = useCopyReceipt();
+  const text = blocks.filter((block): block is Extract<AssistantBlock, { kind: 'text' }> => block.kind === 'text').map(block => block.text).join('\n\n');
+  const endedAt = metrics?.endedAt;
+  const hasMetrics = metrics !== undefined && (metrics.usage !== undefined || metrics.runMs !== undefined || endedAt !== undefined);
+  if (!text.trim() && !onFork && !hasMetrics) return null;
+  return <div className={css.answerActions}>
+    {text.trim() !== '' && (
+      <button type="button" className={css.iconButton} aria-label="复制回答" title="复制回答" onClick={() => { void copy(text); }}>
+        <CopyGlyph />
+      </button>
+    )}
+    {extraActions}
+    {onFork && (
+      <button
+        type="button"
+        className={css.iconButton}
+        aria-label="以此处为基础创建分叉会话"
+        title="以此处为基础创建分叉会话 (Fork)"
+        onClick={onFork}
+      >
+        <svg viewBox="0 0 16 16" width="14" height="14" fill="none" stroke="currentColor" strokeWidth="1.2">
+          <circle cx="4.5" cy="3.5" r="1.8" />
+          <circle cx="4.5" cy="12.5" r="1.8" />
+          <circle cx="11.5" cy="5.5" r="1.8" />
+          <path d="M4.5 5.5v5M4.5 8c2.5 0 4.5-1 7-2.5" strokeLinecap="round" />
+        </svg>
+      </button>
+    )}
+    {metrics && <TurnMetrics usage={metrics.usage} runMs={metrics.runMs} tokensPerSecond={metrics.tokensPerSecond} ttftMs={metrics.ttftMs} />}
+    {endedAt !== undefined && <MessageClock time={endedAt} />}
+    <span role="status" className={css.meta}>{receipt}</span>
+  </div>;
+}
+
+export function UserMessageActions({ text, time }: { text: string; time?: number }) {
+  const { receipt, copy } = useCopyReceipt();
+  const hasText = text.trim() !== '';
+  if (!hasText && time === undefined) return null;
+  return <div className={css.userActions}>
+    {time !== undefined && <MessageClock time={time} />}
+    {hasText && (
+      <button type="button" className={css.iconButton} aria-label="复制消息" title="复制消息" onClick={() => { void copy(text); }}>
+        <CopyGlyph />
+      </button>
+    )}
+    <span role="status" className={css.meta}>{receipt}</span>
+  </div>;
+}

package/src/client/ChoreographedFlow.tsx

@@ -0,0 +1,232 @@
+import { createContext, useContext, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import type { ReactNode, RefObject } from 'react';
+import type { ChatSnapshot } from '@deepseek-ai/dsh-client-ui-chat/client';
+import type { ReaderProps } from './types.js';
+import type { LiveStep, LiveTurnItem } from './live-turn.js';
+import { collapseRows, containsNewUser, flowRows, FOLD_TIMING, retiringKeys } from './fold-choreography.js';
+import type { FoldPhase } from './fold-choreography.js';
+import { Disclosure } from './motion.js';
+import { FoldSummaryText } from './LiveFold.js';
+import { DiffStat } from './DiffPanel.js';
+import { StreamMotionContext } from './streaming.js';
+import css from './Reader.module.css';
+
+const FlowSnapshot = createContext<ChatSnapshot | null>(null);
+/** Public projection only. Descendants cannot leak live data through a frozen frame. */
+export const useFlowChat: ReaderProps['useChat'] = selector => {
+  const snapshot = useContext(FlowSnapshot);
+  if (!snapshot) throw new Error('Flow snapshot provider missing');
+  return selector(snapshot);
+};
+
+export type PresentationFrame = { items: readonly LiveTurnItem[]; snapshot: ChatSnapshot };
+type Transaction = {
+  phase: FoldPhase; shown: PresentationFrame; target: PresentationFrame;
+  retiring: readonly string[]; beforeKeys: ReadonlySet<string>;
+};
+const idle = (frame: PresentationFrame): Transaction => ({ phase: 'idle', shown: frame, target: frame, retiring: [], beforeKeys: new Set() });
+
+function Summary({ item, open, onChange, motion }: {
+  item: Extract<LiveTurnItem, { kind: 'fold' }>; open: boolean; onChange: (open: boolean) => void; motion: boolean;
+}) {
+  const button = useRef<HTMLButtonElement>(null);
+  return <div data-reader-live-fold data-expanded={open} data-reader-live-fold-summary={item.summary}>
+    <div className={css.summaryRow}>
+      <Disclosure open={open} onChange={onChange} buttonRef={button} ariaLabel="此前步骤"
+        label={<FoldSummaryText summary={item.summary} motion={motion} />} />
+      <DiffStat steps={item.steps} label={item.summary} />
+    </div>
+  </div>;
+}
+
+/** Manual disclosure shares the measured-size path; children survive until finish. */
+function FlowCell({ hidden, instant, motion, rowKey, children, summary = false }: {
+  hidden: boolean; instant: boolean; motion: boolean; rowKey: string; children: ReactNode; summary?: boolean;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  const [present, setPresent] = useState(!hidden);
+  const previous = useRef(hidden);
+  if (!hidden && !present) setPresent(true);
+  useLayoutEffect(() => {
+    const el = ref.current;
+    const changed = previous.current !== hidden;
+    previous.current = hidden;
+    if (!el) return;
+    if (!changed || instant || !motion) { setPresent(!hidden); return; }
+    const height = el.scrollHeight;
+    const animation = el.animate([
+      { height: `${hidden ? height : 0}px`, opacity: hidden ? 1 : 0 },
+      { height: `${hidden ? 0 : height}px`, opacity: hidden ? 0 : 1 },
+    ], { duration: 220, easing: 'cubic-bezier(.4,0,.2,1)', fill: 'both' });
+    el.dispatchEvent(new CustomEvent('reader-layout-start', { bubbles: true }));
+    let released = false;
+    const release = () => { if (!released) { released = true; el.dispatchEvent(new CustomEvent('reader-layout-end', { bubbles: true })); } };
+    // Do NOT cancel here. `fill: 'both'` is what currently holds the cell at its
+    // collapsed size; cancelling on finish drops that fill before React has
+    // committed the removal, so the cell snaps back to full height for one frame
+    // — the flash before it disappears. The state change alone retires it; the
+    // cleanup below cancels the animation once that has actually rendered.
+    let settled = false;
+    const settle = () => {
+      if (settled) return;
+      settled = true;
+      setPresent(!hidden);
+      release();
+    };
+    animation.onfinish = settle;
+    // \`fill: 'both'\` pins the opening keyframe for the whole run, so if this
+    // animation never advances the cell stays at height 0 and opacity 0: the row is
+    // in the DOM but reads as "clicked it and nothing happened". A cancelled
+    // animation, or one inside a subtree the compositor skips, never fires
+    // onfinish. Fall back to the state change on a deadline; the cleanup then
+    // cancels the animation and drops the fill.
+    const deadline = window.setTimeout(settle, 220 + 240);
+    return () => { window.clearTimeout(deadline); animation.cancel(); release(); };
+    // `present` is a dependency so that committing it re-runs this effect: the
+    // cleanup then cancels the finished animation *after* the removal has been
+    // applied, which is the only moment the fill can be dropped safely. Without
+    // it the animation was never cancelled at all and every folded cell kept one.
+  }, [hidden, instant, motion, present]);
+  return <div ref={ref} className={css.flowCell} data-flow-key={rowKey} data-flow-summary={summary || undefined}
+    hidden={hidden && !present} aria-hidden={hidden || undefined} {...(hidden ? { inert: '' } : {})}>
+    {present && <div className={css.flowCellInner}>{children}</div>}
+  </div>;
+}
+
+export function ChoreographedFlow({ frame, motion, enabled, urgent, open, onOpenChange, processOpen, renderStep, id }: {
+  frame: PresentationFrame; motion: boolean; enabled: boolean; urgent: boolean;
+  open: Readonly<Record<string, boolean>>; onOpenChange: (key: string, value: boolean) => void;
+  processOpen: boolean; renderStep: (step: LiveStep, folded: boolean) => ReactNode; id: string;
+}) {
+  const root = useRef<HTMLDivElement>(null);
+  const stream = useContext(StreamMotionContext);
+  const latest = useRef(frame); latest.current = frame;
+  const [visible, setVisible] = useState(() => !document.hidden);
+  const [state, setState] = useState<Transaction>(() => idle(frame));
+  const bypass = !motion || !enabled || urgent || !visible || !processOpen || (state.phase !== 'idle' && Object.values(open).some(Boolean));
+  // Render-time adjustment prevents even one paint of the new authoritative layout.
+  if ((bypass || containsNewUser(state.shown.items, frame.items)) && (state.phase !== 'idle' || state.shown !== frame)) {
+    setState(idle(frame));
+  } else if (state.phase === 'idle' && state.shown !== frame) {
+    const retiring = retiringKeys(state.shown.items, frame.items, open);
+    setState(retiring.length ? { ...state, phase: 'collapse', target: frame, retiring,
+      beforeKeys: new Set(flowRows(state.shown.items).map(row => row.key)) } : idle(frame));
+  }
+  useEffect(() => {
+    const update = () => setVisible(!document.hidden);
+    document.addEventListener('visibilitychange', update);
+    return () => document.removeEventListener('visibilitychange', update);
+  }, []);
+  useLayoutEffect(() => {
+    if (state.phase !== 'collapse') return;
+    const el = root.current;
+    if (!el) return;
+    const retiring = new Set(state.retiring);
+    const animations: Animation[] = [];
+    el.dispatchEvent(new CustomEvent('reader-layout-start', { bubbles: true }));
+    for (const cell of el.querySelectorAll<HTMLElement>(':scope > [data-flow-key]')) {
+      const key = cell.dataset.flowKey!;
+      const isHeader = cell.dataset.flowSummary && !state.beforeKeys.has(key);
+      if (!retiring.has(key) && !isHeader) continue;
+      const height = cell.getBoundingClientRect().height;
+      animations.push(cell.animate(isHeader ? [
+        { height: '0px', opacity: 0 }, { height: `${height}px`, opacity: 1 },
+      ] : [
+        { height: `${height}px`, opacity: 1 },
+        { height: `${height * .5}px`, opacity: .85, offset: .5 },
+        { height: '0px', opacity: 0 },
+      ], { duration: FOLD_TIMING.collapse, easing: 'cubic-bezier(.4,0,.2,1)', fill: 'both' }));
+    }
+    let cancelled = false;
+    // Coalesce everything received during shrink, once. No animation restarts.
+    // Idempotent and phase-checked: the promise and the deadline race, and
+    // whichever arrives first wins while the other becomes a no-op.
+    let advanced = false;
+    const advance = () => {
+      if (cancelled || advanced) return;
+      advanced = true;
+      setState(current => current.phase === 'collapse' ? { ...current, phase: 'count', target: latest.current } : current);
+    };
+    // `finished` rejects when an animation is cancelled and can stay pending when a
+    // compositor never runs it to completion, so the promise alone cannot be the only
+    // way out of this phase. Without a deadline a stalled phase would hold the frame
+    // source at `shown` and keep the reveal paused, which reads as a frozen turn
+    // until the view remounts.
+    const deadline = window.setTimeout(advance, FOLD_TIMING.collapse + FOLD_TIMING.watchdogSlack);
+    Promise.all(animations.map(animation => animation.finished)).then(advance, advance);
+    return () => {
+      cancelled = true;
+      window.clearTimeout(deadline);
+      animations.forEach(animation => animation.cancel());
+      el.dispatchEvent(new CustomEvent('reader-layout-end', { bubbles: true }));
+    };
+  }, [state.phase]);
+  useEffect(() => {
+    if (state.phase !== 'count' && state.phase !== 'settle' && state.phase !== 'reveal') return;
+    const phase = state.phase;
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      setState(current => {
+        if (current.phase !== phase) return current;
+        if (phase === 'count') return { ...current, phase: 'settle' };
+        if (phase === 'settle') return { ...current, phase: 'reveal' };
+        return idle(current.target);
+      });
+    };
+    // Count visible presentation time, not a timer that can expire before a
+    // busy browser paints. Each attention phase must get actual rendered frames.
+    let elapsed = 0;
+    let previous: number | undefined;
+    let raf = 0;
+    const tick = (now: number) => {
+      if (previous !== undefined) elapsed += Math.min(40, now - previous);
+      previous = now;
+      if (elapsed < FOLD_TIMING[phase]) { raf = requestAnimationFrame(tick); return; }
+      finish();
+    };
+    raf = requestAnimationFrame(tick);
+    // A hidden tab gets no frames at all, so the frame counter above would never
+    // reach its budget and the phase would hold forever. The wall-clock deadline
+    // advances it anyway; a non-idle phase is what freezes the turn.
+    const deadline = window.setTimeout(finish, FOLD_TIMING[phase] + FOLD_TIMING.watchdogSlack);
+    return () => { window.clearTimeout(deadline); cancelAnimationFrame(raf); };
+  }, [state.phase]);
+  useLayoutEffect(() => {
+    if (state.phase !== 'reveal' || !root.current) return;
+    const el = root.current;
+    el.dispatchEvent(new CustomEvent('reader-layout-start', { bubbles: true }));
+    // Opacity alone still inserts the new layout in one frame. Open real space
+    // first; text stays paused until this entry finishes, then catches up.
+    const animations = Array.from(el.children).filter(child => !(child as HTMLElement).hidden && !state.beforeKeys.has((child as HTMLElement).dataset.flowKey!))
+      .map(child => child.animate([
+        { height: '0px', opacity: 0 },
+        { height: `${child.getBoundingClientRect().height}px`, opacity: 1 },
+      ], { duration: FOLD_TIMING.reveal, easing: 'cubic-bezier(.4,0,.2,1)', fill: 'both' }));
+    return () => {
+      animations.forEach(animation => animation.cancel());
+      el.dispatchEvent(new CustomEvent('reader-layout-end', { bubbles: true }));
+    };
+  }, [state.phase]);
+
+  const blocked = state.phase === 'collapse' || state.phase === 'count' || state.phase === 'settle';
+  const source = state.phase === 'idle' || state.phase === 'collapse' ? state.shown : state.target;
+  const rows = state.phase === 'collapse' ? collapseRows(state.shown.items, state.target.items) : flowRows(source.items);
+  return <FlowSnapshot.Provider value={source.snapshot}>
+    <StreamMotionContext.Provider value={{ ...stream, paused: state.phase !== 'idle', resumed: state.phase === 'reveal' }}>
+      <div id={id} ref={root} className={css.choreographedFlow} data-reader-flow data-reader-transition={state.phase} data-ud-motion="fold-choreography">
+        {rows.map(row => {
+          if (row.kind === 'summary') return <FlowCell key={row.key} rowKey={row.key} hidden={false} instant motion={motion} summary>
+            <Summary item={row.item} open={processOpen && !!open[row.key]} onChange={value => onOpenChange(row.key, value)} motion={motion && state.phase !== 'collapse'} />
+          </FlowCell>;
+          const hidden = !!row.foldKey && (!processOpen || !open[row.foldKey]) || (blocked && state.phase !== 'collapse' && !state.beforeKeys.has(row.key));
+          // Keep retiring child props unchanged until it has actually shrunk.
+          return <FlowCell key={row.key} rowKey={row.key} hidden={hidden} instant={state.phase !== 'idle'} motion={motion}>
+            {renderStep(row.step, !!row.foldKey)}
+          </FlowCell>;
+        })}
+      </div>
+    </StreamMotionContext.Provider>
+  </FlowSnapshot.Provider>;
+}

package/src/client/ClosedProcessSummary.tsx

@@ -0,0 +1,23 @@
+import { useRef } from 'react';
+import css from './Reader.module.css';
+import { Disclosure } from './motion.js';
+import { FoldSummaryText } from './LiveFold.js';
+import { foldSummary } from './live-turn.js';
+import { DiffStat } from './DiffPanel.js';
+import type { LiveStep } from './live-turn.js';
+
+/** Keep process counts discoverable after the live-fold presentation retires. */
+export function ClosedProcessSummary({ steps, open, onChange, controls }: {
+  steps: readonly LiveStep[]; open: boolean; onChange: (value: boolean) => void; controls: string;
+}) {
+  const button = useRef<HTMLButtonElement>(null);
+  if (!steps.length) return null;
+  const summary = foldSummary(steps);
+  return <div className={css.closedProcessSummary} data-reader-closed-summary={summary}>
+    <div className={css.summaryRow}>
+      <Disclosure open={open} onChange={onChange} controls={controls} buttonRef={button} ariaLabel="本轮过程详情"
+        label={<FoldSummaryText summary={summary} motion={false} />} />
+      <DiffStat steps={steps} label={summary} />
+    </div>
+  </div>;
+}

package/src/client/DiffPanel.tsx

@@ -0,0 +1,124 @@
+import { useLayoutEffect, useMemo, useRef, useState } from 'react';
+import type { ReactNode } from 'react';
+import { DiffBlock, diffTotals } from '@deepseek-ai/dsh-client-ui-primitives';
+import css from './Reader.module.css';
+import { diffBlockLabels } from './primitive-labels.js';
+import { FOLD_TIMING } from './fold-choreography.js';
+import { foldDiffHunks } from './tool-activity.js';
+import type { LiveStep } from './live-turn.js';
+
+/**
+ * Reveals and withdraws its child by animating real height, in the plugin's own
+ * motion language. Height is the animated property rather than transform because
+ * the panel pushes the transcript down and the reading scroll measures that
+ * growth; the curve and duration are the fold choreography's, so this reads as
+ * the same gesture as opening a digest.
+ *
+ * Closing animates too: the child stays mounted until the shrink finishes, which
+ * is why the owner keeps it alive on an `open` flag instead of unmounting it.
+ */
+function MorphPanel({ open, children, onSettled, onClosed }: {
+  open: boolean; children: ReactNode; onSettled?: (element: HTMLElement) => void; onClosed: () => void;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  useLayoutEffect(() => {
+    const element = ref.current;
+    if (!element) return;
+    element.dispatchEvent(new CustomEvent('reader-layout-start', { bubbles: true }));
+    let released = false;
+    const release = () => { if (!released) { released = true; element.dispatchEvent(new CustomEvent('reader-layout-end', { bubbles: true })); } };
+    if (typeof element.animate !== 'function') { release(); if (!open) onClosed(); return; }
+    const height = element.scrollHeight;
+    const frames = open
+      ? [{ height: '0px', opacity: 0, transform: 'translateY(-6px)' },
+         { height: `${height}px`, opacity: 1, transform: 'translateY(0)' }]
+      : [{ height: `${height}px`, opacity: 1 },
+         { height: '0px', opacity: 0 }];
+    const animation = element.animate(frames, {
+      duration: FOLD_TIMING.reveal + FOLD_TIMING.settle,
+      easing: 'cubic-bezier(.4,0,.2,1)',
+    });
+    let settled = false;
+    const settle = () => {
+      if (settled) return;
+      settled = true;
+      release();
+      if (open) {
+        element.style.height = 'auto';
+        element.style.overflow = 'visible';
+        onSettled?.(element);
+      } else {
+        onClosed();
+      }
+    };
+    animation.onfinish = settle;
+    const deadline = window.setTimeout(settle, FOLD_TIMING.reveal + FOLD_TIMING.settle + 240);
+    return () => { window.clearTimeout(deadline); animation.cancel(); release(); };
+  }, [open]);
+  return <div ref={ref} className={css.diffOverlay}>{children}</div>;
+}
+
+/**
+ * Keeps a newly opened panel on screen.
+ *
+ * Opening grows the row downward, so a badge near the fold reveals its card below
+ * the viewport and the reader has to chase it. The scroll container is not known
+ * here, so the nearest scrollable ancestor is found and the card's head is brought
+ * to the top of it — the same thing a jump-to-anchor does.
+ */
+function revealPanel(element: HTMLElement): void {
+  let port: HTMLElement | null = element.parentElement;
+  while (port && port.scrollHeight <= port.clientHeight + 1) port = port.parentElement;
+  if (!port) { element.scrollIntoView({ block: 'nearest' }); return; }
+  const gap = element.getBoundingClientRect().top - port.getBoundingClientRect().top;
+  // Already fully visible: leave the scroll alone rather than jumping on every open.
+  if (gap >= 0 && element.getBoundingClientRect().bottom <= port.getBoundingClientRect().bottom) return;
+  port.scrollTop += gap - 8;
+}
+
+/**
+ * Line counts for everything a folded run of steps changed.
+ *
+ * A run that touched no files renders nothing, so an ordinary process digest is
+ * unchanged. Clicking the counts opens the same diff surface the official tool
+ * row uses — one file at a time, red removed / green added, expandable.
+ */
+export function DiffStat({ steps, label }: { steps: readonly LiveStep[]; label: string }) {
+  const hunks = useMemo(() => foldDiffHunks(steps), [steps]);
+  const [open, setOpen] = useState(false);
+  const [visible, setVisible] = useState(false);
+  const totals = useMemo(() => diffTotals(hunks), [hunks]);
+  const [active, setActive] = useState(0);
+  if (!hunks.length) return null;
+  const current = hunks[Math.min(active, hunks.length - 1)]!;
+  return <>
+    <span className={css.diffStatRoot}>
+      <button type="button" className={css.diffStatButton} aria-expanded={open}
+        aria-label={`${label} · 改动 ${totals.added} 行，删除 ${totals.removed} 行`}
+        onClick={event => {
+          event.stopPropagation();
+          if (open) { setOpen(false); return; }
+          setVisible(true);
+          setOpen(true);
+        }}>
+        <span className={css.diffCaret} aria-hidden>{open ? '\u25be' : '\u25b8'}</span>
+        {totals.added > 0 && <span className={css.diffAdded}>+{totals.added}</span>}
+        {totals.removed > 0 && <span className={css.diffRemoved}>-{totals.removed}</span>}
+      </button>
+    </span>
+    {visible && <div className={css.diffOverlayRow}>
+      <MorphPanel open={open} onSettled={revealPanel} onClosed={() => setVisible(false)}>
+        {hunks.length > 1 && <div className={css.diffTabs}>
+          {hunks.map((hunk, index) => <button key={`${hunk.path}:${index}`} type="button"
+            className={css.diffTab} data-active={index === active || undefined}
+            onClick={() => setActive(index)} title={hunk.path}>
+            {hunk.path.split(/[/\\]+/).filter(Boolean).slice(-1)[0] ?? hunk.path}
+          </button>)}
+        </div>}
+        <div className={css.diffScrollArea}>
+          <DiffBlock diffs={[current]} maxLines={36} labels={diffBlockLabels} />
+        </div>
+      </MorphPanel>
+    </div>}
+  </>;
+}

package/src/client/LiveFold.tsx

@@ -0,0 +1,43 @@
+import { useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { FOLD_TIMING } from './fold-choreography.js';
+import css from './Reader.module.css';
+
+/** Values are presentation commits, never live network counters. */
+export function SubtleNumberRoll({ value, motion }: { value: number; motion: boolean }) {
+  const [outgoing, setOutgoing] = useState<number | null>(null);
+  const previous = useRef(value);
+  useLayoutEffect(() => {
+    if (value === previous.current) return;
+    const old = previous.current;
+    previous.current = value;
+    if (!motion) { setOutgoing(null); return; }
+    setOutgoing(old);
+    const timer = window.setTimeout(() => setOutgoing(null), FOLD_TIMING.count);
+    return () => window.clearTimeout(timer);
+  }, [value, motion]);
+  return <span className={css.numberRollRoot} aria-hidden="true">
+    <span className={css.numberRollSizer}>{value}</span>
+    {outgoing !== null && <span key={`out-${outgoing}`} className={`${css.numberRollDigit} ${css.numberRollExit}`}>{outgoing}</span>}
+    <span key={`cur-${value}`} className={`${css.numberRollDigit} ${outgoing !== null ? css.numberRollEnter : ''}`}>{value}</span>
+  </span>;
+}
+
+export function FoldSummaryText({ summary, motion }: { summary: string; motion: boolean }) {
+  const parts = useMemo(() => {
+    const regex = /([^\d]+)(\d+)/g;
+    const result: { text: string; number?: number }[] = [];
+    let end = 0;
+    for (const match of summary.matchAll(regex)) {
+      result.push({ text: match[1]!, number: Number(match[2]) });
+      end = match.index! + match[0].length;
+    }
+    if (end < summary.length) result.push({ text: summary.slice(end) });
+    return result;
+  }, [summary]);
+  return <span className={css.foldSummary} data-reader-fold-summary={summary} aria-label={summary}>
+    {parts.map(part => <span key={part.text} className={css.foldSummaryPart}>
+      <span>{part.text}</span>
+      {part.number !== undefined && <SubtleNumberRoll value={part.number} motion={motion} />}
+    </span>)}
+  </span>;
+}