diffing 0.6.0 → 0.7.0

package/README.md

@@ -1,9 +1,13 @@
 # diffing
 
-A local-first code review tool and double-sided bridge designed for the modern AI coding agent workflow. Review AI-generated changes in a high-fidelity, GitHub-like web UI, leave inline comments, and hand them back to your coding agent to fix in real time — and review the agent's **plan** the same way *before* it writes any code, approving, rejecting, or requesting changes on specific lines and sections.
+<p align="center">
+  <img src="public/favicon.svg" alt="diffing brand icon" width="72" height="72" />
+</p>
 
-<img width="1667" height="1087" alt="image" src="https://github.com/user-attachments/assets/52dcd2af-fc85-44ba-a679-4609e667c6f4" />
+A local-first code review tool and double-sided bridge designed for the modern AI coding agent workflow. Review AI-generated changes in a high-fidelity, GitHub-like web UI, leave inline comments, and hand them back to your coding agent to fix in real time — and review the agent's **plan** the same way *before* it writes any code, approving, rejecting, or requesting changes on specific lines and sections.
 
+<img width="1624" height="1061" alt="image" src="https://github.com/user-attachments/assets/c1e12c28-610e-4d68-abb1-3c8dde58560e" />
+<img width="1624" height="1061" alt="image" src="https://github.com/user-attachments/assets/95a51403-3bce-453c-a831-43a2834c5ed7" />
 
 ---
 
@@ -27,10 +31,11 @@ Prefer the terminal? Add `--tui` for a native-Rust terminal UI — same review f
 diffing --tui
 ```
 > [!WARNING]
-> The TUI is **experimental** in v0.3.0. The interface, keymap, and
-> `server.json` (`mode: "tui"`) on-disk format may change in a minor
-> release. The web UI is the supported path for production workflows.
-> See [Native Terminal UI (TUI)](#native-terminal-ui-tui) for the full feature set, keymap, and stability notes.
+> The TUI is **experimental**. The interface, keymap, and `server.json`
+> (`mode: "tui"`) on-disk format may change in a minor release. The web UI is
+> the supported path for production workflows. See
+> [Native Terminal UI (TUI)](#native-terminal-ui-tui) for the full feature set,
+> keymap, and stability notes.
 
 ### 3. Update
 Check if a new version is available on npm and upgrade instantly via the CLI:
@@ -44,16 +49,18 @@ diffing update
 
 A local Hono-powered review server delivers a full-featured GitHub-like code review interface directly in your browser.
 
-- **Split / Unified View** — Toggle between side-by-side (`split`) and inline (`unified`) diff layouts via toolbar or keyboard shortcut `m`.
+- **Split / Unified View** — Side-by-side (`split`) or inline (`unified`) layouts. Set under **Settings → Diff style**, or press `m` to cycle. Diff style is not a toolbar toggle.
+- **Compact toolbar** — Repo + branch, quiet summary chips (files, `+X/−Y`, open comments), Search (`⌘K`), Plans badge, Resolve all, Settings, and **Send review**.
 - **Syntax Highlighting** — Powered by Shiki via `@pierre/diffs`, with high-fidelity highlighting for 200+ languages.
-- **Interactive File Tree** — Hierarchical file navigation sidebar with collapsible folders, viewed/unviewed tracking, and change-type indicators (added, modified, deleted).
-- **Status Dashboard (Comment Tracker)** — Bottom panel tracking open, replied, and resolved comments with filter tabs and click-to-navigate references to the relevant file and line.
-- **Git Diff Stats** — Toolbar displays repo name, branch, file count, and additions/deletions (`+X/-Y`) computed from the patch.
-- **Server-Side State & Drafts Persistence** — No browser storage is used. All settings, UI panels sizing, session states, and comment drafts are securely stored and persisted server-side in the project's global `.diffing` directory (and global settings inside `~/.config/diffing/settings.json`).
-- **Dynamic Font Customization** — Pick any [Google Fonts](https://fonts.google.com/) family or locally-installed system font for both UI typography and monospace code rendering, configurable via the settings font picker. Google-hosted families are fetched automatically as web fonts and render everywhere; local fonts are applied by name (see the [note on custom fonts](#a-note-on-custom-fonts)).
-- **Resizable Panels** — Drag-to-resize sidebar (240px–640px) and comment tracker panel (100px–600px). Panel states are instantly saved server-side for absolute consistency across browser sessions.
-- **Skeleton Loading Screen** — Full shimmer placeholder UI for toolbar, sidebar, search, tree nodes, and file diffs during initial load.
-- **Image Diff Previews** — Visual side-by-side comparison for added, changed, and deleted image files (PNG, JPEG, GIF, WebP, SVG, BMP, ICO, AVIF).
+- **Interactive File Tree** — Hierarchical navigation with collapsible folders, viewed/unviewed tracking, change-type indicators, smart filter chips (**All / Unviewed / Comments / Since last**), multi-select extension filters, and path search.
+- **Icon file-header actions** — Expand context, open in editor, file-level comment, and Viewed — with tooltips; less chrome noise per card.
+- **Status Dashboard (Comment Tracker)** — Bottom panel tracking open, replied, and resolved comments with severity filters and click-to-navigate.
+- **Multi-round review** — Round history popover, “changed since last send” chips, and outdated-comment detection.
+- **Server-Side State & Drafts Persistence** — No browser storage is used. Settings, panel sizes, session state, and comment drafts live under `~/.diffing/` (global settings in `~/.config/diffing/settings.json`).
+- **Dynamic Font Customization** — Google Fonts or local system fonts for UI + mono (see [custom fonts](#a-note-on-custom-fonts)).
+- **Resizable Panels** — Drag-to-resize sidebar (240px–640px) and comment tracker (100px–600px); sizes persisted server-side.
+- **Skeleton Loading Screen** — Full shimmer placeholder UI during initial load.
+- **Image Diff Previews** — Side-by-side comparison for common image formats.
 
 ---
 
@@ -79,7 +86,8 @@ A local Hono-powered review server delivers a full-featured GitHub-like code rev
 - **Instant Switching** — CSS transitions suppressed during theme changes for a snappy, lag-free experience.
 - **Persistent Setting** — Theme choice saved to `~/.config/diffing/settings.json` and restored on next launch.
 
-<img width="1667" height="1087" alt="image" src="https://github.com/user-attachments/assets/6e4a4552-fef2-4002-8b8f-b544c95c4c26" />
+
+<img width="1624" height="1061" alt="image" src="https://github.com/user-attachments/assets/eaa0675c-21d6-4754-8fbd-97ee63a743dc" />
 
 
 
@@ -99,8 +107,7 @@ Blazing-fast, native fuzzy code search integrated directly into the sidebar sear
 - **Graceful Degradation** — If the native Rust binary is unavailable, search reports as unavailable without crashing the server.
 - **Auto-Indexing** — The Rust engine maintains its own file system watcher for real-time index updates as the working tree changes.
 
-<img width="1840" height="1196" alt="image" src="https://github.com/user-attachments/assets/0830b770-3c7f-44a1-b8ff-a70b2b34144a" />
-
+<img width="1624" height="1061" alt="image" src="https://github.com/user-attachments/assets/2b2bc001-2d3a-4744-b9d5-a23642f1afba" />
 
 ---
 
@@ -115,7 +122,7 @@ Full keyboard-driven navigation with vim-like motions and a modal status bar:
 | `Ctrl+d` / `Ctrl+u` | Scroll half-page down/up |
 | `g` `g` | Jump to top of diff |
 | `G` | Jump to bottom of diff |
-| `m` | Toggle split/unified view |
+| `m` | Toggle split/unified view (also Settings → Diff style) |
 | `t` | Cycle tab size (2 → 4 → 8) |
 | `w` | Toggle line wrap |
 | `n` | Toggle line numbers |
@@ -135,11 +142,21 @@ Full keyboard-driven navigation with vim-like motions and a modal status bar:
 | `g` `t` | Open theme picker |
 | `Cmd/Ctrl+K` | Open global command palette |
 | `Cmd/Ctrl+,` | Toggle settings panel |
-| `?` | Show shortcuts help modal |
+| `?` / `⌘?` | Show shortcuts help modal |
+
+### Plan page extras (when reviewing a plan at `/plan`)
+| Key | Action |
+|-----|--------|
+| `m` | Cycle Source → Read → Split |
+| `z` | Toggle zen reading (switches to Read if needed); Esc also exits zen |
+| `o` | Toggle Outline (left TOC) |
+| `c` | Toggle Comments map (right rail) |
+| `J` / `K` | Next / previous plan |
+| Esc | Exit zen / dismiss Add-comment chip / close draft |
 
 A vim-style status bar at the bottom displays the current mode (NORMAL/INSERT), file path, and a help button. Multi-key sequences use an 800ms key buffer.
 
-<img width="1840" height="1196" alt="image" src="https://github.com/user-attachments/assets/d230d020-4fb2-475a-a8a0-0ae11bb271ff" />
+<img width="1624" height="1061" alt="image" src="https://github.com/user-attachments/assets/f0971704-65a2-4512-978f-6b6e656b5dda" />
 
 
 ---
@@ -147,13 +164,13 @@ A vim-style status bar at the bottom displays the current mode (NORMAL/INSERT),
 ## Native Terminal UI (TUI) — *Experimental*
 
 > [!WARNING]
-> The TUI is **experimental** in v0.3.0. The interface, keymap, and on-disk
-> format of `server.json` (`mode: "tui"`) may change in a minor release
-> before stabilisation. The web UI is the supported path for production
-> workflows; please open an issue before depending on the TUI for CI / agent
-> automation. The web review flow, plan review, and PR review are unaffected.
+> The TUI is **experimental**. The interface, keymap, and on-disk format of
+> `server.json` (`mode: "tui"`) may change in a minor release before
+> stabilisation. The web UI is the supported path for production workflows;
+> please open an issue before depending on the TUI for CI / agent automation.
+> The web review flow, plan review, and PR review are unaffected.
 
-`diffing --tui` opens an **opt-in native-Rust terminal interface** that mirrors the web review dashboard — no browser, no Electron, no port. It's a leaf renderer in a new `crates/diffing-tui/` binary: the Node CLI is still the single source of truth for arg parsing, lockfile discovery, and agent handoff, and the TUI reads the same `~/.diffing/<repo>/*` state on disk and writes a `server.json` with `mode: "tui"`.
+`diffing --tui` opens an **opt-in native-Rust terminal interface** that mirrors the local code-review workflow — no browser or Electron. The renderer and headless tools share one sparse diff index. A random-port loopback API is published through `server.json` with `mode: "tui"` and a per-session capability, so local agents can inspect a large diff without receiving the whole patch.
 
 The default `diffing` behaviour is **byte-identical** with and without `--tui` — the TUI is strictly opt-in. If the env cannot support a TUI (piped stdin, CI, no raw mode) or the binary is missing, you get a one-line stderr note and the normal `git diff` output. The web mode is also unaffected by the TUI build; the same `diffing` install serves either.
 
@@ -169,15 +186,26 @@ diffing --tui -- -- src/            # Limit a TUI review to a directory
 
 **Features**
 
-- **Unified diff render** with a virtualised file card, syntect highlighter, and the same 8 Shiki-compatible colour themes as the web UI.
-- **Vim-style file tree & keymap** — `j/k/gg/G/J/K/Tab/w/t/m/?/` motions, plus `c` (new comment), `e/r/x` (edit / reply / resolve), `]`/`[` (next / previous thread), `?` (help).
+- **Disk-backed streaming index** — Git output is parsed as bytes into sparse file/hunk/checkpoint metadata. The first partial generation is usable during ingestion; neither the TUI nor an agent needs to retain the full patch in memory.
+- **Viewport-only rendering** — only visible rows are sought, decoded, syntax-highlighted, and converted to terminal cells. Unified and split layouts, horizontal scrolling, wrapping, binary markers, untracked files, and live working-tree refresh are supported.
+- **Vim-style file tree & keymap** — numeric counts plus `j/k`, `gg/G`, `Ctrl-d/u`, `J/K`, `]h/[h`, `]c/[c`, `zz`, `h/l`, `/`, `n/N`, `:`, `Tab`, `v`, `w`, `m`, `t`, and `?`. `Esc` cancels a mode; `q` or `Ctrl-C` quits.
 - **Full comment CRUD** — mirrors `src/lib/comments.ts` byte-for-byte; the comment tracker at the bottom lists open / replied / resolved threads with click-to-jump navigation.
 - **Multi-line `tui-textarea` form** with markdown rendering in the preview pane.
 - **Live updates** via `notify` watcher on `comments.json` and the repo working tree — write a comment in another window and it appears immediately.
-- **Send review & agent handoff** — verdict radios + general-comment popover with a live XML preview. Submits via the same `format_comments` envelope as the web UI, copies to clipboard (`pbcopy` / `wl-copy` / `xclip` / `xsel` / `clip.exe`), and persists `pending-review.xml`. The agent-status indicator in the status bar mirrors the web UI's "Send to agent" connection dot.
+- **Send review & agent handoff** — verdict radios + general-comment popover with a live XML preview. `Ctrl-S` persists the review, copies it to the clipboard when available, and immediately wakes every `diffing await-review` waiter. The status bar reports real waiter state.
+- **Headless, token-bounded inspection** — `diffing inspect summary|files|hunks|slice|search` and the equivalent MCP tools page the same index with strict row/byte limits, generation checks, and compact JSON. Every request is loopback-only and requires the session capability.
 - **Cross-platform** — macOS, Linux, and Windows are all first-class. The TUI liveness probe uses `kill(pid, 0)` on Unix and `tasklist /NH /FO CSV` on Windows. Clipboard works on Wayland (`wl-copy`), X11 (`xclip` / `xsel`), macOS (`pbcopy`), and Windows (`clip.exe` / PowerShell `Set-Clipboard`).
 
-**Caveat** — the TUI's "Send to agent" writes the review to disk + clipboard but does not actively unblock a long-polling `diffing await-review`; that requires a Node-side change in a follow-up. The web UI's send button remains the supported native handoff path. The `pending-review.xml` is still produced and the review session is still round-incremented — only the long-poll wake-up is missing.
+The synthetic one-million-line benchmark (50.8 MiB patch) currently reaches a usable partial snapshot in under 1 ms, completes indexing in 47–152 ms, serves viewport reads at 30 µs p95, and peaks at about 54 MiB RSS on the development machine. Run it with `DIFFING_BENCH_LINES=1000000 cargo bench -p diffing-core --bench diff_index`; results vary by machine and filesystem cache.
+
+Headless examples:
+
+```bash
+diffing inspect summary
+diffing inspect files --limit 100
+diffing inspect slice --file 0 --start 0 --max-lines 120 --max-bytes 262144
+diffing inspect search "unsafe" --limit 25
+```
 
 **Building the binary locally**
 
@@ -259,22 +287,34 @@ Bidirectional, event-driven sync between the browser UI and connected AI agents
 The `diffing` binary acts as a port-agnostic CLI client. It automatically discovers the running server by reading a local repository lockfile:
 
 ```bash
-diffing await-review                 # Block process until you click "Send to agent"; outputs comments as XML
-diffing comments [--open] [--json]   # One-shot query of the comments database
-diffing reply <id> --body "..."     # Post an agent response or explanation
-diffing resolve <id>                 # Mark a comment resolved, updating the UI live
-diffing url                          # Retrieve the active server base URL
-
-# Plan review (review a markdown plan before any code is written)
-diffing plan submit <file> [--title T] [--model M] [--id <id>] [--wait]   # Submit/resubmit a plan; prints its id
-diffing plan await [--timeout N]     # Block until the human approves/rejects/requests-changes; outputs the verdict XML
-diffing plan list [--json]           # List submitted plans with their verdicts
-diffing plan show [<id>] [--json] [--version N]   # Show one plan as <plan-review> XML (latest if omitted; use --version to read a historical body)
-diffing plan versions <id> [--json]  # List every submitted version of a plan, oldest-first (current marked with `*`)
-diffing plan reply <commentId> --body "..."   # Reply to an inline plan comment
-diffing plan resolve <commentId>     # Mark a plan comment resolved
+# Code-review handoff
+diffing await-review                 # Block until "Send to agent"; print comments as XML
+diffing comments [--open] [--format xml|json|md]
+diffing reply <id> --body "..."      # Post an agent response
+diffing resolve <id>                 # Mark resolved (UI updates live)
+diffing unresolve <id>               # Re-open a resolved thread
+diffing comment edit <id> --body "..."
+diffing comment delete <id>
+diffing progress --message "…" [--pct 40] [--model M]   # Live progress toast
+diffing url                          # Active server base URL
+
+# Plan review (before any code is written)
+diffing plan submit <file> [--title T] [--model M] [--id <id>] [--wait] [--save-source]
+diffing plan await [--timeout N]
+diffing plan list [--json]
+diffing plan show [<id>] [--json] [--version N]
+diffing plan versions <id> [--json]
+diffing plan reply <commentId> --body "..."
+diffing plan resolve <commentId>
+
+# DX
+diffing doctor                       # Environment / install self-check
+diffing completion <bash|zsh|fish>
+diffing inspect summary|files|hunks|slice|search   # Bounded reads from a TUI session
 ```
 
+Full contracts (flags, exit codes, XML, HTTP): **[docs/cli.md](docs/cli.md)**.
+
 ### B. Model Context Protocol (MCP) Server
 If your agent supports MCP, configure `diffing` as a stdio server. The MCP is
 self-describing and can start or reuse the loopback review server, so an
@@ -309,9 +349,13 @@ Run `diffing mcp --help` for setup details. The server initialization
 instructions tell an unfamiliar model what to do next, and every tool returns
 both readable text and structured content.
 
-- Session: `review_session_status`, `start_review_session`
-- Local review: `get_diff`, `create_comment`, `await_review`, `list_comments`, `reply_to_comment`, `resolve_comment`
-- Plan review: `submit_plan`, `await_plan_review`, `list_plans`, `get_plan`, `get_plan_versions`, `get_plan_version`, `reply_to_plan_comment`, `resolve_plan_comment`
+| Area | Tools |
+|------|-------|
+| Session | `review_session_status`, `start_review_session` |
+| Diff inspection | `get_diff`, `diff_summary`, `diff_files`, `diff_hunks`, `diff_slice`, `diff_search` |
+| Comments | `create_comment`, `list_comments`, `reply_to_comment`, `resolve_comment`, `unresolve_comment`, `edit_comment`, `delete_comment`, `edit_reply`, `delete_reply`, `apply_suggestion`, `resolve_all_comments` |
+| Loop | `await_review`, `report_progress`, `get_review_history` |
+| Plan | `submit_plan`, `await_plan_review`, `list_plans`, `get_plan`, `get_plan_versions`, `get_plan_version`, `reply_to_plan_comment`, `resolve_plan_comment` |
 
 Clients that expose MCP prompts can use `review_local_changes` and
 `submit_plan_for_review`; clients that expose resources can read
@@ -336,7 +380,11 @@ still interpret pasted self-describing XML. The installable `skills/` copies and
 repo-local `.agents/skills/` copies are contract-tested to remain identical.
 
 ### Send Review Popover
-A GitHub-style "finish your review" popover with inline editing of each comment, an optional general/overall comment, and a visual indicator when an agent is waiting. The **"Copy comments"** toolbar button serializes all comments to the XML spec and copies them to the clipboard.
+A GitHub-style **Submit review** / **Send to agent** popover: pick a verdict
+(Approve / Request edits / Reject / **Comment only**), optionally add an overall
+note, preview every inline comment (editable/removable), and release every
+waiting agent. Agent waiting state shows as a green dot on the button.
+**Copy comments** serializes the thread set to the agent XML spec.
 
 ### Port-Agnostic Discovery
 A per-repo lockfile (`server.json`) in `~/.diffing/<repo-hash>/` enables all subcommands and MCP tools to discover the server's port with zero configuration. Stale or crashed server locks are automatically detected and treated as dead via `process.kill(pid, 0)`.
@@ -351,39 +399,29 @@ A `ReviewSession` class with a monotonic `round` counter and race-guard logic en
 Review **any agent plan** — not just code. When an AI agent produces a plan
 (an implementation outline, a design proposal, a migration strategy), `diffing`
 renders the markdown line-by-line so you can comment on specific lines or
-sections and **approve**, **request changes**, or **reject** it — then hands the
-structured verdict back to the waiting agent. It's the "agent waits, human
-releases" handoff, applied *before* any code is written.
+sections and **approve**, **request changes**, **reject**, or **comment only**
+— then hands the structured verdict back to the waiting agent. It's the
+"agent waits, human releases" handoff, applied *before* any code is written.
 
 ```text
 1. The agent submits a markdown plan and blocks (diffing plan submit … --wait).
-2. You open the "Plans" tab, read the plan, and comment on lines/sections.
-3. You click Approve / Request changes / Reject (with an optional overall note).
-4. The agent wakes instantly, receives the verdict + comments as <plan-review> XML,
-   and proceeds, revises-and-resubmits, or stops accordingly.
+2. You open Plans (/plan), read Source / Read / Split, and comment on lines/sections.
+3. You Submit review: Approve / Request changes / Reject / Comment only.
+4. The agent wakes, receives <plan-review> XML, and proceeds, revises, or stops.
 ```
 
-- **Renders any markdown plan** — the plan body is shown via `@pierre/diffs` with
-  full syntax highlighting and line numbers, so it's addressable like a diff.
-- **Line, range & section comments** — hover the gutter `+` or select a line range
-  to comment; each comment auto-captures its enclosing markdown heading (section)
-  and the exact anchored text for the agent.
-- **General comments** — attach notes scoped to the whole plan.
-- **Three-way verdict** — Approve / Request changes / Reject, GitHub-style, with
-  an optional overall comment. Resubmitting a revised plan (same id) bumps the
-  version and re-opens it for review.
-- **Browse plan versions** — every submitted body is kept on disk, oldest-first.
-  A version dropdown next to the `v{n}` chip switches the viewer to any past
-  version; comments are filtered to those anchored to the version you're
-  reading; a "viewing v{N} of v{M}" banner makes the historical context obvious.
-  Available from the CLI (`diffing plan versions <id>`, `diffing plan show <id> --version N`),
-  MCP (`get_plan_versions`, `get_plan_version`), and the HTTP API
-  (`GET /api/plans/:id/versions`, `GET /api/plans/:id/versions/:n`).
-- **Live "Plans" badge** — the diff toolbar shows a badge counting plans awaiting
-  your review, with a green dot when an agent is connected and waiting.
-- **Same channels everywhere** — drive it from the CLI (`diffing plan …`), the
-  MCP tools (`submit_plan`, `await_plan_review`, …), or the HTTP API
-  (`POST /api/plans`, `POST /api/plans/:id/decision`, `GET /api/plan-review/await`).
+- **Source / Read / Split** — always-visible view modes in the plan toolbar (`m` cycles). Read uses full main-column width; **Zen** (`z`) immersive full-width focus (Esc exits).
+- **Resizable split** — drag the Source|Read divider; double-click resets 50/50.
+- **Renders any markdown plan** — Source via `@pierre/diffs` (commentable lines); Read as polished markdown with outline (`o`) and comments map (`c`).
+- **Line, range & section comments** — gutter `+` or select lines (Source); highlight text → Add comment in Read (multiple floating drafts, range steppers, minimize tray, Esc). **Read mode always shows submitted threads inline** under the matching section.
+- **Severity** — optional blocking / nit / question / praise on plan comments (same labels as code review; included in `<plan-review>` handoff XML).
+- **Collapsible threads** — collapse open or resolved cards; collapse the in-card source preview; delete resolved comments and replies.
+- **General comments** — notes scoped to the whole plan.
+- **Four-way verdict** — Approve / Request changes / Reject / Comment only (no file edits). Resubmit with the same id bumps version and re-opens review.
+- **Browse plan versions** — version dropdown, historical banner, comments filtered to the viewed version. CLI / MCP / HTTP as below.
+- **Live "Plans" badge** — toolbar badge for plans awaiting review; green dot when an agent is waiting.
+- **Same channels everywhere** — CLI (`diffing plan …`), MCP (`submit_plan`, `await_plan_review`, …), HTTP (`POST /api/plans`, `POST /api/plans/:id/decision`, `GET /api/plan-review/await`).
+- **Scratch outside the tree** — plan sources under `~/.diffing/<repo>/plan-sources/` (`--save-source`); never commit agent plans into the consumer project.
 
 ### Plan Review XML Specification
 
@@ -400,7 +438,7 @@ self-documenting `<plan-review>` envelope:
 ## Phase 1
 …full markdown of the plan being reviewed…]]></plan-body>
     <comments>
-      <comment id="c1" line="4" section="Phase 1" status="open" created-at="2026-05-29T18:52:29.557Z">
+      <comment id="c1" line="4" section="Phase 1" status="open" severity="blocking" created-at="2026-05-29T18:52:29.557Z">
         <context><![CDATA[Do the first thing]]></context>
         <body><![CDATA[Clarify what "the first thing" is.]]></body>
         <replies>
@@ -412,8 +450,6 @@ self-documenting `<plan-review>` envelope:
 </plan-review>
 ```
 
-<img width="1667" height="1087" alt="image" src="https://github.com/user-attachments/assets/00e884b5-4c90-4a9a-9e24-9ae57d80f3f2" />
-
 ---
 
 ## Reviewing a GitHub PR
@@ -494,13 +530,16 @@ coexist without colliding.
 
 Rich, real-time comment threads directly on diff lines:
 
-- **Inline Threads** — Hover and click the `+` button on any addition or deletion line to start a thread. Supports markdown (GFM + line breaks) with syntax-highlighted fenced code blocks.
-- **Multi-Line Comments** — Select a line range to comment on an entire block of code.
-- **File-Level Comments** — Add general comments scoped to the entire file without targeting a specific line.
-- **Comment Drafts** — Draft system (`diffing-draft-*` keys) with 7-day TTL, stored in the global `.diffing` folder so drafts survive page refreshes without any browser storage footprint.
-- **Agent Attribution** — Replies carry `role` (`user`/`agent`) and the agent's `model` name for clear attribution.
-- **Suggestion Application** — Parse `` ```suggestion `` code blocks from comment bodies and apply them to the file in one click via `POST /api/comments/:id/apply-suggestion`.
-- **Full CRUD API** — REST endpoints for creating, reading, updating, and deleting comments and replies.
+- **Inline Threads** — Hover the gutter `+` or select lines to open a composer **on that line/side** (additions and deletions). Markdown (GFM + breaks) with syntax-highlighted fences. Threads are collapsible.
+- **Multi-Line Comments** — Drag a line range; the form anchors under the bottom line, with a clear `L12–L15 · new|old` label and **range steppers**. Reverse selection is normalized; range is **inclusive** on the agent handoff (`line="12-15"`).
+- **Severity** — Optional triage labels (design-system dropdown): blocking / nit / question / praise. Stored and emitted on agent handoff XML; MCP `create_comment` accepts `severity`.
+- **File-Level Comments** — Notes scoped to the entire file.
+- **Comment Drafts** — Server-side drafts with TTL under `~/.diffing/` (no browser storage).
+- **Agent Attribution** — Replies carry `role` (`user`/`agent`) and `model`.
+- **Suggestion Application** — `` ```suggestion `` blocks (including multi-line) via **Apply suggestion** / `POST /api/comments/:id/apply-suggestion`.
+- **Bulk resolve** — Toolbar **Resolve all** → `POST /api/comments/resolve-all`.
+- **Agent progress** — Agents can `diffing progress` / `report_progress` for a live toast while working.
+- **Full CRUD** — Create, edit, delete (including resolved plan threads), reply, unresolve — CLI, MCP, and HTTP.
 
 ---
 
@@ -628,8 +667,10 @@ When review comments are exported or streamed to a waiting agent, they are seria
     You are an AI coding assistant receiving a structured list of code review comments to address.
     For each file, review the inline comments and apply the changes requested.
     - Target lines are specified by the "line" attribute (e.g. line="42" for single lines, line="42-45" for multi-line blocks, or line="file" for file-level notes).
+    - When line="A-B", the range is INCLUSIVE on that side.
     - "side" indicates whether the comment is on "additions" (new code) or "deletions" (old code).
     - "status" indicates whether the comment is "open" or "resolved". Only address "open" comments.
+    - Optional severity="blocking|nit|question|praise": blocking = must fix; nit = optional polish; question = needs an answer; praise = positive (no change required). Omit (or none) = untriaged.
     - The <code> block contains the code context at the reviewed lines.
     - The <body> tag contains the review feedback or request.
     
@@ -646,7 +687,7 @@ When review comments are exported or streamed to a waiting agent, they are seria
 
   <file path="src/utils/parser.ts">
     <!-- [Example A] Multi-Line Selection Addition Comment -->
-    <comment id="c1" line="42-45" side="additions" status="open" created-at="2026-05-24T22:00:00.000Z">
+    <comment id="c1" line="42-45" side="additions" status="open" severity="blocking" created-at="2026-05-24T22:00:00.000Z">
       <code><![CDATA[
 + const parsedToken = tokenize(input);
 + if (parsedToken.type === 'EOF') {
@@ -662,7 +703,7 @@ When review comments are exported or streamed to a waiting agent, they are seria
     </comment>
 
     <!-- [Example B] Whole-File General Comment -->
-    <comment id="c2" line="file" side="additions" status="open" created-at="2026-05-24T22:08:00.000Z">
+    <comment id="c2" line="file" side="additions" status="open" severity="nit" created-at="2026-05-24T22:08:00.000Z">
       <body><![CDATA[This parser module needs additional unit tests to cover negative bounds.]]></body>
     </comment>
   </file>
@@ -688,22 +729,19 @@ For advanced features, internal API endpoints, sequence specifications, and conf
 
 > [!IMPORTANT]
 > Read the [CLI & Protocol Reference Manual](docs/cli.md) for detailed descriptions of:
-> - TTY Auto-Detection and Output Mode resolution.
-> - The port-agnostic discovery lockfile mechanics.
-> - Monotonic sequence `round` synchronization for race-free polling.
-> - Full Web API endpoints schema (`GET /api/review/await`, `POST /api/comments`, etc.).
-> - Custom git config shell aliases.
-
----
+> - TTY auto-detection and output modes (web / terminal / TUI).
+> - Port-agnostic discovery lockfile (`server.json`) and modes (`web` | `tui` | `gh-pr`).
+> - Full agent CLI surface: `await-review`, `comments`, `reply` / `resolve` / `unresolve`, `comment edit|delete`, `progress`, `plan …`, `gh …`, `inspect`, `doctor`, `completion`, `mcp`.
+> - Complete MCP tool table (session, bounded diff, comment lifecycle, progress, plan).
+> - Monotonic `round` handoff, plan-review XML, and comment XML schemas.
+> - Web API endpoints (`/api/review/await`, `/api/comments`, `/api/plans`, `/api/agent/progress`, …).
+> - Agent guidance: root [`Agents.md`](Agents.md) and installable skills under `skills/`.
 
-## Landing Page
+Changelog for the latest release: [`CHANGELOG.md`](CHANGELOG.md) (current package version **0.7.0**).
 
-<img width="1287" height="6579" alt="screencapture-localhost-3000-2026-05-31-20_57_04" src="https://github.com/user-attachments/assets/a163b00e-a85a-428f-b8d5-2a33ff9fa1eb" />
 
 ---
 
-👉🏻 The project was intially forked from **wong2/diffx**
-
 ## License
 
 MIT

package/dist/apply-suggestion-BAuyCYk6.mjs

@@ -0,0 +1,54 @@
+//#region src/lib/apply-suggestion.ts
+/**
+* Extract the first ```suggestion ... ``` fence body from a comment.
+* Returns null when no fence is present.
+*/
+function extractSuggestionBlock(body) {
+	const match = body.match(/```suggestion\r?\n([\s\S]*?)```/);
+	if (!match) return null;
+	return match[1];
+}
+/**
+* Apply a suggestion fence to file content.
+*
+* - Single-line comments replace one line.
+* - Multi-line comments (startLineNumber..lineNumber) replace that span with
+*   the suggestion lines (which may be shorter or longer than the span).
+* - Suggestion content is split on any common newline style.
+*/
+function applySuggestionToContent(input) {
+	if (input.side !== "additions") return {
+		ok: false,
+		error: "Suggestions can only be applied to added or modified lines"
+	};
+	const suggestion = extractSuggestionBlock(input.body);
+	if (suggestion === null) return {
+		ok: false,
+		error: "No suggestion block found in comment body"
+	};
+	const useCrlf = input.content.includes("\r\n");
+	const lines = input.content.split(/\r?\n/);
+	const end = input.lineNumber;
+	const start = input.startLineNumber && input.startLineNumber > 0 && input.startLineNumber < end ? input.startLineNumber : end;
+	if (start < 1 || end < 1) return {
+		ok: false,
+		error: "Comment line number out of range"
+	};
+	if (end > lines.length) return {
+		ok: false,
+		error: "Comment line number out of range"
+	};
+	const startIdx = start - 1;
+	const deleteCount = end - start + 1;
+	let suggestionLines = suggestion.split(/\r?\n/);
+	if (suggestionLines.length > 1 && suggestionLines[suggestionLines.length - 1] === "") suggestionLines = suggestionLines.slice(0, -1);
+	const next = [...lines];
+	next.splice(startIdx, deleteCount, ...suggestionLines);
+	return {
+		ok: true,
+		content: next.join(useCrlf ? "\r\n" : "\n"),
+		replacedLines: deleteCount
+	};
+}
+//#endregion
+export { applySuggestionToContent };