@crouton-kit/humanloop 0.4.1 → 0.4.3

package/dist/editor/review.d.ts

@@ -24,9 +24,10 @@ export declare function reviewVimscript(): string;
  */
 export declare function formatFeedbackSummary(result: FeedbackResult, feedbackJsonPath: string): string;
 /**
- * Open a markdown file in a clean, read-only Neovim/Vim review session. The
- * human anchors comments to source lines/selections with native vim motions
- * and explicitly submits a proposal. Blocks until the editor exits. Autosaved
- * drafts survive exit; canonical ticket finalization belongs to the controller.
+ * Open a markdown file for review. Humanloop's own terminal surface
+ * (`launchTerminalReview`) is the default: it renders Markdown (including
+ * Mermaid) via termrender and anchors comments to source lines. Passing an
+ * explicit `opts.editor` opts into the legacy read-only Neovim/Vim session
+ * (`launchNeovimReview`), kept only as an explicit compatibility path.
  */
 export declare function launchReview(file: string, opts: ReviewOptions): Promise<FeedbackResult>;

package/dist/editor/review.js

@@ -5,6 +5,7 @@ import { resolve, join } from 'path';
 import { openBrowser } from '../browser/open.js';
 import { startReviewWebServer } from '../browser/server.js';
 import { buildFinalFeedbackResult, readReviewDraft, } from './feedback.js';
+import { launchTerminalReview } from './terminal-review.js';
 function resolveEditor(override) {
     const candidates = override ? [override] : ['nvim', 'vim'];
     for (const bin of candidates) {
@@ -598,13 +599,25 @@ async function stopReviewServer(handle) {
     if (handle !== null)
         await handle.stop();
 }
+/**
+ * Open a markdown file for review. Humanloop's own terminal surface
+ * (`launchTerminalReview`) is the default: it renders Markdown (including
+ * Mermaid) via termrender and anchors comments to source lines. Passing an
+ * explicit `opts.editor` opts into the legacy read-only Neovim/Vim session
+ * (`launchNeovimReview`), kept only as an explicit compatibility path.
+ */
+export async function launchReview(file, opts) {
+    if (opts.editor !== undefined)
+        return launchNeovimReview(file, opts);
+    return launchTerminalReview(file, opts);
+}
 /**
  * Open a markdown file in a clean, read-only Neovim/Vim review session. The
  * human anchors comments to source lines/selections with native vim motions
  * and explicitly submits a proposal. Blocks until the editor exits. Autosaved
  * drafts survive exit; canonical ticket finalization belongs to the controller.
  */
-export async function launchReview(file, opts) {
+async function launchNeovimReview(file, opts) {
     const absFile = resolve(file);
     if (!existsSync(absFile)) {
         throw new Error(`Markdown file not found: ${absFile}`);

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

@@ -0,0 +1,76 @@
+import type { FeedbackComment, FeedbackResult } from '../types.js';
+import type { ReviewOptions } from './review.js';
+export interface ComposeState {
+    buffer: string;
+    cursor: number;
+    /** Id of the comment being edited, or null when composing a new comment. */
+    editingId: string | null;
+    /** Submode to return to once compose closes (Escape or a successful save). */
+    returnMode: 'view' | 'list';
+    anchor: {
+        line: number;
+        endLine: number;
+    };
+}
+export interface ReviewState {
+    sourceLines: string[];
+    comments: FeedbackComment[];
+    version: number;
+    /** 1-based active source line. */
+    activeLine: number;
+    /** Set while a Shift+j/k range is being extended from this line. */
+    selectionAnchor: number | null;
+    /** Scroll offset into the rendered (termrender) lines. */
+    scroll: number;
+    mode: 'view' | 'list' | 'compose' | 'help';
+    compose: ComposeState | null;
+    listIndex: number;
+}
+export declare function initReviewState(sourceLines: string[], comments: FeedbackComment[], version: number): ReviewState;
+export declare function currentAnchor(state: ReviewState): {
+    line: number;
+    endLine: number;
+};
+export declare function moveActiveLine(state: ReviewState, delta: number, extend: boolean): 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;
+export declare function closeCompose(state: ReviewState): ReviewState;
+/** Commits the current compose buffer as a new comment or an edit to an existing one. Empty text cancels. */
+export declare function commitCompose(state: ReviewState, now?: string): ReviewState;
+export declare function openList(state: ReviewState): ReviewState;
+export declare function closeList(state: ReviewState): ReviewState;
+export declare function moveListIndex(state: ReviewState, delta: number): ReviewState;
+export declare function deleteAtListIndex(state: ReviewState): ReviewState;
+export declare function undoLast(state: ReviewState): ReviewState;
+export declare function openHelp(state: ReviewState): ReviewState;
+export declare function closeHelp(state: ReviewState): ReviewState;
+export declare function textInsert(buffer: string, cursor: number, text: string): {
+    buffer: string;
+    cursor: number;
+};
+export declare function textBackspace(buffer: string, cursor: number): {
+    buffer: string;
+    cursor: number;
+};
+export declare function textDelete(buffer: string, cursor: number): {
+    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;
+/** 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[];
+/**
+ * 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`.
+ */
+export declare function launchTerminalReview(file: string, opts: ReviewOptions): Promise<FeedbackResult>;

package/dist/editor/terminal-review.js

@@ -0,0 +1,491 @@
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { buildDraftFeedbackResult, buildFinalFeedbackResult, readReviewDraft, writeReviewDraft } from './feedback.js';
+import { renderMarkdown } 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) {
+    return {
+        sourceLines,
+        comments: [...comments],
+        version,
+        activeLine: comments.length > 0 ? comments[0].line : 1,
+        selectionAnchor: null,
+        scroll: 0,
+        mode: 'view',
+        compose: null,
+        listIndex: 0,
+    };
+}
+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) };
+}
+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));
+    if (!extend)
+        return { ...state, activeLine: next, selectionAnchor: null };
+    return { ...state, activeLine: next, selectionAnchor: state.selectionAnchor ?? state.activeLine };
+}
+export function scrollBy(state, delta, bodyHeight, totalLines) {
+    const maxScroll = Math.max(0, totalLines - bodyHeight);
+    return { ...state, scroll: Math.max(0, Math.min(state.scroll + delta, maxScroll)) };
+}
+export function openComposeNew(state) {
+    return { ...state, mode: 'compose', compose: { buffer: '', cursor: 0, editingId: null, returnMode: 'view', anchor: currentAnchor(state) } };
+}
+export function openComposeEdit(state, index) {
+    const comment = state.comments[index];
+    if (comment === undefined)
+        return state;
+    const buffer = comment.comment;
+    return {
+        ...state,
+        mode: 'compose',
+        compose: { buffer, cursor: [...buffer].length, editingId: comment.id, returnMode: 'list', anchor: { line: comment.line, endLine: comment.endLine } },
+    };
+}
+export function closeCompose(state) {
+    const returnMode = state.compose?.returnMode ?? 'view';
+    return { ...state, mode: returnMode, compose: null };
+}
+/** Commits the current compose buffer as a new comment or an edit to an existing one. Empty text cancels. */
+export function commitCompose(state, now = new Date().toISOString()) {
+    const c = state.compose;
+    if (c === null || c === undefined)
+        return state;
+    const text = c.buffer.trim();
+    if (text.length === 0)
+        return closeCompose(state);
+    if (c.editingId !== null) {
+        const comments = state.comments.map((cm) => (cm.id === c.editingId ? { ...cm, comment: text } : cm));
+        return { ...state, comments, mode: c.returnMode, compose: null };
+    }
+    const lineText = state.sourceLines.slice(c.anchor.line - 1, c.anchor.endLine).join('\n');
+    const comment = { id: randomUUID(), line: c.anchor.line, endLine: c.anchor.endLine, lineText, comment: text, createdAt: now };
+    return { ...state, comments: [...state.comments, comment], mode: c.returnMode, compose: null };
+}
+export function openList(state) {
+    return { ...state, mode: 'list', listIndex: Math.max(0, Math.min(state.listIndex, state.comments.length - 1)) };
+}
+export function closeList(state) {
+    return { ...state, mode: 'view' };
+}
+export function moveListIndex(state, delta) {
+    if (state.comments.length === 0)
+        return state;
+    const next = Math.max(0, Math.min(state.comments.length - 1, state.listIndex + delta));
+    return { ...state, listIndex: next };
+}
+export function deleteAtListIndex(state) {
+    if (state.comments.length === 0)
+        return state;
+    const comments = state.comments.filter((_, i) => i !== state.listIndex);
+    const listIndex = Math.max(0, Math.min(state.listIndex, comments.length - 1));
+    return { ...state, comments, listIndex };
+}
+export function undoLast(state) {
+    if (state.comments.length === 0)
+        return state;
+    return { ...state, comments: state.comments.slice(0, -1) };
+}
+export function openHelp(state) {
+    return { ...state, mode: 'help' };
+}
+export function closeHelp(state) {
+    return { ...state, mode: 'view' };
+}
+// ── Multi-line text-buffer helpers (flat string + code-point cursor) ────────
+function codePoints(s) {
+    return [...s];
+}
+// A single physical keypress (including Enter) almost always arrives as its
+// own 'data' event, so parseKeypress's per-event key flags cover the normal
+// typing path. A chunk longer than one character is a paste (or, rarely,
+// several keystrokes the OS coalesced into one read) and is never re-parsed
+// for key semantics — an embedded CR there means a pasted newline, not a
+// commit. Mirrors tui/input.ts's paste cleaning: strip escape sequences,
+// normalize CR/CRLF to LF, drop remaining control bytes, keep LF.
+function cleanPastedText(input) {
+    return input
+        .replace(/\x1b\[20[01]~/g, '')
+        .replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '')
+        .replace(/\r\n?/g, '\n')
+        .replace(/[\x00-\x09\x0B-\x1F\x7F]/g, '');
+}
+export function textInsert(buffer, cursor, text) {
+    const chars = codePoints(buffer);
+    const at = Math.max(0, Math.min(cursor, chars.length));
+    const next = [...chars.slice(0, at), ...codePoints(text), ...chars.slice(at)].join('');
+    return { buffer: next, cursor: at + codePoints(text).length };
+}
+export function textBackspace(buffer, cursor) {
+    if (cursor <= 0)
+        return { buffer, cursor };
+    const chars = codePoints(buffer);
+    return { buffer: [...chars.slice(0, cursor - 1), ...chars.slice(cursor)].join(''), cursor: cursor - 1 };
+}
+export function textDelete(buffer, cursor) {
+    const chars = codePoints(buffer);
+    if (cursor >= chars.length)
+        return { buffer, cursor };
+    return { buffer: [...chars.slice(0, cursor), ...chars.slice(cursor + 1)].join(''), cursor };
+}
+function lineBoundsAt(chars, cursor) {
+    let start = cursor;
+    while (start > 0 && chars[start - 1] !== '\n')
+        start--;
+    let end = cursor;
+    while (end < chars.length && chars[end] !== '\n')
+        end++;
+    return { start, end };
+}
+export function textHome(buffer, cursor) {
+    return lineBoundsAt(codePoints(buffer), cursor).start;
+}
+export function textEnd(buffer, cursor) {
+    return lineBoundsAt(codePoints(buffer), cursor).end;
+}
+export function textVertical(buffer, cursor, delta) {
+    const chars = codePoints(buffer);
+    const { start, end } = lineBoundsAt(chars, cursor);
+    const col = cursor - start;
+    if (delta < 0) {
+        if (start === 0)
+            return cursor;
+        const prevEnd = start - 1; // the '\n' just before this line
+        const prevStart = lineBoundsAt(chars, prevEnd).start;
+        return Math.min(prevEnd, prevStart + col);
+    }
+    if (end >= chars.length)
+        return cursor;
+    const nextStart = end + 1;
+    const nextEnd = lineBoundsAt(chars, nextStart).end;
+    return Math.min(nextEnd, nextStart + col);
+}
+// ── Rendering (pure) ─────────────────────────────────────────────────────────
+/** 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) {
+    const header = 3; // blank, title, divider
+    if (state.mode === 'view')
+        return header + 2;
+    if (state.mode === 'compose') {
+        const c = state.compose;
+        const bufLines = c ? Math.max(1, c.buffer.split('\n').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) {
+    const maxW = Math.min(Math.max(20, cols - 4), 120);
+    const header = [
+        '',
+        `  ${BOLD}${CYAN}Review — ${fileLabel}${RESET}  ${DIM}${state.comments.length} comment${state.comments.length === 1 ? '' : 's'}${RESET}`,
+        `  ${DIM}${hline(maxW)}${RESET}`,
+    ];
+    const footer = [];
+    if (state.mode === 'compose' && state.compose) {
+        const c = state.compose;
+        const label = c.anchor.line === c.anchor.endLine ? `L${c.anchor.line}` : `L${c.anchor.line}-${c.anchor.endLine}`;
+        footer.push(`  ${YELLOW}${c.editingId !== null ? 'Edit comment' : 'Comment'} on ${label}:${RESET}`);
+        for (const l of renderInputBuffer(c.buffer, c.cursor, Math.max(10, maxW - 2)))
+            footer.push(`  ${l}`);
+        footer.push('');
+        footer.push(`  ${DIM}enter${RESET} save  ${DIM}^J/⌥⏎${RESET} newline  ${DIM}esc${RESET} cancel`);
+    }
+    else if (state.mode === 'list') {
+        if (state.comments.length === 0) {
+            footer.push(`  ${DIM}(no comments yet — space c to add one)${RESET}`);
+        }
+        else {
+            state.comments.forEach((c, i) => {
+                const loc = c.line === c.endLine ? `L${c.line}` : `L${c.line}-${c.endLine}`;
+                const cursor = i === state.listIndex ? `${CYAN}▸${RESET}` : ' ';
+                const text = truncate(c.comment.replace(/\n/g, ' / '), Math.max(10, maxW - 14));
+                footer.push(`  ${cursor} ${DIM}[${loc}]${RESET} ${text}`);
+            });
+        }
+        footer.push('');
+        footer.push(`  ${DIM}j/k${RESET} move  ${DIM}enter/e${RESET} edit  ${DIM}d${RESET} delete  ${DIM}q/esc${RESET} close`);
+    }
+    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}u/d, pgup/pgdn${RESET}  scroll document`);
+        footer.push(`  ${DIM}space c${RESET}     compose comment        ${DIM}space l${RESET}     list comments`);
+        footer.push(`  ${DIM}space u${RESET}     undo last comment      ${DIM}space s${RESET}     submit review`);
+        footer.push(`  ${DIM}?${RESET}           toggle this help       ${DIM}esc${RESET}         close/cancel`);
+        footer.push('');
+        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  ` +
+            `${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 scroll = Math.max(0, Math.min(state.scroll, maxScroll));
+    const body = renderedLines.slice(scroll, scroll + bodyHeight).map((l) => `  ${l}`);
+    if (scroll > 0 && body.length > 0)
+        body[0] = `  ${DIM}↑ ${scroll} more above${RESET}`;
+    const remaining = renderedLines.length - (scroll + bodyHeight);
+    if (remaining > 0 && body.length > 0)
+        body[body.length - 1] = `  ${DIM}↓ ${remaining} more below${RESET}`;
+    while (body.length < bodyHeight)
+        body.push('');
+    const lines = [...header, ...body, ...footer];
+    while (lines.length < rows)
+        lines.push('');
+    return lines.slice(0, 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`.
+ */
+export async function launchTerminalReview(file, opts) {
+    const absFile = resolve(file);
+    const content = readFileSync(absFile, 'utf8');
+    const sourceLines = content.split('\n');
+    const outPath = resolve(opts.output);
+    const draft = readReviewDraft(outPath);
+    let state = initReviewState(sourceLines, draft?.comments ?? [], draft?.version ?? 0);
+    const fileLabel = basename(absFile);
+    if (opts.signal?.aborted)
+        return buildDraftFeedbackResult(absFile, state.comments, draft?.savedAt);
+    setupTerminal();
+    let { cols, rows } = getTerminalSize();
+    let renderedWidth = Math.min(Math.max(20, cols - 4), 120);
+    let renderedLines = renderMarkdown(content, renderedWidth);
+    let prevFrame = [];
+    let spaceArmed = false;
+    let settled = false;
+    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);
+            if (clear) {
+                prevFrame = [];
+                process.stdout.write('\x1b[2J\x1b[H');
+            }
+            const { writes, nextPrevFrame } = diffFrame(prevFrame, lines, rows, cols);
+            process.stdout.write('\x1b[?2026h');
+            for (const w of writes)
+                process.stdout.write(w);
+            process.stdout.write('\x1b[?2026l');
+            prevFrame = nextPrevFrame;
+        };
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            process.stdin.removeListener('data', onData);
+            process.stdout.removeListener('resize', onResize);
+            opts.signal?.removeEventListener('abort', onAbort);
+            restoreTerminal();
+            resolvePromise(result);
+        };
+        const onResize = () => {
+            ({ cols, rows } = getTerminalSize());
+            renderedWidth = Math.min(Math.max(20, cols - 4), 120);
+            renderedLines = renderMarkdown(content, renderedWidth);
+            paint(true);
+        };
+        const onAbort = () => {
+            finish(buildDraftFeedbackResult(absFile, state.comments));
+        };
+        const submit = async () => {
+            persist();
+            const proposal = buildFinalFeedbackResult(absFile, state.comments);
+            if (!opts.signal?.aborted)
+                await opts.onPropose?.(proposal);
+            finish(proposal);
+        };
+        const requestClose = async () => {
+            persist();
+            await opts.onClose?.();
+            finish(buildDraftFeedbackResult(absFile, state.comments));
+        };
+        const handleComposeKey = (input, key) => {
+            const c = state.compose;
+            if (c === null)
+                return;
+            if (key.escape) {
+                state = closeCompose(state);
+                return;
+            }
+            if (key.return) {
+                state = commitCompose(state);
+                persist();
+                return;
+            }
+            if (key.newline) {
+                const r = textInsert(c.buffer, c.cursor, '\n');
+                state = { ...state, compose: { ...c, ...r } };
+                return;
+            }
+            if (key.backspace) {
+                const r = textBackspace(c.buffer, c.cursor);
+                state = { ...state, compose: { ...c, ...r } };
+                return;
+            }
+            if (key.del) {
+                const r = textDelete(c.buffer, c.cursor);
+                state = { ...state, compose: { ...c, ...r } };
+                return;
+            }
+            if (key.leftArrow) {
+                state = { ...state, compose: { ...c, cursor: Math.max(0, c.cursor - 1) } };
+                return;
+            }
+            if (key.rightArrow) {
+                state = { ...state, compose: { ...c, cursor: Math.min([...c.buffer].length, c.cursor + 1) } };
+                return;
+            }
+            if (key.home) {
+                state = { ...state, compose: { ...c, cursor: textHome(c.buffer, c.cursor) } };
+                return;
+            }
+            if (key.end) {
+                state = { ...state, compose: { ...c, cursor: textEnd(c.buffer, c.cursor) } };
+                return;
+            }
+            if (key.upArrow) {
+                state = { ...state, compose: { ...c, cursor: textVertical(c.buffer, c.cursor, -1) } };
+                return;
+            }
+            if (key.downArrow) {
+                state = { ...state, compose: { ...c, cursor: textVertical(c.buffer, c.cursor, 1) } };
+                return;
+            }
+            if (input.length === 1 && !key.ctrl) {
+                const r = textInsert(c.buffer, c.cursor, input);
+                state = { ...state, compose: { ...c, ...r } };
+                return;
+            }
+            if (input.length > 1) {
+                const clean = cleanPastedText(input);
+                if (clean.length === 0)
+                    return;
+                const r = textInsert(c.buffer, c.cursor, clean);
+                state = { ...state, compose: { ...c, ...r } };
+            }
+        };
+        const handleListKey = (input, key) => {
+            if (key.escape || input === 'q') {
+                state = closeList(state);
+                return;
+            }
+            if (input === 'j' || key.downArrow) {
+                state = moveListIndex(state, 1);
+                return;
+            }
+            if (input === 'k' || key.upArrow) {
+                state = moveListIndex(state, -1);
+                return;
+            }
+            if (input === 'e' || key.return) {
+                if (state.comments.length > 0)
+                    state = openComposeEdit(state, state.listIndex);
+                return;
+            }
+            if (input === 'd') {
+                if (state.comments.length > 0) {
+                    state = deleteAtListIndex(state);
+                    persist();
+                }
+                return;
+            }
+        };
+        const onData = (data) => {
+            if (settled)
+                return;
+            const { input, key } = parseKeypress(data);
+            if (key.meta && input === 'i') {
+                void requestClose();
+                return;
+            }
+            if (state.mode === 'compose') {
+                handleComposeKey(input, key);
+                paint();
+                return;
+            }
+            if (spaceArmed) {
+                spaceArmed = false;
+                if (input === 'c')
+                    state = openComposeNew(state);
+                else if (input === 'l')
+                    state = openList(state);
+                else if (input === 'u') {
+                    state = undoLast(state);
+                    persist();
+                }
+                else if (input === 's') {
+                    void submit();
+                    return;
+                }
+                paint();
+                return;
+            }
+            if (state.mode === 'list') {
+                handleListKey(input, key);
+                paint();
+                return;
+            }
+            if (state.mode === 'help') {
+                if (input === '?' || key.escape)
+                    state = closeHelp(state);
+                paint();
+                return;
+            }
+            // view mode
+            if (input === ' ') {
+                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);
+            else if (input === 'u' || key.pageUp)
+                state = scrollBy(state, -Math.max(1, rows - reservedRows(state)), Math.max(1, rows - reservedRows(state)), renderedLines.length);
+            else if (input === 'd' || key.pageDown)
+                state = scrollBy(state, Math.max(1, rows - reservedRows(state)), Math.max(1, rows - reservedRows(state)), renderedLines.length);
+            else if (input === '?')
+                state = openHelp(state);
+            else if (key.escape) {
+                finish(buildDraftFeedbackResult(absFile, state.comments));
+                return;
+            }
+            paint();
+        };
+        process.stdin.on('data', onData);
+        process.stdout.on('resize', onResize);
+        opts.signal?.addEventListener('abort', onAbort, { once: true });
+        paint(true);
+    });
+}

package/dist/inbox/deck-factories.js

@@ -2,6 +2,7 @@ import { validateDeck } from './deck-schema.js';
 /** Build a validated single-option notify deck. id: 'notify', kind: 'notify'. */
 export function notifyDeck(title, opts = {}) {
     return validateDeck({
+        title,
         interactions: [{
                 id: 'notify',
                 title,

package/dist/inbox/deck-schema.d.ts

@@ -12,7 +12,7 @@ export declare const preAnswerSchema: z.ZodObject<{
     label: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const deckSchema: z.ZodObject<{
-    title: z.ZodOptional<z.ZodString>;
+    title: z.ZodString;
     source: z.ZodOptional<z.ZodObject<{
         sessionName: z.ZodOptional<z.ZodString>;
         askedBy: z.ZodOptional<z.ZodString>;

package/dist/inbox/deck-schema.js

@@ -8,11 +8,11 @@ export const interactionOptionSchema = z.object({ id: z.string().min(1), label:
 export const preAnswerSchema = z.object({ selectedOptionId: z.string().optional(), selectedOptionIds: z.array(z.string()).optional(), freetext: z.string().optional(), label: z.string().optional() });
 const interactionSchema = z.object({
     id: z.string().regex(/^[A-Za-z0-9_-]+$/, { error: 'interaction id must match /^[A-Za-z0-9_-]+$/' }).min(1).max(64),
-    title: z.string().min(1), subtitle: z.string().min(1).optional(), body: z.string().optional(), bodyPath: z.string().optional(),
+    title: z.string().trim().min(1), subtitle: z.string().min(1).optional(), body: z.string().optional(), bodyPath: z.string().optional(),
     options: z.array(interactionOptionSchema), multiSelect: z.boolean().optional(), allowFreetext: z.boolean().optional(), freetextLabel: z.string().optional(), kind: z.enum(INTERACTION_KINDS).optional(), preAnswered: preAnswerSchema.optional(),
 });
 const deckSourceSchema = z.object({ sessionName: z.string().optional(), askedBy: z.string().optional(), blockedSince: z.string().optional(), nodeId: z.string().optional(), visual: z.literal('humanloop.visual/v1').optional() });
-export const deckSchema = z.object({ title: z.string().optional(), source: deckSourceSchema.optional(), interactions: z.array(interactionSchema).min(1) }).superRefine((input, ctx) => {
+export const deckSchema = z.object({ title: z.string().trim().min(1), source: deckSourceSchema.optional(), interactions: z.array(interactionSchema).min(1) }).superRefine((input, ctx) => {
     const seen = new Set();
     input.interactions.forEach((interaction, index) => {
         if (interaction.body !== undefined && interaction.bodyPath !== undefined)

package/dist/inbox/scan.js

@@ -32,7 +32,7 @@ function deckSummary(dir, id) {
             return null;
         }
     }
-    return { dir, id, kind: 'deck', title: deck.title ?? first.title, subtitle: first.subtitle, interactionKind: first.kind, source: deck.source ?? {}, blockedSince, claim: claimSummary(dir) };
+    return { dir, id, kind: 'deck', title: deck.title, subtitle: first.subtitle, interactionKind: first.kind, source: deck.source ?? {}, blockedSince, claim: claimSummary(dir) };
 }
 function reviewSummary(dir, id) {
     const raw = readJson(reviewPath(dir));

package/dist/types.d.ts

@@ -72,7 +72,8 @@ export interface DeckSource {
     visual?: 'humanloop.visual/v1';
 }
 export interface Deck {
-    title?: string;
+    /** Short inbox topic for the deck as a whole. */
+    title: string;
     source?: DeckSource;
     interactions: Interaction[];
 }