dsh-retrace 0.3.0 → 0.4.2

package/lib/client.js

@@ -23,7 +23,36 @@ export const inject = ['slots', 'locale', 'conversationEvents']
 const NS = 'retrace'
 const ROUTE_BASE = '/api/plugins/retrace'
 const MARKER_PREFIX = 'retrace'
+/**
+ * Every marker-id prefix this build can recognise. `MARKER_PREFIX` is the
+ * prefix NEW markers are written with; the rest are LEGACY prefixes produced
+ * by earlier plugin names (dsh-message-editor). RENAME RULE: when the plugin
+ * changes its identity again, keep the old prefix in this list (and in
+ * LEGACY_MARKER_PREFIXES) so markers written under the previous name keep
+ * rendering — recognition must never be broken by a rename.
+ */
+const MARKER_PREFIXES = [MARKER_PREFIX, 'message-editor']
+/**
+ * Legacy prefixes whose markers are treated as annotations only: the notice
+ * and the "original input" reference render, but their shadowed ranges are
+ * NEVER hidden. Rationale: a marker written by an older plugin name may not
+ * match this build's edit semantics; hiding content based on it would
+ * silently re-hide conversations the user already sees. Renames must ADD the
+ * retired prefix here (soft-compat: renamed-era markers become annotations,
+ * so a rename can never hide previously visible content).
+ */
+const LEGACY_MARKER_PREFIXES = ['message-editor']
+/** Recognise any marker id this build can interpret, current or legacy. */
+function isMarkerId(id) {
+  return typeof id === 'string' && MARKER_PREFIXES.some((p) => id.startsWith(`${p}-`))
+}
+/** Whether a marker id was written under a legacy (renamed-away) prefix. */
+function isLegacyMarkerId(id) {
+  return typeof id === 'string' && LEGACY_MARKER_PREFIXES.some((p) => id.startsWith(`${p}-`))
+}
 const CONFIG_KEY = 'dsh-retrace:config'
+/** Config keys of renamed-away plugin names, read as a fallback on first load. */
+const LEGACY_CONFIG_KEYS = ['dsh-message-editor:config']
 
 /** Simplified Chinese dictionary (key-set source of truth). */
 const zh = {
@@ -44,13 +73,60 @@ const zh = {
   'marker.referenceHint': '点击展开查看原提问（仅作对照，不会进入模型上下文）',
   'options.title': '消息编辑插件',
   'options.showOriginalInput': '编辑后显示原提问对照',
-  'options.editFromScratch': '编辑后从新对话开始（隐藏此前的消息）',
+  'options.editFromScratch': '编辑后从新对话开始（隐藏此前的消息，默认关）',
+  'options.hideShadowed': '按标记隐藏被编辑/撤回的消息',
+  'options.hideShadowedDesc': '开（默认）：撤回/编辑/重新生成按标记隐藏被替换的那一轮消息。关：所有消息保持可见，标记仅显示提示与对照（查看完整历史用）。一次操作要隐藏超过 40% 的对话时自动降级为不隐藏。',
   'options.versioning': '版本与产物快照',
   'options.versioningDesc': '开：每次撤回/编辑记录一个版本（消息与触碰文件），提供时间线与产物回退；关：仅回退上下文，不记录版本、不追踪产物（最省资源）。',
   'options.git': '启用 git 集成',
   'options.gitDesc': '开：工作区是 git 仓库时用 git 记录与回退（不自动提交、不动你的分支），非仓库可在时间线里一键启用；关：一律用内置快照（存于 ~/.dsh），不触碰工作区 git 状态，功能等价。',
   'options.retention': '版本保留上限',
   'options.retentionDesc': '文件快照只保留最近 N 个版本，超出自动清理最旧的；时间线记录与审计痕迹始终保留。',
+  'timeline.open': '时间线',
+  'timeline.openAria': '打开会话时间线',
+  'timeline.title': '版本时间线',
+  'view.retrace': '版本',
+  'timeline.refresh': '刷新',
+  'timeline.close': '关闭',
+  'timeline.empty': '还没有版本。撤回 / 编辑 / 重新生成会在此记录版本。',
+  'timeline.loading': '加载中…',
+  'timeline.error': '时间线加载失败',
+  'timeline.kind.recall': '撤回',
+  'timeline.kind.edit': '编辑重发',
+  'timeline.kind.regenerate': '重新生成',
+  'timeline.kind.restore': '恢复',
+  'timeline.kind.compaction': '压缩',
+  'timeline.kind.replace': '替换',
+  'timeline.messages': '{count} 条消息',
+  'timeline.files': '{created} 增 / {modified} 改 / {deleted} 删',
+  'timeline.filesNone': '无文件变更',
+  'timeline.preview': '回退预览',
+  'timeline.previewDesc': '将回退到版本 {version}（{kind}）。',
+  'timeline.contextOnly': '仅对话',
+  'timeline.contextOnlyDesc': '移除该版本之后的消息（保留日志审计痕迹）',
+  'timeline.artifactsOnly': '仅产物',
+  'timeline.artifactsOnlyDesc': '把该版本触碰的文件恢复到当时的內容',
+  'timeline.both': '两者',
+  'timeline.bothDesc': '先回退对话，再回退产物',
+  'timeline.messagesRemoved': '将移除 {count} 条消息',
+  'timeline.noChanges': '当前已在该版本状态，无变化',
+  'timeline.artifactsList': '产物动作（{count}）',
+  'timeline.artifact.restore': '恢复',
+  'timeline.artifact.delete': '删除',
+  'timeline.artifact.skip': '跳过',
+  'timeline.confirm': '确认回退',
+  'timeline.cancel': '取消',
+  'timeline.busy': '回退中…',
+  'timeline.detail': '详情',
+  'timeline.trajectory': '轨迹台账',
+  'timeline.jump': '跳转',
+  'timeline.jumpFailed': '该版本在较远的过去（超出自动加载预算），无法直接定位。请向上滚动加载更早消息后重试；或用「详情」查看该版本当时的事件原文。',
+  'timeline.gitRepo': 'git 仓库',
+  'timeline.gitHead': 'HEAD {hash}',
+  'timeline.gitDirty': '工作区有未提交改动',
+  'timeline.gitInit': '启用 git 版本管理',
+  'timeline.gitInitDesc': '在工作区执行 git init（仅添加 .gitignore 与一个基线提交），版本回退将优先使用 git。',
+  'timeline.gitInitConfirm': '确定要初始化 git 吗？',
   'error.generic': '操作失败，请重试',
   'error.busy': '请先停止当前回复再操作',
 }
@@ -73,13 +149,60 @@ const en = {
   'marker.referenceHint': 'Click to expand the original input (reference only, never sent to the model)',
   'options.title': 'Message editor plugin',
   'options.showOriginalInput': 'Show the original input after editing',
-  'options.editFromScratch': 'Start a fresh conversation after editing (hide earlier messages)',
+  'options.editFromScratch': 'Start a fresh conversation after editing (hide earlier messages, default off)',
+  'options.hideShadowed': 'Hide shadowed messages per marker',
+  'options.hideShadowedDesc': 'On (default): recall/edit/regenerate hide the replaced round per their markers. Off: every message stays visible; markers only show the notice and reference (use to review full history). A single op that would hide more than 40% of the conversation degrades to notice-only automatically.',
   'options.versioning': 'Version & artifact snapshots',
   'options.versioningDesc': 'On: every recall/edit records a version (messages and touched files) powering the timeline and artifact rollback. Off: only rewinds context — no version records, no artifact tracking (lightest).',
   'options.git': 'Git integration',
   'options.gitDesc': 'On: uses git to record and roll back when the workspace is a repository (never auto-commits, never touches your branches); non-repo workspaces can enable git from the timeline. Off: built-in snapshots under ~/.dsh only — the plugin never touches the workspace git state; equivalent features.',
   'options.retention': 'Version retention limit',
   'options.retentionDesc': 'File snapshots are kept for the most recent N versions; older ones are pruned automatically (timeline records and the audit trail are always kept).',
+  'timeline.open': 'Timeline',
+  'timeline.openAria': 'Open the session timeline',
+  'timeline.title': 'Version timeline',
+  'view.retrace': 'Versions',
+  'timeline.refresh': 'Refresh',
+  'timeline.close': 'Close',
+  'timeline.empty': 'No versions yet. Recall / edit / regenerate record a version here.',
+  'timeline.loading': 'Loading…',
+  'timeline.error': 'Failed to load the timeline',
+  'timeline.kind.recall': 'Recall',
+  'timeline.kind.edit': 'Edit & resend',
+  'timeline.kind.regenerate': 'Regenerate',
+  'timeline.kind.restore': 'Restore',
+  'timeline.kind.compaction': 'Compaction',
+  'timeline.kind.replace': 'Replace',
+  'timeline.messages': '{count} messages',
+  'timeline.files': '{created} created / {modified} modified / {deleted} deleted',
+  'timeline.filesNone': 'No file changes',
+  'timeline.preview': 'Rollback preview',
+  'timeline.previewDesc': 'Will roll back to version {version} ({kind}).',
+  'timeline.contextOnly': 'Context only',
+  'timeline.contextOnlyDesc': 'Remove messages after this version (the log audit trail stays)',
+  'timeline.artifactsOnly': 'Artifacts only',
+  'timeline.artifactsOnlyDesc': 'Restore the files this version touched to their state at that version',
+  'timeline.both': 'Both',
+  'timeline.bothDesc': 'Roll back the context first, then the artifacts',
+  'timeline.messagesRemoved': '{count} messages will be removed',
+  'timeline.noChanges': 'Already at this version; nothing to change',
+  'timeline.artifactsList': 'Artifact actions ({count})',
+  'timeline.artifact.restore': 'restore',
+  'timeline.artifact.delete': 'delete',
+  'timeline.artifact.skip': 'skip',
+  'timeline.confirm': 'Confirm rollback',
+  'timeline.cancel': 'Cancel',
+  'timeline.busy': 'Rolling back…',
+  'timeline.detail': 'Details',
+  'timeline.trajectory': 'Trajectory',
+  'timeline.jump': 'Jump',
+  'timeline.jumpFailed': 'This version lies too far back (beyond the auto-load budget) to locate directly. Scroll up to load earlier messages, or use Details to read the original event text of this version.',
+  'timeline.gitRepo': 'git repository',
+  'timeline.gitHead': 'HEAD {hash}',
+  'timeline.gitDirty': 'working tree has uncommitted changes',
+  'timeline.gitInit': 'Enable git versioning',
+  'timeline.gitInitDesc': 'Runs git init in the workspace (adds a minimal .gitignore and a baseline commit); rollback will prefer git.',
+  'timeline.gitInitConfirm': 'Initialize git in this workspace?',
   'error.generic': 'Operation failed; please try again',
   'error.busy': 'Stop the current reply before recalling or editing',
 }
@@ -128,17 +251,67 @@ function retraceConfigHeaders() {
 // ---------------------------------------------------------------------------
 // Plugin preferences (localStorage-backed, reactive)
 // ---------------------------------------------------------------------------
-const CONFIG_DEFAULTS = { showOriginalInput: true, editFromScratch: true, versioning: true, git: true, retentionLimit: 50 }
+/**
+ * v3 defaults (2026-08-26 incident fix, finalized): v1's default
+ * `editFromScratch: true` made a single edit hide the WHOLE conversation before
+ * the edit point, so clicking "load earlier" appeared to load nothing. v3 keeps
+ * normal edit UX while making the wipe impossible:
+ *  - `editFromScratch: false` — editing one message no longer rewinds the whole
+ *    conversation; only the edited round is replaced on the model surface.
+ *  - `hideShadowed: true` — the replaced round of an edit/recall/regenerate is
+ *    hidden from the view (the natural "old message disappears" UX), while the
+ *    safety guard in `useHiddenKeys` (40% of the conversation) refuses any
+ *    single marker from blanking out most of the history.
+ */
+const CONFIG_VERSION = 3
+const CONFIG_DEFAULTS = { version: CONFIG_VERSION, showOriginalInput: true, editFromScratch: false, hideShadowed: true, versioning: true, git: true, retentionLimit: 50, prewrite: true }
 const configListeners = new Set()
 let configCache = readConfig()
 
 /** resendMessageId -> the exact text that edit replaced (most recent, host-authoritative). */
 const editReferences = new Map()
 
+/**
+ * Pre-v3 migration: the destructive default `editFromScratch: true` is always
+ * reset to false; `hideShadowed` is reset to true (the natural edit UX) for
+ * configs written under the interim v2 defaults (where it was force-false).
+ * Every other customization is preserved.
+ */
+function migrateConfig(parsed) {
+  const version = typeof parsed.version === 'number' ? parsed.version : 1
+  if (version >= CONFIG_VERSION) return { ...CONFIG_DEFAULTS, ...parsed }
+  return {
+    ...CONFIG_DEFAULTS,
+    ...parsed,
+    version: CONFIG_VERSION,
+    editFromScratch: CONFIG_DEFAULTS.editFromScratch,
+    hideShadowed: CONFIG_DEFAULTS.hideShadowed,
+  }
+}
+
 function readConfig() {
   try {
     const raw = localStorage.getItem(CONFIG_KEY)
-    return { ...CONFIG_DEFAULTS, ...(raw ? JSON.parse(raw) : {}) }
+    if (raw !== null) {
+      const parsed = raw ? JSON.parse(raw) : {}
+      const migrated = migrateConfig(parsed)
+      const storedVersion = typeof parsed.version === 'number' ? parsed.version : 1
+      if (storedVersion < CONFIG_VERSION) {
+        // Persist the migration so the next load starts from the v3 shape.
+        try { localStorage.setItem(CONFIG_KEY, JSON.stringify(migrated)) } catch { /* storage unavailable */ }
+      }
+      return migrated
+    }
+    // Rename-safe fallback: pick up settings saved under a previous plugin name.
+    for (const legacyKey of LEGACY_CONFIG_KEYS) {
+      const legacyRaw = localStorage.getItem(legacyKey)
+      if (legacyRaw !== null) {
+        const migrated = migrateConfig(legacyRaw ? JSON.parse(legacyRaw) : {})
+        try { localStorage.setItem(CONFIG_KEY, JSON.stringify(migrated)) } catch { /* storage unavailable */ }
+        return migrated
+      }
+    }
+    return { ...CONFIG_DEFAULTS }
   } catch {
     return { ...CONFIG_DEFAULTS }
   }
@@ -240,9 +413,11 @@ const userReferenceDefinition = {
 }
 
 function markerOpFromId(id) {
-  if (id.startsWith(`${MARKER_PREFIX}-recall-`)) return 'recall'
-  if (id.startsWith(`${MARKER_PREFIX}-edit-`)) return 'edit'
-  if (id.startsWith(`${MARKER_PREFIX}-regenerate-`)) return 'regenerate'
+  for (const p of MARKER_PREFIXES) {
+    if (id.startsWith(`${p}-recall-`)) return 'recall'
+    if (id.startsWith(`${p}-edit-`)) return 'edit'
+    if (id.startsWith(`${p}-regenerate-`)) return 'regenerate'
+  }
   return 'edit'
 }
 
@@ -250,6 +425,9 @@ function markerOpFromId(id) {
  * The recall/edit/regenerate marker node. Renders a notice row and injects CSS
  * that hides every shadowed message row (they stay in the durable log as an
  * audit trail but disappear from the flow, so view and model context agree).
+ * Legacy-prefix markers (written under a renamed-away plugin name) render as
+ * annotations only: their shadowed ranges are never hidden, so a rename can
+ * never make previously visible content disappear.
  */
 const recallMarkerDefinition = {
   kind: 'recall-marker',
@@ -257,16 +435,22 @@ const recallMarkerDefinition = {
   match: (event) => {
     if (event.type !== 'assistant/message' || !isReplacementSurfaceEvent(event)) return null
     const id = event.data?.message?.id
-    if (typeof id !== 'string' || !id.startsWith(`${MARKER_PREFIX}-`)) return null
+    if (!isMarkerId(id)) return null
     return { id: `marker:${id}`, role: 'start' }
   },
   start: (_context, match) => {
     const event = match.event
+    const id = String(event.data.message.id)
+    const legacy = isLegacyMarkerId(id)
     return {
       seq: event.seq,
       time: event.time,
-      op: markerOpFromId(String(event.data.message.id)),
-      shadowedSeqs: Array.isArray(event.sourceEventSeqs) ? event.sourceEventSeqs.slice() : [],
+      op: markerOpFromId(id),
+      legacy,
+      // Legacy markers never hide: treat their shadowed range as empty so the
+      // notice/reference render but no row is hidden and no action row is
+      // suppressed via useShadowed.
+      shadowedSeqs: legacy ? [] : (Array.isArray(event.sourceEventSeqs) ? event.sourceEventSeqs.slice() : []),
       targetSeq: event.data?.editor?.targetSeq,
       text: event.data?.editor?.text,
     }
@@ -315,6 +499,14 @@ 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.
+ */
+const SHADOW_SAFETY_RATIO = 0.4
+
 /**
  * Every chat-node key that should disappear when `shadowedSeqs` are recalled:
  * the shadowed message rows themselves, plus the per-turn action row (copy /
@@ -325,7 +517,9 @@ function useHiddenKeys(useSession, shadowedSeqs) {
     if (!Array.isArray(shadowedSeqs) || shadowedSeqs.length === 0) return null
     const hidden = new Set(shadowedSeqs)
     const keys = []
+    let rowCount = 0
     for (const node of snapshot.chat.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
@@ -344,6 +538,10 @@ function useHiddenKeys(useSession, 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
   })
 }
@@ -573,12 +771,13 @@ function UserActionsRow({ node, sessionId, useSession, inputActions, t }) {
 
 /** The transient notice row: hides shadowed content, dismissed after the user keeps typing. */
 function RecallMarkerRow({ node, useSession, t }) {
-  const { seq, op, shadowedSeqs } = node.data
+  const { seq, op, shadowedSeqs, legacy } = node.data
   const dismissed = useMarkerDismissed(useSession, seq, op)
-  const hiddenKeys = useHiddenKeys(useSession, shadowedSeqs)
+  const hiddenKeys = legacy || !getConfig().hideShadowed ? null : useHiddenKeys(useSession, shadowedSeqs)
 
   // The hide rules must stay mounted even after the notice is dismissed,
-  // otherwise the recalled message would reappear.
+  // otherwise the recalled message would reappear. Legacy markers and the
+  // `hideShadowed: off` preference never inject hide rules.
   const css = hiddenKeys === null
     ? null
     : hiddenKeys.map((key) => `[data-chat-anchor-key=${JSON.stringify(key)}]{display:none!important}`).join('')
@@ -622,6 +821,7 @@ function OptionsRow({ t }) {
       }),
       createElement('span', null, t('options.editFromScratch')),
     ]),
+    optionRow('hideShadowed', 'options.hideShadowed', 'options.hideShadowedDesc'),
     optionRow('versioning', 'options.versioning', 'options.versioningDesc'),
     optionRow('git', 'options.git', 'options.gitDesc'),
     createElement('div', { key: 'retention', className: 'dsh-rt-option dsh-rt-option-number' }, [
@@ -688,6 +888,44 @@ const CSS = `
 .dsh-rt-retention-input{width:64px;color:var(--dsw-alias-label-primary);background:var(--dsw-alias-bg-elevated);border:1px solid var(--dsw-alias-border-l2);border-radius:6px;padding:2px 6px;font:inherit;font-size:13px;outline:none;margin-top:1px}
 .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-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}
+.dsh-rt-timeline-git-text{color:var(--dsw-alias-label-caption);font-size:11px;line-height:16px}
+.dsh-rt-timeline-list{overflow-y:auto;flex:1;min-height:0;position:relative;--dsh-scrollbar-thumb:var(--dsw-alias-scrollbar-bg-l2)}
+.dsh-rt-timeline-empty{color:var(--dsw-alias-label-tertiary);font-size:12px;line-height:18px;padding:12px 4px;text-align:center}
+.dsh-rt-version{position:absolute;left:0;right:0;height:60px;box-sizing:border-box;display:flex;align-items:flex-start;gap:8px;border:1px solid transparent;border-radius:10px;padding:6px 8px}
+.dsh-rt-version:hover{background:var(--dsw-alias-interactive-bg-hover);border-color:var(--dsw-alias-border-l2)}
+.dsh-rt-version-kind{flex:none;width:22px;height:22px;display:inline-flex;justify-content:center;align-items:center;border-radius:6px;background:var(--dsw-alias-fill-l2);color:var(--dsw-alias-label-secondary);font-size:12px;margin-top:1px}
+.dsh-rt-version-kind-restore{background:var(--dsw-alias-state-success-bg);color:var(--dsw-alias-state-success-primary)}
+.dsh-rt-version-kind-compaction{background:var(--dsw-alias-fill-l2);color:var(--dsw-alias-label-caption)}
+.dsh-rt-version-body{flex:1;min-width:0;display:flex;flex-direction:column;gap:2px}
+.dsh-rt-version-line{display:flex;align-items:center;gap:8px;min-width:0;white-space:nowrap}
+.dsh-rt-version-kind-label{color:var(--dsw-alias-label-primary);font-size:12px;font-weight:600;line-height:16px}
+.dsh-rt-version-time,.dsh-rt-version-msgs{color:var(--dsw-alias-label-tertiary);font-size:11px;line-height:16px}
+.dsh-rt-version-files{color:var(--dsw-alias-label-caption);font-size:11px;line-height:16px;overflow:hidden;text-overflow:ellipsis}
+.dsh-rt-version-text{color:var(--dsw-alias-label-secondary);font-size:11px;line-height:15px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.dsh-rt-version-actions{flex:none;display:inline-flex;gap:4px;opacity:0;transition:opacity .1s}
+.dsh-rt-version:hover .dsh-rt-version-actions{opacity:1}
+.dsh-rt-chip-danger{color:var(--dsw-alias-state-error-primary)}
+.dsh-rt-chip-danger:hover{color:var(--dsw-alias-state-error-primary)}
+.dsh-rt-modal{position:absolute;inset:0;z-index:130;display:flex;flex-direction:column;gap:8px;box-sizing:border-box;border-radius:12px;background:var(--dsw-specific-menu);padding:10px;box-shadow:var(--dsw-shadow-lv3)}
+.dsh-rt-modal-title{display:flex;align-items:center;gap:8px;color:var(--dsw-alias-label-primary);font-size:13px;font-weight:600;line-height:20px}
+.dsh-rt-modal-sub{color:var(--dsw-alias-label-tertiary);font-size:11px;font-weight:400}
+.dsh-rt-modal-body{display:flex;flex-direction:column;gap:6px;overflow-y:auto;min-height:0}
+.dsh-rt-modal-line{color:var(--dsw-alias-label-secondary);font-size:12px;line-height:18px}
+.dsh-rt-modal-files{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:2px;max-height:160px;overflow-y:auto}
+.dsh-rt-modal-files li{display:flex;gap:8px;font-size:12px;line-height:18px;color:var(--dsw-alias-label-secondary)}
+.dsh-rt-art-restore{color:var(--dsw-alias-state-success-primary);flex:none}
+.dsh-rt-art-delete{color:var(--dsw-alias-state-error-primary);flex:none}
+.dsh-rt-art-skip{color:var(--dsw-alias-label-caption);flex:none}
+.dsh-rt-art-path{font-family:var(--dsw-font-mono);min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.dsh-rt-modal-scope{display:flex;flex-direction:column;gap:4px}
+.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}
 `
 
 function ensureStyle() {
@@ -703,6 +941,338 @@ function ensureStyle() {
   }
 }
 
+// ---------------------------------------------------------------------------
+// P1 — Version timeline (header action + floating panel)
+// ---------------------------------------------------------------------------
+// Data sources, per PLAN.md §5.1: the live `session/projection` push frames
+// arrive through the `useProjection` standard kit when present (zero polling);
+// the HTTP `/versions` route is the fallback (opened on demand + manual
+// refresh). Detail reads are lazy `GET /event`; rollback runs
+// `POST /rollback/preview` → confirm → `POST /rollback`; the git banner uses
+// `GET /git/status` and `POST /git/init`. The list window is a zero-dependency
+// fixed-row virtualizer (uniform rows) — @tanstack/react-virtual was evaluated
+// but bundling it (~15 KiB) for a list this size is not worth it.
+
+const KIND_ICONS = { recall: '↩', edit: '✎', regenerate: '↻', restore: '⟲', compaction: '▤', replace: '⇄' }
+
+function kindLabel(kind, t) {
+  return t(`timeline.kind.${kind}`) || kind
+}
+
+function timeLabel(ms) {
+  const date = new Date(ms)
+  return `${date.getMonth() + 1}-${date.getDate()} ${String(date.getHours()).padStart(2, '0')}:${String(date.getMinutes()).padStart(2, '0')}`
+}
+
+function timelineGet(path) {
+  return fetch(`${ROUTE_BASE}${path}`, { headers: retraceConfigHeaders() }).then((res) => {
+    if (res.status < 200 || res.status >= 300) throw new Error(`HTTP ${res.status}`)
+    return res.json()
+  })
+}
+
+/** Format a file-count badge. */
+function fileCountLabel(counts, t) {
+  const total = (counts?.created ?? 0) + (counts?.modified ?? 0) + (counts?.deleted ?? 0)
+  if (total === 0) return t('timeline.filesNone')
+  return t('timeline.files', {
+    created: counts.created ?? 0,
+    modified: counts.modified ?? 0,
+    deleted: counts.deleted ?? 0,
+  })
+}
+
+/**
+ * P1 — Version timeline as an official conversation view tab (PLAN §5.1,
+ * 0.4.2 trajectory-leverage): rendered in the `conversation.view` slot (a tab
+ * next to 对话/轨迹). The versions data channel stays plugin-owned — the live
+ * `session/projection` push frames arrive through
+ * `useProjection('retrace/versions')` when present (zero polling), with the
+ * HTTP `/versions` route as fallback — because versions are DERIVED data the
+ * official event stream does not carry. The view shell, view switching,
+ * paging and the trajectory handoff reuse the official mechanisms.
+ */
+function RetraceView({ sessionId, useProjection, t, actions, store }) {
+  const [versions, setVersions] = useState(null)
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState(null)
+  const [git, setGit] = useState(null)
+  const [gitBusy, setGitBusy] = useState(false)
+  const [preview, setPreview] = useState(null)
+  const [previewScope, setPreviewScope] = useState('both')
+  const [rollbackBusy, setRollbackBusy] = useState(false)
+  const [scrollTop, setScrollTop] = useState(0)
+
+  // Live push-frame path (projection standard kit) — falls back to HTTP.
+  const projected = typeof useProjection === 'function' ? useProjection('retrace/versions') : undefined
+
+  useEffect(() => {
+    if (projected && Array.isArray(projected.versions)) setVersions(projected.versions)
+  }, [projected])
+
+  const refresh = () => {
+    setLoading(true)
+    setError(null)
+    timelineGet(`/versions?sessionId=${encodeURIComponent(sessionId)}`)
+      .then((result) => {
+        if (!result || result.ok !== true) throw new Error(result?.error?.message ?? 'versions failed')
+        setVersions(result.value?.versions ?? [])
+      })
+      .catch((cause) => setError(cause?.message ?? 'timeline error'))
+      .finally(() => setLoading(false))
+  }
+
+  const refreshGit = () => {
+    if (getConfig().git !== true) return
+    timelineGet(`/git/status?sessionId=${encodeURIComponent(sessionId)}`)
+      .then((result) => setGit(result?.ok === true ? result.value : null))
+      .catch(() => setGit(null))
+  }
+
+  // Mount-time load: projection push frames arrive live when the host mounts
+  // the registry; HTTP is the on-demand fallback for minimal compositions.
+  useEffect(() => {
+    if (projected === undefined) refresh()
+    refreshGit()
+    // 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)
+  }
+
+  const requestPreview = (record) => {
+    setPreviewScope('both')
+    setPreview({ versionId: record.versionId, kind: record.kind, boundarySeq: record.boundarySeq, data: null, error: null })
+    callOp('rollback/preview', { sessionId, versionId: record.versionId, scope: 'both' }).then((result) => {
+      setPreview((prev) => prev && prev.versionId === record.versionId
+        ? { ...prev, data: result?.ok === true ? result.value : null, error: result?.ok === true ? null : result?.error?.message ?? null }
+        : prev)
+    })
+  }
+
+  const confirmRollback = () => {
+    if (!preview) return
+    setRollbackBusy(true)
+    callOp('rollback', { sessionId, versionId: preview.versionId, scope: previewScope }).then((result) => {
+      setRollbackBusy(false)
+      if (!result || result.ok !== true) {
+        setPreview((prev) => prev && { ...prev, error: result?.error?.message ?? 'rollback failed' })
+        return
+      }
+      setPreview(null)
+      if (projected === undefined) refresh()
+      refreshGit()
+    })
+  }
+
+  const initGit = () => {
+    if (!window.confirm(t('timeline.gitInitConfirm'))) return
+    setGitBusy(true)
+    callOp('git/init', { sessionId }).then((result) => {
+      setGitBusy(false)
+      refreshGit()
+    })
+  }
+
+  // ---- windowed list (uniform rows, zero-dep) ----
+  const ROW_H = 64
+  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))
+
+  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')),
+      createElement('button', {
+        key: 'refresh',
+        type: 'button',
+        className: 'dsh-rt-chip',
+        onClick: refresh,
+      }, t('timeline.refresh')),
+    ]),
+
+    git !== null && git !== undefined && createElement('div', { key: 'git', className: 'dsh-rt-timeline-git' }, [
+      git.headHash
+        ? [
+            createElement('span', { key: 'r', className: 'dsh-rt-timeline-git-text' }, `${t('timeline.gitRepo')} · ${t('timeline.gitHead', { hash: git.headHash.slice(0, 8) })}${git.dirty ? ` · ${t('timeline.gitDirty')}` : ''}`),
+          ]
+        : createElement('button', {
+            key: 'init',
+            type: 'button',
+            className: 'dsh-rt-chip',
+            disabled: gitBusy,
+            onClick: initGit,
+            title: t('timeline.gitInitDesc'),
+          }, t('timeline.gitInit')),
+    ]),
+
+    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 && list.length === 0 && createElement('div', { key: 'empty', className: 'dsh-rt-timeline-empty' }, t('timeline.empty')),
+
+    list.length > 0 && createElement('div', {
+      key: 'list',
+      className: 'dsh-rt-timeline-list',
+      onScroll: (event) => setScrollTop(event.target.scrollTop),
+    }, [
+      createElement('div', { key: 'spacer', style: { height: `${list.length * ROW_H}px`, position: 'relative' } }, [
+        visible.map((record) => createElement(VersionRow, {
+          key: record.versionId,
+          record,
+          t,
+          top: list.indexOf(record) * ROW_H,
+          onPreview: () => requestPreview(record),
+          onTrajectory: () => actions?.setView?.('trajectory'),
+          onJump: () => jump(record.boundarySeq),
+        })),
+      ]),
+    ]),
+
+    preview && createElement(PreviewBox, {
+      key: 'preview',
+      preview,
+      scope: previewScope,
+      setScope: setPreviewScope,
+      busy: rollbackBusy,
+      t,
+      onConfirm: confirmRollback,
+      onCancel: () => setPreview(null),
+    }),
+  ])
+}
+
+/** One version row (uniform height for the windowed list). */
+function VersionRow({ record, top, t, onPreview, onTrajectory, onJump }) {
+  return createElement('div', { className: 'dsh-rt-version', style: { top: `${top}px` } }, [
+    createElement('span', { key: 'kind', className: `dsh-rt-version-kind dsh-rt-version-kind-${record.kind}`, title: kindLabel(record.kind, t) }, KIND_ICONS[record.kind] ?? '•'),
+    createElement('div', { key: 'body', className: 'dsh-rt-version-body' }, [
+      createElement('div', { key: 'line1', className: 'dsh-rt-version-line' }, [
+        createElement('span', { key: 'kind', className: 'dsh-rt-version-kind-label' }, kindLabel(record.kind, t)),
+        createElement('span', { key: 'time', className: 'dsh-rt-version-time' }, timeLabel(record.createdAt)),
+        createElement('span', { key: 'msgs', className: 'dsh-rt-version-msgs' }, t('timeline.messages', { count: record.messageCount })),
+        createElement('span', { key: 'files', className: 'dsh-rt-version-files' }, fileCountLabel(record.fileCounts, t)),
+      ]),
+      record.markerText
+        ? createElement('div', { key: 'text', className: 'dsh-rt-version-text' }, record.markerText.length > 120 ? `${record.markerText.slice(0, 120)}…` : record.markerText)
+        : null,
+    ]),
+    createElement('span', { key: 'actions', className: 'dsh-rt-version-actions' }, [
+      createElement('button', { key: 'jump', type: 'button', className: 'dsh-rt-chip', onClick: onJump }, t('timeline.jump')),
+      createElement('button', { key: 'trajectory', type: 'button', className: 'dsh-rt-chip', onClick: onTrajectory, title: t('timeline.trajectory') }, t('timeline.trajectory')),
+      createElement('button', { key: 'preview', type: 'button', className: 'dsh-rt-chip dsh-rt-chip-danger', onClick: onPreview }, t('timeline.preview')),
+    ]),
+  ])
+}
+
+/** Rollback preview + confirm box (scope selector + artifact actions). */
+function PreviewBox({ preview, scope, setScope, busy, t, onConfirm, onCancel }) {
+  const data = preview.data
+  const scopes = [
+    ['context', 'timeline.contextOnly', 'timeline.contextOnlyDesc'],
+    ['artifacts', 'timeline.artifactsOnly', 'timeline.artifactsOnlyDesc'],
+    ['both', 'timeline.both', 'timeline.bothDesc'],
+  ]
+  return createElement('div', { className: 'dsh-rt-modal' }, [
+    createElement('div', { key: 'title', className: 'dsh-rt-modal-title' }, [
+      t('timeline.preview'),
+      createElement('span', { key: 'ver', className: 'dsh-rt-modal-sub' }, t('timeline.previewDesc', { version: preview.versionId, kind: kindLabel(preview.kind, t) })),
+    ]),
+    preview.error && createElement('div', { key: 'err', className: 'dsh-rt-error' }, preview.error),
+    data === null && !preview.error && createElement('div', { key: 'wait', className: 'dsh-rt-timeline-empty' }, t('timeline.loading')),
+    data && createElement('div', { key: 'body', className: 'dsh-rt-modal-body' }, [
+      createElement('div', { key: 'ctx', className: 'dsh-rt-modal-line' },
+        data.context?.messages > 0
+          ? t('timeline.messagesRemoved', { count: data.context.messages })
+          : t('timeline.noChanges')),
+      createElement('div', { key: 'art', className: 'dsh-rt-modal-line' }, t('timeline.artifactsList', { count: data.artifacts?.rows?.length ?? 0 })),
+      createElement('ul', { key: 'files', className: 'dsh-rt-modal-files' }, (data.artifacts?.rows ?? []).slice(0, 12).map((row) =>
+        createElement('li', { key: row.path }, [
+          createElement('span', { key: 'a', className: `dsh-rt-art-${row.action}` },
+            row.action === 'skip' ? `${t('timeline.artifact.skip')} (${row.reason ?? ''})` : (row.action === 'delete' ? t('timeline.artifact.delete') : t('timeline.artifact.restore'))),
+          createElement('span', { key: 'p', className: 'dsh-rt-art-path' }, row.path),
+        ]))),
+      createElement('div', { key: 'scope', className: 'dsh-rt-modal-scope' }, scopes.map(([value, labelKey, descKey]) =>
+        createElement('label', { key: value, className: 'dsh-rt-option' }, [
+          createElement('input', { type: 'radio', name: 'rt-scope', checked: scope === value, onChange: () => setScope(value) }),
+          createElement('span', { className: 'dsh-rt-option-text' }, [
+            createElement('span', { className: 'dsh-rt-option-label' }, t(labelKey)),
+            createElement('span', { className: 'dsh-rt-option-desc' }, t(descKey)),
+          ]),
+        ]))),
+    ]),
+    createElement('div', { key: 'buttons', className: 'dsh-rt-modal-buttons' }, [
+      createElement('button', { key: 'cancel', type: 'button', className: 'dsh-rt-editor-cancel', disabled: busy, onClick: onCancel }, t('timeline.cancel')),
+      createElement('button', { key: 'confirm', type: 'button', className: 'dsh-rt-editor-send dsh-rt-confirm', disabled: busy || preview.error !== null, onClick: onConfirm },
+        busy ? t('timeline.busy') : t('timeline.confirm')),
+    ]),
+  ])
+}
+
 // ---------------------------------------------------------------------------
 // Plugin
 // ---------------------------------------------------------------------------
@@ -710,6 +1280,7 @@ export function apply(ctx) {
   const disposeStyle = ensureStyle()
   ctx.effect(() => () => disposeStyle(), 'dsh-retrace: styles')
   ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'dsh-retrace: dictionaries')
+  const t = ctx.locale.bind(NS)
 
   const conversationEvents = ctx.get('conversationEvents')
   if (conversationEvents) {
@@ -743,6 +1314,22 @@ export function apply(ctx) {
     locale: NS,
   }, RecallMarkerRow))
 
+  // P0 (0.4.2, trajectory-leverage) — the version timeline as an official
+  // conversation view tab (next to 对话/轨迹). The view shell + switching are
+  // the official mechanisms; the versions data channel stays plugin-owned
+  // (projection push frames → HTTP /versions fallback).
+  ctx.slots.inject('conversation.view', () => ctx.slots.register({
+    name: 'conversation.view',
+    id: 'retrace',
+    order: 20,
+    locale: NS,
+    label: () => t('view.retrace'),
+    inject: (sessionId, actions) => ({
+      actions,
+      store: ctx.get?.('sessions')?.binding?.(sessionId)?.session,
+    }),
+  }, RetraceView))
+
   ctx.slots.inject('settings.general.item', () => ctx.slots.register({
     name: 'settings.general.item',
     id: 'retrace',