@crouton-kit/humanloop 0.4.5 → 0.4.7

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,8 +141,9 @@ 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.
+ * 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

package/dist/editor/terminal-review.js

@@ -11,23 +11,106 @@ 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',
@@ -35,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
@@ -105,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);
@@ -126,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 } },
@@ -321,7 +408,7 @@ 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`);
@@ -331,15 +418,15 @@ export function renderReviewFrame(state, fileLabel, doc, cols, rows) {
         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  ` +
+        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;
@@ -348,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}`);
@@ -375,8 +462,9 @@ function diskDraftResult(absFile, outPath) {
 /**
  * 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.
+ * 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
@@ -450,7 +538,7 @@ function runTerminalReviewSession(absFile, content, outPath, fileLabel, opts) {
     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;
@@ -488,17 +576,20 @@ function runTerminalReviewSession(absFile, content, outPath, fileLabel, opts) {
         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);
@@ -665,19 +756,19 @@ function runTerminalReviewSession(absFile, content, outPath, fileLabel, 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/dist/web/assets/{abnfDiagram-VRR7QNED-B71KRG4-.js → abnfDiagram-VRR7QNED-DTJq6212.js}

@@ -1 +1 @@
-import{m as e,t}from"./mermaid-parser.core-BbWtntfd.js";import{n}from"./chunk-Y2CYZVJY-DsF7k-Jl.js";import{m as r}from"./src-COFaHe7g.js";import"./chunk-WYO6CB5R-NSErcIKL.js";import"./chunk-VAUOI2AC-CtE8-0Em.js";import{n as i,r as a,t as o}from"./chunk-MOJQB5TN-CNuZ6pa2.js";import{t as s}from"./chunk-JWPE2WC7-DVXcaiue.js";var c=e().RailroadAbnf.parser.LangiumParser,l=n(e=>{let t=e.alternatives.map(u);return t.length===1?t[0]:{type:`choice`,alternatives:t}},`transformAlternation`),u=n(e=>{let t=e.elements.map(f);return t.length===1?t[0]:{type:`sequence`,elements:t}},`transformConcatenation`),d=n(e=>{if(e.includes(`*`)){let[t,n]=e.split(`*`);return{min:t?parseInt(t,10):0,max:n?parseInt(n,10):1/0}}let t=parseInt(e,10);return{min:t,max:t}},`parseRepeat`),f=n(e=>{let t=p(e.primary);if(!e.repeat)return t;let{min:n,max:r}=d(e.repeat);return n===0&&r===1?{type:`optional`,element:t}:{type:`repetition`,element:t,min:n,max:r}},`transformElement`),p=n(e=>{switch(e.$type){case`AbnfStringLiteral`:return{type:`terminal`,value:e.value};case`AbnfNumVal`:return{type:`terminal`,value:e.value};case`AbnfRuleName`:return{type:`nonterminal`,name:e.name};case`AbnfGroup`:return l(e.element);case`AbnfOptionalGroup`:return{type:`optional`,element:l(e.element)};default:throw Error(`Unsupported ABNF primary node: ${e.$type}`)}},`transformPrimary`),m=n(e=>({name:e.name,definition:l(e.definition)}),`transformRule`),h=n(e=>{s(e,o),e.title&&o.setTitle(e.title),e.rules.map(e=>o.addRule(m(e)))},`populateDb`),g={parser:{parse:n(e=>{o.clear(),r.debug(`[ABNF Parser] Starting Langium parse`);let n=c.parse(e);if(n.lexerErrors.length>0||n.parserErrors.length>0)throw new t(n);let i=n.value;r.debug(`[ABNF Parser] Parsed rules:`,i.rules.length),h(i),r.debug(`[ABNF Parser] Parse complete`)},`parse`),parser:{yy:o}},db:o,renderer:a,styles:i};export{g as diagram};
+import{m as e,t}from"./mermaid-parser.core-DvKEagUi.js";import{n}from"./chunk-Y2CYZVJY-DsF7k-Jl.js";import{m as r}from"./src-Di6WPHCL.js";import"./chunk-WYO6CB5R-CzhFb-MZ.js";import"./chunk-VAUOI2AC-Bq5B95aK.js";import{n as i,r as a,t as o}from"./chunk-MOJQB5TN-CFi0PbZk.js";import{t as s}from"./chunk-JWPE2WC7-DVXcaiue.js";var c=e().RailroadAbnf.parser.LangiumParser,l=n(e=>{let t=e.alternatives.map(u);return t.length===1?t[0]:{type:`choice`,alternatives:t}},`transformAlternation`),u=n(e=>{let t=e.elements.map(f);return t.length===1?t[0]:{type:`sequence`,elements:t}},`transformConcatenation`),d=n(e=>{if(e.includes(`*`)){let[t,n]=e.split(`*`);return{min:t?parseInt(t,10):0,max:n?parseInt(n,10):1/0}}let t=parseInt(e,10);return{min:t,max:t}},`parseRepeat`),f=n(e=>{let t=p(e.primary);if(!e.repeat)return t;let{min:n,max:r}=d(e.repeat);return n===0&&r===1?{type:`optional`,element:t}:{type:`repetition`,element:t,min:n,max:r}},`transformElement`),p=n(e=>{switch(e.$type){case`AbnfStringLiteral`:return{type:`terminal`,value:e.value};case`AbnfNumVal`:return{type:`terminal`,value:e.value};case`AbnfRuleName`:return{type:`nonterminal`,name:e.name};case`AbnfGroup`:return l(e.element);case`AbnfOptionalGroup`:return{type:`optional`,element:l(e.element)};default:throw Error(`Unsupported ABNF primary node: ${e.$type}`)}},`transformPrimary`),m=n(e=>({name:e.name,definition:l(e.definition)}),`transformRule`),h=n(e=>{s(e,o),e.title&&o.setTitle(e.title),e.rules.map(e=>o.addRule(m(e)))},`populateDb`),g={parser:{parse:n(e=>{o.clear(),r.debug(`[ABNF Parser] Starting Langium parse`);let n=c.parse(e);if(n.lexerErrors.length>0||n.parserErrors.length>0)throw new t(n);let i=n.value;r.debug(`[ABNF Parser] Parsed rules:`,i.rules.length),h(i),r.debug(`[ABNF Parser] Parse complete`)},`parse`),parser:{yy:o}},db:o,renderer:a,styles:i};export{g as diagram};

package/dist/web/assets/{arc-BzH4jnTf.js → arc-o4T8NCG8.js}

@@ -1 +1 @@
-import{n as e,t}from"./path-BWPyau1x.js";import{a as n,c as r,d as i,f as a,i as o,l as s,m as c,n as l,o as u,p as d,r as f,u as p}from"./dist-RLVSx5kB.js";function m(e){return e.innerRadius}function h(e){return e.outerRadius}function g(e){return e.startAngle}function _(e){return e.endAngle}function v(e){return e&&e.padAngle}function y(e,t,n,r,i,a,o,s){var c=n-e,l=r-t,u=o-i,d=s-a,f=d*c-u*l;if(!(f*f<1e-12))return f=(u*(t-a)-d*(e-i))/f,[e+f*c,t+f*l]}function b(e,t,n,r,i,a,o){var c=e-n,l=t-r,u=(o?a:-a)/d(c*c+l*l),f=u*l,p=-u*c,m=e+f,h=t+p,g=n+f,_=r+p,v=(m+g)/2,y=(h+_)/2,b=g-m,x=_-h,S=b*b+x*x,C=i-a,w=m*_-g*h,T=(x<0?-1:1)*d(s(0,C*C*S-w*w)),E=(w*x-b*T)/S,D=(-w*b-x*T)/S,O=(w*x+b*T)/S,k=(-w*b+x*T)/S,A=E-v,j=D-y,M=O-v,N=k-y;return A*A+j*j>M*M+N*N&&(E=O,D=k),{cx:E,cy:D,x01:-f,y01:-p,x11:E*(i/C-1),y11:D*(i/C-1)}}function x(){var s=m,x=h,S=e(0),C=null,w=g,T=_,E=v,D=null,O=t(k);function k(){var e,t,m=+s.apply(this,arguments),h=+x.apply(this,arguments),g=w.apply(this,arguments)-r,_=T.apply(this,arguments)-r,v=l(_-g),k=_>g;if(D||=e=O(),h<m&&(t=h,h=m,m=t),!(h>1e-12))D.moveTo(0,0);else if(v>c-1e-12)D.moveTo(h*u(g),h*a(g)),D.arc(0,0,h,g,_,!k),m>1e-12&&(D.moveTo(m*u(_),m*a(_)),D.arc(0,0,m,_,g,k));else{var A=g,j=_,M=g,N=_,P=v,F=v,I=E.apply(this,arguments)/2,L=I>1e-12&&(C?+C.apply(this,arguments):d(m*m+h*h)),R=p(l(h-m)/2,+S.apply(this,arguments)),z=R,B=R,V,H;if(L>1e-12){var U=o(L/m*a(I)),W=o(L/h*a(I));(P-=U*2)>1e-12?(U*=k?1:-1,M+=U,N-=U):(P=0,M=N=(g+_)/2),(F-=W*2)>1e-12?(W*=k?1:-1,A+=W,j-=W):(F=0,A=j=(g+_)/2)}var G=h*u(A),K=h*a(A),q=m*u(N),J=m*a(N);if(R>1e-12){var Y=h*u(j),X=h*a(j),Z=m*u(M),Q=m*a(M),$;if(v<i)if($=y(G,K,Z,Q,Y,X,q,J)){var ee=G-$[0],te=K-$[1],ne=Y-$[0],re=X-$[1],ie=1/a(f((ee*ne+te*re)/(d(ee*ee+te*te)*d(ne*ne+re*re)))/2),ae=d($[0]*$[0]+$[1]*$[1]);z=p(R,(m-ae)/(ie-1)),B=p(R,(h-ae)/(ie+1))}else z=B=0}F>1e-12?B>1e-12?(V=b(Z,Q,G,K,h,B,k),H=b(Y,X,q,J,h,B,k),D.moveTo(V.cx+V.x01,V.cy+V.y01),B<R?D.arc(V.cx,V.cy,B,n(V.y01,V.x01),n(H.y01,H.x01),!k):(D.arc(V.cx,V.cy,B,n(V.y01,V.x01),n(V.y11,V.x11),!k),D.arc(0,0,h,n(V.cy+V.y11,V.cx+V.x11),n(H.cy+H.y11,H.cx+H.x11),!k),D.arc(H.cx,H.cy,B,n(H.y11,H.x11),n(H.y01,H.x01),!k))):(D.moveTo(G,K),D.arc(0,0,h,A,j,!k)):D.moveTo(G,K),!(m>1e-12)||!(P>1e-12)?D.lineTo(q,J):z>1e-12?(V=b(q,J,Y,X,m,-z,k),H=b(G,K,Z,Q,m,-z,k),D.lineTo(V.cx+V.x01,V.cy+V.y01),z<R?D.arc(V.cx,V.cy,z,n(V.y01,V.x01),n(H.y01,H.x01),!k):(D.arc(V.cx,V.cy,z,n(V.y01,V.x01),n(V.y11,V.x11),!k),D.arc(0,0,m,n(V.cy+V.y11,V.cx+V.x11),n(H.cy+H.y11,H.cx+H.x11),k),D.arc(H.cx,H.cy,z,n(H.y11,H.x11),n(H.y01,H.x01),!k))):D.arc(0,0,m,N,M,k)}if(D.closePath(),e)return D=null,e+``||null}return k.centroid=function(){var e=(+s.apply(this,arguments)+ +x.apply(this,arguments))/2,t=(+w.apply(this,arguments)+ +T.apply(this,arguments))/2-i/2;return[u(t)*e,a(t)*e]},k.innerRadius=function(t){return arguments.length?(s=typeof t==`function`?t:e(+t),k):s},k.outerRadius=function(t){return arguments.length?(x=typeof t==`function`?t:e(+t),k):x},k.cornerRadius=function(t){return arguments.length?(S=typeof t==`function`?t:e(+t),k):S},k.padRadius=function(t){return arguments.length?(C=t==null?null:typeof t==`function`?t:e(+t),k):C},k.startAngle=function(t){return arguments.length?(w=typeof t==`function`?t:e(+t),k):w},k.endAngle=function(t){return arguments.length?(T=typeof t==`function`?t:e(+t),k):T},k.padAngle=function(t){return arguments.length?(E=typeof t==`function`?t:e(+t),k):E},k.context=function(e){return arguments.length?(D=e??null,k):D},k}export{x as t};
+import{n as e,t}from"./path-BWPyau1x.js";import{a as n,c as r,d as i,f as a,i as o,l as s,m as c,n as l,o as u,p as d,r as f,u as p}from"./dist-DFjfKcIt.js";function m(e){return e.innerRadius}function h(e){return e.outerRadius}function g(e){return e.startAngle}function _(e){return e.endAngle}function v(e){return e&&e.padAngle}function y(e,t,n,r,i,a,o,s){var c=n-e,l=r-t,u=o-i,d=s-a,f=d*c-u*l;if(!(f*f<1e-12))return f=(u*(t-a)-d*(e-i))/f,[e+f*c,t+f*l]}function b(e,t,n,r,i,a,o){var c=e-n,l=t-r,u=(o?a:-a)/d(c*c+l*l),f=u*l,p=-u*c,m=e+f,h=t+p,g=n+f,_=r+p,v=(m+g)/2,y=(h+_)/2,b=g-m,x=_-h,S=b*b+x*x,C=i-a,w=m*_-g*h,T=(x<0?-1:1)*d(s(0,C*C*S-w*w)),E=(w*x-b*T)/S,D=(-w*b-x*T)/S,O=(w*x+b*T)/S,k=(-w*b+x*T)/S,A=E-v,j=D-y,M=O-v,N=k-y;return A*A+j*j>M*M+N*N&&(E=O,D=k),{cx:E,cy:D,x01:-f,y01:-p,x11:E*(i/C-1),y11:D*(i/C-1)}}function x(){var s=m,x=h,S=e(0),C=null,w=g,T=_,E=v,D=null,O=t(k);function k(){var e,t,m=+s.apply(this,arguments),h=+x.apply(this,arguments),g=w.apply(this,arguments)-r,_=T.apply(this,arguments)-r,v=l(_-g),k=_>g;if(D||=e=O(),h<m&&(t=h,h=m,m=t),!(h>1e-12))D.moveTo(0,0);else if(v>c-1e-12)D.moveTo(h*u(g),h*a(g)),D.arc(0,0,h,g,_,!k),m>1e-12&&(D.moveTo(m*u(_),m*a(_)),D.arc(0,0,m,_,g,k));else{var A=g,j=_,M=g,N=_,P=v,F=v,I=E.apply(this,arguments)/2,L=I>1e-12&&(C?+C.apply(this,arguments):d(m*m+h*h)),R=p(l(h-m)/2,+S.apply(this,arguments)),z=R,B=R,V,H;if(L>1e-12){var U=o(L/m*a(I)),W=o(L/h*a(I));(P-=U*2)>1e-12?(U*=k?1:-1,M+=U,N-=U):(P=0,M=N=(g+_)/2),(F-=W*2)>1e-12?(W*=k?1:-1,A+=W,j-=W):(F=0,A=j=(g+_)/2)}var G=h*u(A),K=h*a(A),q=m*u(N),J=m*a(N);if(R>1e-12){var Y=h*u(j),X=h*a(j),Z=m*u(M),Q=m*a(M),$;if(v<i)if($=y(G,K,Z,Q,Y,X,q,J)){var ee=G-$[0],te=K-$[1],ne=Y-$[0],re=X-$[1],ie=1/a(f((ee*ne+te*re)/(d(ee*ee+te*te)*d(ne*ne+re*re)))/2),ae=d($[0]*$[0]+$[1]*$[1]);z=p(R,(m-ae)/(ie-1)),B=p(R,(h-ae)/(ie+1))}else z=B=0}F>1e-12?B>1e-12?(V=b(Z,Q,G,K,h,B,k),H=b(Y,X,q,J,h,B,k),D.moveTo(V.cx+V.x01,V.cy+V.y01),B<R?D.arc(V.cx,V.cy,B,n(V.y01,V.x01),n(H.y01,H.x01),!k):(D.arc(V.cx,V.cy,B,n(V.y01,V.x01),n(V.y11,V.x11),!k),D.arc(0,0,h,n(V.cy+V.y11,V.cx+V.x11),n(H.cy+H.y11,H.cx+H.x11),!k),D.arc(H.cx,H.cy,B,n(H.y11,H.x11),n(H.y01,H.x01),!k))):(D.moveTo(G,K),D.arc(0,0,h,A,j,!k)):D.moveTo(G,K),!(m>1e-12)||!(P>1e-12)?D.lineTo(q,J):z>1e-12?(V=b(q,J,Y,X,m,-z,k),H=b(G,K,Z,Q,m,-z,k),D.lineTo(V.cx+V.x01,V.cy+V.y01),z<R?D.arc(V.cx,V.cy,z,n(V.y01,V.x01),n(H.y01,H.x01),!k):(D.arc(V.cx,V.cy,z,n(V.y01,V.x01),n(V.y11,V.x11),!k),D.arc(0,0,m,n(V.cy+V.y11,V.cx+V.x11),n(H.cy+H.y11,H.cx+H.x11),k),D.arc(H.cx,H.cy,z,n(H.y11,H.x11),n(H.y01,H.x01),!k))):D.arc(0,0,m,N,M,k)}if(D.closePath(),e)return D=null,e+``||null}return k.centroid=function(){var e=(+s.apply(this,arguments)+ +x.apply(this,arguments))/2,t=(+w.apply(this,arguments)+ +T.apply(this,arguments))/2-i/2;return[u(t)*e,a(t)*e]},k.innerRadius=function(t){return arguments.length?(s=typeof t==`function`?t:e(+t),k):s},k.outerRadius=function(t){return arguments.length?(x=typeof t==`function`?t:e(+t),k):x},k.cornerRadius=function(t){return arguments.length?(S=typeof t==`function`?t:e(+t),k):S},k.padRadius=function(t){return arguments.length?(C=t==null?null:typeof t==`function`?t:e(+t),k):C},k.startAngle=function(t){return arguments.length?(w=typeof t==`function`?t:e(+t),k):w},k.endAngle=function(t){return arguments.length?(T=typeof t==`function`?t:e(+t),k):T},k.padAngle=function(t){return arguments.length?(E=typeof t==`function`?t:e(+t),k):E},k.context=function(e){return arguments.length?(D=e??null,k):D},k}export{x as t};

package/dist/web/assets/architecture-TIHT7OUA-C6XhPF72.js

@@ -0,0 +1 @@
+import"./chunk-KEIR6QF5-BfrZ3jm6.js";import{M as e}from"./mermaid-parser.core-DvKEagUi.js";export{e as createArchitectureServices};