@crouton-kit/humanloop 0.4.3 → 0.4.4

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

@@ -1,5 +1,11 @@
 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 {
+    start: number;
+    end: number;
+}
 export interface ComposeState {
     buffer: string;
     cursor: number;
@@ -14,11 +20,13 @@ export interface ComposeState {
 }
 export interface ReviewState {
     sourceLines: string[];
+    /** Top-level block source ranges, in document order. Never empty. */
+    blocks: BlockRange[];
     comments: FeedbackComment[];
     version: number;
-    /** 1-based active source line. */
-    activeLine: number;
-    /** Set while a Shift+j/k range is being extended from this line. */
+    /** 0-based index of the anchored block. */
+    activeBlock: number;
+    /** Set while a Shift+j/k range is being extended from this block. */
     selectionAnchor: number | null;
     /** Scroll offset into the rendered (termrender) lines. */
     scroll: number;
@@ -26,12 +34,38 @@ export interface ReviewState {
     compose: ComposeState | null;
     listIndex: number;
 }
-export declare function initReviewState(sourceLines: string[], comments: FeedbackComment[], version: number): ReviewState;
+/** 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`. */
 export declare function currentAnchor(state: ReviewState): {
     line: number;
     endLine: number;
 };
-export declare function moveActiveLine(state: ReviewState, delta: number, extend: boolean): ReviewState;
+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
+ *  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): {
+    first: number;
+    last: number;
+} | null;
+/** Minimal scroll adjustment that keeps rows `first..last` visible with
+ *  `margin` rows of context (the margin yields whenever honoring it would push
+ *  either edge of the span out of view); a taller-than-view span pins `first`
+ *  at the top — one row down when scrolled, so the `↑ more above` indicator
+ *  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
+ *  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;
 export declare function openComposeNew(state: ReviewState): ReviewState;
 export declare function openComposeEdit(state: ReviewState, index: number): ReviewState;
@@ -60,17 +94,22 @@ export declare function textDelete(buffer: string, cursor: number): {
 export declare function textHome(buffer: string, cursor: number): number;
 export declare function textEnd(buffer: string, cursor: number): number;
 export declare function textVertical(buffer: string, cursor: number, delta: number): number;
+/** Width the document is rendered at for a given terminal width: 2-col left
+ *  margin + 2-col gutter before the content, capped for readability. */
+export declare function renderWidthForCols(cols: number): number;
 /** Reserved (non-body) rows for each mode's fixed header/footer chrome. Kept in
- *  sync with renderReviewFrame so scroll math can clamp before a repaint. */
-export declare function reservedRows(state: ReviewState): number;
-export declare function renderReviewFrame(state: ReviewState, fileLabel: string, renderedLines: string[], cols: number, rows: number): string[];
+ *  sync with renderReviewFrame so scroll math can clamp before a repaint — the
+ *  compose case counts the same hard-wrapped input lines the frame renders. */
+export declare function reservedRows(state: ReviewState, cols: number): number;
+export declare function renderReviewFrame(state: ReviewState, fileLabel: string, doc: RenderedDoc, cols: number, rows: number): string[];
 /**
  * Open a Markdown file in humanloop's own terminal review surface: the
- * document renders via termrender (Mermaid included), source-line anchors
- * drive comments independent of rendered scroll position, 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`.
+ * 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`.
  */
 export declare function launchTerminalReview(file: string, opts: ReviewOptions): Promise<FeedbackResult>;

package/dist/editor/terminal-review.js

@@ -1,17 +1,29 @@
 import { randomUUID } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { basename, resolve } from 'node:path';
+import stringWidth from 'string-width';
 import { buildDraftFeedbackResult, buildFinalFeedbackResult, readReviewDraft, writeReviewDraft } from './feedback.js';
-import { renderMarkdown } from '../render/termrender.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, RESET, YELLOW, hline, sanitize, truncate } from '../tui/ansi.js';
-export function initReviewState(sourceLines, comments, version) {
+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)
+            return i;
+    }
+    return Math.max(0, blocks.length - 1);
+}
+export function initReviewState(sourceLines, blocks, comments, version) {
+    const safeBlocks = blocks.length > 0 ? blocks : [{ start: 1, end: Math.max(1, sourceLines.length) }];
     return {
         sourceLines,
+        blocks: safeBlocks,
         comments: [...comments],
         version,
-        activeLine: comments.length > 0 ? comments[0].line : 1,
+        activeBlock: comments.length > 0 ? blockIndexForLine(safeBlocks, comments[0].line) : 0,
         selectionAnchor: null,
         scroll: 0,
         mode: 'view',
@@ -19,17 +31,84 @@ export function initReviewState(sourceLines, 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) };
+}
+/** Source-line anchor of the current block selection — what a committed
+ *  comment records as `line`/`endLine`. */
 export function currentAnchor(state) {
-    if (state.selectionAnchor === null)
-        return { line: state.activeLine, endLine: state.activeLine };
-    return { line: Math.min(state.selectionAnchor, state.activeLine), endLine: Math.max(state.selectionAnchor, state.activeLine) };
+    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 moveActiveLine(state, delta, extend) {
-    const total = Math.max(1, state.sourceLines.length);
-    const next = Math.max(1, Math.min(total, state.activeLine + delta));
+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));
     if (!extend)
-        return { ...state, activeLine: next, selectionAnchor: null };
-    return { ...state, activeLine: next, selectionAnchor: state.selectionAnchor ?? state.activeLine };
+        return { ...state, activeBlock: next, selectionAnchor: null };
+    return { ...state, activeBlock: next, selectionAnchor: state.selectionAnchor ?? state.activeBlock };
+}
+/** 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
+ *  is visible somewhere in the document. */
+export function commentedBlockSet(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) {
+                out.add(i);
+                hit = true;
+            }
+        });
+        if (!hit)
+            out.add(blockIndexForLine(state.blocks, 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 };
+}
+/** Minimal scroll adjustment that keeps rows `first..last` visible with
+ *  `margin` rows of context (the margin yields whenever honoring it would push
+ *  either edge of the span out of view); a taller-than-view span pins `first`
+ *  at the top — one row down when scrolled, so the `↑ more above` indicator
+ *  overwrites the preceding row, never the pinned one. Always returns a scroll
+ *  clamped to the document. */
+export function scrollToReveal(scroll, first, last, bodyHeight, total, margin = 2) {
+    const maxScroll = Math.max(0, total - bodyHeight);
+    let next = Math.max(0, Math.min(scroll, maxScroll));
+    if (last - first + 1 >= bodyHeight)
+        return Math.max(0, Math.min(Math.max(0, first - 1), maxScroll));
+    if (first - margin < next)
+        next = Math.max(first - margin, last - (bodyHeight - 1));
+    else if (last + margin > next + bodyHeight - 1)
+        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
+ *  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);
+    if (range === null)
+        return state;
+    const scroll = scrollToReveal(state.scroll, range.first, range.last, bodyHeight, doc.lines.length);
+    return scroll === state.scroll ? state : { ...state, scroll };
 }
 export function scrollBy(state, delta, bodyHeight, totalLines) {
     const maxScroll = Math.max(0, totalLines - bodyHeight);
@@ -43,8 +122,12 @@ 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);
     return {
         ...state,
+        activeBlock: 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 } },
     };
@@ -168,23 +251,40 @@ export function textVertical(buffer, cursor, delta) {
     return Math.min(nextEnd, nextStart + col);
 }
 // ── Rendering (pure) ─────────────────────────────────────────────────────────
+/** Width the document is rendered at for a given terminal width: 2-col left
+ *  margin + 2-col gutter before the content, capped for readability. */
+export function renderWidthForCols(cols) {
+    return Math.min(Math.max(20, cols - 6), 120);
+}
+// Single-hue anchor tint (a dark neutral step below the CYAN gutter bar).
+// termrender's only reset is `\x1b[0m`, so re-arming the background after each
+// reset keeps the tint alive across inner styling. Heading rows carry their
+// own background and won't show the tint — the gutter bar still marks them.
+const TINT_BG = `${ESC}48;5;236m`;
+function tintRow(row, width) {
+    const pad = Math.max(0, width - stringWidth(sanitize(row)));
+    return TINT_BG + row.replaceAll(RESET, RESET + TINT_BG) + ' '.repeat(pad) + RESET;
+}
 /** Reserved (non-body) rows for each mode's fixed header/footer chrome. Kept in
- *  sync with renderReviewFrame so scroll math can clamp before a repaint. */
-export function reservedRows(state) {
+ *  sync with renderReviewFrame so scroll math can clamp before a repaint — the
+ *  compose case counts the same hard-wrapped input lines the frame renders. */
+export function reservedRows(state, cols) {
     const header = 3; // blank, title, divider
     if (state.mode === 'view')
-        return header + 2;
+        return header + 1;
     if (state.mode === 'compose') {
         const c = state.compose;
-        const bufLines = c ? Math.max(1, c.buffer.split('\n').length) : 1;
+        const maxW = Math.min(Math.max(20, cols - 4), 120);
+        const bufLines = c ? renderInputBuffer(c.buffer, c.cursor, Math.max(10, maxW - 2)).length : 1;
         return header + 3 + bufLines;
     }
     if (state.mode === 'list')
         return header + Math.max(1, state.comments.length) + 2;
     return header + 8; // help
 }
-export function renderReviewFrame(state, fileLabel, renderedLines, cols, rows) {
+export function renderReviewFrame(state, fileLabel, doc, cols, rows) {
     const maxW = Math.min(Math.max(20, cols - 4), 120);
+    const docW = renderWidthForCols(cols);
     const header = [
         '',
         `  ${BOLD}${CYAN}Review — ${fileLabel}${RESET}  ${DIM}${state.comments.length} comment${state.comments.length === 1 ? '' : 's'}${RESET}`,
@@ -217,7 +317,7 @@ export function renderReviewFrame(state, fileLabel, renderedLines, cols, rows) {
     }
     else if (state.mode === 'help') {
         footer.push('  Keys:');
-        footer.push(`  ${DIM}j/k${RESET}         move anchor line       ${DIM}shift+j/k${RESET}   extend range`);
+        footer.push(`  ${DIM}j/k${RESET}         move anchor block      ${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`);
@@ -226,21 +326,34 @@ export function renderReviewFrame(state, fileLabel, renderedLines, cols, rows) {
         footer.push(`  ${DIM}esc / ?${RESET} close`);
     }
     else {
-        const anchor = currentAnchor(state);
-        const label = anchor.line === anchor.endLine ? `L${anchor.line}` : `L${anchor.line}-${anchor.endLine}`;
-        const preview = truncate(sanitize(state.sourceLines.slice(anchor.line - 1, anchor.endLine).join(' / ')), Math.max(10, maxW - 20));
-        footer.push(`  ${DIM}Anchor:${RESET} ${CYAN}${label}${RESET}  ${DIM}${preview}${RESET}`);
-        footer.push(`  ${DIM}j/k${RESET} anchor  ${DIM}shift-j/k${RESET} range  ${DIM}u/d${RESET} scroll  ${DIM}space c${RESET} comment  ` +
+        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`);
     }
     const reserved = header.length + footer.length;
     const bodyHeight = Math.max(1, rows - reserved);
-    const maxScroll = Math.max(0, renderedLines.length - bodyHeight);
+    const maxScroll = Math.max(0, doc.lines.length - bodyHeight);
     const scroll = Math.max(0, Math.min(state.scroll, maxScroll));
-    const body = renderedLines.slice(scroll, scroll + bodyHeight).map((l) => `  ${l}`);
+    const { lo, hi } = selectedBlockBounds(state);
+    const commented = commentedBlockSet(state);
+    const body = [];
+    for (let i = 0; i < bodyHeight; i++) {
+        const abs = scroll + i;
+        if (abs >= doc.lines.length) {
+            body.push('');
+            continue;
+        }
+        const row = doc.lines[abs];
+        const b = doc.rows[abs] ?? null;
+        if (b !== null && b >= lo && b <= hi)
+            body.push(`  ${CYAN}▌${RESET} ${tintRow(row, docW)}`);
+        else if (b !== null && commented.has(b))
+            body.push(`  ${YELLOW}▎${RESET} ${row}`);
+        else
+            body.push(`    ${row}`);
+    }
     if (scroll > 0 && body.length > 0)
         body[0] = `  ${DIM}↑ ${scroll} more above${RESET}`;
-    const remaining = renderedLines.length - (scroll + bodyHeight);
+    const remaining = doc.lines.length - (scroll + bodyHeight);
     if (remaining > 0 && body.length > 0)
         body[body.length - 1] = `  ${DIM}↓ ${remaining} more below${RESET}`;
     while (body.length < bodyHeight)
@@ -253,12 +366,13 @@ export function renderReviewFrame(state, fileLabel, renderedLines, cols, rows) {
 // ── Host loop (impure — the only part that touches the real TTY) ───────────
 /**
  * Open a Markdown file in humanloop's own terminal review surface: the
- * document renders via termrender (Mermaid included), source-line anchors
- * drive comments independent of rendered scroll position, 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`.
+ * 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`.
  */
 export async function launchTerminalReview(file, opts) {
     const absFile = resolve(file);
@@ -266,24 +380,25 @@ export async function launchTerminalReview(file, opts) {
     const sourceLines = content.split('\n');
     const outPath = resolve(opts.output);
     const draft = readReviewDraft(outPath);
-    let state = initReviewState(sourceLines, draft?.comments ?? [], draft?.version ?? 0);
     const fileLabel = basename(absFile);
     if (opts.signal?.aborted)
-        return buildDraftFeedbackResult(absFile, state.comments, draft?.savedAt);
+        return buildDraftFeedbackResult(absFile, draft?.comments ?? [], draft?.savedAt);
     setupTerminal();
     let { cols, rows } = getTerminalSize();
-    let renderedWidth = Math.min(Math.max(20, cols - 4), 120);
-    let renderedLines = renderMarkdown(content, renderedWidth);
+    let doc = renderMarkdownWithMap(content, renderWidthForCols(cols));
+    let state = initReviewState(sourceLines, doc.blocks, draft?.comments ?? [], draft?.version ?? 0);
     let prevFrame = [];
     let spaceArmed = false;
     let settled = false;
+    const bodyH = () => Math.max(1, rows - reservedRows(state, cols));
+    state = ensureAnchorVisible(state, doc, bodyH());
     return new Promise((resolvePromise) => {
         const persist = () => {
             state = { ...state, version: state.version + 1 };
             writeReviewDraft(outPath, state.comments, state.version);
         };
         const paint = (clear = false) => {
-            const lines = renderReviewFrame(state, fileLabel, renderedLines, cols, rows);
+            const lines = renderReviewFrame(state, fileLabel, doc, cols, rows);
             if (clear) {
                 prevFrame = [];
                 process.stdout.write('\x1b[2J\x1b[H');
@@ -307,8 +422,20 @@ export async function launchTerminalReview(file, opts) {
         };
         const onResize = () => {
             ({ cols, rows } = getTerminalSize());
-            renderedWidth = Math.min(Math.max(20, cols - 4), 120);
-            renderedLines = renderMarkdown(content, renderedWidth);
+            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);
+            state = {
+                ...state,
+                blocks,
+                activeBlock: Math.min(state.activeBlock, lastIdx),
+                selectionAnchor: state.selectionAnchor === null ? null : Math.min(state.selectionAnchor, lastIdx),
+            };
+            state = ensureAnchorVisible(state, doc, bodyH());
             paint(true);
         };
         const onAbort = () => {
@@ -405,8 +532,10 @@ export async function launchTerminalReview(file, opts) {
                 return;
             }
             if (input === 'e' || key.return) {
-                if (state.comments.length > 0)
+                if (state.comments.length > 0) {
                     state = openComposeEdit(state, state.listIndex);
+                    state = ensureAnchorVisible(state, doc, bodyH());
+                }
                 return;
             }
             if (input === 'd') {
@@ -432,8 +561,10 @@ export async function launchTerminalReview(file, opts) {
             }
             if (spaceArmed) {
                 spaceArmed = false;
-                if (input === 'c')
+                if (input === 'c') {
                     state = openComposeNew(state);
+                    state = ensureAnchorVisible(state, doc, bodyH());
+                }
                 else if (input === 'l')
                     state = openList(state);
                 else if (input === 'u') {
@@ -463,18 +594,26 @@ export async function launchTerminalReview(file, opts) {
                 spaceArmed = true;
                 return;
             }
-            if (input === 'j' || key.downArrow)
-                state = moveActiveLine(state, 1, false);
-            else if (input === 'k' || key.upArrow)
-                state = moveActiveLine(state, -1, false);
-            else if (input === 'J')
-                state = moveActiveLine(state, 1, true);
-            else if (input === 'K')
-                state = moveActiveLine(state, -1, true);
+            if (input === 'j' || key.downArrow) {
+                state = moveActiveBlock(state, 1, false);
+                state = ensureAnchorVisible(state, doc, bodyH());
+            }
+            else if (input === 'k' || key.upArrow) {
+                state = moveActiveBlock(state, -1, false);
+                state = ensureAnchorVisible(state, doc, bodyH());
+            }
+            else if (input === 'J') {
+                state = moveActiveBlock(state, 1, true);
+                state = ensureAnchorVisible(state, doc, bodyH());
+            }
+            else if (input === 'K') {
+                state = moveActiveBlock(state, -1, true);
+                state = ensureAnchorVisible(state, doc, bodyH());
+            }
             else if (input === 'u' || key.pageUp)
-                state = scrollBy(state, -Math.max(1, rows - reservedRows(state)), Math.max(1, rows - reservedRows(state)), renderedLines.length);
+                state = scrollBy(state, -bodyH(), bodyH(), doc.lines.length);
             else if (input === 'd' || key.pageDown)
-                state = scrollBy(state, Math.max(1, rows - reservedRows(state)), Math.max(1, rows - reservedRows(state)), renderedLines.length);
+                state = scrollBy(state, bodyH(), bodyH(), doc.lines.length);
             else if (input === '?')
                 state = openHelp(state);
             else if (key.escape) {

package/dist/render/termrender.d.ts

@@ -17,6 +17,20 @@ export declare function ensureRenderer(): void;
 export declare function isRendererReady(): boolean;
 /** Render markdown to terminal lines via the pinned binary; plaintext fallback. */
 export declare function renderMarkdown(md: string, width: number): string[];
+export interface RenderedDoc {
+    /** Rendered ANSI rows — byte-identical to the plain `doc render` output. */
+    lines: string[];
+    /** Per-row index into `blocks`; null for the blank separator rows between blocks. */
+    rows: (number | null)[];
+    /** Per top-level block: 1-indexed inclusive source-line bounds. Never empty. */
+    blocks: {
+        start: number;
+        end: number;
+    }[];
+}
+/** Render markdown with a row→source-line map via the pinned binary
+ *  (`doc render --line-map`); plaintext paragraph-block fallback. */
+export declare function renderMarkdownWithMap(md: string, width: number): RenderedDoc;
 /** Validate markdown via `termrender doc check`. */
 export declare function checkMarkdown(md: string): {
     ok: true;

package/dist/render/termrender.js

@@ -492,6 +492,125 @@ export function renderMarkdown(md, width) {
     _bodyCache.set(key, fallback);
     return fallback;
 }
+/** Validate + normalize `doc render --line-map` JSON into a RenderedDoc.
+ *  Null block bounds (a scanner edge case) are filled from neighbors and
+ *  clamped into the source range; an empty block list gets one whole-doc
+ *  block so callers can always anchor. Malformed shape → null (tool fault). */
+function parseRenderedDoc(out, source) {
+    let parsed;
+    try {
+        parsed = JSON.parse(out);
+    }
+    catch {
+        return null;
+    }
+    const p = parsed;
+    if (!Array.isArray(p.lines) || !Array.isArray(p.rows) || !Array.isArray(p.blocks))
+        return null;
+    if (p.rows.length !== p.lines.length)
+        return null;
+    if (!p.lines.every((l) => typeof l === 'string'))
+        return null;
+    const blockCount = p.blocks.length;
+    if (!p.rows.every((r) => r === null || (typeof r === 'number' && Number.isInteger(r) && r >= 0 && r < blockCount)))
+        return null;
+    const totalSource = Math.max(1, source.split('\n').length);
+    const blocks = [];
+    let prevEnd = 0;
+    for (const raw of p.blocks) {
+        if (typeof raw !== 'object' || raw === null)
+            return null;
+        // Bounds are integers or null — a fractional bound would otherwise flow
+        // into a recorded comment's line/endLine instead of tripping tool-fault.
+        if (raw.start != null && !Number.isInteger(raw.start))
+            return null;
+        if (raw.end != null && !Number.isInteger(raw.end))
+            return null;
+        const start = typeof raw.start === 'number' ? raw.start : prevEnd + 1;
+        const end = typeof raw.end === 'number' ? Math.max(raw.end, start) : start;
+        const s = Math.max(1, Math.min(start, totalSource));
+        const e = Math.max(s, Math.min(end, totalSource));
+        blocks.push({ start: s, end: e });
+        prevEnd = e;
+    }
+    if (blocks.length === 0)
+        blocks.push({ start: 1, end: totalSource });
+    return { lines: p.lines, rows: p.rows, 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. */
+function fallbackDocWithMap(md, width) {
+    const src = sanitize(md).split('\n');
+    const blocks = [];
+    let openAt = null;
+    for (let i = 0; i < src.length; i++) {
+        if (src[i].trim() !== '') {
+            if (openAt === null)
+                openAt = i;
+        }
+        else if (openAt !== null) {
+            blocks.push({ start: openAt + 1, end: i });
+            openAt = null;
+        }
+    }
+    if (openAt !== null)
+        blocks.push({ start: openAt + 1, end: src.length });
+    if (blocks.length === 0)
+        blocks.push({ start: 1, end: Math.max(1, src.length) });
+    const lines = [];
+    const rows = [];
+    blocks.forEach((b, bi) => {
+        if (bi > 0) {
+            lines.push('');
+            rows.push(null);
+        }
+        for (const l of wrap(src.slice(b.start - 1, b.end).join('\n'), width)) {
+            lines.push(l);
+            rows.push(bi);
+        }
+    });
+    return { lines, rows, blocks };
+}
+const _mapCache = new Map();
+/** Render markdown with a row→source-line map via the pinned binary
+ *  (`doc render --line-map`); plaintext paragraph-block fallback. */
+export function renderMarkdownWithMap(md, width) {
+    const key = `${md}\0${width}`;
+    const cached = _mapCache.get(key);
+    if (cached)
+        return cached;
+    ensureRenderer();
+    if (rendererState === 'ready') {
+        try {
+            const out = execFileSync(VENV_BIN, ['doc', 'render', '--width', String(width), '--color', 'on', '--line-map'], {
+                input: md,
+                encoding: 'utf-8',
+                timeout: 5000,
+                stdio: ['pipe', 'pipe', 'pipe'],
+                // JSON-escaped ANSI inflates well past execFileSync's 1MB default.
+                maxBuffer: 64 * 1024 * 1024,
+            });
+            const doc = parseRenderedDoc(out.trim(), md);
+            if (doc !== null) {
+                _mapCache.set(key, doc);
+                return doc;
+            }
+            // A working renderer never emits a malformed map — tool fault.
+            invalidateRenderer('doc render --line-map (malformed output)');
+        }
+        catch (err) {
+            // Same contract as renderMarkdown: non-timeout failure implicates the
+            // tool; a timeout is a slow/large doc — just fall to the local map.
+            if (!isTimeout(err))
+                invalidateRenderer('doc render --line-map');
+        }
+    }
+    // The fallback is cheap to recompute and deliberately NOT cached: a
+    // transient failure (e.g. a timeout) must not pin degraded block anchoring
+    // for the rest of the session when a later re-render could succeed.
+    return fallbackDocWithMap(md, width);
+}
 /** Validate markdown via `termrender doc check`. */
 export function checkMarkdown(md) {
     ensureRenderer();

package/dist/render/version.d.ts

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

package/dist/render/version.js

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

package/package.json

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