@levistudio/redline 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -4,17 +4,33 @@ All notable changes to Redline are documented here. The format follows [Keep a C
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-05-15
+
 ### Added
-- Node-compatible launcher (`bin/redline.cjs`) so `npx @levistudio/redline <file>` works alongside `bunx`.
-- `ROADMAP.md` and this changelog.
+- **Escalation handoff** ([#86](https://github.com/alevi/redline/pull/86)). When a comment needs something the inline review agent can't provide — an external style guide, a spec it can't see, a decision that needs the wider project — the agent flags its reply with an escalate verdict. The comment shows an "Escalated" badge, the round banner notes the count, and the session's closeout summary and `.review/<file>.result` carry an `escalations` array so the agent that launched the review picks the feedback up.
+
+### Fixed
+- **Revision integrity check and retry** ([#86](https://github.com/alevi/redline/pull/86)). The revision pass now validates its output on every run and rejects a revision that silently drops document sections no comment touched, instead of writing a mangled document to disk. A failed validation retries once before surfacing an error.
+- **Cross-block and image-spanning selections** ([#85](https://github.com/alevi/redline/pull/85)) now anchor correctly. Selecting across a block boundary, or across an image, no longer fails with an anchoring error.
+- **Sessions are no longer abandoned on a transient SSE drop** ([#84](https://github.com/alevi/redline/pull/84)). A backgrounded tab, laptop sleep, or a brief network blip no longer causes the server to exit; only an explicit tab close ends the session. A server that does go away surfaces a clear "session ended" banner instead of a raw fetch error.
+
+## [0.2.0] - 2026-05-11
+
+### Added
+- **Inline diff view** with a header toggle on revised rounds ([#79](https://github.com/alevi/redline/pull/79)). After a revision pass, the document opens with the diff rendered in place — block-level insert/delete bands and word-level marks for modified paragraphs. `Show changes` / `Hide changes` in the header flips between diff and clean view at any time. View choice persists per file in `sessionStorage`.
+- **Markdown rendering in agent thread replies** ([#75](https://github.com/alevi/redline/pull/75)). Agent replies in the sidebar now render `**bold**`, lists, inline `code`, fenced blocks, and links instead of showing raw markdown. Same `marked` + `sanitize-html` pipeline as the document body.
 
 ### Changed
-- Package renamed to scoped `@levistudio/redline` for npm publishing.
-- README rewritten around the AI-doc-review use case.
+- **Doc header decluttered** ([#74](https://github.com/alevi/redline/pull/74)). `Compare with previous` moved out of the header and into the round-badge dropdown (only when there's a prior round to compare against). Filename no longer renders all-caps.
+- **Banner hierarchy fixed** ([#77](https://github.com/alevi/redline/pull/77)). The reviewer's `--context` focus now reads at full document weight with a 3px accent stripe; the first-run safety notice is demoted to a muted inline line with an underlined "Got it" link. Importance now matches behavior: context shapes every reply for the session, the safety notice is once-per-machine.
+
+### Fixed
+- **Selections spanning a heading into a paragraph** ([#78](https://github.com/alevi/redline/pull/78)) are no longer rejected. The browser's `Selection.toString()` emits `\n\n` between blocks; `captureSelection` now normalizes those before searching the document text, and `highlightText` stores the normalized form so the highlight survives re-renders.
+- Block-level deletes in the diff view now render with strikethrough (previously only word-level deletes inside modified paragraphs were struck through) ([#79](https://github.com/alevi/redline/pull/79)).
 
-## [0.1.0] - 2026-05-09
+## [0.1.0] - 2026-05-11
 
-Initial public release.
+Initial public release on npm as `@levistudio/redline`.
 
 ### Added
 - Local review reader (Bun + Hono server, browser UI) for Markdown files.
@@ -25,6 +41,8 @@ Initial public release.
 - Verdict-aware resolve: every agent reply ships with `requires_revision` so the round-level button auto-defaults to **Revise document** or **Accept as-is**.
 - One-shot revision command: `redline resolve <file> [--model <id>]`.
 - `redline-review` skill for outer-agent handoff (Claude Code etc.).
+- Node-compatible launcher (`bin/redline.cjs`) so `npx @levistudio/redline <file>` works alongside `bunx`.
+- `ROADMAP.md` and this changelog.
 - CSRF token on every mutating `/api/*` request.
 - Cross-process file lock around sidecar transactions.
 - `realpath` check on the static-asset route to block symlink escapes.
@@ -33,5 +51,7 @@ Initial public release.
 - Auto-installs missing dependencies on first CLI run.
 - Initial test suite: server, sidecar, parsing, model-picking, rendering, diff, SSE, integration, happy-dom client.
 
-[Unreleased]: https://github.com/alevi/redline/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/alevi/redline/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/alevi/redline/releases/tag/v0.3.0
+[0.2.0]: https://github.com/alevi/redline/releases/tag/v0.2.0
 [0.1.0]: https://github.com/alevi/redline/releases/tag/v0.1.0

package/README.md

@@ -42,7 +42,7 @@ Two long-lived processes:
 
 Review state lives in a sidecar JSON file at `.review/<filename>.json` next to the doc. History snapshots of every revision land in `.review/history/<filename>.<iso>.md` *before* the revision is written, so you can roll back from disk if a revision goes sideways. Both should be gitignored unless you want them in the repo.
 
-After each revision, the browser overlays a side-by-side diff against the previous round so you can read the agent's changes in context. From there you either open another round of comments or click **Looks good** to finish.
+After each revision, the new round opens with the document rendered inline as a diff against the previous round — insert and delete bands at the block level, word-level marks within modified paragraphs — so you can read the agent's changes in place. Use the **Show changes** / **Hide changes** toggle in the header to flip back to the clean view at any time. From there you either open another round of comments or click **Looks good** to finish.
 
 [CLAUDE.md](CLAUDE.md) has the full architecture tour: sidecar schema, SSE event vocabulary, model picking, frontend gotchas.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levistudio/redline",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Inline comments on Markdown files, for human-in-the-loop AI doc review.",
   "keywords": [
     "markdown",

package/src/agent.ts

@@ -89,8 +89,11 @@ const REPLY_SYSTEM_PROMPT_BODY =
   "Good: message: \"Got it.\"  reason: \"Add a third line to the hard line breaks example\"\n" +
   "When requires_revision is false, leave reason empty (or a very short note about why no edit). The reply IS the answer.\n" +
   "\n" +
+  "Separately, decide whether this comment needs the agent that LAUNCHED this review rather than you. That outer agent has the project context, tools, and authority you don't — e.g. an external style guide or canon you can't see, a spec to check the document against, or a decision that depends on the wider project. When the comment asks for something like that, set ESCALATE: true and briefly tell the reviewer in your message that you've routed it to the launching agent. Otherwise ESCALATE: false. Escalating does not change requires_revision — judge that on its own.\n" +
+  "\n" +
   "Output exactly this format and nothing else (no prose before/after, no code fences). Use these literal markers — do not escape quotes inside the message:\n" +
   "REQUIRES_REVISION: <true|false>\n" +
+  "ESCALATE: <true|false>\n" +
   "REASON: <one short sentence describing the edit, or empty>\n" +
   "---MESSAGE---\n" +
   "<your reply text — quotes, punctuation, anything>\n" +
@@ -114,12 +117,13 @@ async function postReply(
   commentId: string,
   message: string,
   requires_revision: boolean,
-  revision_reason: string
+  revision_reason: string,
+  escalate: boolean
 ) {
   await fetch(`${BASE_URL}/api/comment/${commentId}/reply`, {
     method: "POST",
     headers: { "Content-Type": "application/json", ...CSRF_HEADER },
-    body: JSON.stringify({ role: "agent", name: "Claude", message, requires_revision, revision_reason }),
+    body: JSON.stringify({ role: "agent", name: "Claude", message, requires_revision, revision_reason, escalate }),
   });
 }
 
@@ -185,8 +189,8 @@ async function handleComment(commentId: string) {
 
     if (reply.trim()) {
       const parsed = parseReply(reply);
-      console.log(`[agent] verdict for ${commentId}: requires_revision=${parsed.requires_revision}`);
-      await postReply(commentId, parsed.message, parsed.requires_revision, parsed.reason);
+      console.log(`[agent] verdict for ${commentId}: requires_revision=${parsed.requires_revision} escalate=${parsed.escalate}`);
+      await postReply(commentId, parsed.message, parsed.requires_revision, parsed.reason, parsed.escalate);
     }
   } catch (err) {
     await logReplyFailure(commentId, err);

package/src/cli.ts

@@ -4,6 +4,10 @@ import { mkdir, writeFile } from "fs/promises";
 import { spawnSync } from "child_process";
 import { createRequire } from "module";
 import path from "path";
+// reviewSummary only `import type`s from ./sidecar, so it pulls in no
+// third-party deps at runtime — safe to import statically ahead of the
+// preflight. abandon() needs it synchronously (signal context).
+import { collectEscalations, formatReviewSummary } from "./reviewSummary";
 
 // Ensure redline's own dependencies are resolvable before any third-party
 // imports load. `redline` is invoked from arbitrary projects: in a checkout
@@ -137,6 +141,7 @@ if (args[0] === "resolve") {
 
   const resultFile = path.join(path.dirname(resolved), ".review", path.basename(resolved) + ".result");
   const startupFile = path.join(path.dirname(resolved), ".review", path.basename(resolved) + ".startup.json");
+  const sidecarFile = path.join(path.dirname(resolved), ".review", path.basename(resolved) + ".json");
 
   // Clear stale state from a prior run so a polling agent can't be misled
   // by a leftover .result or .startup.json file that predates this process.
@@ -274,19 +279,36 @@ if (args[0] === "resolve") {
     const status = lastRevisionError ? "error" : "abandoned";
     const payload: Record<string, unknown> = { status, file: resolved };
     if (lastRevisionError) payload.reason = lastRevisionError;
+    // Carry escalations through the error/abandon path too — on an incomplete
+    // session they matter more, not less. Read the sidecar synchronously:
+    // abandon runs in signal context where async I/O may not complete.
+    let escalations: import("./reviewSummary").EscalationItem[] = [];
+    try {
+      if (existsSync(sidecarFile)) {
+        const raw = readFileSync(sidecarFile, "utf-8");
+        if (raw.trim()) escalations = collectEscalations(JSON.parse(raw));
+      }
+    } catch { /* best effort — never block shutdown on the summary */ }
+    payload.escalations = escalations;
     // Synchronous write so the result file lands even if the runtime is
     // terminating due to a signal (async I/O may not complete in that case).
     try {
       mkdirSync(path.dirname(resultFile), { recursive: true });
       writeFileSync(resultFile, JSON.stringify(payload, null, 2));
     } catch { /* best effort */ }
-    console.log(`\nREDLINE_RESULT: ${status}${lastRevisionError ? ` reason="${lastRevisionError}"` : ""}`);
+    if (escalations.length) {
+      console.log(
+        `\n⚠ ${escalations.length} comment${escalations.length !== 1 ? "s" : ""} escalated to the launching agent — see ${path.basename(resultFile)}`
+      );
+    }
+    const escSuffix = escalations.length ? ` escalations=${escalations.length}` : "";
+    console.log(`\nREDLINE_RESULT: ${status}${lastRevisionError ? ` reason="${lastRevisionError}"` : ""}${escSuffix}`);
     // Exit 3 = revision error; 2 = abandoned. Both still distinguish from 0 (approved).
     process.exit(lastRevisionError ? 3 : 2);
   };
 
   // Happy-path finish: human clicked Done.
-  app.onFinished(({ totalRounds, totalComments }) => {
+  app.onFinished(async ({ totalRounds, totalComments }) => {
     serverExiting = true;
     killAgent().catch(() => { /* shutdown already in flight */ });
     try { unlinkSync(startupFile); } catch { /* best effort */ }
@@ -296,10 +318,25 @@ if (args[0] === "resolve") {
     console.log(`   ${totalRounds} round${totalRounds !== 1 ? "s" : ""} · ${totalComments} comment${totalComments !== 1 ? "s" : ""} addressed`);
     console.log(`   Revised document: ${resolved}`);
     console.log(`${line}`);
+
+    // Print the full comment threads so the launching agent — which has no
+    // live channel to the inline review agent — sees everything the reviewer
+    // said, including escalated feedback meant for it.
+    let escalations: import("./reviewSummary").EscalationItem[] = [];
+    try {
+      const { loadSidecar } = await import("./sidecar");
+      const sidecar = await loadSidecar(resolved);
+      escalations = collectEscalations(sidecar);
+      console.log(`\n${formatReviewSummary(sidecar)}`);
+    } catch (e) {
+      console.error("[redline] Failed to build review summary:", e);
+    }
+
     // Machine-greppable result line for a calling agent. Keep this stable.
-    console.log(`REDLINE_RESULT: approved file=${resolved} rounds=${totalRounds} comments=${totalComments}`);
+    const escSuffix = escalations.length ? ` escalations=${escalations.length}` : "";
+    console.log(`\nREDLINE_RESULT: approved file=${resolved} rounds=${totalRounds} comments=${totalComments}${escSuffix}`);
     console.log("");
-    writeResult({ status: "approved", file: resolved, rounds: totalRounds, comments: totalComments })
+    writeResult({ status: "approved", file: resolved, rounds: totalRounds, comments: totalComments, escalations })
       .finally(() => process.exit(0));
   });
 

package/src/client/cards.ts

@@ -1,4 +1,4 @@
-import { escapeHtml, latestVerdict, type ClientComment, type ThreadEntry } from "./lib";
+import { escapeHtml, isEscalated, latestVerdict, type ClientComment, type ThreadEntry } from "./lib";
 import { state } from "./state";
 
 export type CardCallbacks = {
@@ -41,6 +41,12 @@ export function buildCommentCard(comment: ClientComment): HTMLDivElement {
       quote.appendChild(vbadge);
     }
   }
+  if (isEscalated(comment)) {
+    const ebadge = document.createElement("span");
+    ebadge.className = "escalate-badge";
+    ebadge.textContent = "↑ Escalated";
+    quote.appendChild(ebadge);
+  }
   quote.appendChild(document.createTextNode('"' + comment.quote + '"'));
   card.appendChild(quote);
 
@@ -166,9 +172,13 @@ function buildThreadEntry(entry: ThreadEntry, isLatestVerdict: boolean): HTMLDiv
     const reason = entry.revision_reason ? escapeHtml(entry.revision_reason) : "edit queued";
     verdictHtml = `<div class="verdict revise"><span class="verdict-icon">\u270E</span><span>${reason}</span></div>`;
   }
+  if (role === "agent" && entry.escalate === true) {
+    verdictHtml += `<div class="verdict escalate"><span class="verdict-icon">\u2191</span><span>Routed to the launching agent</span></div>`;
+  }
+  const messageHtml = entry.messageHtml ?? escapeHtml(entry.message);
   div.innerHTML = `
     <div class="thread-role ${role}">${escapeHtml(label)}</div>
-    <div class="thread-message">${escapeHtml(entry.message)}</div>
+    <div class="thread-message">${messageHtml}</div>
     ${verdictHtml}
   `;
   return div;

package/src/client/diff.ts

@@ -1,37 +1,72 @@
 import { apiFetch } from "./state";
-import { state } from "./state";
 import {
-  applyRoundState,
+  applyDiffSwap,
+  diffStateKey,
+  revertDiffSwap,
+  updateToggleButton,
+} from "./diffToggle";
+import {
+  applyHighlights,
+  renderComments,
   triggerRoundAction,
 } from "./render";
 
-export function showRevisionBanner(): void {
-  if (document.getElementById("revision-banner")) return;
-  const banner = document.createElement("div");
-  banner.id = "revision-banner";
-  banner.className = "revision-banner";
-  banner.innerHTML =
-    '<span class="revision-banner-text">Document revised.</span>' +
-    '<button class="revision-banner-link" id="revision-banner-diff">See what changed \u2192</button>' +
-    '<button class="revision-banner-dismiss" aria-label="Dismiss">\u2715</button>';
-  banner.querySelector("#revision-banner-diff")!.addEventListener("click", () => {
-    banner.remove();
-    showDiffOverlay();
-  });
-  banner.querySelector(".revision-banner-dismiss")!.addEventListener("click", () => banner.remove());
-  const prose = document.getElementById("prose")!;
-  prose.parentNode!.insertBefore(banner, prose);
-}
+let originalProseHtml: string | null = null;
+let diffHtmlCache: string | null = null;
 
-async function showDiffOverlay(): Promise<void> {
+async function fetchDiffHtml(): Promise<string | null> {
+  if (diffHtmlCache !== null) return diffHtmlCache;
   const res = await fetch("/api/diff");
   const data = await res.json();
-  if (!data.ok) return;
-  document.getElementById("diff-panel-body")!.innerHTML = data.html;
+  if (!data.ok) return null;
+  diffHtmlCache = data.html as string;
+  return diffHtmlCache;
+}
+
+function syncToggleButton(on: boolean): void {
+  const btn = document.getElementById("btn-toggle-diff") as HTMLButtonElement | null;
+  if (btn) updateToggleButton(btn, on);
+}
+
+export async function enableDiffMode(): Promise<void> {
+  const prose = document.getElementById("prose");
+  if (!prose) return;
+  const html = await fetchDiffHtml();
+  if (html == null) return;
+  const previous = applyDiffSwap(prose, html);
+  if (previous != null) originalProseHtml = previous;
+  syncToggleButton(true);
+  try { sessionStorage.setItem(diffStateKey(window.__REDLINE__.contextTitle), "1"); } catch {}
+  applyHighlights();
+  renderComments();
+}
+
+export function disableDiffMode(): void {
+  const prose = document.getElementById("prose");
+  if (!prose || originalProseHtml == null) return;
+  if (!revertDiffSwap(prose, originalProseHtml)) return;
+  syncToggleButton(false);
+  try { sessionStorage.removeItem(diffStateKey(window.__REDLINE__.contextTitle)); } catch {}
+  applyHighlights();
+  renderComments();
+}
+
+async function toggleDiff(): Promise<void> {
+  const prose = document.getElementById("prose");
+  if (!prose) return;
+  if (prose.dataset.diffMode === "on") disableDiffMode();
+  else await enableDiffMode();
+}
+
+async function showDiffOverlay(): Promise<void> {
+  const html = await fetchDiffHtml();
+  if (html == null) return;
+  document.getElementById("diff-panel-body")!.innerHTML = html;
   document.getElementById("diff-overlay")!.classList.add("open");
 }
 
 export function initDiffHandlers(): void {
+  document.getElementById("btn-toggle-diff")?.addEventListener("click", () => { void toggleDiff(); });
   document.getElementById("btn-compare")?.addEventListener("click", () => showDiffOverlay());
 
   document.getElementById("diff-btn-accept")!.addEventListener("click", async () => {
@@ -40,7 +75,7 @@ export function initDiffHandlers(): void {
     const btnAccept = document.getElementById("btn-accept") as HTMLButtonElement | null;
     if (btnAccept) {
       btnAccept.disabled = true;
-      btnAccept.textContent = "\u2713 Done";
+      btnAccept.textContent = "✓ Done";
     }
     const banner = document.getElementById("sidebar-status-banner");
     if (banner) {

package/src/client/diffToggle.ts

@@ -0,0 +1,32 @@
+// Pure helpers for the inline-diff toggle. Kept in their own module so they
+// can be unit-tested without pulling in render.ts (which expects a populated
+// window.__REDLINE__ at module-load time).
+
+export function diffStateKey(contextTitle: string): string {
+  return "rl-diff-on-" + contextTitle;
+}
+
+export function updateToggleButton(btn: HTMLButtonElement, on: boolean): void {
+  btn.classList.toggle("active", on);
+  btn.setAttribute("aria-pressed", on ? "true" : "false");
+  btn.textContent = on ? "Hide changes" : "Show changes";
+}
+
+// Swap prose contents into diff view. Returns the previous innerHTML so the
+// caller can restore it later, or null if the prose is already in diff mode
+// (we don't want to clobber the saved-original by overwriting it with the
+// diff HTML we just installed).
+export function applyDiffSwap(prose: HTMLElement, diffHtml: string): string | null {
+  if (prose.dataset.diffMode === "on") return null;
+  const previous = prose.innerHTML;
+  prose.innerHTML = diffHtml;
+  prose.dataset.diffMode = "on";
+  return previous;
+}
+
+export function revertDiffSwap(prose: HTMLElement, originalHtml: string): boolean {
+  if (prose.dataset.diffMode !== "on") return false;
+  prose.innerHTML = originalHtml;
+  prose.dataset.diffMode = "off";
+  return true;
+}

package/src/client/lib.ts

@@ -16,8 +16,13 @@ export type ThreadEntry = {
   role?: "human" | "agent";
   name?: string;
   message: string;
+  // Server-rendered sanitized HTML for `message`. Present on entries
+  // delivered through the API/bootstrap; absent on entries the client
+  // builds locally before the next refresh. Falls back to escaped text.
+  messageHtml?: string;
   requires_revision?: boolean;
   revision_reason?: string;
+  escalate?: boolean;
 };
 
 export function escapeHtml(s: string): string {
@@ -40,6 +45,11 @@ export function latestVerdict(comment: ClientComment): "revise" | "accept" | nul
   return null;
 }
 
+// True when an agent reply flagged this comment for the launching agent.
+export function isEscalated(comment: ClientComment): boolean {
+  return (comment.thread || []).some((e) => e.role === "agent" && e.escalate === true);
+}
+
 export function nearestCell(node: Node): HTMLElement | null {
   const el = node.nodeType === Node.TEXT_NODE ? node.parentNode : node;
   return el && (el as Element).closest ? ((el as Element).closest("td, th") as HTMLElement | null) : null;
@@ -82,57 +92,138 @@ export type Captured = {
   context_after: string;
 };
 
-// Walk the prose container's text nodes, locate the selection's start, and
-// return the quote with surrounding context. Returns null when the selection
-// can't be relocated against flat text (e.g. crossed an <img>).
-export function captureSelection(prose: Element, sel: Selection, text: string): Captured | null {
-  const range = sel.getRangeAt(0);
+type FlatSegment = {
+  node: Text | HTMLImageElement;
+  start: number;
+  len: number;
+  isImg: boolean;
+};
 
-  const walker = (prose.ownerDocument || document).createTreeWalker(prose, NodeFilter.SHOW_TEXT);
-  const segments: { node: Text; start: number }[] = [];
+// An <img> contributes no characters of its own, so on its own it can't be
+// anchored against. We give it a presence in the flat text as an
+// `[image: alt]` token — the same shape the image-only comment path uses — so
+// a selection can run text → image → text and still round-trip.
+function imgToken(img: HTMLImageElement): string {
+  return "[image: " + (img.alt || "") + "]";
+}
+
+// Walk a container into a flat string plus the segments that produced it.
+// Text nodes contribute their value; <img> elements contribute an
+// `[image: alt]` token. Segments are in document order. captureSelection and
+// highlightText both build flat through here so their coordinates agree.
+function buildFlat(container: Element): { flat: string; segments: FlatSegment[] } {
+  const doc = container.ownerDocument || document;
+  const walker = doc.createTreeWalker(container, NodeFilter.SHOW_TEXT | NodeFilter.SHOW_ELEMENT, {
+    acceptNode(n: Node) {
+      if (n.nodeType === Node.TEXT_NODE) return NodeFilter.FILTER_ACCEPT;
+      return (n as Element).tagName === "IMG" ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP;
+    },
+  });
+  const segments: FlatSegment[] = [];
   let flat = "";
   let node: Node | null;
   while ((node = walker.nextNode())) {
-    const tn = node as Text;
-    segments.push({ node: tn, start: flat.length });
-    flat += tn.nodeValue ?? "";
+    if (node.nodeType === Node.TEXT_NODE) {
+      const v = (node as Text).nodeValue ?? "";
+      segments.push({ node: node as Text, start: flat.length, len: v.length, isImg: false });
+      flat += v;
+    } else {
+      const img = node as HTMLImageElement;
+      const tok = imgToken(img);
+      segments.push({ node: img, start: flat.length, len: tok.length, isImg: true });
+      flat += tok;
+    }
   }
+  return { flat, segments };
+}
 
-  let quoteStart = -1;
-  for (const seg of segments) {
-    if (seg.node === range.startContainer) {
-      quoteStart = seg.start + range.startOffset;
-      break;
+// Map both range endpoints onto the flat text and return the quote with
+// surrounding context. Returns null only when the selection can't be resolved
+// against the flat text at all.
+//
+// The quote is sliced straight out of `flat` rather than reconstructed from
+// `sel.toString()`. sel.toString() joins blocks with "\n"/"\n\n" separators
+// that don't exist in the walker's output, and marked emits stray whitespace
+// text nodes between block tags — so the two never line up across a block
+// boundary. Working in flat coordinates sidesteps the mismatch: `flat` is the
+// single source of truth, and highlightText re-finds the quote against the
+// same flat string later. `text` is kept only as a last-resort fallback for
+// the rare case where an endpoint can't be resolved.
+export function captureSelection(prose: Element, sel: Selection, text: string): Captured | null {
+  const range = sel.getRangeAt(0);
+  const { flat, segments } = buildFlat(prose);
+  if (segments.length === 0) return null;
+
+  // Map a range boundary point onto an index into `flat`. Text-node boundaries
+  // are the common case; Chrome sometimes anchors a drag to an element node
+  // plus a child index, which we resolve to the nearest segment edge.
+  const pointToFlat = (container: Node, offset: number, side: "start" | "end"): number => {
+    for (const seg of segments) {
+      if (seg.node === container) {
+        if (seg.isImg) return offset > 0 ? seg.start + seg.len : seg.start;
+        return seg.start + offset;
+      }
     }
-  }
+    if (container.nodeType === Node.TEXT_NODE) return -1;
+    const kids = container.childNodes;
+    const segEnd = (seg: FlatSegment) => seg.start + seg.len;
+    if (side === "start") {
+      const ref = offset < kids.length ? kids[offset]! : null;
+      if (ref) {
+        for (const seg of segments) {
+          if (ref === seg.node || ref.contains(seg.node)) return seg.start;
+          if (ref.compareDocumentPosition(seg.node) & Node.DOCUMENT_POSITION_FOLLOWING)
+            return seg.start;
+        }
+        return flat.length;
+      }
+      let end = -1;
+      for (const seg of segments) if (container.contains(seg.node)) end = segEnd(seg);
+      return end === -1 ? flat.length : end;
+    }
+    const ref = offset > 0 ? kids[offset - 1]! : null;
+    if (ref) {
+      let end = -1;
+      for (const seg of segments) {
+        if (
+          ref === seg.node ||
+          ref.contains(seg.node) ||
+          ref.compareDocumentPosition(seg.node) & Node.DOCUMENT_POSITION_PRECEDING
+        ) {
+          end = segEnd(seg);
+        }
+      }
+      return end === -1 ? 0 : end;
+    }
+    for (const seg of segments) if (container.contains(seg.node)) return seg.start;
+    return 0;
+  };
 
-  if (quoteStart === -1) {
-    return { quote: text, context_before: "", context_after: "" };
+  let flatStart = pointToFlat(range.startContainer, range.startOffset, "start");
+  let flatEnd = pointToFlat(range.endContainer, range.endOffset, "end");
+  if (flatStart === -1 || flatEnd === -1 || flatEnd <= flatStart) {
+    return text ? { quote: text, context_before: "", context_after: "" } : null;
   }
 
-  const slice = flat.slice(quoteStart, quoteStart + text.length);
-  if (slice !== text) {
-    // Trimming in the caller, or block-boundary newlines that sel.toString()
-    // inserts but our flat-text walker doesn't, can shift the true start a
-    // few chars away from range.startOffset. Search a small window around
-    // quoteStart for the text before giving up.
-    const windowStart = Math.max(0, quoteStart - 64);
-    const windowEnd = Math.min(flat.length, quoteStart + text.length + 64);
-    const found = flat.indexOf(text, windowStart);
-    if (found === -1 || found >= windowEnd) return null;
-    quoteStart = found;
-  }
+  // Trim whitespace overshoot: a drag that ends a hair past a block — or
+  // starts in the gap before one — shouldn't fail or carry stray newlines.
+  // This is the "clamp": a small overshoot anchors to what the user meant.
+  while (flatStart < flatEnd && /\s/.test(flat[flatStart]!)) flatStart++;
+  while (flatEnd > flatStart && /\s/.test(flat[flatEnd - 1]!)) flatEnd--;
+  if (flatEnd <= flatStart) return null;
 
   return {
-    quote: text,
-    context_before: flat.slice(Math.max(0, quoteStart - 32), quoteStart),
-    context_after: flat.slice(quoteStart + text.length, quoteStart + text.length + 32),
+    quote: flat.slice(flatStart, flatEnd),
+    context_before: flat.slice(Math.max(0, flatStart - 32), flatStart),
+    context_after: flat.slice(flatEnd, flatEnd + 32),
   };
 }
 
 // Wrap occurrences of `text` inside `container` with <mark> elements. Uses
-// `contextBefore` to disambiguate when a quote appears multiple times.
-// Image quotes (`[image: alt]`) wrap the matching <img> instead.
+// `contextBefore` to disambiguate when a quote appears multiple times. The
+// quote is matched against the same flat text captureSelection produced, so
+// `[image: alt]` tokens in the quote wrap the corresponding <img> — whether
+// the quote is image-only or text mixed with an image.
 // Returns the marks created (caller can attach event listeners).
 export function highlightText(
   container: Element,
@@ -144,35 +235,9 @@ export function highlightText(
   const doc = container.ownerDocument || document;
   const marks: HTMLElement[] = [];
 
-  const imgMatch = text.match(/^\[image:\s*(.*)\]$/);
-  if (imgMatch) {
-    const alt = imgMatch[1];
-    const imgs = container.querySelectorAll("img");
-    for (const img of imgs) {
-      if ((img.alt || "") === alt) {
-        const mark = doc.createElement("mark");
-        mark.className = "rl-highlight rl-img" + (resolved ? " resolved" : "");
-        mark.dataset.commentId = id;
-        img.parentNode!.insertBefore(mark, img);
-        mark.appendChild(img);
-        marks.push(mark);
-        return marks;
-      }
-    }
-    return marks;
-  }
-
   (container as HTMLElement).normalize();
 
-  const walker = doc.createTreeWalker(container, NodeFilter.SHOW_TEXT);
-  const segments: { node: Text; start: number }[] = [];
-  let flat = "";
-  let node: Node | null;
-  while ((node = walker.nextNode())) {
-    const tn = node as Text;
-    segments.push({ node: tn, start: flat.length });
-    flat += tn.nodeValue ?? "";
-  }
+  const { flat, segments } = buildFlat(container);
 
   let quoteStart = -1;
   if (contextBefore) {
@@ -184,18 +249,28 @@ export function highlightText(
 
   const quoteEnd = quoteStart + text.length;
 
-  const toWrap: { node: Text; localStart: number; localEnd: number }[] = [];
   for (const seg of segments) {
-    const segEnd = seg.start + (seg.node.nodeValue?.length ?? 0);
-    if (segEnd <= quoteStart || seg.start >= quoteEnd) continue;
-    toWrap.push({
-      node: seg.node,
-      localStart: Math.max(0, quoteStart - seg.start),
-      localEnd: Math.min(seg.node.nodeValue?.length ?? 0, quoteEnd - seg.start),
-    });
-  }
+    const segStart = seg.start;
+    const segEnd = seg.start + seg.len;
+    if (segEnd <= quoteStart || segStart >= quoteEnd) continue;
+
+    if (seg.isImg) {
+      // Image tokens are atomic — wrap the <img> only when the quote covers
+      // the whole token, never on a partial overlap.
+      if (segStart < quoteStart || segEnd > quoteEnd) continue;
+      const img = seg.node as HTMLImageElement;
+      const mark = doc.createElement("mark");
+      mark.className = "rl-highlight rl-img" + (resolved ? " resolved" : "");
+      mark.dataset.commentId = id;
+      img.parentNode!.insertBefore(mark, img);
+      mark.appendChild(img);
+      marks.push(mark);
+      continue;
+    }
 
-  for (const { node: tn, localStart, localEnd } of toWrap) {
+    const tn = seg.node as Text;
+    const localStart = Math.max(0, quoteStart - segStart);
+    const localEnd = Math.min(seg.len, quoteEnd - segStart);
     const mark = doc.createElement("mark");
     mark.className = "rl-highlight" + (resolved ? " resolved" : "");
     mark.dataset.commentId = id;