@crouton-kit/humanloop 0.4.4 → 0.4.6

package/dist/editor/parked.d.ts

@@ -0,0 +1,16 @@
+import type { FeedbackResult } from '../types.js';
+export type ParkedReviewAction = {
+    type: 'submitted';
+    result: FeedbackResult;
+} | {
+    type: 'take-back';
+} | {
+    type: 'cancel';
+};
+/**
+ * Park the terminal while the browser owns the review. Watches raw stdin for
+ * `w` (take back) and Ctrl+C (cancel), racing those against the browser's
+ * submit promise. `takeBackTarget` names the surface `w` returns to in the
+ * parked notice (e.g. "nvim", "the terminal review").
+ */
+export declare function waitForParkedReviewSubmit(submitted: Promise<FeedbackResult>, signal: AbortSignal | undefined, takeBackTarget: string): Promise<ParkedReviewAction>;

package/dist/editor/parked.js

@@ -0,0 +1,50 @@
+/**
+ * Park the terminal while the browser owns the review. Watches raw stdin for
+ * `w` (take back) and Ctrl+C (cancel), racing those against the browser's
+ * submit promise. `takeBackTarget` names the surface `w` returns to in the
+ * parked notice (e.g. "nvim", "the terminal review").
+ */
+export async function waitForParkedReviewSubmit(submitted, signal, takeBackTarget) {
+    process.stderr.write('\nhumanloop: browser review handoff is active.\n' +
+        '  The terminal surface is parked; the browser is the editing authority.\n' +
+        `  Press w to take back into ${takeBackTarget}, or Ctrl+C to exit with an unsubmitted draft.\n\n`);
+    return new Promise((resolveAction) => {
+        const stdin = process.stdin;
+        const interactive = stdin.isTTY;
+        const wasRaw = stdin.isRaw;
+        let settled = false;
+        const cleanup = () => {
+            signal?.removeEventListener('abort', onAbort);
+            if (!interactive)
+                return;
+            stdin.off('data', onData);
+            if (stdin.setRawMode)
+                stdin.setRawMode(wasRaw);
+            stdin.pause();
+        };
+        const finish = (action) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolveAction(action);
+        };
+        const onAbort = () => finish({ type: 'cancel' });
+        const onData = (chunk) => {
+            const text = chunk.toString('utf8');
+            if (text === 'w' || text === 'W')
+                finish({ type: 'take-back' });
+            if (text === '\u0003')
+                finish({ type: 'cancel' });
+        };
+        if (interactive) {
+            stdin.setRawMode(true);
+            stdin.resume();
+            stdin.on('data', onData);
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+        if (signal?.aborted)
+            onAbort();
+        submitted.then((result) => finish({ type: 'submitted', result }), () => finish({ type: 'cancel' }));
+    });
+}

package/dist/editor/review.d.ts

@@ -12,7 +12,8 @@ export interface ReviewOptions {
     onClose?: () => Promise<void> | void;
     /** Controller cancellation closes the editor/browser handoff without proposing a result. */
     signal?: AbortSignal;
-    /** Reuse this controller-owned directory for `review.vim`; an existing script is left untouched. */
+    /** Reuse this controller-owned directory for review artifacts (`review.vim`,
+     *  the browser-handoff job id); an existing script is left untouched. */
     jobDir?: string;
 }
 export declare function reviewVimscript(): string;

package/dist/editor/review.js

@@ -6,6 +6,7 @@ import { openBrowser } from '../browser/open.js';
 import { startReviewWebServer } from '../browser/server.js';
 import { buildFinalFeedbackResult, readReviewDraft, } from './feedback.js';
 import { launchTerminalReview } from './terminal-review.js';
+import { waitForParkedReviewSubmit } from './parked.js';
 function resolveEditor(override) {
     const candidates = override ? [override] : ['nvim', 'vim'];
     for (const bin of candidates) {
@@ -551,50 +552,6 @@ function draftFeedback(path, absFile) {
         savedAt: draft?.savedAt ?? new Date().toISOString(),
     };
 }
-async function waitForParkedReviewSubmit(submitted, signal) {
-    process.stderr.write('\nhumanloop: browser review handoff is active.\n' +
-        '  The terminal editor is parked; the browser is the editing authority.\n' +
-        '  Press w to take back into nvim, or Ctrl+C to exit with an unsubmitted draft.\n\n');
-    return new Promise((resolveAction) => {
-        const stdin = process.stdin;
-        const interactive = stdin.isTTY;
-        const wasRaw = stdin.isRaw;
-        let settled = false;
-        const cleanup = () => {
-            signal?.removeEventListener('abort', onAbort);
-            if (!interactive)
-                return;
-            stdin.off('data', onData);
-            if (stdin.setRawMode)
-                stdin.setRawMode(wasRaw);
-            stdin.pause();
-        };
-        const finish = (action) => {
-            if (settled)
-                return;
-            settled = true;
-            cleanup();
-            resolveAction(action);
-        };
-        const onAbort = () => finish({ type: 'cancel' });
-        const onData = (chunk) => {
-            const text = chunk.toString('utf8');
-            if (text === 'w' || text === 'W')
-                finish({ type: 'take-back' });
-            if (text === '\u0003')
-                finish({ type: 'cancel' });
-        };
-        if (interactive) {
-            stdin.setRawMode(true);
-            stdin.resume();
-            stdin.on('data', onData);
-        }
-        signal?.addEventListener('abort', onAbort, { once: true });
-        if (signal?.aborted)
-            onAbort();
-        submitted.then((result) => finish({ type: 'submitted', result }), () => finish({ type: 'cancel' }));
-    });
-}
 async function stopReviewServer(handle) {
     if (handle !== null)
         await handle.stop();
@@ -690,12 +647,16 @@ async function launchNeovimReview(file, opts) {
                 server.activate();
                 process.stderr.write(`humanloop: browser review handoff active — ${server.url}\n`);
                 openBrowser(server.url);
-                const action = await waitForParkedReviewSubmit(submitted, opts.signal);
+                const action = await waitForParkedReviewSubmit(submitted, opts.signal, 'nvim');
                 if (action.type === 'submitted') {
                     await stopReviewServer(server);
                     clearFlag(handoffFlagPath);
-                    if (!opts.signal?.aborted)
-                        await opts.onPropose?.(action.result);
+                    // An abort landing during the async stop must not produce a submitted
+                    // result whose canonical onPropose convergence was skipped — fall
+                    // back to the disk draft (the browser submit already persisted it).
+                    if (opts.signal?.aborted)
+                        return draftFeedback(outPath, absFile);
+                    await opts.onPropose?.(action.result);
                     return action.result;
                 }
                 if (action.type === 'take-back') {
@@ -711,9 +672,12 @@ async function launchNeovimReview(file, opts) {
             }
             await stopReviewServer(server);
             if (existsSync(submitFlagPath)) {
+                // Same abort-during-stop race as the parked branch above: an aborted
+                // review must resolve as a draft, never as an unconverged proposal.
+                if (opts.signal?.aborted)
+                    return draftFeedback(outPath, absFile);
                 const proposal = proposedFeedback(outPath, absFile);
-                if (!opts.signal?.aborted)
-                    await opts.onPropose?.(proposal);
+                await opts.onPropose?.(proposal);
                 return proposal;
             }
             return draftFeedback(outPath, absFile);

package/dist/editor/terminal-review.d.ts

@@ -1,11 +1,29 @@
 import type { FeedbackComment, FeedbackResult } from '../types.js';
 import type { ReviewOptions } from './review.js';
 import { type RenderedDoc } from '../render/termrender.js';
-/** 1-indexed inclusive source-line bounds of one top-level rendered block. */
-export interface BlockRange {
+/** One leaf anchor unit: the finest step j/k moves by. Consecutive rendered
+ *  rows sharing one source span collapse into a single unit that knows both
+ *  its source-line bounds and its rendered-row bounds. */
+export interface AnchorUnit {
+    /** 1-indexed inclusive source-line bounds. */
     start: number;
     end: number;
+    /** 0-indexed inclusive rendered-row bounds in the mapped doc. */
+    firstRow: number;
+    lastRow: number;
 }
+/** The anchorable shape of a rendered doc: ordered leaf units plus the
+ *  per-row owning-unit index the painter keys off. */
+export interface AnchorDoc {
+    units: AnchorUnit[];
+    /** Per rendered row: index into `units`, or null (separator rows). */
+    rowUnits: (number | null)[];
+}
+/** Derive leaf anchor units from a mapped render: dedupe runs of consecutive
+ *  rows carrying the identical source span. A mapped row without a leaf span
+ *  (an unmapped block) anchors at its whole block's range, so every content
+ *  row belongs to a unit; separator rows belong to none. */
+export declare function deriveAnchorUnits(doc: RenderedDoc): AnchorDoc;
 export interface ComposeState {
     buffer: string;
     cursor: number;
@@ -20,13 +38,15 @@ export interface ComposeState {
 }
 export interface ReviewState {
     sourceLines: string[];
-    /** Top-level block source ranges, in document order. Never empty. */
-    blocks: BlockRange[];
+    /** Ordered leaf anchor units. Never empty. */
+    units: AnchorUnit[];
+    /** Per rendered row: owning unit index, or null for separator rows. */
+    rowUnits: (number | null)[];
     comments: FeedbackComment[];
     version: number;
-    /** 0-based index of the anchored block. */
-    activeBlock: number;
-    /** Set while a Shift+j/k range is being extended from this block. */
+    /** 0-based index of the anchored unit. */
+    activeUnit: number;
+    /** Set while a Shift+j/k range is being extended from this unit. */
     selectionAnchor: number | null;
     /** Scroll offset into the rendered (termrender) lines. */
     scroll: number;
@@ -34,25 +54,41 @@ export interface ReviewState {
     compose: ComposeState | null;
     listIndex: number;
 }
-/** Index of the block containing `line`; snaps forward across gaps (blank
- *  separator lines between blocks) and clamps to the last block. */
-export declare function blockIndexForLine(blocks: BlockRange[], line: number): number;
-export declare function initReviewState(sourceLines: string[], blocks: BlockRange[], comments: FeedbackComment[], version: number): ReviewState;
-/** Source-line anchor of the current block selection — what a committed
- *  comment records as `line`/`endLine`. */
+/** Best unit for a source line: the NARROWEST unit containing it — code/table
+ *  chrome units carry their whole block's range and sit before the per-line
+ *  content units in rendered order, so "first whose end reaches the line"
+ *  would wrongly pick the chrome over the exact code line. A line no unit
+ *  contains (a blank separator) snaps forward to the next unit; past the end
+ *  clamps to the last. */
+export declare function unitIndexForLine(units: AnchorUnit[], line: number): number;
+/** Remap a unit from an old unit list into a re-derived one: an exact
+ *  source-range match wins (chrome and leaf units can share source lines),
+ *  else the best unit for its first line. */
+export declare function remapUnitIndex(units: AnchorUnit[], prev: AnchorUnit): number;
+/** First/last unit indices overlapping the source range `line..endLine`;
+ *  a range touching no unit snaps like unitIndexForLine. */
+export declare function unitRangeForSpan(units: AnchorUnit[], line: number, endLine: number): {
+    lo: number;
+    hi: number;
+};
+export declare function initReviewState(sourceLines: string[], anchor: AnchorDoc, comments: FeedbackComment[], version: number): ReviewState;
+/** Source-line anchor of the current unit selection — what a committed
+ *  comment records as `line`/`endLine`. Whole-block chrome units can carry a
+ *  wider range than their neighbors, so take the min/max over the selection
+ *  rather than trusting the endpoints alone. */
 export declare function currentAnchor(state: ReviewState): {
     line: number;
     endLine: number;
 };
-export declare function moveActiveBlock(state: ReviewState, delta: number, extend: boolean): ReviewState;
-/** Block indices overlapped by any existing comment's source range. A stale
- *  draft range lying wholly past the last block (the file shrank between draft
- *  save and reopen) still gets a marker on its clamped block, so every comment
+export declare function moveActiveUnit(state: ReviewState, delta: number, extend: boolean): ReviewState;
+/** Unit indices overlapped by any existing comment's source range. A stale
+ *  draft range lying wholly past the last unit (the file shrank between draft
+ *  save and reopen) still gets a marker on its clamped unit, so every comment
  *  is visible somewhere in the document. */
-export declare function commentedBlockSet(state: ReviewState): Set<number>;
-/** First/last rendered-row indices produced by blocks `lo..hi`, or null when
- *  no row maps into that range. */
-export declare function anchorRowRange(rows: (number | null)[], lo: number, hi: number): {
+export declare function commentedUnitSet(state: ReviewState): Set<number>;
+/** First/last rendered-row indices spanned by units `lo..hi`, or null when
+ *  the indices fall outside the unit list. */
+export declare function anchorRowRange(units: AnchorUnit[], lo: number, hi: number): {
     first: number;
     last: number;
 } | null;
@@ -63,7 +99,7 @@ export declare function anchorRowRange(rows: (number | null)[], lo: number, hi:
  *  overwrites the preceding row, never the pinned one. Always returns a scroll
  *  clamped to the document. */
 export declare function scrollToReveal(scroll: number, first: number, last: number, bodyHeight: number, total: number, margin?: number): number;
-/** Auto-scroll so the active block (the moving edge of a selection) is
+/** Auto-scroll so the active unit (the moving edge of a selection) is
  *  visible. Free-scrolling (`u`/`d`) is untouched until the next anchor move. */
 export declare function ensureAnchorVisible(state: ReviewState, doc: RenderedDoc, bodyHeight: number): ReviewState;
 export declare function scrollBy(state: ReviewState, delta: number, bodyHeight: number, totalLines: number): ReviewState;
@@ -105,11 +141,14 @@ export declare function renderReviewFrame(state: ReviewState, fileLabel: string,
 /**
  * Open a Markdown file in humanloop's own terminal review surface: the
  * document renders via termrender (Mermaid included), the anchor is a
- * highlighted block in the rendered document itself (gutter bar + tint via
- * termrender's row→source map), and the human explicitly submits a proposal.
- * Never edits the source file. Autosaves the comment draft to `opts.output`
- * (the `progress.json` convention). Canonical ticket finalization stays with
- * the caller's `onPropose` (the adapter calls `completeReview`); this function
- * never writes `response.json`.
+ * highlighted leaf unit — a bullet, table row, code line, paragraph — in the
+ * rendered document itself (gutter bar + tint via termrender's per-row source
+ * spans), and the human explicitly submits a proposal.
+ * `space w` hands the review off to the browser surface (same park/take-back
+ * semantics as the Neovim path); the draft round-trips between surfaces via
+ * `opts.output`. Never edits the source file. Autosaves the comment draft to
+ * `opts.output` (the `progress.json` convention). Canonical ticket
+ * finalization stays with the caller's `onPropose` (the adapter calls
+ * `completeReview`); this function never writes `response.json`.
  */
 export declare function launchTerminalReview(file: string, opts: ReviewOptions): Promise<FeedbackResult>;

package/dist/editor/terminal-review.js

@@ -1,29 +1,116 @@
 import { randomUUID } from 'node:crypto';
-import { readFileSync } from 'node:fs';
-import { basename, resolve } from 'node:path';
+import { mkdtempSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
 import stringWidth from 'string-width';
+import { waitForParkedReviewSubmit } from './parked.js';
+import { openBrowser } from '../browser/open.js';
+import { startReviewWebServer } from '../browser/server.js';
 import { buildDraftFeedbackResult, buildFinalFeedbackResult, readReviewDraft, writeReviewDraft } from './feedback.js';
 import { renderMarkdownWithMap } from '../render/termrender.js';
 import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress } from '../tui/terminal.js';
 import { diffFrame, renderInputBuffer } from '../tui/render.js';
 import { BOLD, CYAN, DIM, ESC, RESET, YELLOW, hline, sanitize, truncate } from '../tui/ansi.js';
-/** Index of the block containing `line`; snaps forward across gaps (blank
- *  separator lines between blocks) and clamps to the last block. */
-export function blockIndexForLine(blocks, line) {
-    for (let i = 0; i < blocks.length; i++) {
-        if (blocks[i].end >= line)
+/** Derive leaf anchor units from a mapped render: dedupe runs of consecutive
+ *  rows carrying the identical source span. A mapped row without a leaf span
+ *  (an unmapped block) anchors at its whole block's range, so every content
+ *  row belongs to a unit; separator rows belong to none. */
+export function deriveAnchorUnits(doc) {
+    const units = [];
+    const rowUnits = new Array(doc.lines.length).fill(null);
+    for (let r = 0; r < doc.lines.length; r++) {
+        let span = doc.spans[r] ?? null;
+        if (span === null) {
+            const b = doc.rows[r] ?? null;
+            const block = b !== null ? doc.blocks[b] : undefined;
+            if (block === undefined)
+                continue;
+            span = [block.start, block.end];
+        }
+        const prev = units[units.length - 1];
+        if (prev !== undefined && prev.lastRow === r - 1 && prev.start === span[0] && prev.end === span[1]) {
+            prev.lastRow = r;
+        }
+        else {
+            units.push({ start: span[0], end: span[1], firstRow: r, lastRow: r });
+        }
+        rowUnits[r] = units.length - 1;
+    }
+    if (units.length === 0) {
+        // Degenerate map (nothing anchorable) — one whole-doc unit over all rows.
+        units.push({
+            start: doc.blocks[0]?.start ?? 1,
+            end: doc.blocks[doc.blocks.length - 1]?.end ?? 1,
+            firstRow: 0,
+            lastRow: Math.max(0, doc.lines.length - 1),
+        });
+        for (let r = 0; r < rowUnits.length; r++)
+            rowUnits[r] = 0;
+    }
+    return { units, rowUnits };
+}
+/** Best unit for a source line: the NARROWEST unit containing it — code/table
+ *  chrome units carry their whole block's range and sit before the per-line
+ *  content units in rendered order, so "first whose end reaches the line"
+ *  would wrongly pick the chrome over the exact code line. A line no unit
+ *  contains (a blank separator) snaps forward to the next unit; past the end
+ *  clamps to the last. */
+export function unitIndexForLine(units, line) {
+    let best = -1;
+    for (let i = 0; i < units.length; i++) {
+        const u = units[i];
+        if (u.start <= line && u.end >= line) {
+            if (best === -1 || u.end - u.start < units[best].end - units[best].start)
+                best = i;
+        }
+    }
+    if (best !== -1)
+        return best;
+    for (let i = 0; i < units.length; i++) {
+        if (units[i].start > line)
             return i;
     }
-    return Math.max(0, blocks.length - 1);
+    return Math.max(0, units.length - 1);
+}
+/** Remap a unit from an old unit list into a re-derived one: an exact
+ *  source-range match wins (chrome and leaf units can share source lines),
+ *  else the best unit for its first line. */
+export function remapUnitIndex(units, prev) {
+    for (let i = 0; i < units.length; i++) {
+        if (units[i].start === prev.start && units[i].end === prev.end)
+            return i;
+    }
+    return unitIndexForLine(units, prev.start);
+}
+/** First/last unit indices overlapping the source range `line..endLine`;
+ *  a range touching no unit snaps like unitIndexForLine. */
+export function unitRangeForSpan(units, line, endLine) {
+    let lo = -1;
+    let hi = -1;
+    units.forEach((u, i) => {
+        if (u.start <= endLine && u.end >= line) {
+            if (lo === -1)
+                lo = i;
+            hi = i;
+        }
+    });
+    if (lo === -1) {
+        const snap = unitIndexForLine(units, line);
+        return { lo: snap, hi: snap };
+    }
+    return { lo, hi };
 }
-export function initReviewState(sourceLines, blocks, comments, version) {
-    const safeBlocks = blocks.length > 0 ? blocks : [{ start: 1, end: Math.max(1, sourceLines.length) }];
+export function initReviewState(sourceLines, anchor, comments, version) {
+    const safe = anchor.units.length > 0
+        ? anchor
+        : { units: [{ start: 1, end: Math.max(1, sourceLines.length), firstRow: 0, lastRow: 0 }], rowUnits: anchor.rowUnits };
     return {
         sourceLines,
-        blocks: safeBlocks,
+        units: safe.units,
+        rowUnits: safe.rowUnits,
         comments: [...comments],
         version,
-        activeBlock: comments.length > 0 ? blockIndexForLine(safeBlocks, comments[0].line) : 0,
+        activeUnit: comments.length > 0 ? unitIndexForLine(safe.units, comments[0].line) : 0,
         selectionAnchor: null,
         scroll: 0,
         mode: 'view',
@@ -31,58 +118,63 @@ export function initReviewState(sourceLines, blocks, comments, version) {
         listIndex: 0,
     };
 }
-function selectedBlockBounds(state) {
-    const sel = state.selectionAnchor ?? state.activeBlock;
-    return { lo: Math.min(state.activeBlock, sel), hi: Math.max(state.activeBlock, sel) };
+function selectedUnitBounds(state) {
+    const sel = state.selectionAnchor ?? state.activeUnit;
+    return { lo: Math.min(state.activeUnit, sel), hi: Math.max(state.activeUnit, sel) };
 }
-/** Source-line anchor of the current block selection — what a committed
- *  comment records as `line`/`endLine`. */
+/** Source-line anchor of the current unit selection — what a committed
+ *  comment records as `line`/`endLine`. Whole-block chrome units can carry a
+ *  wider range than their neighbors, so take the min/max over the selection
+ *  rather than trusting the endpoints alone. */
 export function currentAnchor(state) {
-    const { lo, hi } = selectedBlockBounds(state);
-    const first = state.blocks[lo] ?? { start: 1, end: Math.max(1, state.sourceLines.length) };
-    const last = state.blocks[hi] ?? first;
-    return { line: first.start, endLine: last.end };
-}
-export function moveActiveBlock(state, delta, extend) {
-    const last = Math.max(0, state.blocks.length - 1);
-    const next = Math.max(0, Math.min(last, state.activeBlock + delta));
+    const { lo, hi } = selectedUnitBounds(state);
+    let line = Number.POSITIVE_INFINITY;
+    let endLine = 0;
+    for (let i = lo; i <= hi; i++) {
+        const u = state.units[i];
+        if (u === undefined)
+            continue;
+        line = Math.min(line, u.start);
+        endLine = Math.max(endLine, u.end);
+    }
+    if (!Number.isFinite(line))
+        return { line: 1, endLine: Math.max(1, state.sourceLines.length) };
+    return { line, endLine: Math.max(line, endLine) };
+}
+export function moveActiveUnit(state, delta, extend) {
+    const last = Math.max(0, state.units.length - 1);
+    const next = Math.max(0, Math.min(last, state.activeUnit + delta));
     if (!extend)
-        return { ...state, activeBlock: next, selectionAnchor: null };
-    return { ...state, activeBlock: next, selectionAnchor: state.selectionAnchor ?? state.activeBlock };
+        return { ...state, activeUnit: next, selectionAnchor: null };
+    return { ...state, activeUnit: next, selectionAnchor: state.selectionAnchor ?? state.activeUnit };
 }
-/** Block indices overlapped by any existing comment's source range. A stale
- *  draft range lying wholly past the last block (the file shrank between draft
- *  save and reopen) still gets a marker on its clamped block, so every comment
+/** Unit indices overlapped by any existing comment's source range. A stale
+ *  draft range lying wholly past the last unit (the file shrank between draft
+ *  save and reopen) still gets a marker on its clamped unit, so every comment
  *  is visible somewhere in the document. */
-export function commentedBlockSet(state) {
+export function commentedUnitSet(state) {
     const out = new Set();
     for (const c of state.comments) {
         let hit = false;
-        state.blocks.forEach((b, i) => {
-            if (b.start <= c.endLine && b.end >= c.line) {
+        state.units.forEach((u, i) => {
+            if (u.start <= c.endLine && u.end >= c.line) {
                 out.add(i);
                 hit = true;
             }
         });
         if (!hit)
-            out.add(blockIndexForLine(state.blocks, c.line));
+            out.add(unitIndexForLine(state.units, c.line));
     }
     return out;
 }
-/** First/last rendered-row indices produced by blocks `lo..hi`, or null when
- *  no row maps into that range. */
-export function anchorRowRange(rows, lo, hi) {
-    let first = -1;
-    let last = -1;
-    for (let r = 0; r < rows.length; r++) {
-        const b = rows[r];
-        if (b !== null && b >= lo && b <= hi) {
-            if (first === -1)
-                first = r;
-            last = r;
-        }
-    }
-    return first === -1 ? null : { first, last };
+/** First/last rendered-row indices spanned by units `lo..hi`, or null when
+ *  the indices fall outside the unit list. */
+export function anchorRowRange(units, lo, hi) {
+    const a = units[lo];
+    const b = units[hi];
+    if (a === undefined || b === undefined)
+        return null;
+    return { first: a.firstRow, last: b.lastRow };
 }
 /** Minimal scroll adjustment that keeps rows `first..last` visible with
  *  `margin` rows of context (the margin yields whenever honoring it would push
@@ -101,10 +193,10 @@ export function scrollToReveal(scroll, first, last, bodyHeight, total, margin =
         next = Math.min(last + margin - (bodyHeight - 1), first);
     return Math.max(0, Math.min(next, maxScroll));
 }
-/** Auto-scroll so the active block (the moving edge of a selection) is
+/** Auto-scroll so the active unit (the moving edge of a selection) is
  *  visible. Free-scrolling (`u`/`d`) is untouched until the next anchor move. */
 export function ensureAnchorVisible(state, doc, bodyHeight) {
-    const range = anchorRowRange(doc.rows, state.activeBlock, state.activeBlock);
+    const range = anchorRowRange(state.units, state.activeUnit, state.activeUnit);
     if (range === null)
         return state;
     const scroll = scrollToReveal(state.scroll, range.first, range.last, bodyHeight, doc.lines.length);
@@ -122,11 +214,10 @@ export function openComposeEdit(state, index) {
     if (comment === undefined)
         return state;
     const buffer = comment.comment;
-    const lo = blockIndexForLine(state.blocks, comment.line);
-    const hi = blockIndexForLine(state.blocks, comment.endLine);
+    const { lo, hi } = unitRangeForSpan(state.units, comment.line, comment.endLine);
     return {
         ...state,
-        activeBlock: hi,
+        activeUnit: hi,
         selectionAnchor: lo === hi ? null : lo,
         mode: 'compose',
         compose: { buffer, cursor: [...buffer].length, editingId: comment.id, returnMode: 'list', anchor: { line: comment.line, endLine: comment.endLine } },
@@ -280,7 +371,7 @@ export function reservedRows(state, cols) {
     }
     if (state.mode === 'list')
         return header + Math.max(1, state.comments.length) + 2;
-    return header + 8; // help
+    return header + 9; // help
 }
 export function renderReviewFrame(state, fileLabel, doc, cols, rows) {
     const maxW = Math.min(Math.max(20, cols - 4), 120);
@@ -317,24 +408,25 @@ export function renderReviewFrame(state, fileLabel, doc, cols, rows) {
     }
     else if (state.mode === 'help') {
         footer.push('  Keys:');
-        footer.push(`  ${DIM}j/k${RESET}         move anchor block      ${DIM}shift+j/k${RESET}   extend selection`);
+        footer.push(`  ${DIM}j/k${RESET}         move anchor            ${DIM}shift+j/k${RESET}   extend selection`);
         footer.push(`  ${DIM}u/d, pgup/pgdn${RESET}  scroll document`);
         footer.push(`  ${DIM}space c${RESET}     compose comment        ${DIM}space l${RESET}     list comments`);
         footer.push(`  ${DIM}space u${RESET}     undo last comment      ${DIM}space s${RESET}     submit review`);
+        footer.push(`  ${DIM}space w${RESET}     hand off to browser`);
         footer.push(`  ${DIM}?${RESET}           toggle this help       ${DIM}esc${RESET}         close/cancel`);
         footer.push('');
         footer.push(`  ${DIM}esc / ?${RESET} close`);
     }
     else {
-        footer.push(`  ${DIM}j/k${RESET} block  ${DIM}shift-j/k${RESET} extend  ${DIM}u/d${RESET} scroll  ${DIM}space c${RESET} comment  ` +
-            `${DIM}space l${RESET} list  ${DIM}space u${RESET} undo  ${DIM}space s${RESET} submit  ${DIM}?${RESET} help  ${DIM}esc${RESET} close`);
+        footer.push(`  ${DIM}j/k${RESET} move  ${DIM}shift-j/k${RESET} extend  ${DIM}u/d${RESET} scroll  ${DIM}space c${RESET} comment  ` +
+            `${DIM}space l${RESET} list  ${DIM}space u${RESET} undo  ${DIM}space s${RESET} submit  ${DIM}space w${RESET} browser  ${DIM}?${RESET} help  ${DIM}esc${RESET} close`);
     }
     const reserved = header.length + footer.length;
     const bodyHeight = Math.max(1, rows - reserved);
     const maxScroll = Math.max(0, doc.lines.length - bodyHeight);
     const scroll = Math.max(0, Math.min(state.scroll, maxScroll));
-    const { lo, hi } = selectedBlockBounds(state);
-    const commented = commentedBlockSet(state);
+    const { lo, hi } = selectedUnitBounds(state);
+    const commented = commentedUnitSet(state);
     const body = [];
     for (let i = 0; i < bodyHeight; i++) {
         const abs = scroll + i;
@@ -343,10 +435,10 @@ export function renderReviewFrame(state, fileLabel, doc, cols, rows) {
             continue;
         }
         const row = doc.lines[abs];
-        const b = doc.rows[abs] ?? null;
-        if (b !== null && b >= lo && b <= hi)
+        const u = state.rowUnits[abs] ?? null;
+        if (u !== null && u >= lo && u <= hi)
             body.push(`  ${CYAN}▌${RESET} ${tintRow(row, docW)}`);
-        else if (b !== null && commented.has(b))
+        else if (u !== null && commented.has(u))
             body.push(`  ${YELLOW}▎${RESET} ${row}`);
         else
             body.push(`    ${row}`);
@@ -363,30 +455,90 @@ export function renderReviewFrame(state, fileLabel, doc, cols, rows) {
         lines.push('');
     return lines.slice(0, rows);
 }
-// ── Host loop (impure — the only part that touches the real TTY) ───────────
+function diskDraftResult(absFile, outPath) {
+    const draft = readReviewDraft(outPath);
+    return buildDraftFeedbackResult(absFile, draft?.comments ?? [], draft?.savedAt);
+}
 /**
  * Open a Markdown file in humanloop's own terminal review surface: the
  * document renders via termrender (Mermaid included), the anchor is a
- * highlighted block in the rendered document itself (gutter bar + tint via
- * termrender's row→source map), and the human explicitly submits a proposal.
- * Never edits the source file. Autosaves the comment draft to `opts.output`
- * (the `progress.json` convention). Canonical ticket finalization stays with
- * the caller's `onPropose` (the adapter calls `completeReview`); this function
- * never writes `response.json`.
+ * highlighted leaf unit — a bullet, table row, code line, paragraph — in the
+ * rendered document itself (gutter bar + tint via termrender's per-row source
+ * spans), and the human explicitly submits a proposal.
+ * `space w` hands the review off to the browser surface (same park/take-back
+ * semantics as the Neovim path); the draft round-trips between surfaces via
+ * `opts.output`. Never edits the source file. Autosaves the comment draft to
+ * `opts.output` (the `progress.json` convention). Canonical ticket
+ * finalization stays with the caller's `onPropose` (the adapter calls
+ * `completeReview`); this function never writes `response.json`.
  */
 export async function launchTerminalReview(file, opts) {
     const absFile = resolve(file);
     const content = readFileSync(absFile, 'utf8');
-    const sourceLines = content.split('\n');
     const outPath = resolve(opts.output);
-    const draft = readReviewDraft(outPath);
     const fileLabel = basename(absFile);
-    if (opts.signal?.aborted)
-        return buildDraftFeedbackResult(absFile, draft?.comments ?? [], draft?.savedAt);
+    // Created lazily on the first browser handoff, reused across take-backs.
+    let jobDir = opts.jobDir ?? null;
+    while (true) {
+        if (opts.signal?.aborted)
+            return diskDraftResult(absFile, outPath);
+        const outcome = await runTerminalReviewSession(absFile, content, outPath, fileLabel, opts);
+        if (outcome.type === 'done')
+            return outcome.result;
+        // Browser handoff: the TUI is parked (terminal already restored, draft
+        // persisted); the browser is the editing authority until it submits, the
+        // human takes back with `w`, or the review is cancelled.
+        if (jobDir === null)
+            jobDir = mkdtempSync(join(tmpdir(), 'hl-review-'));
+        let resolveSubmitted;
+        const submitted = new Promise((resolveSubmittedPromise) => {
+            resolveSubmitted = resolveSubmittedPromise;
+        });
+        const server = await startReviewWebServer({
+            jobDir,
+            file: absFile,
+            output: outPath,
+            onSubmit: (result) => resolveSubmitted(result),
+        });
+        if (opts.signal?.aborted) {
+            await server.stop();
+            return diskDraftResult(absFile, outPath);
+        }
+        server.activate();
+        process.stderr.write(`humanloop: browser review handoff active — ${server.url}\n`);
+        openBrowser(server.url);
+        const action = await waitForParkedReviewSubmit(submitted, opts.signal, 'the terminal review');
+        if (action.type === 'submitted') {
+            await server.stop();
+            // An abort landing during the async stop() must not produce a submitted
+            // result whose canonical onPropose convergence was skipped — fall back
+            // to the disk draft (the browser submit already persisted its comments).
+            if (opts.signal?.aborted)
+                return diskDraftResult(absFile, outPath);
+            await opts.onPropose?.(action.result);
+            return action.result;
+        }
+        if (action.type === 'take-back') {
+            await server.requestTakeBack();
+            await server.stop();
+            process.stderr.write('humanloop: taking review back into the terminal review.\n');
+            continue; // re-enter the TUI; the next session re-reads the draft from disk
+        }
+        await server.stop();
+        return diskDraftResult(absFile, outPath);
+    }
+}
+/** One TUI session over the document. Resolves when the review reaches a
+ *  final result (submit/close/cancel) or the human requests browser handoff;
+ *  either way the terminal is restored before resolution. Re-reads the draft
+ *  from disk on entry so browser edits survive a take-back. */
+function runTerminalReviewSession(absFile, content, outPath, fileLabel, opts) {
+    const sourceLines = content.split('\n');
+    const draft = readReviewDraft(outPath);
     setupTerminal();
     let { cols, rows } = getTerminalSize();
     let doc = renderMarkdownWithMap(content, renderWidthForCols(cols));
-    let state = initReviewState(sourceLines, doc.blocks, draft?.comments ?? [], draft?.version ?? 0);
+    let state = initReviewState(sourceLines, deriveAnchorUnits(doc), draft?.comments ?? [], draft?.version ?? 0);
     let prevFrame = [];
     let spaceArmed = false;
     let settled = false;
@@ -410,7 +562,7 @@ export async function launchTerminalReview(file, opts) {
             process.stdout.write('\x1b[?2026l');
             prevFrame = nextPrevFrame;
         };
-        const finish = (result) => {
+        const finishWith = (outcome) => {
             if (settled)
                 return;
             settled = true;
@@ -418,22 +570,26 @@ export async function launchTerminalReview(file, opts) {
             process.stdout.removeListener('resize', onResize);
             opts.signal?.removeEventListener('abort', onAbort);
             restoreTerminal();
-            resolvePromise(result);
+            resolvePromise(outcome);
         };
+        const finish = (result) => finishWith({ type: 'done', result });
         const onResize = () => {
             ({ cols, rows } = getTerminalSize());
             doc = renderMarkdownWithMap(content, renderWidthForCols(cols));
-            // Blocks derive from the source, not the width, so a same-renderer
-            // re-render keeps the count — but a mid-session renderer→fallback
-            // transition can reshape the block list, so clamp the indices. Committed
-            // comments are untouched either way (their source lines are frozen).
-            const blocks = doc.blocks;
-            const lastIdx = Math.max(0, blocks.length - 1);
+            // Unit SOURCE ranges are width-independent under the same renderer (only
+            // their rendered-row bounds move), but a mid-session renderer→fallback
+            // transition can reshape the list — so remap the anchor by its source
+            // line rather than trusting the old index. Committed comments are
+            // untouched either way (their source lines are frozen).
+            const prevActive = state.units[state.activeUnit];
+            const prevSel = state.selectionAnchor !== null ? state.units[state.selectionAnchor] : undefined;
+            const { units, rowUnits } = deriveAnchorUnits(doc);
             state = {
                 ...state,
-                blocks,
-                activeBlock: Math.min(state.activeBlock, lastIdx),
-                selectionAnchor: state.selectionAnchor === null ? null : Math.min(state.selectionAnchor, lastIdx),
+                units,
+                rowUnits,
+                activeUnit: prevActive !== undefined ? remapUnitIndex(units, prevActive) : 0,
+                selectionAnchor: prevSel !== undefined ? remapUnitIndex(units, prevSel) : null,
             };
             state = ensureAnchorVisible(state, doc, bodyH());
             paint(true);
@@ -575,6 +731,11 @@ export async function launchTerminalReview(file, opts) {
                     void submit();
                     return;
                 }
+                else if (input === 'w') {
+                    persist();
+                    finishWith({ type: 'handoff' });
+                    return;
+                }
                 paint();
                 return;
             }
@@ -595,19 +756,19 @@ export async function launchTerminalReview(file, opts) {
                 return;
             }
             if (input === 'j' || key.downArrow) {
-                state = moveActiveBlock(state, 1, false);
+                state = moveActiveUnit(state, 1, false);
                 state = ensureAnchorVisible(state, doc, bodyH());
             }
             else if (input === 'k' || key.upArrow) {
-                state = moveActiveBlock(state, -1, false);
+                state = moveActiveUnit(state, -1, false);
                 state = ensureAnchorVisible(state, doc, bodyH());
             }
             else if (input === 'J') {
-                state = moveActiveBlock(state, 1, true);
+                state = moveActiveUnit(state, 1, true);
                 state = ensureAnchorVisible(state, doc, bodyH());
             }
             else if (input === 'K') {
-                state = moveActiveBlock(state, -1, true);
+                state = moveActiveUnit(state, -1, true);
                 state = ensureAnchorVisible(state, doc, bodyH());
             }
             else if (input === 'u' || key.pageUp)

package/dist/render/termrender.d.ts

@@ -22,6 +22,10 @@ export interface RenderedDoc {
     lines: string[];
     /** Per-row index into `blocks`; null for the blank separator rows between blocks. */
     rows: (number | null)[];
+    /** Per-row finest 1-indexed inclusive source-line range the renderer knows
+     *  (a bullet, a table row, a code line…); null for separator rows and rows
+     *  of unmapped blocks. Same length as `lines`. */
+    spans: ([number, number] | null)[];
     /** Per top-level block: 1-indexed inclusive source-line bounds. Never empty. */
     blocks: {
         start: number;

package/dist/render/termrender.js

@@ -505,9 +505,9 @@ function parseRenderedDoc(out, source) {
         return null;
     }
     const p = parsed;
-    if (!Array.isArray(p.lines) || !Array.isArray(p.rows) || !Array.isArray(p.blocks))
+    if (!Array.isArray(p.lines) || !Array.isArray(p.rows) || !Array.isArray(p.spans) || !Array.isArray(p.blocks))
         return null;
-    if (p.rows.length !== p.lines.length)
+    if (p.rows.length !== p.lines.length || p.spans.length !== p.lines.length)
         return null;
     if (!p.lines.every((l) => typeof l === 'string'))
         return null;
@@ -535,11 +535,42 @@ function parseRenderedDoc(out, source) {
     }
     if (blocks.length === 0)
         blocks.push({ start: 1, end: totalSource });
-    return { lines: p.lines, rows: p.rows, blocks };
+    const spans = [];
+    for (let r = 0; r < p.spans.length; r++) {
+        const raw = p.spans[r];
+        if (raw === null) {
+            spans.push(null);
+            continue;
+        }
+        // Same strictness as rows: a span is [start, end], 1-indexed inclusive
+        // integers in order, inside the source — these values flow straight into
+        // a recorded comment's line/endLine, so an out-of-range endpoint is tool
+        // fault to reject, never something to clamp into the wrong line.
+        if (!Array.isArray(raw) || raw.length !== 2)
+            return null;
+        const [s, e] = raw;
+        if (!Number.isInteger(s) || !Number.isInteger(e))
+            return null;
+        if (s < 1 || e < s || e > totalSource)
+            return null;
+        // Relational contract: a separator row (rows[r] === null) carries no
+        // span, and a leaf span stays inside its owning block's source range. A
+        // map that disagrees with its own rows/blocks would let a comment on a
+        // visible row record against unrelated source text.
+        const rowBlock = p.rows[r];
+        if (rowBlock === null)
+            return null;
+        const owner = blocks[rowBlock];
+        if (s < owner.start || e > owner.end)
+            return null;
+        spans.push([s, e]);
+    }
+    return { lines: p.lines, rows: p.rows, spans, blocks };
 }
 /** Renderer-free mapped render: group consecutive non-blank source lines into
  *  paragraph blocks and word-wrap each — the same shape as the termrender map,
- *  with degraded (plaintext) rendering. */
+ *  with degraded (plaintext) rendering. Each source line is wrapped on its own
+ *  and spans exactly itself, so leaf anchoring degrades to true line-by-line. */
 function fallbackDocWithMap(md, width) {
     const src = sanitize(md).split('\n');
     const blocks = [];
@@ -560,17 +591,24 @@ function fallbackDocWithMap(md, width) {
         blocks.push({ start: 1, end: Math.max(1, src.length) });
     const lines = [];
     const rows = [];
+    const spans = [];
     blocks.forEach((b, bi) => {
         if (bi > 0) {
             lines.push('');
             rows.push(null);
+            spans.push(null);
         }
-        for (const l of wrap(src.slice(b.start - 1, b.end).join('\n'), width)) {
-            lines.push(l);
-            rows.push(bi);
+        // wrap() treats each '\n'-separated line as its own paragraph, so wrapping
+        // line-by-line emits the exact rows the joined-block wrap produced.
+        for (let ln = b.start; ln <= b.end; ln++) {
+            for (const l of wrap(src[ln - 1] ?? '', width)) {
+                lines.push(l);
+                rows.push(bi);
+                spans.push([ln, ln]);
+            }
         }
     });
-    return { lines, rows, blocks };
+    return { lines, rows, spans, blocks };
 }
 const _mapCache = new Map();
 /** Render markdown with a row→source-line map via the pinned binary

package/dist/render/version.d.ts

@@ -1 +1 @@
-export declare const TERMRENDER_VERSION = "4.11.0";
+export declare const TERMRENDER_VERSION = "4.12.0";

package/dist/render/version.js

@@ -1 +1 @@
-export const TERMRENDER_VERSION = '4.11.0';
+export const TERMRENDER_VERSION = '4.12.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/humanloop",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "Human-in-the-loop decision TUI — agents write questions, humans answer them",
   "engines": {
     "node": ">=22.19.0"