dsh-plugin-message-edit 1.0.0

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 SpookySandwich
+
+Portions of the host-side branching logic are derived from dsh-message-edit,
+Copyright (c) Moeblack, also released under the MIT License.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,78 @@
+# dsh-plugin-message-edit
+
+English | [简体中文](README.md)
+
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![dsh](https://img.shields.io/badge/dsh-0.1.0--rc.7-4b8dff)](https://github.com/deepseek-ai/deepseek-harness)
+[![stars](https://img.shields.io/github/stars/SpookySandwich/dsh-plugin-message-edit?style=flat&label=stars)](https://github.com/SpookySandwich/dsh-plugin-message-edit/stargazers)
+
+Edit a message you already sent and the conversation **rewinds and branches** from that point, the way ChatGPT, Claude and DeepSeek all do it. The old version is not overwritten — a `‹ 2/4 ›` counter appears under the bubble, and a Versions tab draws the whole tree.
+
+![demo](https://raw.githubusercontent.com/SpookySandwich/dsh-plugin-message-edit/master/assets/demo.gif)
+
+## Version Tree Visualization
+
+No matter how deeply conversations diverge or how many times prompts are edited, the **Versions** tab projects a clear, turn-level branching hierarchy with real-time active path highlights and instant navigation:
+
+![Version Tree](https://raw.githubusercontent.com/SpookySandwich/dsh-plugin-message-edit/master/assets/tree-demo.png)
+
+## What it does
+
+- **Edit and branch.** Revise a past prompt and send: a new branch regenerates from the full context *before* that turn. This is a true rewind, not a fork that continues from the end.
+- **Version counter.** When a message has alternatives, `‹ n/m ›` appears beneath it. The arrows move between them instantaneously.
+- **Version tree.** A **Versions** tab lays the branches out as a graph you can pan, zoom and drag. The current path is highlighted; click any node to jump to that conversation.
+- **Zero-flicker instant switching.** Family-aware SWR client caching enables 0ms version switching and graph navigation without indicator flicker or loading delays.
+- **In-memory host caching.** Parsed turns and version metadata are cached in host memory, eliminating redundant disk I/O and JSON parsing for deep branching trees.
+- **Automatic cancellation.** Branching immediately cancels any still-streaming obsolete sibling turns across the conversation family to save tokens and compute.
+- **Retry.** Re-run a turn without editing it (Claude layout).
+- **Copy.** Put the message text on the clipboard.
+- **Durable.** Every branch is a real persisted session, and version links are stored as durable events so the tree survives restarts. New branches automatically group into the parent session's workspace.
+
+## Interface style
+
+The three interfaces this imitates differ in **where the controls sit and which ones exist**, so the preset changes exactly that — never the colours, which stay native to DSH. Pick one under **Settings → Message Tree**; the panel previews it live.
+
+| Preset | Controls under the bubble | Shown | Editor buttons |
+| --- | --- | --- | --- |
+| **ChatGPT** | edit, copy | on hover | `Cancel` / `Send` **inside** the box |
+| **DeepSeek** | edit, copy | always — like DSH itself | `Cancel` / `Send` **inside** the box |
+| **Claude** | **retry**, edit, copy | on hover | `Cancel` / `Save` **below** the box |
+
+Only Claude offers retry on a user message, matching the real interface. There is no share button, because DSH has none.
+
+## Install
+
+```bash
+dsh plugin --profile web add dsh-plugin-message-edit
+```
+
+Restart DSH afterwards — the host half loads with the server. The interface follows DSH's display language (English / 中文).
+
+## How it works
+
+DSH sessions are append-only event logs with no in-session branching, so a rewind has to be built:
+
+- The host half serves `/message-tree`. Editing a message creates a **new session seeded with every event before the target turn**, writes a durable `message-tree/version` marker naming what changed, and submits the edited prompt.
+- Those markers are read back to reconstruct the tree, the `‹ n/m ›` ring, and which branch you are currently on.
+- The marker is written with the envelope's `ignorable` flag. Plugin event types live outside the harness vocabulary, and without that flag the reader refuses to interpret the whole log — the session simply fails to open.
+- Only the plain `user` message node is shadowed, at priority `-1`. Reasoning, tool calls and steering rows keep the host renderer.
+
+The host-side branching logic derives from [dsh-message-edit](https://github.com/Moeblack/dsh-message-edit) (MIT © Moeblack), reworked for ChatGPT-style rewind semantics, sibling fan-out, and the interface presets above.
+
+The names are similar, so to be explicit: this is a separate plugin. Its route, cordis id and durable event type keep a distinct `message-tree` spelling precisely so both can be installed side by side without colliding.
+
+## Documentation
+
+For technical details and developer guides, see:
+- [Architecture Overview](docs/ARCHITECTURE.md): Host/client architecture, Cordis lifecycle injection, durable event storage, and HTTP API.
+- [Tree Data Model & Algorithms](docs/TREE_DATA_MODEL.md): Turn-level message tree projection, sibling fan-out, ghost recovery, and active path calculation.
+- [Development & Testing Guide](docs/DEVELOPMENT.md): Build pipeline, automated test suite, and local installation instructions.
+
+## Compatibility
+
+Coexists with [dsh-plugin-smooth-stream](https://github.com/SpookySandwich/dsh-plugin-smooth-stream) and [dsh-plugin-rollout-scout](https://github.com/SpookySandwich/dsh-plugin-rollout-scout).
+
+## License
+
+MIT © SpookySandwich. Portions of the host half derive from dsh-message-edit (MIT © Moeblack).
+

package/README.md

@@ -0,0 +1,78 @@
+# dsh-plugin-message-edit
+
+[English](README.en.md) | 简体中文
+
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![dsh](https://img.shields.io/badge/dsh-0.1.0--rc.7-4b8dff)](https://github.com/deepseek-ai/deepseek-harness)
+[![stars](https://img.shields.io/github/stars/SpookySandwich/dsh-plugin-message-edit?style=flat&label=stars)](https://github.com/SpookySandwich/dsh-plugin-message-edit/stargazers)
+
+编辑一条已经发出的消息，对话会从那一刻 **真正回溯并分叉**——和 ChatGPT、Claude、DeepSeek 的做法一致。旧版本不会被覆盖：气泡下方出现 `‹ 2/4 ›` 计数，「版本」标签页则画出整棵树。
+
+![演示](https://raw.githubusercontent.com/SpookySandwich/dsh-plugin-message-edit/master/assets/demo-zh.gif)
+
+## 版本树分支展示
+
+无论对话如何深层分叉、编辑多少次，「版本」标签页均会呈现清晰的轮次级分支图，当前会话所在路径实时高亮，点击任意节点即可平滑跳转：
+
+![版本树](https://raw.githubusercontent.com/SpookySandwich/dsh-plugin-message-edit/master/assets/tree-demo.png)
+
+## 功能
+
+- **编辑并分叉**：修改过去的提问并发送，新分支会带着该轮 *之前* 的完整上下文重新生成。这是真正的回溯，而不是从末尾继续的 fork。
+- **版本计数**：一条消息存在多个版本时，下方出现 `‹ n/m ›`，左右箭头在各版本间即时切换。
+- **版本树**：新增「版本」标签页，以图的方式展示所有分支，可平移、缩放、拖动。当前所在分支高亮，点击任意节点即可跳转。
+- **零延迟与即时切换**：客户端家族级 SWR 缓存与乐观预加载，点击箭头或树节点切换版本 0ms 响应，无指示器闪烁或加载白屏。
+- **高性能内存缓存**：宿主端内存解析缓存，消除重复磁盘 I/O 与日志重析，即便是深度分叉的庞大家族树也能毫秒级响应。
+- **自动中止旧分支**：分叉时自动停止同家族中仍在流式生成的回复，避免浪费 Token 与计算资源。
+- **重试**：不修改内容，直接重跑该轮（Claude 布局）。
+- **复制**：把消息文本复制到剪贴板。
+- **持久可靠**：每个分支都是真实会话，版本关系写入持久事件，重启后依旧完整。新分支自动归入父会话的工作区。
+
+## 界面风格
+
+这三家界面的差别在于 **操作按钮放在哪里、有哪些**，因此预设只改变这一点，颜色始终沿用 DSH 原生配色。在 **设置 → 消息树** 中选择，面板内有实时预览。
+
+| 预设 | 气泡下方的按钮 | 显示方式 | 编辑框按钮 |
+| --- | --- | --- | --- |
+| **ChatGPT** | 编辑、复制 | 悬停时显示 | `取消` / `发送` 在框 **内部** |
+| **DeepSeek** | 编辑、复制 | 始终显示——与 DSH 一致 | `取消` / `发送` 在框 **内部** |
+| **Claude** | **重试**、编辑、复制 | 悬停时显示 | `取消` / `保存` 在框 **下方** |
+
+只有 Claude 在用户消息上提供重试，与真实界面一致。没有分享按钮——DSH 本身没有，就不自行发明。
+
+## 安装
+
+```bash
+dsh plugin --profile web add dsh-plugin-message-edit
+```
+
+安装后请重启 DSH：宿主端随服务器加载。界面跟随 DSH 显示语言（中文 / English）。
+
+## 工作原理
+
+DSH 的会话是仅追加的事件日志，本身不支持会话内分支，因此回溯需要另行实现：
+
+- 宿主端提供 `/message-tree` 接口。编辑消息时，会 **以目标轮次之前的全部事件为种子创建一个新会话**，写入持久的 `message-tree/version` 标记说明改动内容，并把编辑后的提问送入。
+- 之后读取这些标记，还原出整棵版本树、`‹ n/m ›` 计数，以及当前处于哪个分支。
+- 标记事件带有信封上的 `ignorable` 标志。插件自定义的事件类型不在宿主的事件词表内，缺少该标志时读取端会拒绝解释整份日志，会话将直接打不开。
+- 只遮蔽普通的 `user` 消息节点（优先级 `-1`）；思考、工具调用与引导消息仍由宿主渲染。
+
+宿主端的分支逻辑源自 [dsh-message-edit](https://github.com/Moeblack/dsh-message-edit)（MIT © Moeblack），在其基础上重做为 ChatGPT 式回溯语义、同级分支展开，以及上述界面预设。
+
+两者名字相近，这里说明一下：这是另一个独立插件。它的路由、cordis id 与持久事件类型都保留了 `message-tree` 这一套命名，正是为了两个插件可以同时安装而互不冲突。
+
+## 文档
+
+更多技术细节与开发指南，请参阅：
+- [架构概览 (Architecture)](docs/ARCHITECTURE.md)：宿主/客户端架构、Cordis 服务注入、持久事件模型与 HTTP 接口。
+- [树数据模型与算法 (Tree Data Model)](docs/TREE_DATA_MODEL.md)：轮次级消息树构建、同级展开、删除会话（Ghost）桥接与高亮路径计算。
+- [开发与测试指南 (Development)](docs/DEVELOPMENT.md)：构建流程、单元测试与本地安装说明。
+
+## 兼容性
+
+可与 [dsh-plugin-smooth-stream](https://github.com/SpookySandwich/dsh-plugin-smooth-stream)、[dsh-plugin-rollout-scout](https://github.com/SpookySandwich/dsh-plugin-rollout-scout) 共存。
+
+## 许可
+
+MIT © SpookySandwich。宿主端部分逻辑源自 dsh-message-edit（MIT © Moeblack）。
+

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# The loader entry id stays `message-tree` on purpose: Moeblack's
+# dsh-message-edit uses the id `message-edit`, and two entries sharing an id
+# collide when both plugins are installed. `name` is the package to import,
+# so it follows the package rename.
+- insert:
+    - id: message-tree
+      name: dsh-plugin-message-edit

package/docs/ARCHITECTURE.md

@@ -0,0 +1,156 @@
+# Architecture Overview
+
+`dsh-plugin-message-edit` provides ChatGPT/Claude-style conversation branching and message editing for [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness).
+
+Because DSH session event logs are append-only without native in-session branching, this plugin splits responsibilities across a **Node.js Host Service** and a **Browser/Web Client**.
+
+---
+
+## 1. System Components
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      DSH Desktop / Web                      │
+│                                                             │
+│  ┌──────────────────────┐         ┌──────────────────────┐  │
+│  │     Client Half      │  HTTP   │      Host Half       │  │
+│  │  (plugin.client.js)  │<───────>│    (lib/index.js)    │  │
+│  └──────────┬───────────┘         └──────────┬───────────┘  │
+│             │                                │              │
+│    Shadow User Message              Cordis Services:        │
+│    Versions Tab (Graph)             - sessions              │
+│    Settings UI                      - agents                │
+│                                     - webServer             │
+│                                     - sessionPersistence    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 1.1 Host Half (`lib/index.js`)
+- Runs in the Node.js backend process via Cordis lifecycle injection.
+- Registers the `/message-tree` HTTP route on `ctx.webServer`.
+- Owns branch creation transactions (`POST /message-tree`):
+  1. Truncates parent events up to the target turn.
+  2. Seeds a new DSH session with the prefix events.
+  3. Appends a durable `message-tree/version` marker with `ignorable: true`.
+  4. Submits the edited prompt into the new session.
+- Owns graph queries (`GET /message-tree?sessionId=...`):
+  - Traverses the session family DAG.
+  - Recovers deleted/ghost ancestors from surviving descendants' event logs.
+  - Extracts turn event boundaries for turn-level rendering.
+
+### 1.2 Client Half (`plugin.client.js`)
+- Runs in the browser / renderer process.
+- Injects a shadowed `user` message renderer at priority `-1` to add the edit/copy/retry toolbar and `‹ n/m ›` version ring without modifying agent responses, tool calls, or reasoning blocks.
+- Adds the **Versions** tab (`VIEW_ORDER: 16`) providing an interactive pan/zoom graph with spring physics.
+- Adds settings options in **Settings → Message Edit** with live layout switching (ChatGPT, DeepSeek, Claude styles).
+
+---
+
+## 2. Durable Storage Model
+
+DSH sessions are immutable append-only logs. When branching:
+
+1. **Seed Inheritance**: A new session is initialized whose log begins with an exact clone of the parent's event log up to the start of the edited turn (`seedLength`).
+2. **Durable Marker**: The host appends a custom event:
+   ```json
+   {
+     "type": "message-tree/version",
+     "data": {
+       "schemaVersion": 1,
+       "effect": {
+         "operation": "edit",
+         "targetTurn": 1,
+         "targetEventSeq": 5,
+         "before": "Original message text",
+         "after": "Edited message text"
+       },
+       "inverse": {
+         "kind": "restore-version",
+         "sessionId": "parent-session-id"
+       }
+     }
+   }
+   ```
+3. **`ignorable` Flag**: Custom plugin event types fall outside DSH's core schema. The event envelope must set `ignorable: true`; otherwise, DSH's built-in event reader will reject the entire session log.
+
+---
+
+## 3. HTTP API
+
+### `GET /message-tree?sessionId={id}`
+Returns the entire conversation family surrounding the requested session.
+
+**Response Schema:**
+```json
+{
+  "sessionId": "current-session-id",
+  "versions": [
+    {
+      "sessionId": "session-a",
+      "createdAt": 1724334000000,
+      "depth": 0,
+      "current": false,
+      "onCurrentPath": true,
+      "turns": [
+        { "turn": 1, "text": "Hello", "time": 1724334001000 },
+        { "turn": 2, "text": "Tell me more", "time": 1724334005000 }
+      ]
+    },
+    {
+      "sessionId": "session-b",
+      "parentSessionId": "session-a",
+      "createdAt": 1724334020000,
+      "depth": 1,
+      "current": true,
+      "onCurrentPath": true,
+      "operation": "edit",
+      "targetTurn": 1,
+      "before": "Hello",
+      "after": "Hello world",
+      "turns": [
+        { "turn": 1, "text": "Hello world", "time": 1724334021000 },
+        { "turn": 2, "text": "What is next?", "time": 1724334025000 }
+      ]
+    }
+  ]
+}
+```
+
+### `POST /message-tree`
+Performs branch creation or reactivation.
+
+- **`edit`**: Rewinds to before the specified user turn, creates a new branched session, appends a durable `message-tree/version` marker, and submits the replacement prompt.
+- **`retry`**: Rewinds to before the target turn, creates a child session, and replays the original user prompt.
+- **`activate`**: Unarchives an archived version session via the host registry queue so the client can navigate to it.
+
+---
+
+## 4. Performance & In-Memory Caching
+
+1. **Host-Side Parsed Session Cache (`sessionParsedCache`)**:
+   - Parses turn boundaries (`extractTurns`) and version headers once per immutable event sequence.
+   - Bounded to 500 session entries with key invalidation on live event count / disk mtime changes.
+   - Subsequent `tree()` queries across siblings in the family hit in-memory cache in sub-millisecond time.
+
+2. **Client-Side Family SWR Store (`treeStore`)**:
+   - Maps every non-deleted branch in a tree to the shared family structure upon fetch.
+   - Switching between sibling branches (`‹ n/m ›` or Versions view) is 100% synchronous (0ms lag, zero indicator flicker).
+   - Uses monotonic request timestamps to prevent race-condition overwrites from out-of-order responses.
+   - Optimistically seeds newly created edit/retry branches before navigation.
+
+---
+
+## 5. Security and Error Resilience
+
+- **Ignorable Event Envelope**: `ignorable: true` ensures foreign event markers do not crash the core DSH log parser.
+- **Fail-Safe Mutation Recovery**: Transaction reversals (`child.dispose()`) on failures prevent dangling session artifacts.
+- **Memory Bounded Stores**: LRU bounds (500 sessions) prevent unbounded memory growth in long-running processes.
+
+## 6. Naming & Namespaces
+
+- **NPM Package**: `dsh-plugin-message-edit`
+- **Cordis Service Name**: `message-tree`
+- **HTTP Path**: `/message-tree`
+- **Durable Event Type**: `message-tree/version`
+
+> The package uses `dsh-plugin-message-edit` for discovery, but retains `message-tree` in routes, cordis IDs, and event types to prevent collisions with prior third-party plugins (such as `dsh-message-edit`) and ensure seamless side-by-side operation.

package/docs/DEVELOPMENT.md

@@ -0,0 +1,75 @@
+# Development & Testing Guide
+
+This guide covers building, testing, packaging, and installing `dsh-plugin-message-edit`.
+
+---
+
+## 1. Repository Structure
+
+```
+dsh-plugin-message-edit/
+├── lib/
+│   ├── index.js          # Host-side Cordis plugin (routes, session log processing)
+│   ├── tree-logic.js     # Pure tree algorithms (shared with client and tests)
+│   └── client.js         # Generated client bundle (wrapped from plugin.client.js)
+├── plugin.client.js      # Source client-side UI and React components
+├── scripts/
+│   └── build-client.mjs  # Build script wrapping plugin.client.js into lib/client.js
+├── test/
+│   └── tree.test.mjs     # Automated test suite (36+ unit tests)
+├── cordis.patch.yml      # Service dependencies and injection metadata
+├── docs/                 # Technical architecture and data model documentation
+└── package.json
+```
+
+---
+
+## 2. Build Pipeline
+
+The client component [`plugin.client.js`](file:///D:/dsh-plugin-message-edit/plugin.client.js) is written in browser-compatible JavaScript. Before distribution or testing, it is wrapped with a Cordis module preamble into [`lib/client.js`](file:///D:/dsh-plugin-message-edit/lib/client.js).
+
+### Build Client
+```bash
+npm run build
+```
+Executes `node scripts/build-client.mjs` to regenerate `lib/client.js`.
+
+### Check Build Integrity
+```bash
+node scripts/build-client.mjs --check
+```
+Exits with code 1 if `lib/client.js` is out of date relative to `plugin.client.js`.
+
+---
+
+## 3. Testing
+
+The project includes an automated test suite verifying tree construction, sibling fan-out, ghost recovery, active path calculation, and ring index calculation.
+
+```bash
+npm test
+```
+Runs the build check and executes `test/tree.test.mjs`.
+
+To add new tests, edit [`test/tree.test.mjs`](file:///D:/dsh-plugin-message-edit/test/tree.test.mjs).
+
+---
+
+## 4. Local Installation into DSH Desktop
+
+### Step 1: Build and Package
+```bash
+npm run build
+npm pack
+```
+This produces a tarball: `dsh-plugin-message-edit-0.1.0.tgz`.
+
+### Step 2: Install into DSH Profile
+To install into the DSH Desktop profile:
+```bash
+dsh plugin --profile desktop add file:/path/to/dsh-plugin-message-edit-0.1.0.tgz
+```
+Or sync files directly into `~/.dsh/profiles/desktop/node_modules/dsh-plugin-message-edit/`.
+
+### Step 3: Restart DSH Desktop
+Restart DSH Desktop to reload the host-side plugin in the server process and mount the updated client interface.

package/docs/TREE_DATA_MODEL.md

@@ -0,0 +1,96 @@
+# Tree Data Model & Algorithms
+
+This document details how conversation versions and turns are represented, branched, and visualized in `dsh-plugin-message-edit`.
+
+---
+
+## 1. Dual-Level Representation
+
+There are two distinct levels of data representation in the system:
+
+1. **Storage Level (Session DAG)**:
+   - DSH enforces session-level isolation. Each branch is a distinct DSH session record with `parentSession` and `seedLength`.
+   - The host maintains durable `message-tree/version` markers detailing which turn was edited/retried and what changed.
+
+2. **Presentation Level (Turn-Level Branching Tree)**:
+   - A user thinks of conversation branching at the **message/turn** level, not the session container level.
+   - `buildTurnTree` projects the session versions into individual turn nodes.
+
+```
+Session DAG (Storage):
+Session A (Original)  ──[edit turn 1]──>  Session B (Fork)
+
+Turn Tree (Visualization):
+               [Root Conversation]
+                 /             \
+        [A: Turn 1 (1/2)]    [B: Turn 1 (2/2) - Edited]
+               |                    |
+        [A: Turn 2]          [B: Turn 2]
+```
+
+---
+
+## 2. Core Algorithms
+
+### 2.1 Turn Tree Construction (`buildTurnTree`)
+*Location: [`lib/tree-logic.js`](file:///D:/dsh-plugin-message-edit/lib/tree-logic.js#L173), [`plugin.client.js`](file:///D:/dsh-plugin-message-edit/plugin.client.js#L415)*
+
+Transforms `versions` into an array of turn nodes:
+1. **Root Conversation Node (`${rootSessionId}#root`)**: Represents the origin anchor of the conversation.
+2. **Root Session Turns**:
+   - Turn 1 hangs off `${rootSessionId}#root`.
+   - Turn $k$ ($k > 1$) hangs off `${rootSessionId}#t${k-1}`.
+3. **Forked Session Turns**:
+   - For a session branched at `targetTurn = T`:
+     - If $T = 1$: Turn 1 hangs off `${rootSessionId}#root` (sibling of the original Turn 1).
+     - If $T > 1$: Turn $T$ hangs off `${parentSessionId}#t${T-1}` (sibling of parent's Turn $T$).
+     - Subsequent turns $T+1, T+2, \dots$ hang off the previous turn in the same session (`${sessionId}#t${k-1}`).
+4. **Safety Fallback**: Any node whose computed `parentId` does not exist in the graph is automatically attached to `${rootSessionId}#root`, preventing disconnected subtrees.
+
+### 2.2 Sibling Fan-Out (`attachParentId`)
+*Location: [`lib/tree-logic.js`](file:///D:/dsh-plugin-message-edit/lib/tree-logic.js#L9)*
+
+When a user edits Turn 1 repeatedly (e.g. Turn 1 $\rightarrow$ Edit 1 $\rightarrow$ Edit 2 while viewing Edit 1):
+- Without fan-out, edits form a chain: $A \rightarrow B \rightarrow C$.
+- `attachParentId` traverses up versions of the same turn and stops at the first session that is *not* an edit of that turn ($A$).
+- Result: Both Edit 1 and Edit 2 hang off $A$ as sibling branches.
+
+### 2.3 Ghost Ancestor Recovery (`ancestorChainFromLog` & `collectFamily`)
+*Location: [`lib/tree-logic.js`](file:///D:/dsh-plugin-message-edit/lib/tree-logic.js#L110-L171)*
+
+If an intermediate session in a family is deleted by the user in DSH:
+- The deleted session's own event log is gone.
+- However, its descendant sessions inherited its prefix log (including the `message-tree/version` marker describing the deleted parent).
+- `ancestorChainFromLog` inspects the surviving descendant's seed events to reconstruct deleted ancestors as **ghost nodes** (`deleted: true`).
+- `collectFamily` ensures the family graph remains fully connected even when intermediate nodes are deleted.
+
+### 2.4 Active Path Calculation
+*Location: [`lib/tree-logic.js`](file:///D:/dsh-plugin-message-edit/lib/tree-logic.js#L318-L339)*
+
+To highlight only the active branch path without highlighting superseded sibling branches:
+1. Locate the latest turn node in `currentSessionId`.
+2. Walk upwards following `parentId` pointers until reaching `${rootSessionId}#root`.
+3. Mark only nodes on this walk with `onCurrentPath = true`.
+
+### 2.5 Bubble Version Ring (`ringFor`)
+*Location: [`lib/tree-logic.js`](file:///D:/dsh-plugin-message-edit/lib/tree-logic.js#L30-L68)*
+
+Calculates the `‹ n/m ›` counter under a message at `turn` while viewing `sessionId`:
+- Walks parent links to find the common fork point for that turn.
+- Filters out deleted/ghost sessions (renumbering over surviving versions).
+- Returns `{ alternatives, index }`. If fewer than 2 alternatives exist, returns `null` (counter is hidden).
+
+---
+
+## 3. Graph Layout & Springs
+
+*Location: [`plugin.client.js`](file:///D:/dsh-plugin-message-edit/plugin.client.js#L567-L612)*
+
+- **Tidy Tree Layout (`layoutTurnTree`)**:
+  - Leaf nodes take successive horizontal slots (`cursor * SLOT_X`, where `SLOT_X = 206px`).
+  - Parent nodes center horizontally over their children (`(min_x + max_x) / 2`).
+  - Depths scale vertically (`depth * SLOT_Y`, where `SLOT_Y = 132px`).
+- **Spring Physics (`springs.current`)**:
+  - Cards smoothly animate to their target coordinates using critically-damped spring equations ($k = 190, c = 24$).
+  - New cards spawn at their parent's coordinates and spring outward.
+  - Edges are rendered as cubic SVG bezier curves connecting parent card bottoms to child card tops.