dsh-plugin-message-edit 1.0.0 → 1.1.0

package/docs/DEVELOPMENT.md

@@ -1,75 +1,147 @@
-# Development & Testing Guide
+# 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
+```
+Automatically builds the client first, checks that it matches the source, then
+runs the Node test runner. Install development dependencies with `npm ci` on a
+fresh checkout before running tests (Node 22.19+ or Node 24).
+
+- `test/tree.test.mjs`: 36 assertions covering branch and version-tree behavior.
+- `test/client-images.test.mjs`: loads the generated client through its module
+  loader, mounts its registered user-message component using React and jsdom,
+  and checks image delegation, multiple/image-only messages, old-host fallback,
+  text-only messages, and entering/cancelling an edit. Host services and the image
+  gallery are test doubles; these are not full DSH integration tests.
+- `test/client-registration.test.mjs`: checks module dependencies and visible
+  failures when services or registrations are unavailable.
+- `test/session-record.test.mjs` and `test/host-compatibility.test.mjs`: cover
+  legacy/current session shapes, live/resumed edit requests, retained images,
+  retry ancestry, nested version markers, and cache invalidation.
+
+GitHub Actions runs these checks for pull requests and branch pushes, on
+Linux (Node 22 and 24) and Windows (Node 22). It also runs:
+
+```bash
+npm run check:package
+```
+
+This creates a real npm archive in a temporary directory, verifies that runtime
+entry points are present and development-only directories are absent, checks
+the host entry's syntax, and removes the temporary archive. `npm pack` and
+`npm publish` now build the client automatically through `prepack`, preventing
+an old or missing generated client from being shipped.
+
+The workflow needs to be pushed to GitHub to run there. Making its checks
+mandatory before merging is a separate repository ruleset/branch-protection
+setting; adding the workflow alone does not block the Merge button.
+
+Before accepting an image-rendering change, also check it in a running DSH:
+send text with one/multiple images and an image-only message, open an image in
+the native viewer, enter/cancel an edit, then verify the original attachments
+survive an edit submission. CI's gallery double cannot verify native image
+loading, lightbox behavior, or compatibility with DSH's module injection.
+
+To add new tests, edit [`test/tree.test.mjs`](file:///D:/dsh-plugin-message-edit/test/tree.test.mjs).
+
+### Optional real DSH acceptance
+
+`test/fixtures/dsh-acceptance.mjs` is an offline model adapter and live/cold
+session fixture for an installed official DSH `0.1.5-rc.2` runtime. Mount it
+only in a new temporary home whose name contains `message-edit-dsh-qa-`.
+Set `DSH_HOME` to that home and `DSH_QA_MODULES` to the official runtime's
+`node_modules` directory. Use a separate Web profile with the base/Web bundles,
+a built copy of this plugin, and a loader entry for the fixture. Never point
+this fixture at an existing user's DSH home.
+
+Once the isolated server prints its URL, run:
+
+```bash
+node scripts/verify-dsh-acceptance.mjs http://127.0.0.1:61587
+```
+
+The verifier exercises real HTTP edit/retry operations, local model execution,
+image retention, unchanged source messages, and nested branch markers. Restart
+the same isolated server and repeat to exercise persisted branches. The fixture
+adds `/qa/state` and `/qa/followup` endpoints solely for this disposable test.
+Browser acceptance additionally checks the settings entry, version switcher,
+thumbnails, and native original-image viewer. No remote API key is needed.
+
+For an automated fresh-boot and restart run, set `DSH_QA_MODULES` to the
+official runtime's `node_modules` directory and run:
 
-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
+node scripts/run-dsh-acceptance.mjs
 ```
-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.
+The runner owns and removes a unique temporary home, boots the official CLI
+on an OS-selected port, runs the verifier, restarts the host, and repeats.
+The restart pass explicitly resumes and retries an already seeded branch.
+CI runs this on Linux and Windows in addition to the regression suite.
+
+---
+
+## 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

@@ -1,96 +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.
+# 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`, `isSeeded`, and a separate `inheritedEventCount`.
+   - 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.