dsh-retrace 0.4.2 → 0.4.3

package/lib/dynamic-client.js

@@ -126,7 +126,17 @@ return {
         "timeline.gitInitDesc": "\u5728\u5DE5\u4F5C\u533A\u6267\u884C git init\uFF08\u4EC5\u6DFB\u52A0 .gitignore \u4E0E\u4E00\u4E2A\u57FA\u7EBF\u63D0\u4EA4\uFF09\uFF0C\u7248\u672C\u56DE\u9000\u5C06\u4F18\u5148\u4F7F\u7528 git\u3002",
         "timeline.gitInitConfirm": "\u786E\u5B9A\u8981\u521D\u59CB\u5316 git \u5417\uFF1F",
         "error.generic": "\u64CD\u4F5C\u5931\u8D25\uFF0C\u8BF7\u91CD\u8BD5",
-        "error.busy": "\u8BF7\u5148\u505C\u6B62\u5F53\u524D\u56DE\u590D\u518D\u64CD\u4F5C"
+        "error.busy": "\u8BF7\u5148\u505C\u6B62\u5F53\u524D\u56DE\u590D\u518D\u64CD\u4F5C",
+        "view.fork": "\u5206\u53C9",
+        "fork.title": "\u5206\u53C9\u56FE",
+        "fork.empty": "\u8FD8\u6CA1\u6709\u5206\u53C9\u3002\u64A4\u56DE / \u7F16\u8F91 / \u91CD\u65B0\u751F\u6210 / \u6062\u590D\u4F1A\u5728\u6B64\u4EA7\u751F\u5206\u53C9\u3002",
+        "fork.refresh": "\u5237\u65B0",
+        "fork.spine": "\u5F53\u524D\u8DEF\u5F84",
+        "fork.shadowed": "\u88AB\u906E\u853D {count} \u4E2A\u8282\u70B9",
+        "fork.node.user": "\u7528\u6237\u6D88\u606F",
+        "fork.node.assistant": "\u52A9\u624B\u56DE\u590D",
+        "fork.node.tool": "\u5DE5\u5177\u7ED3\u679C",
+        "fork.histTitle": "\u5386\u53F2\u5206\u53C9\u70B9"
       };
       var en = {
         "action.edit": "Edit",
@@ -201,7 +211,17 @@ return {
         "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"
+        "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"
       };
       var SURFACE_TYPES = /* @__PURE__ */ new Set(["user/message", "assistant/message", "tool/result"]);
       function isReplacementSurfaceEvent(event) {
@@ -411,29 +431,51 @@ return {
         });
       }
       var SHADOW_SAFETY_RATIO = 0.4;
-      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") {
+            const closingSeq = node.data?.closing?.finalNode?.seq;
+            if (typeof closingSeq === "number" && hidden.has(closingSeq)) keys.push(node.key);
+            continue;
+          }
+          if (node.kind === "tool-call") {
+            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;
+      }
+      var 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") {
-              const closingSeq = node.data?.closing?.finalNode?.seq;
-              if (typeof closingSeq === "number" && hidden.has(closingSeq)) keys.push(node.key);
-              continue;
-            }
-            if (node.kind === "tool-call") {
-              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);
           }
-          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 = /* @__PURE__ */ new Set();
+          const perMarker = /* @__PURE__ */ 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
+          };
         });
       }
       function useMarkerDismissed(useSession, markerSeq, op) {
@@ -635,7 +677,8 @@ return {
       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);
         const css = hiddenKeys === null ? null : hiddenKeys.map((key) => `[data-chat-anchor-key=${JSON.stringify(key)}]{display:none!important}`).join("");
         const count = Array.isArray(shadowedSeqs) ? shadowedSeqs.length : 0;
         const label = op === "recall" ? count > 1 ? t("marker.recallMany", { count }) : t("marker.recallOne") : op === "regenerate" ? t("marker.regenerate") : t("marker.edit");
@@ -736,7 +779,8 @@ return {
       .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}
@@ -773,7 +817,121 @@ return {
       .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)}
       `;
+      var JUMP_PAGE_BUDGET = 24;
+      function switchToViewTab(viewId) {
+        const ORDER = { chat: 0, trajectory: 1, retrace: 2, "retrace-fork": 3 };
+        const index = ORDER[viewId];
+        if (index === void 0) {
+          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();
+      }
+      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);
+        });
+      }
+      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);
+      }
+      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;
+          key = keyOfSeq(anchorSeq);
+        }
+        if (key === null) {
+          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;
+        }
+        const el = await waitForElement(`[data-chat-anchor-key=${JSON.stringify(key)}]`, 90);
+        if (el === null) return;
+        el.scrollIntoView({ behavior: "smooth", block: "center" });
+        flashKey(key);
+      }
+      var NODE_ICONS = { "user/message": "\u{1F464}", "assistant/message": "\u{1F916}", "tool/result": "\u{1F527}" };
+      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;
+      }
+      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) {
+            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 () => {
         };
@@ -841,63 +999,7 @@ return {
           if (projected === void 0) refresh();
           refreshGit();
         }, []);
-        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;
-            key = keyOfSeq(boundarySeq);
-          }
-          if (key === null) {
-            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;
-          }
-          const el = await waitForElement(`[data-chat-anchor-key=${JSON.stringify(key)}]`, 90);
-          if (el === null) return;
-          el.scrollIntoView({ behavior: "smooth", block: "center" });
-          flashKey(key);
-        };
-        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);
-          });
-        }
-        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 jump = (boundarySeq) => jumpToAnchor(store, boundarySeq);
         const requestPreview = (record) => {
           setPreviewScope("both");
           setPreview({ versionId: record.versionId, kind: record.kind, boundarySeq: record.boundarySeq, data: null, error: null });
@@ -930,6 +1032,10 @@ return {
         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));
+        (0, import_react.useEffect)(() => {
+          if (list.length === 0) return void 0;
+          return bindListHeight(document.querySelector(".dsh-rt-view .dsh-rt-timeline-list"));
+        }, [list.length]);
         return (0, import_react.createElement)("div", { className: "dsh-rt-view" }, [
           (0, import_react.createElement)("div", { key: "head", className: "dsh-rt-timeline-head" }, [
             (0, import_react.createElement)("span", { key: "title", className: "dsh-rt-timeline-title" }, t("timeline.title")),
@@ -967,7 +1073,7 @@ return {
                 t,
                 top: list.indexOf(record) * ROW_H,
                 onPreview: () => requestPreview(record),
-                onTrajectory: () => actions?.setView?.("trajectory"),
+                onTrajectory: () => switchToViewTab("trajectory"),
                 onJump: () => jump(record.boundarySeq)
               }))
             ])
@@ -1050,6 +1156,135 @@ return {
           ])
         ]);
       }
+      function ForkView({ sessionId, useProjection, t, actions, store }) {
+        const [fork, setFork] = (0, import_react.useState)(null);
+        const [loading, setLoading] = (0, import_react.useState)(false);
+        const [error, setError] = (0, import_react.useState)(null);
+        const [scrollTop, setScrollTop] = (0, import_react.useState)(0);
+        const projected = typeof useProjection === "function" ? useProjection("retrace/forkmap") : void 0;
+        const versions = typeof useProjection === "function" ? useProjection("retrace/versions") : void 0;
+        const markerBySeq = new Map((versions?.versions ?? []).map((v) => [v.boundarySeq, v.markerText]));
+        (0, import_react.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));
+        };
+        (0, import_react.useEffect)(() => {
+          if (projected === void 0) refresh();
+        }, []);
+        const nodes = fork?.nodes ?? [];
+        const boundaries = fork?.boundaries ?? [];
+        const boundaryBySeq = new Map(boundaries.map((b) => [b.seq, b]));
+        const spineSeqSet = new Set(nodes.map((n) => n.seq));
+        const offSpine = boundaries.filter((b) => !spineSeqSet.has(b.seq));
+        (0, import_react.useEffect)(() => {
+          if (nodes.length === 0) return void 0;
+          return bindListHeight(document.querySelector(".dsh-rt-view .dsh-rt-fork-list"));
+        }, [nodes.length]);
+        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 (0, import_react.createElement)("div", { className: "dsh-rt-view" }, [
+          (0, import_react.createElement)("div", { key: "head", className: "dsh-rt-timeline-head" }, [
+            (0, import_react.createElement)("span", { key: "title", className: "dsh-rt-timeline-title" }, t("fork.title")),
+            (0, import_react.createElement)("button", {
+              key: "refresh",
+              type: "button",
+              className: "dsh-rt-chip",
+              onClick: refresh
+            }, t("fork.refresh"))
+          ]),
+          error !== null && (0, import_react.createElement)("div", { key: "error", className: "dsh-rt-error" }, error),
+          loading && (0, import_react.createElement)("div", { key: "loading", className: "dsh-rt-timeline-empty" }, t("timeline.loading")),
+          !loading && nodes.length === 0 && (0, import_react.createElement)("div", { key: "empty", className: "dsh-rt-timeline-empty" }, t("fork.empty")),
+          nodes.length > 0 && (0, import_react.createElement)("div", { key: "spine", className: "dsh-rt-fork-spine-label" }, t("fork.spine")),
+          nodes.length > 0 && (0, import_react.createElement)("div", {
+            key: "list",
+            className: "dsh-rt-fork-list",
+            onScroll: (event) => setScrollTop(event.target.scrollTop)
+          }, [
+            (0, import_react.createElement)("div", { key: "spacer", style: { height: `${nodes.length * ROW_H}px`, position: "relative" } }, [
+              visible.map((node) => (0, import_react.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 && (0, import_react.createElement)("div", { key: "hist", className: "dsh-rt-fork-hist" }, [
+            (0, import_react.createElement)("div", { key: "title", className: "dsh-rt-fork-spine-label" }, t("fork.histTitle")),
+            offSpine.map((boundary) => (0, import_react.createElement)(ForkHistRow, {
+              key: boundary.seq,
+              boundary,
+              markerText: markerBySeq.get(boundary.seq),
+              t,
+              onJump: () => jumpToAnchor(store, boundary.seq)
+            }))
+          ])
+        ]);
+      }
+      function ForkRow({ node, boundary, markerText, t, top, onJump }) {
+        const isBoundary = boundary !== void 0;
+        const icon = isBoundary ? KIND_ICONS[boundary.kind] ?? "\u2022" : NODE_ICONS[node.type] ?? "\u2022";
+        const label = isBoundary ? kindLabel(boundary.kind, t) : nodeTypeLabel(node.type, t);
+        return (0, import_react.createElement)("div", {
+          className: `dsh-rt-fork-row${isBoundary ? " dsh-rt-fork-boundary" : ""}`,
+          style: { top: `${top}px` }
+        }, [
+          (0, import_react.createElement)("span", { key: "icon", className: "dsh-rt-fork-icon" }, icon),
+          (0, import_react.createElement)("div", { key: "body", className: "dsh-rt-fork-body" }, [
+            (0, import_react.createElement)("div", { key: "line", className: "dsh-rt-fork-line" }, [
+              (0, import_react.createElement)("span", { key: "label", className: "dsh-rt-fork-label" }, label),
+              (0, import_react.createElement)("span", { key: "seq", className: "dsh-rt-fork-seq" }, `#${node.seq}`),
+              isBoundary && boundary.replacedSeqs.length > 0 && (0, import_react.createElement)(
+                "span",
+                { key: "shadowed", className: "dsh-rt-fork-shadowed" },
+                t("fork.shadowed", { count: boundary.replacedSeqs.length })
+              )
+            ]),
+            isBoundary && markerText && (0, import_react.createElement)(
+              "div",
+              { key: "text", className: "dsh-rt-fork-text" },
+              markerText.length > 140 ? `${markerText.slice(0, 140)}\u2026` : markerText
+            )
+          ]),
+          (0, import_react.createElement)("button", { key: "jump", type: "button", className: "dsh-rt-chip", onClick: onJump }, t("timeline.jump"))
+        ]);
+      }
+      function ForkHistRow({ boundary, markerText, t, onJump }) {
+        return (0, import_react.createElement)("div", { className: "dsh-rt-fork-hist-row" }, [
+          (0, import_react.createElement)("span", { key: "icon", className: "dsh-rt-fork-icon" }, KIND_ICONS[boundary.kind] ?? "\u2022"),
+          (0, import_react.createElement)("div", { key: "body", className: "dsh-rt-fork-body" }, [
+            (0, import_react.createElement)("div", { key: "line", className: "dsh-rt-fork-line" }, [
+              (0, import_react.createElement)("span", { key: "label", className: "dsh-rt-fork-label" }, kindLabel(boundary.kind, t)),
+              (0, import_react.createElement)("span", { key: "seq", className: "dsh-rt-fork-seq" }, `#${boundary.seq}`),
+              boundary.replacedSeqs.length > 0 && (0, import_react.createElement)(
+                "span",
+                { key: "shadowed", className: "dsh-rt-fork-shadowed" },
+                t("fork.shadowed", { count: boundary.replacedSeqs.length })
+              )
+            ]),
+            markerText && (0, import_react.createElement)(
+              "div",
+              { key: "text", className: "dsh-rt-fork-text" },
+              markerText.length > 140 ? `${markerText.slice(0, 140)}\u2026` : markerText
+            )
+          ]),
+          (0, import_react.createElement)("button", { key: "jump", type: "button", className: "dsh-rt-chip", onClick: onJump }, t("timeline.jump"))
+        ]);
+      }
       function apply(ctx) {
         const disposeStyle = ensureStyle();
         ctx.effect(() => () => disposeStyle(), "dsh-retrace: styles");
@@ -1093,6 +1328,17 @@ return {
             store: ctx.get?.("sessions")?.binding?.(sessionId)?.session
           })
         }, RetraceView));
+        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",

package/lib/forkmap.js

@@ -0,0 +1,106 @@
+/**
+ * dsh-retrace — `retrace/forkmap` pure fold (PLAN §5.2, P2.1).
+ *
+ * The fork map is the BRANCH-TOPOLOGY presentation layer ("how we got here"):
+ * every surface replacement — recall / edit / regenerate / restore markers,
+ * compaction checkpoints, and any other replace — is a FORK POINT that shadows
+ * a range of the old path and continues a new path. This module mirrors the
+ * official `foldSurface` state transition (the same one the versions unit
+ * uses) and additionally records each boundary with the seqs it shadowed, so
+ * the client can render:
+ *
+ *   spine     — the current-surface node flow (markers sit ON the spine),
+ *   branches  — at each boundary, the shadowed (old-path) node cluster.
+ *
+ * Data notes (verified against the official source, 2026-08-26):
+ *   - replace `start`/`end` are EVENT SEQS (not surface indices); the shadowed
+ *     seqs are the surface nodes the splice removed — exactly
+ *     `foldSurface(...).replacements[].shadowedSeqs`.
+ *   - official `traceEvent` does NOT link a marker to its new path
+ *     (new-path events never cite the marker, so `derivedEventSeqs` is empty)
+ *     — the new path IS the spine: the surface nodes after the boundary
+ *     (PLAN.md:295 "标记→新路径无需自解析" corrected by research).
+ *   - boundaries ARE the versions (every replacement closes a version); the
+ *     wire stays lean (no markerText — the client joins it from
+ *     `retrace/versions` by boundarySeq).
+ *
+ * The module is import-free except for the shared boundary predicates, stays
+ * transport-neutral, and is registered alongside `retrace/versions` in the
+ * versioning seam. No side effects: pure fold only.
+ */
+import {
+  classifyBoundaryKind,
+  isReplacementSurfaceEvent,
+  isSurfaceEvent,
+} from './version-index.js'
+
+/** Fork-map fold state (plain JSON — durable checkpoint rows validate it). */
+export function createForkmapState() {
+  return {
+    /** Current surface nodes: `{ seq, type }` in fold order (mirror foldSurface). */
+    nodes: [],
+    /** Replacement boundaries in append order. */
+    boundaries: [],
+  }
+}
+
+/**
+ * Fold one committed event into the fork-map state.
+ *
+ * Performance contract (load-bearing for the projection registry): when the
+ * event changes nothing — no surface move, no boundary — the SAME state
+ * reference is returned (`Object.is` gates the change feed).
+ *
+ * @param {ReturnType<typeof createForkmapState>} state
+ * @param {object} event
+ * @returns the next state (same reference when nothing changed).
+ */
+export function applyForkmap(state, event) {
+  if (!event || typeof event.seq !== 'number') return state
+  let next = state
+  let shadowed = null
+
+  // 1. Surface fold (mirror foldSurface / the versions unit).
+  if (isSurfaceEvent(event)) {
+    const op = event.surfaceOp
+    if (op === 'append') {
+      next = { ...next, nodes: [...next.nodes, { seq: event.seq, type: event.type }] }
+    } else if (op && op.op === 'replace') {
+      const startIdx = next.nodes.findIndex((node) => node.seq === op.start)
+      const endIdx = next.nodes.findIndex((node) => node.seq === op.end)
+      if (startIdx !== -1 && endIdx !== -1 && startIdx <= endIdx) {
+        shadowed = next.nodes.slice(startIdx, endIdx + 1).map((node) => node.seq)
+        const nodes = next.nodes.slice()
+        nodes.splice(startIdx, endIdx - startIdx + 1, { seq: event.seq, type: event.type })
+        next = { ...next, nodes }
+      }
+    }
+  }
+
+  // 2. Boundary (fork point). The shadowed range is the splice's removal when
+  //    the span was live; otherwise fall back to the marker's own citation.
+  if (isReplacementSurfaceEvent(event)) {
+    const cited = Array.isArray(event.sourceEventSeqs) ? event.sourceEventSeqs : []
+    const replacedSeqs = shadowed !== null ? shadowed : cited
+    const boundary = {
+      seq: event.seq,
+      kind: classifyBoundaryKind(event),
+      replacedSeqs,
+    }
+    next = { ...next, boundaries: [...next.boundaries, boundary] }
+  }
+
+  return next
+}
+
+/** The client-visible wire value (what `session/projection` frames serve). */
+export function viewForkmap(state) {
+  return {
+    nodes: state.nodes.map((node) => ({ seq: node.seq, type: node.type })),
+    boundaries: state.boundaries.map((boundary) => ({
+      seq: boundary.seq,
+      kind: boundary.kind,
+      replacedSeqs: boundary.replacedSeqs,
+    })),
+  }
+}

package/lib/http.js

@@ -8,6 +8,9 @@
  *   GET  /api/plugins/retrace/versions?sessionId=
  *     — live projection snapshot (HTTP fallback channel; the push channel is
  *       `session/projection` frames via dsh-host-apiproxy).
+ *   GET  /api/plugins/retrace/forkmap?sessionId=
+ *     — the fork-map projection snapshot (branch topology, P2.1; same
+ *       push-frame + HTTP fallback dual channel as /versions).
  *   GET  /api/plugins/retrace/event?sessionId=&seq=&before=&after=
  *     — one event + context window (sessionQuery.readEvent, lazy reads).
  *   GET  /api/plugins/retrace/surface?sessionId=
@@ -87,6 +90,15 @@ export function createRetraceHttpHandler(ctx, { sessions, agents, seam, rollback
     }
   }
 
+  function handleForkmap(req, res, sessionId, config) {
+    seam.setConfig(sessionId, config)
+    try {
+      sendJson(res, 200, { ok: true, value: seam.snapshotForkmap(sessionId) })
+    } catch (error) {
+      sendError(res, error)
+    }
+  }
+
   async function handleEvent(req, res, searchParams) {
     const sessionId = searchParams.get('sessionId') ?? ''
     const seq = Number(searchParams.get('seq'))
@@ -249,6 +261,8 @@ export function createRetraceHttpHandler(ctx, { sessions, agents, seam, rollback
       switch (op) {
         case 'versions':
           return handleVersions(req, res, sessionId, config)
+        case 'forkmap':
+          return handleForkmap(req, res, sessionId, config)
         case 'event':
           return void handleEvent(req, res, searchParams)
         case 'surface':