@north-light/crouter 0.3.170 → 0.3.172

package/dist/clients/inbox/review/__tests__/editor-roundtrip.test.js

@@ -0,0 +1,29 @@
+import assert from 'node:assert/strict';
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { editBufferInEditor } from '../roundtrip.js';
+const temp = mkdtempSync(join(tmpdir(), 'humanloop-editor-roundtrip-'));
+const priorEditor = process.env.EDITOR;
+try {
+    const successfulEditor = join(temp, 'success-editor');
+    writeFileSync(successfulEditor, '#!/bin/sh\nprintf "edited\\n" > "$1"\n');
+    chmodSync(successfulEditor, 0o755);
+    process.env.EDITOR = successfulEditor;
+    assert.deepEqual(editBufferInEditor('original'), { text: 'edited' }, 'editor readback replaces the buffer and removes one editor-added newline');
+    const failingEditor = join(temp, 'failing-editor');
+    writeFileSync(failingEditor, '#!/bin/sh\nexit 9\n');
+    chmodSync(failingEditor, 0o755);
+    process.env.EDITOR = failingEditor;
+    const failed = editBufferInEditor('keep this');
+    assert.equal(failed.text, 'keep this', 'a failing editor leaves the active input intact');
+    assert.match(failed.error ?? '', /exited with status 9/, 'a failing editor reports its status to the host');
+}
+finally {
+    if (priorEditor === undefined)
+        delete process.env.EDITOR;
+    else
+        process.env.EDITOR = priorEditor;
+    rmSync(temp, { recursive: true, force: true });
+}
+console.log('editor round-trip tests passed');

package/dist/clients/inbox/review/__tests__/remap.test.js

@@ -0,0 +1,196 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { buildLineMap, remapRange } from '../remap.js';
+describe('remap', () => {
+    describe('buildLineMap', () => {
+        it('identity mapping when content unchanged', () => {
+            const lines = ['line 1', 'line 2', 'line 3'];
+            const map = buildLineMap(lines, lines);
+            assert.equal(map.get(0), 0);
+            assert.equal(map.get(1), 1);
+            assert.equal(map.get(2), 2);
+        });
+        it('preserves normalized equivalence', () => {
+            const oldLines = ['line  1', '  line  2  ', 'line 3'];
+            const newLines = ['line 1', 'line 2', 'line 3'];
+            const map = buildLineMap(oldLines, newLines);
+            // All lines are normalized equivalent, so they map 1:1
+            assert.equal(map.get(0), 0);
+            assert.equal(map.get(1), 1);
+            assert.equal(map.get(2), 2);
+        });
+        it('handles common prefix', () => {
+            const oldLines = ['a', 'b', 'c', 'x'];
+            const newLines = ['a', 'b', 'c', 'x'];
+            const map = buildLineMap(oldLines, newLines);
+            // All lines match 1:1
+            assert.equal(map.get(0), 0);
+            assert.equal(map.get(1), 1);
+            assert.equal(map.get(2), 2);
+            assert.equal(map.get(3), 3);
+        });
+        it('handles common suffix', () => {
+            const oldLines = ['x', 'a', 'b', 'c'];
+            const newLines = ['x', 'a', 'b', 'c'];
+            const map = buildLineMap(oldLines, newLines);
+            assert.equal(map.get(0), 0);
+            assert.equal(map.get(1), 1);
+            assert.equal(map.get(2), 2);
+            assert.equal(map.get(3), 3);
+        });
+        it('handles insertion above range', () => {
+            const oldLines = ['x', 'y', 'z'];
+            const newLines = ['a', 'b', 'x', 'y', 'z'];
+            const map = buildLineMap(oldLines, newLines);
+            // Original lines are shifted down by 2
+            assert.equal(map.get(0), 2); // 'x'
+            assert.equal(map.get(1), 3); // 'y'
+            assert.equal(map.get(2), 4); // 'z'
+        });
+        it('handles deletion creating gaps', () => {
+            const oldLines = ['a', 'b', 'c', 'd', 'e'];
+            const newLines = ['a', 'c', 'e'];
+            const map = buildLineMap(oldLines, newLines);
+            assert.equal(map.get(0), 0); // 'a'
+            assert.equal(map.get(1), undefined); // 'b' deleted
+            assert.equal(map.get(2), 1); // 'c'
+            assert.equal(map.get(3), undefined); // 'd' deleted
+            assert.equal(map.get(4), 2); // 'e'
+        });
+    });
+    describe('remapRange', () => {
+        it('returns kept when both endpoints unmoved', () => {
+            const oldLines = ['a', 'b', 'c', 'd'];
+            const newLines = ['a', 'b', 'c', 'd'];
+            const map = buildLineMap(oldLines, newLines);
+            const result = remapRange(map, { line: 1, endLine: 3 });
+            assert.equal(result.kind, 'kept');
+            if (result.kind === 'kept') {
+                assert.equal(result.line, 1);
+                assert.equal(result.endLine, 3);
+            }
+        });
+        it('pure insertion above range keeps content identity', () => {
+            const oldLines = ['x', 'y', 'z'];
+            const newLines = ['a', 'b', 'x', 'y', 'z'];
+            const map = buildLineMap(oldLines, newLines);
+            // Range [0, 2] in old file → should map to [2, 4] in new
+            const result = remapRange(map, { line: 0, endLine: 2 });
+            assert.equal(result.kind, 'shifted');
+            if (result.kind === 'shifted') {
+                assert.equal(result.line, 2);
+                assert.equal(result.endLine, 4);
+            }
+        });
+        it('pure deletion of whole range yields detached', () => {
+            const oldLines = ['a', 'b', 'c', 'd', 'e'];
+            const newLines = ['a', 'e'];
+            const map = buildLineMap(oldLines, newLines);
+            // Range [1, 4] contains only deleted lines
+            const result = remapRange(map, { line: 1, endLine: 4 });
+            assert.equal(result.kind, 'detached');
+        });
+        it('partial range deletion yields shifted', () => {
+            const oldLines = ['a', 'b', 'c', 'd', 'e'];
+            const newLines = ['a', 'c', 'e'];
+            const map = buildLineMap(oldLines, newLines);
+            // Range [0, 3] contains 'a' (survives), 'b' (deleted), 'c' (survives), 'd' (deleted)
+            // Should remap to min=0, max=1 (the span of survivors)
+            const result = remapRange(map, { line: 0, endLine: 3 });
+            assert.equal(result.kind, 'shifted');
+            if (result.kind === 'shifted') {
+                assert.equal(result.line, 0); // min of survivors
+                assert.equal(result.endLine, 2); // max + 1
+            }
+        });
+        it('reindentation of entire file yields kept', () => {
+            const oldLines = ['  line 1', '  line 2', '  line 3'];
+            const newLines = ['    line 1', '    line 2', '    line 3'];
+            const map = buildLineMap(oldLines, newLines);
+            // After normalization, all lines match 1:1
+            const result = remapRange(map, { line: 0, endLine: 3 });
+            assert.equal(result.kind, 'kept');
+            if (result.kind === 'kept') {
+                assert.equal(result.line, 0);
+                assert.equal(result.endLine, 3);
+            }
+        });
+        it('handles range with one survivor in middle', () => {
+            const oldLines = [
+                'keep1',
+                'delete1',
+                'delete2',
+                'keep2',
+                'delete3',
+            ];
+            const newLines = ['keep1', 'keep2'];
+            const map = buildLineMap(oldLines, newLines);
+            // Range [1, 4] covers delete1, delete2, keep2
+            // Only keep2 survives at index 1
+            const result = remapRange(map, { line: 1, endLine: 4 });
+            assert.equal(result.kind, 'shifted');
+            if (result.kind === 'shifted') {
+                assert.equal(result.line, 1);
+                assert.equal(result.endLine, 2);
+            }
+        });
+        it('detached when entire range deleted', () => {
+            const oldLines = ['a', 'b', 'c', 'd'];
+            const newLines = ['a', 'd'];
+            const map = buildLineMap(oldLines, newLines);
+            // Range [1, 3] contains only 'b' and 'c', both deleted
+            const result = remapRange(map, { line: 1, endLine: 3 });
+            assert.equal(result.kind, 'detached');
+        });
+        it('handles range at start', () => {
+            const oldLines = ['x', 'keep1', 'keep2', 'keep3'];
+            const newLines = ['keep1', 'keep2', 'keep3'];
+            const map = buildLineMap(oldLines, newLines);
+            // Range [1, 3] should map to [0, 2]
+            const result = remapRange(map, { line: 1, endLine: 3 });
+            assert.equal(result.kind, 'shifted');
+            if (result.kind === 'shifted') {
+                assert.equal(result.line, 0);
+                assert.equal(result.endLine, 2);
+            }
+        });
+        it('handles range at end', () => {
+            const oldLines = ['keep1', 'keep2', 'keep3', 'x'];
+            const newLines = ['keep1', 'keep2', 'keep3'];
+            const map = buildLineMap(oldLines, newLines);
+            // Range [1, 4] should map to [1, 3]
+            const result = remapRange(map, { line: 1, endLine: 4 });
+            assert.equal(result.kind, 'shifted');
+            if (result.kind === 'shifted') {
+                assert.equal(result.line, 1);
+                assert.equal(result.endLine, 3);
+            }
+        });
+    });
+    describe('performance', () => {
+        it('5000-line file with 20-line edit completes quickly', () => {
+            // Build old file: 5000 identical lines
+            const oldLines = [];
+            for (let i = 0; i < 5000; i++) {
+                oldLines.push(`line ${i}`);
+            }
+            // Build new file: insert 20 lines at position 2000
+            const newLines = [
+                ...oldLines.slice(0, 2000),
+                ...Array.from({ length: 20 }, (_, i) => `inserted ${i}`),
+                ...oldLines.slice(2000),
+            ];
+            // Measure time
+            const start = performance.now();
+            const map = buildLineMap(oldLines, newLines);
+            const elapsed = performance.now() - start;
+            // Should complete in well under 10s (the ordinary test budget)
+            // Even a naive implementation should handle this in <100ms
+            assert(elapsed < 1000, `buildLineMap took ${elapsed}ms, should be <1000ms`);
+            // Verify a few mappings
+            assert.equal(map.get(1999), 1999);
+            assert.equal(map.get(2000), 2020); // shifted by 20
+            assert.equal(map.get(2001), 2021);
+        });
+    });
+});

package/dist/clients/inbox/review/__tests__/review-core.test.js

@@ -0,0 +1,341 @@
+import assert from 'node:assert/strict';
+import stringWidth from 'string-width';
+import { deriveAnchorUnits, remapUnitIndex, unitIndexForLine, unitRangeForSpan, } from '../anchors.js';
+import { closeList, commentedUnitSet, commitCompose, currentAnchor, deleteAtListIndex, ensureAnchorVisible, anchorRowRange, initReviewState, moveActiveUnit, moveListIndex, openComposeEdit, openComposeNew, openList, scrollBy, scrollToReveal, textBackspace, textEnd, textHome, textInsert, textVertical, textVerticalWrapped, textWordBackspace, textWordLeft, textWordRight, undoLast, } from '../state.js';
+import { maxHScroll, panBy, renderReviewFrame, } from '../frame.js';
+import { matchReviewKey } from '../keys.js';
+assert.equal(matchReviewKey('\x1bR'), null, 'legacy Alt+Shift+R remains viewer-global');
+assert.equal(matchReviewKey('\x1b[82;4u'), null, 'Kitty Alt+Shift+R remains viewer-global');
+assert.equal(matchReviewKey('\x1bi'), null, 'Alt+I remains owned outside the review surface');
+// A small doc: a heading, a two-bullet list, a paragraph. The list is ONE
+// top-level block but each bullet carries its own leaf span — so anchoring
+// steps bullet-to-bullet, not list-to-list.
+const sourceLines = ['# Title', '', '- line three', '- line four', '', 'line six'];
+const existingComment = {
+    id: 'c1',
+    revision: 1,
+    line: 6,
+    endLine: 6,
+    lineText: 'line six',
+    comment: 'note',
+    status: 'open',
+    authorKind: 'human',
+    createdAt: 'now',
+    anchorStatus: 'live',
+};
+const doc = {
+    lines: ['TITLE', '', '• row three', '• row four', '', 'row six'],
+    rows: [0, null, 1, 1, null, 2],
+    spans: [[1, 1], null, [3, 3], [4, 4], null, [6, 6]],
+    blocks: [
+        { type: 'paragraph', start: 1, end: 1 },
+        { type: 'paragraph', start: 3, end: 4 },
+        { type: 'paragraph', start: 6, end: 6 },
+    ],
+};
+const anchor = deriveAnchorUnits(doc);
+const { units } = anchor;
+// deriveAnchorUnits: one unit per leaf span run; rowUnits keys the painter.
+{
+    assert.equal(units.length, 4, 'each bullet is its own unit — the list block splits');
+    assert.deepEqual(units[0], { start: 1, end: 1, firstRow: 0, lastRow: 0 });
+    assert.deepEqual(units[1], { start: 3, end: 3, firstRow: 2, lastRow: 2 });
+    assert.deepEqual(units[2], { start: 4, end: 4, firstRow: 3, lastRow: 3 });
+    assert.deepEqual(units[3], { start: 6, end: 6, firstRow: 5, lastRow: 5 });
+    assert.deepEqual(anchor.rowUnits, [0, null, 1, 2, null, 3]);
+}
+// deriveAnchorUnits: consecutive rows sharing a span (a wrapped bullet)
+// collapse into one unit; a mapped row with no leaf span (an unmapped block)
+// anchors at its whole block's range; a separator between identical spans
+// still splits units.
+{
+    const d = {
+        lines: ['a1', 'a2 (wrapped)', '', 'chrome'],
+        rows: [0, 0, null, 1],
+        spans: [[2, 2], [2, 2], null, null],
+        blocks: [
+            { type: 'paragraph', start: 1, end: 3 },
+            { type: 'paragraph', start: 5, end: 9 },
+        ],
+    };
+    const a = deriveAnchorUnits(d);
+    assert.deepEqual(a.units, [
+        { start: 2, end: 2, firstRow: 0, lastRow: 1 },
+        { start: 5, end: 9, firstRow: 3, lastRow: 3 },
+    ]);
+    assert.deepEqual(a.rowUnits, [0, 0, null, 1]);
+}
+// deriveAnchorUnits: a fully unmapped doc degrades to one whole-doc unit.
+{
+    const d = { lines: ['x', 'y'], rows: [null, null], spans: [null, null], blocks: [{ type: 'paragraph', start: 1, end: 7 }] };
+    const a = deriveAnchorUnits(d);
+    assert.deepEqual(a.units, [{ start: 1, end: 7, firstRow: 0, lastRow: 1 }]);
+    assert.deepEqual(a.rowUnits, [0, 0]);
+}
+// unitIndexForLine: containment, forward snap across gaps, clamp past the end.
+{
+    assert.equal(unitIndexForLine(units, 1), 0);
+    assert.equal(unitIndexForLine(units, 2), 1, 'a gap line snaps forward to the next unit');
+    assert.equal(unitIndexForLine(units, 3), 1);
+    assert.equal(unitIndexForLine(units, 4), 2);
+    assert.equal(unitIndexForLine(units, 6), 3);
+    assert.equal(unitIndexForLine(units, 99), 3, 'past the last unit clamps to the last unit');
+}
+// unitRangeForSpan: all units overlapping a source range (chrome units carry
+// their block's whole range, so a whole-fence comment covers every fence unit).
+{
+    assert.deepEqual(unitRangeForSpan(units, 3, 4), { lo: 1, hi: 2 }, 'a two-bullet comment spans both bullet units');
+    assert.deepEqual(unitRangeForSpan(units, 6, 6), { lo: 3, hi: 3 });
+    assert.deepEqual(unitRangeForSpan(units, 2, 2), { lo: 1, hi: 1 }, 'a gap-only range snaps forward');
+    const fence = deriveAnchorUnits({
+        lines: ['┌─', 'code a', 'code b', '└─'],
+        rows: [0, 0, 0, 0],
+        spans: [[5, 10], [6, 6], [7, 7], [5, 10]],
+        blocks: [{ type: 'paragraph', start: 5, end: 10 }],
+    });
+    assert.equal(fence.units.length, 4, 'fence = top chrome + per-line content + bottom chrome');
+    assert.deepEqual(unitRangeForSpan(fence.units, 5, 10), { lo: 0, hi: 3 }, 'a whole-fence comment highlights every fence unit');
+    // Narrowest-containing lookup: a code line resolves to its own unit even
+    // though the whole-block chrome unit sits earlier in rendered order.
+    assert.equal(unitIndexForLine(fence.units, 6), 1, 'a code line resolves to its leaf unit, not the fence chrome');
+    assert.equal(unitIndexForLine(fence.units, 7), 2);
+    assert.equal(unitIndexForLine(fence.units, 5), 0, 'the fence opener resolves to the chrome unit');
+    // Resize remapping: an exact source-range match is preserved (chrome and
+    // leaf units share source lines), else the narrowest containing unit wins.
+    assert.equal(remapUnitIndex(fence.units, { start: 6, end: 6, firstRow: 9, lastRow: 9 }), 1, 'remap keeps a code-line anchor on its code line');
+    assert.equal(remapUnitIndex(fence.units, { start: 5, end: 10, firstRow: 9, lastRow: 9 }), 0, 'remap keeps a chrome anchor on the identical-range unit');
+    assert.equal(remapUnitIndex(fence.units, { start: 8, end: 9, firstRow: 0, lastRow: 0 }), 0, 'no exact match falls back to the best unit for its first line');
+}
+// Anchor motion: j/k move unit-to-unit; Shift+j/k extends across units.
+{
+    let state = initReviewState(sourceLines, anchor, [], 0);
+    assert.deepEqual(currentAnchor(state), { line: 1, endLine: 1 });
+    state = moveActiveUnit(state, 1, false);
+    assert.deepEqual(currentAnchor(state), { line: 3, endLine: 3 }, 'j moves to a single bullet, not the whole list');
+    state = moveActiveUnit(state, 1, true);
+    assert.deepEqual(currentAnchor(state), { line: 3, endLine: 4 }, 'shift+j extends the selection downward');
+    state = moveActiveUnit(state, 1, true);
+    assert.deepEqual(currentAnchor(state), { line: 3, endLine: 6 }, 'shift+j extends across the block boundary');
+    state = moveActiveUnit(state, -3, true);
+    assert.deepEqual(currentAnchor(state), { line: 1, endLine: 3 }, 'shift+k can extend the selection back past the anchor');
+    state = moveActiveUnit(state, 1, false);
+    assert.deepEqual(currentAnchor(state), { line: 3, endLine: 3 }, 'a plain j/k collapses the selection');
+    // Bounds
+    state = moveActiveUnit(state, -100, false);
+    assert.equal(state.activeUnit, 0, 'anchor cannot move above the first unit');
+    state = moveActiveUnit(state, 100, false);
+    assert.equal(state.activeUnit, units.length - 1, 'anchor cannot move past the last unit');
+}
+// currentAnchor over chrome units takes the min/max across the selection.
+{
+    const fence = deriveAnchorUnits({
+        lines: ['┌─', 'code a', '└─'],
+        rows: [0, 0, 0],
+        spans: [[5, 8], [6, 6], [5, 8]],
+        blocks: [{ type: 'paragraph', start: 5, end: 8 }],
+    });
+    let state = initReviewState(['', '', '', '', '```', 'a', 'b', '```'], fence, [], 0);
+    state = moveActiveUnit(state, 1, false); // content line unit
+    assert.deepEqual(currentAnchor(state), { line: 6, endLine: 6 });
+    state = moveActiveUnit(state, 1, true); // extend onto bottom chrome (5-8)
+    assert.deepEqual(currentAnchor(state), { line: 5, endLine: 8 }, 'chrome in the selection widens to the block range');
+}
+// An existing comment positions the initial anchor on its unit.
+{
+    const state = initReviewState(sourceLines, anchor, [existingComment], 0);
+    assert.equal(state.activeUnit, 3);
+}
+// Compose emits a daemon mutation payload without changing the projection.
+{
+    let state = initReviewState(sourceLines, anchor, [], 0);
+    state = moveActiveUnit(state, 1, false); // bullet unit → L3
+    state = moveActiveUnit(state, 1, true); // extend → L3-4
+    state = openComposeNew(state);
+    assert.equal(state.mode, 'compose');
+    assert.deepEqual(state.compose?.anchor, { line: 3, endLine: 4 });
+    state = { ...state, compose: { ...state.compose, buffer: 'needs a rewrite' } };
+    let committed = commitCompose(state);
+    state = committed.state;
+    assert.equal(state.mode, 'view');
+    assert.deepEqual(committed.commit, { editingId: null, anchor: { line: 3, endLine: 4 }, text: 'needs a rewrite' });
+    assert.deepEqual(state.comments, [], 'the daemon projection remains unchanged until refreshed');
+    // A projection refresh supplies the daemon-created comment before later edits.
+    state = { ...state, comments: [existingComment] };
+    // Empty compose closes without a mutation.
+    state = openComposeNew(state);
+    committed = commitCompose(state);
+    state = committed.state;
+    assert.equal(committed.commit, null);
+    assert.equal(state.mode, 'view');
+    // Editing from the list preserves selection and identifies the comment for the daemon.
+    state = moveActiveUnit(state, -100, false); // move anchor away first
+    state = openList(state);
+    state = openComposeEdit(state, 0);
+    assert.equal(state.compose?.editingId, existingComment.id);
+    assert.equal(state.activeUnit, 3, 'editing re-anchors onto the comment\'s last unit');
+    assert.equal(state.selectionAnchor, null, 'a single-line comment selects one unit');
+    state = { ...state, compose: { ...state.compose, buffer: 'edited note' } };
+    committed = commitCompose(state);
+    state = committed.state;
+    assert.equal(state.mode, 'list', 'editing from the list returns to the list');
+    assert.deepEqual(committed.commit, { editingId: existingComment.id, anchor: { line: 6, endLine: 6 }, text: 'edited note' });
+    assert.deepEqual(state.comments, [existingComment], 'editing does not locally alter the projection');
+    // The commented unit set marks every unit overlapped by the projection.
+    assert.deepEqual([...commentedUnitSet(state)], [3]);
+    state = closeList(state);
+    assert.equal(state.mode, 'view');
+    const undone = undoLast(state);
+    assert.equal(undone.id, existingComment.id, 'undo identifies the daemon comment to remove');
+    assert.deepEqual(undone.state.comments, [existingComment]);
+}
+// List navigation and delete-by-index identify daemon comments without changing the projection.
+{
+    const secondComment = { ...existingComment, id: 'c2', line: 3, endLine: 3, lineText: '- line three', comment: 'second' };
+    let state = initReviewState(sourceLines, anchor, [existingComment, secondComment], 0);
+    state = openList(state);
+    state = moveListIndex(state, 1);
+    assert.equal(state.listIndex, 1);
+    const deleted = deleteAtListIndex(state);
+    assert.equal(deleted.id, secondComment.id);
+    assert.deepEqual(deleted.state.comments, [existingComment, secondComment]);
+    assert.equal(deleted.state.listIndex, 1);
+}
+// anchorRowRange: the rendered rows spanned by a unit range.
+{
+    assert.deepEqual(anchorRowRange(units, 1, 2), { first: 2, last: 3 });
+    assert.deepEqual(anchorRowRange(units, 0, 3), { first: 0, last: 5 });
+    assert.equal(anchorRowRange(units, 9, 9), null);
+}
+// scrollToReveal: margin-aware reveal, top pin for oversize spans, clamping.
+{
+    assert.equal(scrollToReveal(0, 10, 11, 8, 30, 2), 6, 'reveals a below-view anchor with a bottom margin');
+    assert.equal(scrollToReveal(6, 1, 1, 8, 30, 2), 0, 'reveals an above-view anchor, clamped at the top');
+    assert.equal(scrollToReveal(0, 4, 20, 8, 30), 3, 'a taller-than-view span pins its first row one below the indicator row');
+    assert.equal(scrollToReveal(0, 0, 20, 8, 30), 0, 'an oversize span starting at the top pins at zero');
+    assert.equal(scrollToReveal(3, 5, 6, 8, 30), 3, 'an already-visible anchor leaves the scroll untouched');
+    assert.equal(scrollToReveal(50, 25, 25, 8, 30, 2), 22, 'a stale overshoot scroll is clamped into the document');
+    // The margin yields before it may push the span's own edges out of view.
+    assert.equal(scrollToReveal(0, 10, 16, 8, 30, 2), 10, 'down-reveal of a bodyHeight-1 span keeps its first row visible');
+    assert.equal(scrollToReveal(20, 10, 16, 8, 30, 2), 9, 'up-reveal of a bodyHeight-1 span keeps its last row visible');
+    assert.equal(scrollToReveal(0, 10, 10, 2, 30, 2), 10, 'a tiny viewport still shows the anchored row itself');
+}
+// ensureAnchorVisible follows the active unit's rendered rows.
+{
+    let state = initReviewState(sourceLines, anchor, [], 0);
+    state = { ...state, activeUnit: 3, scroll: 0 };
+    state = ensureAnchorVisible(state, doc, 2);
+    assert.equal(state.scroll, 4, 'the anchored unit\'s rows scroll into view');
+}
+// Scroll clamps to [0, totalLines - bodyHeight] and never goes negative.
+{
+    let state = initReviewState(sourceLines, anchor, [], 0);
+    state = scrollBy(state, -50, 10, 30);
+    assert.equal(state.scroll, 0, 'scroll cannot go negative');
+    state = scrollBy(state, 50, 10, 30);
+    assert.equal(state.scroll, 20, 'scroll clamps to the maximum');
+    state = scrollBy(state, 50, 10, 30);
+    assert.equal(state.scroll, 20, 'scroll stays clamped on repeated overshoot');
+}
+// Multi-line text-buffer helpers used by the compose input.
+{
+    let r = textInsert('', 0, 'hello');
+    assert.deepEqual(r, { buffer: 'hello', cursor: 5 });
+    r = textInsert(r.buffer, 5, '\nworld');
+    assert.deepEqual(r, { buffer: 'hello\nworld', cursor: 11 });
+    assert.equal(textHome(r.buffer, 11), 6, 'home jumps to the start of the current line');
+    assert.equal(textEnd(r.buffer, 6), 11, 'end jumps to the end of the current line');
+    assert.equal(textVertical(r.buffer, 8, -1), 2, 'up preserves the column on the previous line');
+    r = textBackspace(r.buffer, 11);
+    assert.deepEqual(r, { buffer: 'hello\nworl', cursor: 10 });
+}
+// Word motion and visual (wrapped) vertical motion in the compose box: alt+arrow
+// steps whole words, and up/down step the rows the box actually paints — a long
+// soft-wrapped comment is many visual rows even though it is one logical line.
+{
+    const b = 'alpha beta gamma';
+    assert.equal(textWordLeft(b, 16), 11, 'alt+left lands on the start of the word before the cursor');
+    assert.equal(textWordLeft(b, 11), 6, 'alt+left from a word start skips to the previous word');
+    assert.equal(textWordRight(b, 0), 5, 'alt+right lands just past the current word');
+    assert.equal(textWordRight(b, 5), 10, 'alt+right skips the space then the next word');
+    assert.deepEqual(textWordBackspace(b, 16), { buffer: 'alpha beta ', cursor: 11 }, 'alt+backspace erases one word');
+    // width 6 wraps into rows 'alpha ' | 'beta g' | 'amma'.
+    assert.equal(textVerticalWrapped(b, 2, 1, 6), 8, 'down moves to the next wrapped row, same column');
+    assert.equal(textVerticalWrapped(b, 8, -1, 6), 2, 'up moves back to the previous wrapped row');
+    assert.equal(textVerticalWrapped(b, 2, -1, 6), 2, 'up on the first row is a no-op');
+    assert.equal(textVerticalWrapped(b, 15, 1, 6), 15, 'down on the last row is a no-op');
+    assert.equal(textVerticalWrapped('ab\ncd', 1, 1, 40), 4, 'hard newlines still separate rows');
+}
+// Render frame: the anchor highlight (gutter bar + tint) covers exactly the
+// active unit's rows — one bullet, not the whole list — plus commented-unit
+// markers and a key-hints-only footer.
+{
+    let state = initReviewState(sourceLines, anchor, [], 0);
+    state = moveActiveUnit(state, 1, false); // first bullet (rendered row 2)
+    const frame = renderReviewFrame(state, 'doc.md', doc, 60, 20);
+    assert.equal(frame.length, 20, 'the frame always fills the requested row count');
+    const joined = frame.join('\n');
+    assert.match(joined, /Review — doc\.md/);
+    assert.match(joined, /0 comments/);
+    assert.ok(!joined.includes('Anchor:'), 'the view footer carries no anchor caption');
+    // Header is 3 rows; body row i shows doc row scroll+i.
+    const bodyRow2 = frame[3 + 2];
+    const bodyRow3 = frame[3 + 3];
+    const bodyRow0 = frame[3];
+    assert.ok(bodyRow2.includes('▌') && bodyRow2.includes('\x1b[48;5;236m'), 'the anchored bullet row gets the gutter bar and tint');
+    assert.ok(!bodyRow3.includes('▌'), 'the sibling bullet in the same list block is NOT highlighted');
+    assert.ok(!bodyRow0.includes('▌'), 'non-anchored rows carry no anchor gutter');
+    // A comment on the paragraph marks its rows with the commented gutter.
+    state = {
+        ...state,
+        comments: [existingComment],
+    };
+    const frame2 = renderReviewFrame(state, 'doc.md', doc, 60, 20);
+    assert.ok(frame2[3 + 5].includes('▎'), 'commented units get the comment gutter marker');
+    assert.ok(!frame2[3 + 3].includes('▎'), 'uncommented sibling units carry no comment marker');
+}
+// ── Regression: a Mermaid diagram wider than the pane (reported bug) ────────
+// Wide diagram rows used to run past the terminal's right edge; the spillover
+// wrapped and was unreachable. Every emitted row must now fit the frame, and
+// h/l must reach the far end of the diagram.
+{
+    const wide = '\u2500'.repeat(300);
+    const wideDoc = {
+        lines: ['TITLE', '', wide, '', 'tail'],
+        rows: [0, null, 1, null, 2],
+        spans: [[1, 1], null, [3, 3], null, [5, 5]],
+        blocks: [
+            { type: 'heading', start: 1, end: 1 },
+            { type: 'mermaid', start: 3, end: 3 },
+            { type: 'paragraph', start: 5, end: 5 },
+        ],
+    };
+    const cols = 80;
+    let s = initReviewState(['# t', '', 'diagram', '', 'tail'], deriveAnchorUnits(wideDoc), [], 0);
+    const widths = (frame) => frame.map((line) => stringWidth(line));
+    const frame = renderReviewFrame(s, 'doc.md', wideDoc, cols, 20);
+    assert.ok(Math.max(...widths(frame)) <= cols, 'every frame row fits inside the terminal');
+    // The readable column stays centered while a full-pane diagram enters and
+    // leaves the viewport; only the diagram rows claim the pane.
+    const titleIndent = (at) => {
+        const title = renderReviewFrame({ ...s, scroll: at }, 'doc.md', wideDoc, 200, 7)[1];
+        return title.match(/^ */)?.[0].length ?? 0;
+    };
+    assert.equal(titleIndent(1), titleIndent(0), 'a visible wide diagram does not pull the review column left');
+    assert.equal(titleIndent(2), titleIndent(0), 'the review column remains fixed after scrolling past the diagram');
+    assert.ok(frame[3 + 2].includes('\u203a'), 'a diagram continuing to the right says so');
+    assert.ok(!frame[3 + 2].includes('\u2039'), 'nothing is hidden to the left at offset 0');
+    // h/l pan is bounded by what the visible rows actually overflow by.
+    const max = maxHScroll(s, wideDoc, cols, 20);
+    assert.equal(max, 300 - (cols - 4), 'pan reach is the widest visible row minus the body rectangle');
+    s = panBy(s, 10_000, wideDoc, cols, 20);
+    assert.equal(s.hscroll, max, 'panning right clamps at the end of the diagram');
+    const panned = renderReviewFrame(s, 'doc.md', wideDoc, cols, 20);
+    assert.ok(Math.max(...widths(panned)) <= cols, 'panned rows stay inside the terminal too');
+    assert.ok(panned[3 + 2].includes('\u2039'), 'a diagram continuing to the left says so');
+    assert.ok(!panned[3 + 2].includes('\u203a'), 'the far edge of the diagram is reachable');
+    // Prose rows never move under panning — only overflowing rows do.
+    assert.equal(panned[3 + 4].replace(/\x1b\[[0-9;]*m/g, '').trim(), 'tail');
+    s = panBy(s, -10_000, wideDoc, cols, 20);
+    assert.equal(s.hscroll, 0, 'panning left returns to the diagram start');
+}
+console.log('terminal review tests passed');

package/dist/clients/inbox/review/anchors.d.ts

@@ -0,0 +1,41 @@
+import type { RenderedDoc } from '../../../core/termrender/termrender.js';
+/** 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;
+/** 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;
+};