dsh-better-display 0.1.1

package/src/client/projection.ts

@@ -0,0 +1,118 @@
+import type { AssistantBlock, ToolCallBlock, TurnLocation } from '@deepseek-ai/dsh-client-ui-conversation/client';
+import type { AssistantChatData, ChatConversationViewNode } from '@deepseek-ai/dsh-client-ui-chat/client';
+import { activityPhase } from './tool-activity.js';
+
+export interface ReaderGroup { key: string; turn: number | null; keys: readonly string[] }
+export interface TurnBoundary { status: 'open' | 'closed' | 'unknown'; reason: string | null; latestStep: number; closingStep: number | null }
+
+// Run on structural publication, not on each text delta. Node seats subscribe by key.
+export function groupNodes(order: readonly string[], get: (key: string) => ChatConversationViewNode | undefined): ReaderGroup[] {
+  const groups: ReaderGroup[] = [];
+  const seenTurns = new Set<number>();
+  for (const key of order) {
+    const node = get(key);
+    if (!node || node.visibility === 'hidden') continue;
+    const turn = node.location.kind === 'step' || node.location.kind === 'turn' ? node.location.turn.turn : null;
+    const previous = groups.at(-1);
+    if (turn !== null && previous?.turn === turn) {
+      (previous.keys as string[]).push(key);
+    } else {
+      groups.push({ key: turn === null ? `node:${key}` : seenTurns.has(turn) ? `turn:${turn}:${key}` : `turn:${turn}`, turn, keys: [key] });
+      if (turn !== null) seenTurns.add(turn);
+    }
+  }
+  return groups;
+}
+
+export function boundaryOf(turn: TurnLocation | undefined): TurnBoundary {
+  return {
+    status: turn?.status ?? 'unknown',
+    reason: turn?.end?.data.reason.kind ?? null,
+    latestStep: turn?.steps.at(-1)?.step ?? -1,
+    closingStep: turn?.data.get('turn-tail')?.closing?.step ?? null,
+  };
+}
+
+export function isEarlierNarration(data: AssistantChatData, boundary: TurnBoundary): boolean {
+  // New body text, a tool call, or a settled step is not a completed turn.
+  if (data.status !== 'settled' || boundary.status !== 'closed' || boundary.reason !== 'completed') return false;
+  if (data.blocks.some(block => block.kind === 'image' || block.kind === 'other')) return false;
+  return boundary.closingStep !== null && data.step < boundary.closingStep;
+}
+
+export function processExpanded(choice: boolean | undefined, boundary: TurnBoundary): boolean {
+  return choice ?? !(boundary.status === 'closed' && boundary.reason === 'completed');
+}
+
+/** Reading while running must not pin the process open after completion. */
+export function processChoiceKey(groupKey: string, boundary: TurnBoundary): string {
+  return `${groupKey}:${boundary.status}:${boundary.reason ?? 'pending'}`;
+}
+
+/** A body-only assistant step is not a thinking/process disclosure. */
+export function hasProcessContent(node: ChatConversationViewNode | undefined, boundary: TurnBoundary): boolean {
+  if (!node || node.visibility === 'hidden') return false;
+  if (node.kind === 'assistant-step') {
+    const data = node.data as AssistantChatData;
+    return data.blocks.some(block => block.kind === 'reasoning' && block.text.trim() !== '')
+      || (isEarlierNarration(data, boundary) && hasVisibleBody(data.blocks));
+  }
+  return node.kind === 'context' || node.kind === 'model-retry' || node.kind === 'system-prompt' || node.kind === 'turn-process'
+    || node.kind === 'command' || node.kind === 'manual-compaction' || node.kind === 'compaction';
+}
+
+export function hasVisibleBody(blocks: readonly AssistantBlock[]): boolean {
+  return blocks.some(block => block.kind === 'image' || block.kind === 'other' || (block.kind === 'text' && block.text.trim() !== ''));
+}
+
+/** Keep native block order. In particular, never lift a later Think above text. */
+export function assistantSegments(blocks: readonly AssistantBlock[]): { kind: 'reasoning' | 'body'; start: number; blocks: AssistantBlock[] }[] {
+  const segments: ReturnType<typeof assistantSegments> = [];
+  let previous: ReturnType<typeof assistantSegments>[number] | undefined;
+  blocks.forEach((block, index) => {
+    if (block.kind === 'tool-call') { previous = undefined; return; }
+    const kind = block.kind === 'reasoning' ? 'reasoning' : 'body';
+    if (previous?.kind === kind) previous.blocks.push(block);
+    else {
+      previous = { kind, start: index, blocks: [block] };
+      segments.push(previous);
+    }
+  });
+  return segments;
+}
+
+export function toolFailed(block: ToolCallBlock): boolean {
+  return activityPhase({ block }) === 'failed';
+}
+
+export function toolName(block: ToolCallBlock): string {
+  return 'kind' in block ? block.call?.name ?? '工具调用' : block.name;
+}
+
+export function terminalLabel(reason: string | null): string | null {
+  switch (reason) {
+    case 'completed': return null;
+    case 'aborted': case 'interrupted': return '本轮已停止，已生成的内容仍保留。';
+    case 'blocked': return '本轮需要处理阻塞事项；请查看原对话与下方操作区。';
+    case 'max-tokens': return '输出达到本轮长度限制，内容可能尚未完整。';
+    case 'error': return '本轮未完成；错误信息保留在下方。';
+    case null: return null;
+    default: return `本轮结束状态：${reason}。请在原对话中核对完整记录。`;
+  }
+}
+
+/**
+ * Extract the first usable fork anchor seq from candidate message nodes.
+ * Only the durable closing message seq cuts the intended turn prefix: an
+ * absent anchor must surface as undefined (never as 0 or NaN), because the
+ * host treats a missing atSeq as a whole-session fork.
+ */
+export function forkAnchorSeq(
+  candidates: ReadonlyArray<{ seq?: unknown } | null | undefined>,
+): number | undefined {
+  for (const candidate of candidates) {
+    const seq = candidate?.seq;
+    if (typeof seq === 'number' && Number.isFinite(seq)) return seq;
+  }
+  return undefined;
+}

package/src/client/reasoning-follow.ts

@@ -0,0 +1,12 @@
+/** Transitions.dev Reasoning stream, adapted to appended content, never a loop. */
+export const REASON_HOLD = 840;
+export const REASON_STEP = 500;
+export const REASON_LINES = 2;
+
+export function reasoningTarget(top: number, contentHeight: number, viewportHeight: number, lineHeight: number): number {
+  const end = Math.max(0, contentHeight - viewportHeight);
+  const current = Math.min(end, Math.max(0, top));
+  // Receiving a burst changes the available transcript, never the step size.
+  // Only the final, partial step may be shorter than the reference's two lines.
+  return Math.min(end, current + Math.max(1, lineHeight) * REASON_LINES);
+}

package/src/client/settings-copy.ts

@@ -0,0 +1,53 @@
+export type SettingsCopyKey =
+  | 'nav'
+  | 'openTitle'
+  | 'openDescription'
+  | 'skillTitle'
+  | 'skillInstalled'
+  | 'skillMissing'
+  | 'skillPurpose'
+  | 'skillPluginNote'
+  | 'skillInstall'
+  | 'skillRecheck'
+  | 'skillChecking'
+  | 'skillUnavailable';
+
+export type SettingsCopy = Record<SettingsCopyKey, string>;
+
+export const en: SettingsCopy = {
+  nav: 'Better Display',
+  openTitle: 'Open deliverables in built-in panel',
+  openDescription: 'Off by default: chips and inline file mentions open in the system app. Turn this on to preview them in the right Sidebar, matching official chat. Reveal and folder actions still use the system file manager.',
+  skillTitle: 'generative-mcpapps skill',
+  skillInstalled: 'Installed',
+  skillMissing: 'Not detected',
+  skillPurpose: 'This install is for model auto-selection of MCP Apps. Reader already renders mcp-app fences when the model emits them.',
+  skillPluginNote: 'Shipping the pack inside this plugin repository does not install it into the harness skill catalog.',
+  skillInstall: 'Copy the whole generative-mcpapps folder (including references and examples) into .dsh/skills or .agents/skills — in your home or the project, you choose — then Re-check. There is no one-click install that works on every host.',
+  skillRecheck: 'Re-check',
+  skillChecking: 'Checking…',
+  skillUnavailable: 'Could not query the host skill catalog. Copy into .dsh/skills or .agents/skills (home or project), then Re-check.',
+};
+
+export const zh: SettingsCopy = {
+  nav: 'Better Display',
+  openTitle: '在内置面板中打开产物',
+  openDescription: '默认关闭：产物芯片和正文中的文件提及会用系统应用打开。打开后与官方对话一致，在右侧栏预览。访达 / 资源管理器中的显示与打开所在文件夹不受此开关控制。',
+  skillTitle: 'generative-mcpapps 技能',
+  skillInstalled: '已安装',
+  skillMissing: '未检测到',
+  skillPurpose: '这项安装是为了让模型自动选用 MCP Apps。阅读页在模型写出 mcp-app 代码块时已经会渲染，不依赖该技能是否装进宿主。',
+  skillPluginNote: '技能包只出现在本插件仓库里，并不等于当前 Agent 已经加载它。',
+  skillInstall: '把完整的 generative-mcpapps 文件夹（含 references 与 examples）复制到 .dsh/skills 或 .agents/skills（家目录或项目目录，由你选），然后重新检测。没有在所有宿主上都可用的一键安装。',
+  skillRecheck: '重新检测',
+  skillChecking: '正在检测…',
+  skillUnavailable: '无法查询宿主技能目录。请复制到 .dsh/skills 或 .agents/skills（家目录或项目），再重新检测。',
+};
+
+export function settingsLanguage(tag: string | undefined): 'zh' | 'en' {
+  return (tag ?? '').toLowerCase().startsWith('zh') ? 'zh' : 'en';
+}
+
+export function settingsCopyFor(tag: string | undefined): SettingsCopy {
+  return settingsLanguage(tag) === 'zh' ? zh : en;
+}

package/src/client/settings-slots.ts

@@ -0,0 +1,20 @@
+/**
+ * Community-plugin SlotMap merge for Settings pages.
+ * Official plugins import `@deepseek-ai/dsh-client-ui-settings/client` instead.
+ * Shape matches that package's `settings.section` (list / root / close).
+ */
+import type { SettingsCopyKey } from './settings-copy.js';
+
+export interface SettingsSectionOwnerProps {
+  /** Close the settings panel (the shell owns the open state). */
+  close: () => void;
+}
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    'settings.section': { kind: 'list'; scope: 'root'; owner: SettingsSectionOwnerProps };
+  }
+  interface LocaleNamespaceMap {
+    'better-display': SettingsCopyKey;
+  }
+}

package/src/client/settings.tsx

@@ -0,0 +1,73 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type {} from './settings-slots.js';
+import { settingsCopyFor, zh, en } from './settings-copy.js';
+import { SettingsSection, type BetterDisplaySettingsInjected, type OpenPrefs } from './SettingsSection.js';
+import { firstSessionId, skillsFromListResult, type SkillStatusProbe } from './skill-status.js';
+import type { HostSkillStatus } from '../skill-status.js';
+
+interface LocaleFace {
+  register?: (ns: string, dicts: { zh: unknown; en: unknown }) => () => void;
+  bind?: (ns: string) => (key: string) => string;
+  getSnapshot?: () => { locale?: string; language?: string };
+}
+
+interface RemoteSkillsFace {
+  list?: (arg: { sessionId: string }, signal?: AbortSignal) => Promise<unknown>;
+}
+
+function languageTag(ctx: Context): string | undefined {
+  const locale = (ctx.get?.('locale') ?? (ctx as unknown as { locale?: LocaleFace }).locale) as LocaleFace | undefined;
+  const snap = locale?.getSnapshot?.();
+  return snap?.locale ?? snap?.language
+    ?? (typeof document !== 'undefined' ? document.documentElement.lang : undefined)
+    ?? (typeof navigator !== 'undefined' ? navigator.language : undefined);
+}
+
+function createSkillProbe(ctx: Context): SkillStatusProbe {
+  return {
+    fetchHostStatus: async () => {
+      const sessions = ctx.sessions as { list?: { getSnapshot?: () => { byId?: Record<string, { cwd?: string }> } } } | undefined;
+      const snap = sessions?.list?.getSnapshot?.();
+      const id = firstSessionId(snap);
+      const cwd = id && snap?.byId ? snap.byId[id]?.cwd : undefined;
+      const url = cwd
+        ? `/better-display/skill-status?cwd=${encodeURIComponent(cwd)}`
+        : '/better-display/skill-status';
+      const res = await fetch(url);
+      if (!res.ok) return undefined;
+      return await res.json() as HostSkillStatus;
+    },
+    listRemoteSkills: async () => {
+      const remote = ctx.remote as { skills?: RemoteSkillsFace } | undefined;
+      const skills = remote?.skills
+        ?? (ctx.get?.('remote.skills') as RemoteSkillsFace | undefined)
+        ?? ((ctx.get?.('remote') as { skills?: RemoteSkillsFace } | undefined)?.skills);
+      const sessions = ctx.sessions as { list?: { getSnapshot?: () => { ids?: string[]; byId?: Record<string, unknown> } } } | undefined;
+      const sessionId = firstSessionId(sessions?.list?.getSnapshot?.());
+      if (!skills?.list || !sessionId) return undefined;
+      return skillsFromListResult(await skills.list({ sessionId }));
+    },
+  };
+}
+
+export function installBetterDisplaySettings(ctx: Context, prefs: OpenPrefs): void {
+  const locale = (ctx.get?.('locale') ?? (ctx as unknown as { locale?: LocaleFace }).locale) as LocaleFace | undefined;
+  if (locale?.register) {
+    ctx.effect(() => locale.register!('better-display', { zh, en }), 'dsh-better-display: settings copy');
+  }
+  const checkSkill = createSkillProbe(ctx);
+  const injected = (): BetterDisplaySettingsInjected => ({
+    prefs,
+    copy: settingsCopyFor(languageTag(ctx)),
+    languageTag: languageTag(ctx),
+    checkSkill,
+  });
+  ctx.slots.inject('settings.section', () => ctx.slots.register({
+    name: 'settings.section',
+    id: 'better-display',
+    order: 40,
+    label: () => locale?.bind?.('better-display')?.('nav') || settingsCopyFor(languageTag(ctx)).nav,
+    locale: locale?.bind ? 'better-display' : undefined,
+    inject: injected,
+  }, SettingsSection));
+}

package/src/client/skill-status.ts

@@ -0,0 +1,78 @@
+import {
+  CONVENTIONAL_SKILL_ROOTS,
+  GENERATIVE_MCPAPPS_SKILL,
+  SKILL_PACK_RELATIVE,
+  publicSkillRoots,
+  skillListIncludes,
+  skillsFromListResult,
+  toPublicSkillStatus,
+  type HostSkillStatus,
+} from '../skill-status.js';
+
+export {
+  CONVENTIONAL_SKILL_ROOTS,
+  GENERATIVE_MCPAPPS_SKILL,
+  SKILL_PACK_RELATIVE,
+  publicSkillRoots,
+  skillListIncludes,
+  skillsFromListResult,
+  toPublicSkillStatus,
+};
+export type { HostSkillStatus };
+
+export interface SkillStatusSnapshot {
+  readonly name: typeof GENERATIVE_MCPAPPS_SKILL;
+  readonly installed: boolean;
+  readonly via: 'skills.list' | 'skill-root' | null;
+  readonly roots: HostSkillStatus['roots'];
+  readonly packPath?: string;
+  readonly hostReached: boolean;
+}
+
+export interface SkillStatusProbe {
+  listRemoteSkills?: () => Promise<readonly { readonly name?: string }[] | undefined>;
+  fetchHostStatus?: () => Promise<HostSkillStatus | undefined>;
+}
+
+export async function detectGenerativeMcpappsSkill(probe: SkillStatusProbe): Promise<SkillStatusSnapshot> {
+  let host: HostSkillStatus | undefined;
+  if (probe.fetchHostStatus) {
+    try {
+      host = await probe.fetchHostStatus();
+    } catch {
+      host = undefined;
+    }
+  }
+
+  let remoteHit = false;
+  if (probe.listRemoteSkills) {
+    try {
+      remoteHit = skillListIncludes(await probe.listRemoteSkills());
+    } catch {
+      remoteHit = false;
+    }
+  }
+
+  const installed = Boolean(host?.installed || remoteHit);
+  const via = remoteHit ? 'skills.list' : (host?.via ?? null);
+  const publicHost = host === undefined ? undefined : toPublicSkillStatus(host);
+  return {
+    name: GENERATIVE_MCPAPPS_SKILL,
+    installed,
+    via,
+    roots: publicHost?.roots ?? publicSkillRoots(),
+    hostReached: host !== undefined,
+  };
+}
+
+/** mkdir/cp using conventional relative roots only. Host paths are ignored. */
+export function shortestInstallCommand(_status?: Pick<SkillStatusSnapshot, 'packPath' | 'roots'>): string {
+  const dest = CONVENTIONAL_SKILL_ROOTS[0];
+  return `mkdir -p ${dest} && cp -R ${SKILL_PACK_RELATIVE} ${dest}/`;
+}
+
+export function firstSessionId(list: { ids?: readonly string[]; byId?: Record<string, unknown> } | undefined): string | undefined {
+  if (list?.ids && list.ids.length > 0) return list.ids[0];
+  const keys = list?.byId ? Object.keys(list.byId) : [];
+  return keys[0];
+}

package/src/client/store.ts

@@ -0,0 +1,30 @@
+import { defineStore } from '@deepseek-ai/dsh-client-store';
+import type { EngineStoreHandle } from '@deepseek-ai/dsh-client-store';
+import type { DeliverableOpenMode } from './open-file.js';
+
+export interface ReaderState {
+  expanded: Record<string, boolean>;
+  motion: boolean;
+  autoFold: boolean;
+  /** Default stays the system app. `sidebar` is opt-in. */
+  deliverableOpenMode: DeliverableOpenMode;
+}
+type ReaderActions = {
+  setExpanded: (draft: ReaderState, key: string, value: boolean) => void;
+  setMotion: (draft: ReaderState, value: boolean) => void;
+  setAutoFold: (draft: ReaderState, value: boolean) => void;
+  setDeliverableOpenMode: (draft: ReaderState, value: DeliverableOpenMode) => void;
+};
+
+export function createReaderStore(): EngineStoreHandle<ReaderState, ReaderActions> {
+  return defineStore({
+    init: (): ReaderState => ({ expanded: {}, motion: true, autoFold: true, deliverableOpenMode: 'external' }),
+    persist: 'dsh.reader.v1',
+    actions: {
+      setExpanded: (draft, key: string, value: boolean) => { draft.expanded[key] = value; },
+      setMotion: (draft, value: boolean) => { draft.motion = value; },
+      setAutoFold: (draft, value: boolean) => { draft.autoFold = value; },
+      setDeliverableOpenMode: (draft, value: DeliverableOpenMode) => { draft.deliverableOpenMode = value; },
+    },
+  });
+}

package/src/client/stream-buffer.ts

@@ -0,0 +1,100 @@
+/** Presentation only. The original session string remains the source of truth. */
+export const STREAM_TIMING = { catchUpMs: 180, maxQueuedMs: 240, finishMs: 96, revealMs: 350, minimumRate: 100 } as const;
+const graphemes = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+
+function atOrAfter(values: readonly number[], target: number): number {
+  let low = 0;
+  let high = values.length - 1;
+  while (low < high) {
+    const middle = (low + high) >>> 1;
+    if (values[middle]! < target) low = middle + 1;
+    else high = middle;
+  }
+  return low;
+}
+
+export class StreamBuffer {
+  target: string;
+  visible: string;
+  revision = 0;
+  private boundaries = [0];
+  private arrivals: { end: number; at: number }[] = [];
+  private lastAt: number | null = null;
+  private credit = 0;
+  private finishAt: number | null = null;
+
+  constructor(initial = '') {
+    this.target = initial;
+    this.visible = initial;
+    this.segment(0);
+  }
+
+  get pending(): boolean { return this.visible.length < this.target.length; }
+
+  private segment(from: number): void {
+    const index = atOrAfter(this.boundaries, from);
+    this.boundaries.length = index;
+    for (const part of graphemes.segment(this.target.slice(from))) this.boundaries.push(from + part.index);
+    if (this.boundaries.at(-1) !== this.target.length) this.boundaries.push(this.target.length);
+  }
+
+  /** Non-append updates, cancellations and hidden/reduced views never replay. */
+  update(text: string, now: number, options: { immediate?: boolean; finished?: boolean } = {}): void {
+    if (options.immediate || !text.startsWith(this.target)) {
+      if (text !== this.target) this.revision++;
+      this.target = text;
+      this.flush();
+      this.boundaries = [0];
+      this.segment(0);
+      return;
+    }
+    if (text !== this.target) {
+      const wasPending = this.pending;
+      const from = this.boundaries.at(-2) ?? 0;
+      this.target = text;
+      // Re-segment the previous last cluster: an emoji/combining sequence can
+      // itself span transport chunks. Frozen source prefixes are not scanned.
+      this.segment(from);
+      this.arrivals.push({ end: text.length, at: now });
+      if (!wasPending) { this.lastAt = now; this.credit = 0; }
+    }
+    if (options.finished && this.finishAt === null) this.finishAt = now + STREAM_TIMING.finishMs;
+    if (!options.finished) this.finishAt = null;
+    if (this.target.length - this.visible.length > 8192) { this.revision++; this.flush(); }
+  }
+
+  flush(): void {
+    this.visible = this.target;
+    this.arrivals = [];
+    this.credit = 0;
+    this.lastAt = null;
+    this.finishAt = null;
+  }
+
+  advance(now: number): boolean {
+    if (!this.pending) return false;
+    const before = this.visible.length;
+    const index = atOrAfter(this.boundaries, before);
+    const remaining = this.boundaries.length - index - 1;
+    const delta = Math.max(0, now - (this.lastAt ?? now));
+    this.lastAt = now;
+    const windowMs = this.finishAt === null ? STREAM_TIMING.catchUpMs : Math.max(16, Math.min(STREAM_TIMING.catchUpMs, this.finishAt - now));
+    const rate = Math.max(STREAM_TIMING.minimumRate, remaining * 1000 / windowMs);
+    this.credit += rate * delta / 1000;
+    const count = Math.floor(this.credit);
+    this.credit -= count;
+    let end = this.boundaries[Math.min(this.boundaries.length - 1, index + count)]!;
+    for (const item of this.arrivals) {
+      if (now - item.at < STREAM_TIMING.maxQueuedMs) break;
+      end = Math.max(end, this.boundaries[atOrAfter(this.boundaries, item.end)]!);
+    }
+    if (this.finishAt !== null && now >= this.finishAt) end = this.target.length;
+    // Never expose half of a surrogate pair while the source can still grow.
+    if (end && /[\uD800-\uDBFF]/.test(this.target[end - 1]!) && this.finishAt === null) end--;
+    end = Math.max(before, end);
+    this.visible = this.target.slice(0, end);
+    this.arrivals = this.arrivals.filter(item => item.end > end);
+    if (!this.pending) { this.credit = 0; this.lastAt = null; }
+    return end !== before;
+  }
+}

package/src/client/streaming.tsx

@@ -0,0 +1,62 @@
+import { createContext, useContext, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { StreamBuffer } from './stream-buffer.js';
+import { WORD_MOTION } from './word-timeline.js';
+
+export const StreamMotionContext = createContext<{ enabled: boolean; activatedAt: number; paused?: boolean; resumed?: boolean }>({ enabled: false, activatedAt: 0 });
+
+export function useStreamingText(source: string, streaming: boolean, options: { startedAt?: number; interrupted: boolean; selected: boolean }) {
+  const { enabled, activatedAt, paused = false, resumed = false } = useContext(StreamMotionContext);
+  const fresh = resumed || (options.startedAt ?? 0) >= activatedAt;
+  const buffer = useRef<StreamBuffer>();
+  // Only newly mounted content after a fold uses the catch-up path. History and
+  // user-opened drawers stay immediate; already mounted prefixes never replay.
+  if (!buffer.current) buffer.current = new StreamBuffer(enabled && (streaming || resumed) && fresh ? '' : source);
+  const [display, setDisplay] = useState(() => ({ text: buffer.current!.visible, revision: 0 }));
+  const [finalizing, setFinalizing] = useState(streaming);
+  const frame = useRef(0);
+  const immediate = !enabled || options.interrupted || options.selected;
+  const publish = () => {
+    const current = buffer.current!;
+    setDisplay(previous => previous.text === current.visible && previous.revision === current.revision ? previous : { text: current.visible, revision: current.revision });
+  };
+  const handoff = useRef(resumed);
+  const presentationClock = useRef(performance.now());
+  useLayoutEffect(() => {
+    cancelAnimationFrame(frame.current);
+    if (paused && !immediate && !document.hidden) return;
+    const current = buffer.current!;
+    let previous = performance.now();
+    current.update(source, handoff.current ? presentationClock.current : previous, { immediate: immediate || document.hidden, finished: !streaming && !resumed });
+    publish();
+    const tick = (now: number) => {
+      // A delayed browser frame must not dump the whole buffered response at
+      // first paint. Bound catch-up by visible frame time for this handoff only.
+      presentationClock.current += Math.min(32, Math.max(0, now - previous));
+      previous = now;
+      if (document.hidden) current.flush();
+      else current.advance(handoff.current ? presentationClock.current : now);
+      publish();
+      if (current.pending) frame.current = requestAnimationFrame(tick);
+      else handoff.current = false;
+    };
+    if (current.pending) frame.current = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(frame.current);
+  }, [source, streaming, immediate, paused, resumed]);
+  useEffect(() => {
+    const hidden = () => {
+      if (!document.hidden) return;
+      cancelAnimationFrame(frame.current);
+      buffer.current!.flush(); publish(); setFinalizing(false);
+    };
+    document.addEventListener('visibilitychange', hidden);
+    return () => document.removeEventListener('visibilitychange', hidden);
+  }, []);
+  const pending = display.text !== source;
+  useEffect(() => {
+    if (streaming || pending) { setFinalizing(true); return; }
+    if (immediate || document.hidden) { setFinalizing(false); return; }
+    const timer = setTimeout(() => setFinalizing(false), WORD_MOTION.duration + WORD_MOTION.maxDelay);
+    return () => clearTimeout(timer);
+  }, [streaming, pending, immediate]);
+  return { text: immediate ? source : display.text, pending: !immediate && pending, revision: display.revision, formatStreaming: streaming || (!immediate && (pending || finalizing)), reveal: enabled && !options.interrupted && !options.selected };
+}

package/src/client/style.d.ts

@@ -0,0 +1,4 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>;
+  export default classes;
+}

package/src/client/timeline.ts

@@ -0,0 +1,77 @@
+import type { TurnLocation } from '@deepseek-ai/dsh-client-ui-conversation/client';
+
+export interface TimelineItem {
+  readonly turn: number;
+  readonly prompt: string;
+  readonly response: string;
+  readonly hasDeliverables: boolean;
+  readonly anchor:
+    | { readonly kind: 'loaded'; readonly key: string }
+    | { readonly kind: 'unloaded'; readonly seq: number };
+}
+
+interface RawOutlineEntry {
+  readonly turn?: unknown;
+  readonly seq?: unknown;
+  readonly prompt?: unknown;
+  readonly response?: unknown;
+}
+
+interface LoadedTurnNavigationItem {
+  readonly turn: number;
+  readonly anchorKey: string;
+  readonly prompt: string;
+  readonly response: string;
+}
+
+/**
+ * Merge host turn outline with loaded navigation items and turn deliverables.
+ * Guarantees strictly ascending turn order and dedupes entries.
+ */
+export function mergeTimelineItems(
+  loaded: readonly LoadedTurnNavigationItem[] | undefined,
+  outline: unknown,
+  turnsWithDeliverables?: ReadonlySet<number>,
+): readonly TimelineItem[] {
+  const byTurn = new Map<number, TimelineItem>();
+
+  // 1. Process host whole-log outline (if available)
+  if (Array.isArray(outline)) {
+    for (const raw of outline) {
+      if (typeof raw !== 'object' || raw === null) continue;
+      const entry = raw as RawOutlineEntry;
+      if (typeof entry.turn !== 'number' || !Number.isSafeInteger(entry.turn) || entry.turn < 0) continue;
+      if (typeof entry.seq !== 'number' || !Number.isSafeInteger(entry.seq) || entry.seq < 0) continue;
+
+      byTurn.set(entry.turn, {
+        turn: entry.turn,
+        prompt: typeof entry.prompt === 'string' ? entry.prompt.trim() : '',
+        response: typeof entry.response === 'string' ? entry.response.trim() : '',
+        hasDeliverables: turnsWithDeliverables?.has(entry.turn) ?? false,
+        anchor: { kind: 'unloaded', seq: entry.seq },
+      });
+    }
+  }
+
+  // 2. Overlay loaded items (taking loaded anchor, preferring freshest previews)
+  if (Array.isArray(loaded)) {
+    for (const item of loaded) {
+      if (typeof item.turn !== 'number') continue;
+      const preview = byTurn.get(item.turn);
+      const prompt = item.prompt?.trim() || preview?.prompt || '';
+      const response = item.response?.trim() || preview?.response || '';
+      const hasDeliverables = turnsWithDeliverables?.has(item.turn) ?? preview?.hasDeliverables ?? false;
+
+      byTurn.set(item.turn, {
+        turn: item.turn,
+        prompt,
+        response,
+        hasDeliverables,
+        anchor: { kind: 'loaded', key: item.anchorKey },
+      });
+    }
+  }
+
+  if (byTurn.size === 0) return [];
+  return [...byTurn.values()].sort((a, b) => a.turn - b.turn);
+}