@crouton-kit/humanloop 0.4.8 → 0.4.10

package/dist/render/termrender.d.ts

@@ -26,8 +26,10 @@ export interface RenderedDoc {
      *  (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. */
+    /** Per top-level block: its termrender block type plus 1-indexed inclusive
+     *  source-line bounds. Never empty. */
     blocks: {
+        type: string;
         start: number;
         end: number;
     }[];
@@ -35,6 +37,21 @@ export interface RenderedDoc {
 /** 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;
+/**
+ * The shared block-aware mapped render: prose blocks keep the readability cap
+ * (`proseWidth`), while diagram blocks are re-rendered at the pane's full
+ * `paneWidth` and spliced back in by block index. Both surfaces (terminal
+ * review and the ask deck) go through this, so "which blocks may be wide" is
+ * decided once, from the renderer's own block types, never by heuristics on
+ * the emitted rows.
+ *
+ * Row order, block list and source spans are the narrow render's; only the
+ * rows OF a wide block are replaced, so anchoring stays source-based and
+ * unchanged.
+ */
+export declare function renderMarkdownBlockAware(md: string, proseWidth: number, paneWidth: number): RenderedDoc;
+/** Block-aware render as plain rows, for surfaces that do not anchor. */
+export declare function renderMarkdownBlockAwareLines(md: string, proseWidth: number, paneWidth: number): string[];
 /** Validate markdown via `termrender doc check`. */
 export declare function checkMarkdown(md: string): {
     ok: true;

package/dist/render/termrender.js

@@ -492,6 +492,10 @@ export function renderMarkdown(md, width) {
     _bodyCache.set(key, fallback);
     return fallback;
 }
+/** Block types allowed to use the full pane width instead of the prose cap:
+ *  a diagram is a picture, not prose, so a readability column limit only
+ *  shrinks it below what the pane could show. */
+const WIDE_BLOCK_TYPES = new Set(['mermaid']);
 /** 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
@@ -520,6 +524,10 @@ function parseRenderedDoc(out, source) {
     for (const raw of p.blocks) {
         if (typeof raw !== 'object' || raw === null)
             return null;
+        // The block type is what lets callers render diagrams differently from
+        // prose; a map without it cannot drive block-aware rendering at all.
+        if (typeof raw.type !== 'string' || raw.type === '')
+            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))
@@ -530,11 +538,11 @@ function parseRenderedDoc(out, source) {
         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 });
+        blocks.push({ type: raw.type, start: s, end: e });
         prevEnd = e;
     }
     if (blocks.length === 0)
-        blocks.push({ start: 1, end: totalSource });
+        blocks.push({ type: 'paragraph', start: 1, end: totalSource });
     const spans = [];
     for (let r = 0; r < p.spans.length; r++) {
         const raw = p.spans[r];
@@ -581,14 +589,14 @@ function fallbackDocWithMap(md, width) {
                 openAt = i;
         }
         else if (openAt !== null) {
-            blocks.push({ start: openAt + 1, end: i });
+            blocks.push({ type: 'paragraph', start: openAt + 1, end: i });
             openAt = null;
         }
     }
     if (openAt !== null)
-        blocks.push({ start: openAt + 1, end: src.length });
+        blocks.push({ type: 'paragraph', start: openAt + 1, end: src.length });
     if (blocks.length === 0)
-        blocks.push({ start: 1, end: Math.max(1, src.length) });
+        blocks.push({ type: 'paragraph', start: 1, end: Math.max(1, src.length) });
     const lines = [];
     const rows = [];
     const spans = [];
@@ -649,6 +657,59 @@ export function renderMarkdownWithMap(md, width) {
     // for the rest of the session when a later re-render could succeed.
     return fallbackDocWithMap(md, width);
 }
+/**
+ * The shared block-aware mapped render: prose blocks keep the readability cap
+ * (`proseWidth`), while diagram blocks are re-rendered at the pane's full
+ * `paneWidth` and spliced back in by block index. Both surfaces (terminal
+ * review and the ask deck) go through this, so "which blocks may be wide" is
+ * decided once, from the renderer's own block types, never by heuristics on
+ * the emitted rows.
+ *
+ * Row order, block list and source spans are the narrow render's; only the
+ * rows OF a wide block are replaced, so anchoring stays source-based and
+ * unchanged.
+ */
+export function renderMarkdownBlockAware(md, proseWidth, paneWidth) {
+    const base = renderMarkdownWithMap(md, proseWidth);
+    if (paneWidth <= proseWidth)
+        return base;
+    if (!base.blocks.some((b) => WIDE_BLOCK_TYPES.has(b.type)))
+        return base;
+    const wide = renderMarkdownWithMap(md, paneWidth);
+    // Same source, so the two renders describe the same top-level blocks. A
+    // disagreement means one of the two maps is degraded (renderer failure mid
+    // session) — render the narrow one rather than splice mismatched rows.
+    if (wide.blocks.length !== base.blocks.length)
+        return base;
+    const lines = [];
+    const rows = [];
+    const spans = [];
+    for (let r = 0; r < base.lines.length; r++) {
+        const bi = base.rows[r] ?? null;
+        if (bi === null || !WIDE_BLOCK_TYPES.has(base.blocks[bi].type)) {
+            lines.push(base.lines[r]);
+            rows.push(bi);
+            spans.push(base.spans[r] ?? null);
+            continue;
+        }
+        // First row of this block's run: emit the wide render's rows for the same
+        // block, then skip the narrow run (a block's rows are contiguous).
+        if (r === 0 || base.rows[r - 1] !== bi) {
+            for (let q = 0; q < wide.lines.length; q++) {
+                if (wide.rows[q] !== bi)
+                    continue;
+                lines.push(wide.lines[q]);
+                rows.push(bi);
+                spans.push(wide.spans[q] ?? null);
+            }
+        }
+    }
+    return { lines, rows, spans, blocks: base.blocks };
+}
+/** Block-aware render as plain rows, for surfaces that do not anchor. */
+export function renderMarkdownBlockAwareLines(md, proseWidth, paneWidth) {
+    return renderMarkdownBlockAware(md, proseWidth, paneWidth).lines;
+}
 /** 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.12.0";
+export declare const TERMRENDER_VERSION = "4.12.1";

package/dist/render/version.js

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

package/dist/tui/ansi.d.ts

@@ -33,11 +33,35 @@ export declare function hardWrap(text: string, maxWidth: number): string[];
  * them as cheap no-ops.
  */
 export declare function centerHorizontal(lines: string[], cols: number, contentWidth: number): string[];
+/** Visible width of a line in display cells (string-width ignores ANSI). */
+export declare function visibleWidth(line: string): number;
 /**
- * ANSI-aware clip: truncate a line's *visible* width to `maxWidth`, passing
- * escape sequences through untouched. Every line written to the terminal must
- * fit within the columns, or it physically wraps onto the next row — which
- * breaks diffFrame's one-logical-line-per-row model and strands spillover text
- * on rows the differ believes are empty (so it never erases them).
+ * The one display-cell containment primitive: the visible cells
+ * `[start, start + width)` of `line`, with escape sequences preserved.
+ *
+ * Every line written to the terminal must fit within its rectangle, or it
+ * physically wraps onto the next row — which breaks diffFrame's
+ * one-logical-line-per-row model and strands spillover text on rows the
+ * differ believes are empty (so it never erases them). Styling seen before
+ * the window is replayed at its head so a slice keeps the colors it had in
+ * place, and a double-width glyph straddling either edge becomes spaces so
+ * the slice occupies exactly the cells it claims.
+ */
+export declare function sliceCells(line: string, start: number, width: number): string;
+/**
+ * ANSI-aware clip: truncate a line's visible width to `maxWidth`. Thin
+ * wrapper over `sliceCells` so containment has a single implementation.
  */
 export declare function clipLine(line: string, maxWidth: number): string;
+/**
+ * Horizontal window onto a row that may be wider than its rectangle (a
+ * Mermaid diagram rendered at the pane's full width). A row that fits is
+ * returned untouched — panning only ever moves content that overflows, so
+ * prose stays put while a diagram slides. Hidden content on either side is
+ * marked with a dim ‹/› in the edge cell, so the row always states whether
+ * more of the diagram exists left or right, and the marker disappears once
+ * that edge is reached (nothing is unreachable).
+ */
+export declare function panLine(line: string, offset: number, width: number): string;
+/** Cells of `line` that fall outside a `width`-wide rectangle. */
+export declare function rowOverflow(line: string, width: number): number;

package/dist/tui/ansi.js

@@ -172,39 +172,135 @@ export function centerHorizontal(lines, cols, contentWidth) {
     const pad = ' '.repeat(extraPad);
     return lines.map((line) => (line === '' ? '' : pad + line));
 }
+/** Visible width of a line in display cells (string-width ignores ANSI). */
+export function visibleWidth(line) {
+    return stringWidth(line);
+}
+const ANSI_TOKEN = /\x1b\[[0-9;?]*[a-zA-Z]|\x1b[@-_]/g;
+const GRAPHEMES = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+/** ANSI escapes are tokens of their own; all printable text is segmented into
+ * extended grapheme clusters before widths or slice boundaries are calculated.
+ * `string-width` assigns display width to the complete cluster (not its
+ * constituent code points), which keeps ZWJ emoji, flags, skin tones and
+ * combining sequences indivisible while panning. */
+function displayTokens(line) {
+    const tokens = [];
+    let at = 0;
+    ANSI_TOKEN.lastIndex = 0;
+    for (let match = ANSI_TOKEN.exec(line); match !== null; match = ANSI_TOKEN.exec(line)) {
+        for (const segment of GRAPHEMES.segment(line.slice(at, match.index))) {
+            tokens.push({ ansi: false, text: segment.segment, width: stringWidth(segment.segment) });
+        }
+        tokens.push({ ansi: true, text: match[0] });
+        at = match.index + match[0].length;
+    }
+    for (const segment of GRAPHEMES.segment(line.slice(at))) {
+        tokens.push({ ansi: false, text: segment.segment, width: stringWidth(segment.segment) });
+    }
+    return tokens;
+}
 /**
- * ANSI-aware clip: truncate a line's *visible* width to `maxWidth`, passing
- * escape sequences through untouched. Every line written to the terminal must
- * fit within the columns, or it physically wraps onto the next row — which
- * breaks diffFrame's one-logical-line-per-row model and strands spillover text
- * on rows the differ believes are empty (so it never erases them).
+ * The one display-cell containment primitive: the visible cells
+ * `[start, start + width)` of `line`, with escape sequences preserved.
+ *
+ * Every line written to the terminal must fit within its rectangle, or it
+ * physically wraps onto the next row — which breaks diffFrame's
+ * one-logical-line-per-row model and strands spillover text on rows the
+ * differ believes are empty (so it never erases them). Styling seen before
+ * the window is replayed at its head so a slice keeps the colors it had in
+ * place, and a double-width glyph straddling either edge becomes spaces so
+ * the slice occupies exactly the cells it claims.
  */
-export function clipLine(line, maxWidth) {
-    if (maxWidth < 1)
+export function sliceCells(line, start, width) {
+    if (width < 1)
         return '';
-    if (stringWidth(line) <= maxWidth)
-        return line; // string-width ignores ANSI
+    const from = Math.max(0, start);
+    const end = from + width;
+    let carried = ''; // styling established before the window
     let out = '';
-    let w = 0;
-    let i = 0;
-    let sawAnsi = false;
-    while (i < line.length) {
-        if (line[i] === '\x1b') {
-            const m = /^\x1b\[[0-9;?]*[a-zA-Z]|^\x1b[@-_]/.exec(line.slice(i));
-            if (m !== null) {
-                out += m[0];
-                i += m[0].length;
-                sawAnsi = true;
-                continue;
+    let emitted = false; // any escape inside the window
+    let cell = 0;
+    for (const token of displayTokens(line)) {
+        if (token.ansi) {
+            if (cell < from)
+                carried += token.text;
+            else {
+                out += token.text;
+                emitted = true;
             }
+            continue;
         }
-        const ch = String.fromCodePoint(line.codePointAt(i));
-        const cw = stringWidth(ch);
-        if (w + cw > maxWidth)
+        if (cell >= end)
             break;
-        out += ch;
-        w += cw;
-        i += ch.length;
+        const cw = token.width;
+        // A standalone combining mark has no cells but is still a complete
+        // grapheme cluster; retain it whenever its zero-width position is inside
+        // the window rather than dropping it through the usual boundary check.
+        if (cw === 0) {
+            if (cell >= from)
+                out += token.text;
+            continue;
+        }
+        if (cell + cw <= from) {
+            cell += cw;
+            continue;
+        }
+        if (cell < from) { // whole grapheme straddles the left edge
+            out += ' '.repeat(cell + cw - from);
+            cell += cw;
+            continue;
+        }
+        if (cell + cw > end) { // whole grapheme straddles the right edge
+            out += ' '.repeat(end - cell);
+            cell = end;
+            break;
+        }
+        out += token.text;
+        cell += cw;
+    }
+    if (out === '')
+        return '';
+    if (carried !== '') {
+        out = carried + out;
+        emitted = true;
     }
-    return sawAnsi ? out + RESET : out;
+    return emitted ? out + RESET : out;
+}
+/**
+ * ANSI-aware clip: truncate a line's visible width to `maxWidth`. Thin
+ * wrapper over `sliceCells` so containment has a single implementation.
+ */
+export function clipLine(line, maxWidth) {
+    if (maxWidth < 1)
+        return '';
+    if (stringWidth(line) <= maxWidth)
+        return line; // string-width ignores ANSI
+    return sliceCells(line, 0, maxWidth);
+}
+/**
+ * Horizontal window onto a row that may be wider than its rectangle (a
+ * Mermaid diagram rendered at the pane's full width). A row that fits is
+ * returned untouched — panning only ever moves content that overflows, so
+ * prose stays put while a diagram slides. Hidden content on either side is
+ * marked with a dim ‹/› in the edge cell, so the row always states whether
+ * more of the diagram exists left or right, and the marker disappears once
+ * that edge is reached (nothing is unreachable).
+ */
+export function panLine(line, offset, width) {
+    if (width < 1)
+        return '';
+    const w = stringWidth(line);
+    if (w <= width)
+        return line;
+    const max = w - width;
+    const off = Math.max(0, Math.min(offset, max));
+    const left = off > 0;
+    const right = off < max;
+    const innerWidth = width - (left ? 1 : 0) - (right ? 1 : 0);
+    const body = innerWidth > 0 ? sliceCells(line, off + (left ? 1 : 0), innerWidth) : '';
+    return `${left ? `${DIM}‹${RESET}` : ''}${body}${right ? `${DIM}›${RESET}` : ''}`;
+}
+/** Cells of `line` that fall outside a `width`-wide rectangle. */
+export function rowOverflow(line, width) {
+    return Math.max(0, stringWidth(line) - width);
 }

package/dist/tui/app.js

@@ -4,7 +4,6 @@ import { dirname, resolve as resolvePath } from 'node:path';
 import { setupTerminal, restoreTerminal, parseKeypress, getTerminalSize } from './terminal.js';
 import { diffFrame, renderOverview, renderItemReview, renderFinal, renderHandoff, clampItemReviewScroll } from './render.js';
 import { handleKeypress, assignShortcuts } from './input.js';
-import { renderMarkdown } from '../render/termrender.js';
 import { editBufferInEditor } from '../editor/roundtrip.js';
 import { validateDeck } from '../inbox/deck-schema.js';
 import { canonicalizeInteraction } from '../inbox/visual.js';
@@ -57,6 +56,8 @@ function buildInitialState(deck, editorAvailable = false, followUpAvailable = fa
         bodyMode: 'question',
         scrollOffset: 0,
         bodyScrollOffsets: { question: 0, visual: 0 },
+        hscrollOffset: 0,
+        hscrollMax: 0,
         editorAvailable,
         followUpAvailable,
         followUp: undefined,
@@ -107,20 +108,6 @@ function rebindPersist(internals) {
         internals.callbacks.onProgress?.(responses);
     };
 }
-function visualRenderWidth(cols) {
-    return Math.max(1, Math.min(cols - 4, 76));
-}
-function renderVisualMarkdown(markdown, cols) {
-    return renderMarkdown(markdown, visualRenderWidth(cols)).join('\n');
-}
-/** Reflow ready Visual Markdown locally without issuing another request. */
-function rerenderVisuals(internals) {
-    for (const [id, visual] of internals.state.visuals) {
-        if (visual.status !== 'ready' || visual.markdown === undefined)
-            continue;
-        internals.state.visuals.set(id, { ...visual, content: renderVisualMarkdown(visual.markdown, internals.cols) });
-    }
-}
 function visualRequestInteraction(interaction) {
     return canonicalizeInteraction(interaction);
 }
@@ -136,6 +123,17 @@ function retireVisuals(internals) {
         catch { /* stale UI currency remains authoritative even if a host cancel fails */ }
     }
 }
+function detachVisuals(internals) {
+    internals.visualGeneration += 1;
+    const handles = [...internals.visualHandles.values()];
+    internals.visualHandles.clear();
+    for (const handle of handles) {
+        try {
+            handle.detach();
+        }
+        catch { /* UI teardown remains local even if provider cleanup fails */ }
+    }
+}
 function fireVisuals(internals, interactions) {
     const provider = internals.visualProvider;
     if (provider === undefined)
@@ -163,7 +161,7 @@ function fireVisuals(internals, interactions) {
             if (!internals.state.interactions.some((candidate) => candidate.id === interaction.id))
                 return;
             internals.state.visuals.set(interaction.id, result.status === 'ready' && typeof result.markdown === 'string'
-                ? { questionId: interaction.id, content: renderVisualMarkdown(result.markdown, internals.cols), markdown: result.markdown, status: 'ready' }
+                ? { questionId: interaction.id, content: result.markdown, markdown: result.markdown, status: 'ready' }
                 : { questionId: interaction.id, content: '', status: 'error' });
             internals.callbacks.onDirty?.();
         }).catch(() => {
@@ -208,7 +206,13 @@ export function mountPanel(opts) {
     const renderLines = () => {
         switch (internals.state.phase) {
             case 'overview': return renderOverview(internals.state, internals.cols, internals.rows);
-            case 'item-review': return renderItemReview(internals.state, internals.cols, internals.rows);
+            case 'item-review':
+                // The one pre-render clamp: keeps scrollOffset/hscrollOffset inside the
+                // current body's bounds (so u/d and h/l stay responsive) and publishes
+                // the live horizontal reach the input layer reads. The renderer itself
+                // stays pure; running it here covers mount, resize and every keypress.
+                clampItemReviewScroll(internals.state, internals.cols, internals.rows);
+                return renderItemReview(internals.state, internals.cols, internals.rows);
             case 'final': return renderFinal(internals.state, internals.cols, internals.rows);
         }
     };
@@ -242,11 +246,6 @@ export function mountPanel(opts) {
                 request: (question) => internals.callbacks.onFollowUpRequest?.(question),
                 cancel: () => internals.callbacks.onFollowUpCancel?.(),
             });
-            // Pre-render clamp (input layer): keep scrollOffset within the current
-            // body's bounds so u/d stay responsive. The renderer itself is pure.
-            if (internals.state.phase === 'item-review') {
-                clampItemReviewScroll(internals.state, internals.cols, internals.rows);
-            }
         },
         render() {
             if (!internals.mounted)
@@ -256,19 +255,15 @@ export function mountPanel(opts) {
         handleResize(cols, rows) {
             internals.cols = cols;
             internals.rows = rows;
-            // Width changes reflow saved visual markdown, so clamp against the new
-            // content and geometry rather than the stale pre-resize wrapping.
-            rerenderVisuals(internals);
-            if (internals.state.phase === 'item-review') {
-                clampItemReviewScroll(internals.state, cols, rows);
-            }
+            // Visual Markdown is re-rendered by the item layout at this width, so
+            // the same block-aware geometry drives both resize and initial paint.
             return renderLines();
         },
         unmount() {
             if (!internals.mounted)
                 return;
             internals.mounted = false;
-            retireVisuals(internals);
+            detachVisuals(internals);
             internals.state.persist = undefined;
         },
         loadDeck(deck, loadOpts) {

package/dist/tui/input.js

@@ -1,3 +1,4 @@
+import { panItemReview } from './render.js';
 // 'w' is reserved for the host-level "open in browser" handoff (see
 // tui/app.ts resolveInteractionDir) — never auto-assignable as an option
 // shortcut, or pressing it would race the handoff against picking that option.
@@ -180,6 +181,16 @@ function handleItemReview(input, key, state, render, followUp) {
         render();
         return;
     }
+    // Body pan: contextual, so h/l only claim the key while the visible body
+    // actually overflows its rectangle (a wide diagram) AND no option owns that
+    // shortcut. Otherwise they fall through to the option/action handling below.
+    if ((input === 'h' || input === 'l' || key.leftArrow || key.rightArrow)
+        && (state.hscrollMax ?? 0) > 0
+        && !interaction.options.some((o) => o.shortcut === input)) {
+        panItemReview(state, input === 'h' || key.leftArrow ? -1 : 1);
+        render();
+        return;
+    }
     if (input === 'j' || key.downArrow) {
         const max = actionCount(interaction) - 1;
         state.selectedAction = Math.min(state.selectedAction + 1, max);
@@ -576,6 +587,7 @@ function advanceItem(state, direction) {
     state.bodyMode = 'question';
     state.scrollOffset = 0;
     state.bodyScrollOffsets = { question: 0, visual: 0 };
+    state.hscrollOffset = 0;
 }
 /**
  * Move to the next interaction WITHOUT a response, falling through to the
@@ -598,6 +610,7 @@ function advanceToNextUnanswered(state) {
     state.bodyMode = 'question';
     state.scrollOffset = 0;
     state.bodyScrollOffsets = { question: 0, visual: 0 };
+    state.hscrollOffset = 0;
 }
 function actionCount(interaction) {
     return interaction.options.length + (interaction.allowFreetext && interaction.options.length > 0 ? 1 : 0);

package/dist/tui/render.d.ts

@@ -21,6 +21,9 @@ export declare function renderInputBuffer(buffer: string, cursor: number, maxWid
  * renderer mutating state mid-frame.
  */
 export declare function clampItemReviewScroll(state: TuiState, cols: number, rows: number): void;
+/** Pan the card body horizontally. Clamping happens in the pre-render clamp
+ *  the host already runs, exactly like vertical over-scroll. */
+export declare function panItemReview(state: TuiState, direction: -1 | 1): void;
 export declare function renderItemReview(state: TuiState, cols: number, rows: number): string[];
 export declare function renderFinal(state: TuiState, cols: number, rows: number): string[];
 /**