dsh-retrace 0.4.2 → 0.4.3

package/lib/client.js

@@ -129,6 +129,16 @@ const zh = {
   'timeline.gitInitConfirm': '确定要初始化 git 吗？',
   'error.generic': '操作失败，请重试',
   'error.busy': '请先停止当前回复再操作',
+  'view.fork': '分叉',
+  'fork.title': '分叉图',
+  'fork.empty': '还没有分叉。撤回 / 编辑 / 重新生成 / 恢复会在此产生分叉。',
+  'fork.refresh': '刷新',
+  'fork.spine': '当前路径',
+  'fork.shadowed': '被遮蔽 {count} 个节点',
+  'fork.node.user': '用户消息',
+  'fork.node.assistant': '助手回复',
+  'fork.node.tool': '工具结果',
+  'fork.histTitle': '历史分叉点',
 }
 /** English dictionary, checked complete against the zh key set. */
 const en = {
@@ -205,6 +215,16 @@ const en = {
   'timeline.gitInitConfirm': 'Initialize git in this workspace?',
   'error.generic': 'Operation failed; please try again',
   'error.busy': 'Stop the current reply before recalling or editing',
+  'view.fork': 'Fork',
+  'fork.title': 'Fork map',
+  'fork.empty': 'No forks yet. Recall / edit / regenerate / restore fork the path here.',
+  'fork.refresh': 'Refresh',
+  'fork.spine': 'Current path',
+  'fork.shadowed': '{count} shadowed nodes',
+  'fork.node.user': 'User message',
+  'fork.node.assistant': 'Assistant reply',
+  'fork.node.tool': 'Tool result',
+  'fork.histTitle': 'Historical fork points',
 }
 
 // ---------------------------------------------------------------------------
@@ -500,10 +520,10 @@ function useShadowed(useSession, seq) {
 }
 
 /**
- * If one marker would hide more than this share of the conversation's rows,
- * the hiding is refused (the marker still renders as a notice). A single
- * recall/edit must never blank out most of the history — the rows stay in the
- * durable log and remain visible.
+ * If ALL markers together would hide more than this share of the conversation's
+ * rows, hiding is refused for EVERY marker (they render as notices only). A
+ * recall/edit — even several stacked edits — must never blank out most of the
+ * history: the rows stay in the durable log and remain visible.
  */
 const SHADOW_SAFETY_RATIO = 0.4
 
@@ -512,37 +532,64 @@ const SHADOW_SAFETY_RATIO = 0.4
  * the shadowed message rows themselves, plus the per-turn action row (copy /
  * feedback / branch) when its finalized assistant reply is among them.
  */
-function useHiddenKeys(useSession, shadowedSeqs) {
+function hiddenKeysFor(shadowedSeqs, nodes) {
+  if (!Array.isArray(shadowedSeqs) || shadowedSeqs.length === 0) return null
+  const hidden = new Set(shadowedSeqs)
+  const keys = []
+  for (const node of nodes.values()) {
+    if (node.kind === 'recall-marker') continue
+    if (node.kind === 'turn-tail') {
+      // `closing` is the finalized assistant-step *data*; the message seq
+      // lives on its `finalNode` (matching how the app reads `closing.finalNode.seq`).
+      const closingSeq = node.data?.closing?.finalNode?.seq
+      if (typeof closingSeq === 'number' && hidden.has(closingSeq)) keys.push(node.key)
+      continue
+    }
+    if (node.kind === 'tool-call') {
+      // Tool rows anchor at the tool/call event seq, which is a log-only
+      // event and never a surface node, so it cannot appear in shadowedSeqs.
+      // Match the settled result's surface seq (root.seq) instead.
+      const resultSeq = node.data?.root?.seq
+      if (typeof resultSeq === 'number' && hidden.has(resultSeq)) keys.push(node.key)
+      continue
+    }
+    if (typeof node.anchorSeq === 'number' && hidden.has(node.anchorSeq)) keys.push(node.key)
+  }
+  return keys.length === 0 ? null : keys
+}
+
+/**
+ * Global hide plan (0.4.3): one snapshot pass computes EVERY marker's hidden
+ * keys and applies the safety guard to their UNION. A single normal edit still
+ * hides its replaced round (a few rows ≪ the threshold); a session where
+ * stacked edits would collectively hide most of the history degrades EVERY
+ * marker to notice-only, so history can never silently vanish from the view.
+ */
+const EMPTY_HIDE_PLAN = { degraded: false, hiddenFor: () => null }
+function useMarkerHidePlan(useSession) {
   return useSession((snapshot) => {
-    if (!Array.isArray(shadowedSeqs) || shadowedSeqs.length === 0) return null
-    const hidden = new Set(shadowedSeqs)
-    const keys = []
+    const nodes = snapshot.chat.nodes
     let rowCount = 0
-    for (const node of snapshot.chat.nodes.values()) {
+    const markers = []
+    for (const node of nodes.values()) {
       if (typeof node.anchorSeq === 'number') rowCount += 1
-      if (node.kind === 'recall-marker') continue
-      if (node.kind === 'turn-tail') {
-        // `closing` is the finalized assistant-step *data*; the message seq
-        // lives on its `finalNode` (matching how the app reads `closing.finalNode.seq`).
-        const closingSeq = node.data?.closing?.finalNode?.seq
-        if (typeof closingSeq === 'number' && hidden.has(closingSeq)) keys.push(node.key)
-        continue
-      }
-      if (node.kind === 'tool-call') {
-        // Tool rows anchor at the tool/call event seq, which is a log-only
-        // event and never a surface node, so it cannot appear in shadowedSeqs.
-        // Match the settled result's surface seq (root.seq) instead.
-        const resultSeq = node.data?.root?.seq
-        if (typeof resultSeq === 'number' && hidden.has(resultSeq)) keys.push(node.key)
-        continue
+      if (node.kind === 'recall-marker') {
+        markers.push({ key: node.key, shadowedSeqs: node.data?.shadowedSeqs })
       }
-      if (typeof node.anchorSeq === 'number' && hidden.has(node.anchorSeq)) keys.push(node.key)
     }
-    // Safety guard (2026-08-26 incident): a marker covering a huge share of the
-    // conversation (e.g. an edit with "fresh conversation" semantics) degrades
-    // to notice-only — history must never silently vanish from the view.
-    if (keys.length > 0 && rowCount > 0 && keys.length / rowCount > SHADOW_SAFETY_RATIO) return null
-    return keys.length === 0 ? null : keys
+    if (markers.length === 0) return EMPTY_HIDE_PLAN
+    const union = new Set()
+    const perMarker = new Map()
+    for (const marker of markers) {
+      const keys = hiddenKeysFor(marker.shadowedSeqs, nodes)
+      perMarker.set(marker.key, keys)
+      if (keys !== null) for (const key of keys) union.add(key)
+    }
+    const degraded = rowCount > 0 && union.size / rowCount > SHADOW_SAFETY_RATIO
+    return {
+      degraded,
+      hiddenFor: (key) => (degraded ? null : (perMarker.get(key) ?? null)),
+    }
   })
 }
 
@@ -773,7 +820,8 @@ function UserActionsRow({ node, sessionId, useSession, inputActions, t }) {
 function RecallMarkerRow({ node, useSession, t }) {
   const { seq, op, shadowedSeqs, legacy } = node.data
   const dismissed = useMarkerDismissed(useSession, seq, op)
-  const hiddenKeys = legacy || !getConfig().hideShadowed ? null : useHiddenKeys(useSession, shadowedSeqs)
+  const hidePlan = useMarkerHidePlan(useSession)
+  const hiddenKeys = legacy || !getConfig().hideShadowed ? null : hidePlan.hiddenFor(node.key)
 
   // The hide rules must stay mounted even after the notice is dismissed,
   // otherwise the recalled message would reappear. Legacy markers and the
@@ -889,7 +937,8 @@ const CSS = `
 .dsh-rt-retention-input:focus{box-shadow:0 0 0 2px var(--dsw-alias-state-business-primary)}
 .dsh-rt-option input{accent-color:var(--dsw-alias-state-business-primary)}
 /* ---- P1 timeline (conversation view tab) ---- */
-.dsh-rt-view{box-sizing:border-box;display:flex;flex-direction:column;gap:6px;height:100%;min-height:0;padding:12px 16px 0}
+
+.dsh-rt-view{box-sizing:border-box;display:flex;flex-direction:column;gap:6px;flex:1 1 0%;min-height:0;overflow:hidden;padding:12px 16px 0}
 .dsh-rt-timeline-head{display:flex;align-items:center;gap:8px;flex:none}
 .dsh-rt-timeline-title{color:var(--dsw-alias-label-primary);font-size:13px;font-weight:600;line-height:20px;flex:1}
 .dsh-rt-timeline-git{display:flex;align-items:center;gap:6px;flex:none;border:1px dashed var(--dsw-alias-border-l2);border-radius:8px;padding:4px 8px}
@@ -926,8 +975,170 @@ const CSS = `
 .dsh-rt-modal-buttons{display:flex;justify-content:flex-end;gap:8px;flex:none}
 .dsh-rt-confirm{background:var(--dsw-alias-state-error-primary)}
 .dsh-rt-modal-json{margin:0;overflow:auto;color:var(--dsw-alias-label-secondary);background:var(--dsw-alias-bg-elevated);border:1px solid var(--dsw-alias-border-l2);border-radius:8px;padding:8px;font-family:var(--dsw-font-mono);font-size:11px;line-height:15px;white-space:pre-wrap;word-break:break-all}
+.dsh-rt-fork-list{overflow-y:auto;flex:1;min-height:0;position:relative}
+.dsh-rt-fork-spine-label{color:var(--dsw-alias-label-caption);font-size:11px;line-height:16px;flex:none}
+.dsh-rt-fork-row{position:absolute;left:0;right:0;box-sizing:border-box;display:flex;align-items:flex-start;gap:8px;padding:6px 8px;border-radius:8px}
+.dsh-rt-fork-row:hover{background:var(--dsw-alias-interactive-bg-hover)}
+.dsh-rt-fork-icon{flex:none;width:22px;height:22px;display:inline-flex;justify-content:center;align-items:center;font-size:13px;color:var(--dsw-alias-label-secondary)}
+.dsh-rt-fork-boundary .dsh-rt-fork-icon{color:var(--dsw-alias-state-warning-primary)}
+.dsh-rt-fork-body{flex:1;min-width:0;display:flex;flex-direction:column;gap:2px}
+.dsh-rt-fork-line{display:flex;align-items:baseline;gap:8px;min-width:0}
+.dsh-rt-fork-label{font-size:12px;font-weight:500;line-height:18px;color:var(--dsw-alias-label-primary);white-space:nowrap}
+.dsh-rt-fork-seq{font-family:var(--dsw-font-mono);font-size:11px;line-height:18px;color:var(--dsw-alias-label-caption);flex:none}
+.dsh-rt-fork-shadowed{font-size:11px;line-height:18px;color:var(--dsw-alias-state-warning-primary);flex:none}
+.dsh-rt-fork-text{font-size:11px;line-height:16px;color:var(--dsw-alias-label-secondary);min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.dsh-rt-fork-boundary{border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-elevated)}
+.dsh-rt-fork-hist{display:flex;flex-direction:column;gap:4px;border-top:1px solid var(--dsw-alias-border-l2);padding-top:8px;overflow-y:auto;flex:none}
+.dsh-rt-fork-hist-row{display:flex;align-items:flex-start;gap:8px;padding:4px 8px;border-radius:8px}
+.dsh-rt-fork-hist-row:hover{background:var(--dsw-alias-interactive-bg-hover)}
 `
 
+const JUMP_PAGE_BUDGET = 24
+
+/**
+ * Switch to a conversation view tab programmatically.
+ *
+ * The official API offers no setView to third-party views: `actions` is only
+ * injected to entries that declare a `store`, and the chat store is private to
+ * ui-conversation — so `actions?.setView?.(...)` silently no-ops for plugins
+ * (0.4.2 relied on it; verified against the renderer source 2026-08-26). The
+ * only programmatic path is clicking the tab-bar button — the same path a user
+ * click takes. Tab buttons render in registration order (priority, then
+ * order): chat=0, trajectory=10, retrace=20, retrace-fork=30. A view with an
+ * earlier order would shift the indices; verified on the real harness before
+ * relying on the positions.
+ */
+function switchToViewTab(viewId) {
+  const ORDER = { chat: 0, trajectory: 1, retrace: 2, 'retrace-fork': 3 }
+  const index = ORDER[viewId]
+  if (index === undefined) {
+    console.warn(`[dsh-retrace] no tab order registered for "${viewId}"`)
+    return
+  }
+  const buttons = [...document.querySelectorAll('[role="tablist"] [role="tab"]')]
+  const button = buttons[index]
+  if (!button) {
+    console.warn(`[dsh-retrace] tab "${viewId}" (index ${index}) not found in the conversation tab bar`)
+    return
+  }
+  button.click()
+}
+
+/** rAF poll for an element that appears after a view switch + render pass. */
+function waitForElement(selector, frames) {
+  return new Promise((resolve) => {
+    let remaining = frames
+    const probe = () => {
+      const el = document.querySelector(selector)
+      if (el !== null) return resolve(el)
+      if (remaining-- <= 0) return resolve(null)
+      requestAnimationFrame(probe)
+    }
+    requestAnimationFrame(probe)
+  })
+}
+
+/** One-shot highlight for the jumped-to row (removes itself). */
+function flashKey(key) {
+  const id = `dsh-rt-jump-${key.replace(/[^a-z0-9]/gi, '-')}`
+  if (document.querySelector(`style[data-plugin-css="${id}"]`)) return
+  const tag = document.createElement('style')
+  tag.dataset.pluginCss = id
+  tag.textContent = `[data-chat-anchor-key=${JSON.stringify(key)}]{animation:dsh-rt-flash 1.6s ease-out 2}@keyframes dsh-rt-flash{0%,100%{background:transparent}30%,70%{background:var(--dsw-alias-state-business-primary)}55%{background:color-mix(in srgb,var(--dsw-alias-state-business-primary) 30%,transparent)}}`
+  document.head.appendChild(tag)
+  setTimeout(() => tag.remove(), 3400)
+}
+
+/**
+ * Shared jump (versions + fork views): switch to the chat tab, page up via the
+ * session store until the anchor seq is loaded, then scroll the chat row into
+ * view once it renders. The view switch unmounts the current view, so the
+ * whole flow runs here. The store has no seek-to-seq API — only `loadOlder`
+ * (50/page) — so far-away targets are unreachable without thousands of pages;
+ * cap the budget.
+ */
+async function jumpToAnchor(store, anchorSeq) {
+  switchToViewTab('chat')
+  if (!store || typeof store.loadOlder !== 'function' || typeof store.getSnapshot !== 'function') return
+  const keyOfSeq = (seq) => {
+    const nodes = store.getSnapshot()?.chat?.nodes
+    if (!nodes) return null
+    for (const node of nodes.values()) {
+      if (typeof node.anchorSeq === 'number' && node.anchorSeq === seq) return node.key
+    }
+    return null
+  }
+  let key = keyOfSeq(anchorSeq)
+  let pages = 0
+  while (key === null && pages < JUMP_PAGE_BUDGET && store.hasMore) {
+    const before = store.getSnapshot()?.chat?.nodes?.size ?? 0
+    await store.loadOlder()
+    const after = store.getSnapshot()?.chat?.nodes?.size ?? 0
+    pages += 1
+    if (after === before) break // page returned nothing
+    key = keyOfSeq(anchorSeq)
+  }
+  if (key === null) {
+    // Give the last prepend a tick to propagate into the snapshot first.
+    await new Promise((resolve) => setTimeout(resolve, 60))
+    key = keyOfSeq(anchorSeq)
+  }
+  if (key === null) {
+    console.warn(`[dsh-retrace] jump target seq ${anchorSeq} not reached within ${JUMP_PAGE_BUDGET} pages`)
+    return
+  }
+  // The chat view is now mounted (tab click above); poll for its rendered row.
+  const el = await waitForElement(`[data-chat-anchor-key=${JSON.stringify(key)}]`, 90)
+  if (el === null) return
+  el.scrollIntoView({ behavior: 'smooth', block: 'center' })
+  flashKey(key)
+}
+
+/** Surface node type → icon (fork spine rows). */
+const NODE_ICONS = { 'user/message': '👤', 'assistant/message': '🤖', 'tool/result': '🔧' }
+
+/** Surface node type → localized label. */
+function nodeTypeLabel(type, t) {
+  if (type === 'user/message') return t('fork.node.user')
+  if (type === 'assistant/message') return t('fork.node.assistant')
+  if (type === 'tool/result') return t('fork.node.tool')
+  return type
+}
+
+/**
+ * Bound a windowed list to the available height.
+ *
+ * The conversation view area is a flex chain whose middle (`viewArea`,
+ * `flex:1 0 auto; min-height:auto`) grows to CONTENT — a virtualized list's
+ * tall spacer (N × rowHeight) inflates the whole view to the full list height,
+ * so the list never scrolls and the window slice never moves (verified on the
+ * real harness 2026-08-26; the official trajectory view avoids this because
+ * its virtualized content contributes no tall spacer). Measuring the list
+ * height against the viewport and setting it explicitly caps the spacer's
+ * contribution — the view then collapses back to the bounded height.
+ */
+function bindListHeight(listEl) {
+  if (!listEl) return () => {}
+  const measure = () => {
+    const top = listEl.getBoundingClientRect().top
+    const height = Math.max(120, window.innerHeight - top - 16)
+    if (Math.abs(listEl.clientHeight - height) > 4) {
+      // The list is a flex item (flex:1 → flex-basis:0%); a plain height is
+      // ignored by the flex layout, so pin it with flex:none.
+      listEl.style.flex = 'none'
+      listEl.style.height = `${height}px`
+    }
+  }
+  measure()
+  const ro = typeof ResizeObserver === 'function' ? new ResizeObserver(measure) : null
+  ro?.observe(document.body)
+  window.addEventListener('resize', measure)
+  return () => {
+    ro?.disconnect()
+    window.removeEventListener('resize', measure)
+  }
+}
+
 function ensureStyle() {
   if (typeof document === 'undefined') return () => {}
   if (document.querySelector(`style[data-plugin-css="${STYLE_ID}"]`)) return () => {}
@@ -1037,74 +1248,11 @@ function RetraceView({ sessionId, useProjection, t, actions, store }) {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [])
 
-  // Jump: switch to the chat view, then page up via the session store until
-  // the anchor seq is loaded, then scroll the chat row into view once it
-  // renders (the view switch unmounts this view, so the whole flow runs here).
-  // The store has no seek-to-seq API — only `loadOlder` (50/page) — so
-  // far-away targets are unreachable without thousands of pages; cap the budget.
-  const JUMP_PAGE_BUDGET = 24
-  const jump = async (boundarySeq) => {
-    actions?.setView?.('chat')
-    const target = store
-    if (!target || typeof target.loadOlder !== 'function' || typeof target.getSnapshot !== 'function') return
-    const keyOfSeq = (seq) => {
-      const nodes = target.getSnapshot()?.chat?.nodes
-      if (!nodes) return null
-      for (const node of nodes.values()) {
-        if (typeof node.anchorSeq === 'number' && node.anchorSeq === seq) return node.key
-      }
-      return null
-    }
-    let key = keyOfSeq(boundarySeq)
-    let pages = 0
-    while (key === null && pages < JUMP_PAGE_BUDGET && target.hasMore) {
-      const before = target.getSnapshot()?.chat?.nodes?.size ?? 0
-      await target.loadOlder()
-      const after = target.getSnapshot()?.chat?.nodes?.size ?? 0
-      pages += 1
-      if (after === before) break // page returned nothing
-      key = keyOfSeq(boundarySeq)
-    }
-    if (key === null) {
-      // Give the last prepend a tick to propagate into the snapshot first.
-      await new Promise((resolve) => setTimeout(resolve, 60))
-      key = keyOfSeq(boundarySeq)
-    }
-    if (key === null) {
-      console.warn(`[dsh-retrace] jump target seq ${boundarySeq} not reached within ${JUMP_PAGE_BUDGET} pages`)
-      return
-    }
-    // The chat view is now mounted (setView above); poll for its rendered row.
-    const el = await waitForElement(`[data-chat-anchor-key=${JSON.stringify(key)}]`, 90)
-    if (el === null) return
-    el.scrollIntoView({ behavior: 'smooth', block: 'center' })
-    flashKey(key)
-  }
-
-  /** rAF poll for an element that appears after a view switch + render pass. */
-  function waitForElement(selector, frames) {
-    return new Promise((resolve) => {
-      let remaining = frames
-      const probe = () => {
-        const el = document.querySelector(selector)
-        if (el !== null) return resolve(el)
-        if (remaining-- <= 0) return resolve(null)
-        requestAnimationFrame(probe)
-      }
-      requestAnimationFrame(probe)
-    })
-  }
-
-  /** One-shot highlight for the jumped-to row (removes itself). */
-  function flashKey(key) {
-    const id = `dsh-rt-jump-${key.replace(/[^a-z0-9]/gi, '-')}`
-    if (document.querySelector(`style[data-plugin-css="${id}"]`)) return
-    const tag = document.createElement('style')
-    tag.dataset.pluginCss = id
-    tag.textContent = `[data-chat-anchor-key=${JSON.stringify(key)}]{animation:dsh-rt-flash 1.6s ease-out 2}@keyframes dsh-rt-flash{0%,100%{background:transparent}30%,70%{background:var(--dsw-alias-state-business-primary)}55%{background:color-mix(in srgb,var(--dsw-alias-state-business-primary) 30%,transparent)}}`
-    document.head.appendChild(tag)
-    setTimeout(() => tag.remove(), 3400)
-  }
+  // Jump: switch to the chat tab (tab-bar click — `actions?.setView?.()` is a
+  // silent no-op for store-less third-party views), page up via the session
+  // store until the anchor seq is loaded, then scroll the chat row into view.
+  // The whole flow runs here because the view switch unmounts this view.
+  const jump = (boundarySeq) => jumpToAnchor(store, boundarySeq)
 
   const requestPreview = (record) => {
     setPreviewScope('both')
@@ -1145,6 +1293,13 @@ function RetraceView({ sessionId, useProjection, t, actions, store }) {
   const list = versions ?? []
   const visible = list.slice(Math.max(0, Math.floor(scrollTop / ROW_H) - 2), Math.min(list.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2))
 
+  // Same view-area height trap as the fork list (see bindListHeight).
+  useEffect(() => {
+    if (list.length === 0) return undefined
+    return bindListHeight(document.querySelector('.dsh-rt-view .dsh-rt-timeline-list'))
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [list.length])
+
   return createElement('div', { className: 'dsh-rt-view' }, [
     createElement('div', { key: 'head', className: 'dsh-rt-timeline-head' }, [
       createElement('span', { key: 'title', className: 'dsh-rt-timeline-title' }, t('timeline.title')),
@@ -1187,7 +1342,7 @@ function RetraceView({ sessionId, useProjection, t, actions, store }) {
           t,
           top: list.indexOf(record) * ROW_H,
           onPreview: () => requestPreview(record),
-          onTrajectory: () => actions?.setView?.('trajectory'),
+          onTrajectory: () => switchToViewTab('trajectory'),
           onJump: () => jump(record.boundarySeq),
         })),
       ]),
@@ -1273,6 +1428,171 @@ function PreviewBox({ preview, scope, setScope, busy, t, onConfirm, onCancel })
   ])
 }
 
+/**
+ * P2.1 — Fork map: the branch-topology view (PLAN §5.2).
+ *
+ * Data: `retrace/forkmap` projection — live push frames via
+ * `useProjection('retrace/forkmap')` (zero polling), HTTP `/forkmap` fallback.
+ * Rendering: a spine of current-surface nodes (the CURRENT path — markers sit
+ * on it); at each boundary (recall / edit / regenerate / restore — the fork
+ * points) a card shows the shadowed (OLD-path) cluster count plus the marker
+ * summary, joined from `retrace/versions` by boundarySeq (the fork-map wire
+ * stays lean). Node clicks jump to the conversation via the shared
+ * `jumpToAnchor` (tab-bar click + loadOlder + anchor scroll).
+ *
+ * The old-path node details (messages/thinking/tools inside a cluster) belong
+ * to P2.2 (branch-intent cards); this skeleton establishes the topology.
+ */
+function ForkView({ sessionId, useProjection, t, actions, store }) {
+  const [fork, setFork] = useState(null)
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState(null)
+  const [scrollTop, setScrollTop] = useState(0)
+
+  // Live push-frame path (projection standard kit) — falls back to HTTP.
+  const projected = typeof useProjection === 'function' ? useProjection('retrace/forkmap') : undefined
+  // markerText lives in the versions wire; join it by boundarySeq.
+  const versions = typeof useProjection === 'function' ? useProjection('retrace/versions') : undefined
+  const markerBySeq = new Map((versions?.versions ?? []).map((v) => [v.boundarySeq, v.markerText]))
+
+  useEffect(() => {
+    if (projected && Array.isArray(projected.nodes) && Array.isArray(projected.boundaries)) setFork(projected)
+  }, [projected])
+
+  const refresh = () => {
+    setLoading(true)
+    setError(null)
+    timelineGet(`/forkmap?sessionId=${encodeURIComponent(sessionId)}`)
+      .then((result) => {
+        if (!result || result.ok !== true) throw new Error(result?.error?.message ?? 'forkmap failed')
+        setFork(result.value?.nodes ? result.value : null)
+      })
+      .catch((cause) => setError(cause?.message ?? 'forkmap error'))
+      .finally(() => setLoading(false))
+  }
+
+  // Mount-time load: push frames arrive live when the host mounts the
+  // registry; HTTP is the on-demand fallback for minimal compositions.
+  useEffect(() => {
+    if (projected === undefined) refresh()
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  const nodes = fork?.nodes ?? []
+  const boundaries = fork?.boundaries ?? []
+  const boundaryBySeq = new Map(boundaries.map((b) => [b.seq, b]))
+  // Boundaries whose marker is no longer on the current surface (a later
+  // replace shadowed it — e.g. chained edits of one message) have no spine
+  // node; render them in a historical section so every fork point stays
+  // visible.
+  const spineSeqSet = new Set(nodes.map((n) => n.seq))
+  const offSpine = boundaries.filter((b) => !spineSeqSet.has(b.seq))
+
+  // The view-area flex chain grows to content; bound the list height so the
+  // virtual spacer doesn't inflate the whole view (see bindListHeight).
+  useEffect(() => {
+    if (nodes.length === 0) return undefined
+    return bindListHeight(document.querySelector('.dsh-rt-view .dsh-rt-fork-list'))
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [nodes.length])
+
+  // ---- windowed list (uniform rows, zero-dep; same as the versions view) ----
+  const ROW_H = 56
+  const visible = nodes.slice(
+    Math.max(0, Math.floor(scrollTop / ROW_H) - 2),
+    Math.min(nodes.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2),
+  )
+
+  return createElement('div', { className: 'dsh-rt-view' }, [
+    createElement('div', { key: 'head', className: 'dsh-rt-timeline-head' }, [
+      createElement('span', { key: 'title', className: 'dsh-rt-timeline-title' }, t('fork.title')),
+      createElement('button', {
+        key: 'refresh',
+        type: 'button',
+        className: 'dsh-rt-chip',
+        onClick: refresh,
+      }, t('fork.refresh')),
+    ]),
+
+    error !== null && createElement('div', { key: 'error', className: 'dsh-rt-error' }, error),
+    loading && createElement('div', { key: 'loading', className: 'dsh-rt-timeline-empty' }, t('timeline.loading')),
+    !loading && nodes.length === 0 && createElement('div', { key: 'empty', className: 'dsh-rt-timeline-empty' }, t('fork.empty')),
+
+    nodes.length > 0 && createElement('div', { key: 'spine', className: 'dsh-rt-fork-spine-label' }, t('fork.spine')),
+
+    nodes.length > 0 && createElement('div', {
+      key: 'list',
+      className: 'dsh-rt-fork-list',
+      onScroll: (event) => setScrollTop(event.target.scrollTop),
+    }, [
+      createElement('div', { key: 'spacer', style: { height: `${nodes.length * ROW_H}px`, position: 'relative' } }, [
+        visible.map((node) => createElement(ForkRow, {
+          key: node.seq,
+          node,
+          boundary: boundaryBySeq.get(node.seq),
+          markerText: markerBySeq.get(node.seq),
+          t,
+          top: nodes.indexOf(node) * ROW_H,
+          onJump: () => jumpToAnchor(store, node.seq),
+        })),
+      ]),
+    ]),
+
+    offSpine.length > 0 && createElement('div', { key: 'hist', className: 'dsh-rt-fork-hist' }, [
+      createElement('div', { key: 'title', className: 'dsh-rt-fork-spine-label' }, t('fork.histTitle')),
+      offSpine.map((boundary) => createElement(ForkHistRow, {
+        key: boundary.seq,
+        boundary,
+        markerText: markerBySeq.get(boundary.seq),
+        t,
+        onJump: () => jumpToAnchor(store, boundary.seq),
+      })),
+    ]),
+  ])
+}
+
+/** One spine row; boundary rows additionally show the old-path cluster. */
+function ForkRow({ node, boundary, markerText, t, top, onJump }) {
+  const isBoundary = boundary !== undefined
+  const icon = isBoundary ? (KIND_ICONS[boundary.kind] ?? '•') : (NODE_ICONS[node.type] ?? '•')
+  const label = isBoundary ? kindLabel(boundary.kind, t) : nodeTypeLabel(node.type, t)
+  return createElement('div', {
+    className: `dsh-rt-fork-row${isBoundary ? ' dsh-rt-fork-boundary' : ''}`,
+    style: { top: `${top}px` },
+  }, [
+    createElement('span', { key: 'icon', className: 'dsh-rt-fork-icon' }, icon),
+    createElement('div', { key: 'body', className: 'dsh-rt-fork-body' }, [
+      createElement('div', { key: 'line', className: 'dsh-rt-fork-line' }, [
+        createElement('span', { key: 'label', className: 'dsh-rt-fork-label' }, label),
+        createElement('span', { key: 'seq', className: 'dsh-rt-fork-seq' }, `#${node.seq}`),
+        isBoundary && boundary.replacedSeqs.length > 0 && createElement('span', { key: 'shadowed', className: 'dsh-rt-fork-shadowed' },
+          t('fork.shadowed', { count: boundary.replacedSeqs.length })),
+      ]),
+      isBoundary && markerText && createElement('div', { key: 'text', className: 'dsh-rt-fork-text' },
+        markerText.length > 140 ? `${markerText.slice(0, 140)}…` : markerText),
+    ]),
+    createElement('button', { key: 'jump', type: 'button', className: 'dsh-rt-chip', onClick: onJump }, t('timeline.jump')),
+  ])
+}
+
+/** A historical fork point whose marker was itself shadowed (not on the spine). */
+function ForkHistRow({ boundary, markerText, t, onJump }) {
+  return createElement('div', { className: 'dsh-rt-fork-hist-row' }, [
+    createElement('span', { key: 'icon', className: 'dsh-rt-fork-icon' }, KIND_ICONS[boundary.kind] ?? '•'),
+    createElement('div', { key: 'body', className: 'dsh-rt-fork-body' }, [
+      createElement('div', { key: 'line', className: 'dsh-rt-fork-line' }, [
+        createElement('span', { key: 'label', className: 'dsh-rt-fork-label' }, kindLabel(boundary.kind, t)),
+        createElement('span', { key: 'seq', className: 'dsh-rt-fork-seq' }, `#${boundary.seq}`),
+        boundary.replacedSeqs.length > 0 && createElement('span', { key: 'shadowed', className: 'dsh-rt-fork-shadowed' },
+          t('fork.shadowed', { count: boundary.replacedSeqs.length })),
+      ]),
+      markerText && createElement('div', { key: 'text', className: 'dsh-rt-fork-text' },
+        markerText.length > 140 ? `${markerText.slice(0, 140)}…` : markerText),
+    ]),
+    createElement('button', { key: 'jump', type: 'button', className: 'dsh-rt-chip', onClick: onJump }, t('timeline.jump')),
+  ])
+}
+
 // ---------------------------------------------------------------------------
 // Plugin
 // ---------------------------------------------------------------------------
@@ -1330,6 +1650,19 @@ export function apply(ctx) {
     }),
   }, RetraceView))
 
+  // P2.1 — the fork-map view as a second official tab (next to 对话/轨迹/版本).
+  ctx.slots.inject('conversation.view', () => ctx.slots.register({
+    name: 'conversation.view',
+    id: 'retrace-fork',
+    order: 30,
+    locale: NS,
+    label: () => t('view.fork'),
+    inject: (sessionId, actions) => ({
+      actions,
+      store: ctx.get?.('sessions')?.binding?.(sessionId)?.session,
+    }),
+  }, ForkView))
+
   ctx.slots.inject('settings.general.item', () => ctx.slots.register({
     name: 'settings.general.item',
     id: 'retrace',