@crouton-kit/humanloop 0.1.2 → 0.1.3

package/dist/tui/render.js

@@ -1,5 +1,45 @@
+import { execFileSync } from 'node:child_process';
 import stringWidth from 'string-width';
-import { getTerminalSize } from './terminal.js';
+// ── Termrender body rendering ────────────────────────────────────────────────
+let _termrenderAvail = null;
+function isTermrenderAvailable() {
+    if (_termrenderAvail !== null)
+        return _termrenderAvail;
+    try {
+        execFileSync('termrender', ['--version'], { stdio: 'pipe', timeout: 3000 });
+        _termrenderAvail = true;
+    }
+    catch {
+        _termrenderAvail = false;
+    }
+    return _termrenderAvail;
+}
+const _bodyCache = new Map();
+function renderBody(text, width) {
+    const key = `${text}\0${width}`;
+    const cached = _bodyCache.get(key);
+    if (cached)
+        return cached;
+    if (isTermrenderAvailable()) {
+        try {
+            const out = execFileSync('termrender', ['--width', String(width)], {
+                input: text,
+                encoding: 'utf-8',
+                timeout: 5000,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            const lines = out.split('\n');
+            if (lines.length > 0 && lines[lines.length - 1] === '')
+                lines.pop();
+            _bodyCache.set(key, lines);
+            return lines;
+        }
+        catch { /* fall through */ }
+    }
+    const fallback = wrap(sanitize(text), width);
+    _bodyCache.set(key, fallback);
+    return fallback;
+}
 // ── ANSI helpers ─────────────────────────────────────────────────────────────
 const ESC = '\x1b[';
 const RESET = `${ESC}0m`;
@@ -8,24 +48,13 @@ const DIM = `${ESC}2m`;
 const ITALIC = `${ESC}3m`;
 const GREEN = `${ESC}32m`;
 const YELLOW = `${ESC}33m`;
-const BLUE = `${ESC}34m`;
-const MAGENTA = `${ESC}35m`;
 const CYAN = `${ESC}36m`;
-const GRAY = `${ESC}90m`;
-const BG_BLUE = `${ESC}44m`;
-const WHITE = `${ESC}37m`;
-// Strip ANSI escape sequences and other C0/C1 control bytes from user-supplied
-// text so it can't poison the alt-screen buffer (cursor moves, color bleed,
-// embedded \x1b[2J that clears the screen, etc). Keeps \n and \t which the
-// wrappers handle explicitly.
 const CONTROL_CHARS_RE = /\x1b\[[0-9;?]*[a-zA-Z]|\x1b[@-_]|[\x00-\x08\x0B\x0E-\x1F\x7F-\x9F]/g;
 export function sanitize(text) {
     if (typeof text !== 'string')
         return '';
     return text.replace(CONTROL_CHARS_RE, '');
 }
-// For one-line displays (overview rows, summaries): collapse all whitespace
-// — including newlines and tabs — to single spaces so the row stays one line.
 function singleLine(text) {
     return sanitize(text).replace(/\s+/g, ' ').trim();
 }
@@ -34,7 +63,6 @@ function truncate(text, maxWidth) {
         return '';
     if (stringWidth(text) <= maxWidth)
         return text;
-    // Iterate by codepoint, not UTF-16 code unit, so surrogate pairs don't split.
     const chars = [...text];
     let w = 0;
     let out = '';
@@ -58,8 +86,6 @@ function hline(width, char = '─') {
         return '';
     return char.repeat(width);
 }
-// Word-wrap that ALSO respects \n as a hard break and ALSO breaks oversized
-// words at maxWidth so a single 200-char token doesn't overflow the frame.
 function wrap(text, maxWidth) {
     if (maxWidth < 1)
         return [text];
@@ -74,7 +100,6 @@ function wrap(text, maxWidth) {
         const words = para.split(/[ \t]+/).filter(Boolean);
         let current = '';
         for (let word of words) {
-            // Hard-break a word that's wider than the line.
             while (stringWidth(word) > maxWidth) {
                 if (current) {
                     out.push(current);
@@ -99,7 +124,6 @@ function wrap(text, maxWidth) {
     }
     return out.length > 0 ? out : [''];
 }
-// Take the longest prefix of `s` whose visible width is <= maxWidth.
 function sliceByWidth(s, maxWidth) {
     let w = 0;
     let out = '';
@@ -110,8 +134,6 @@ function sliceByWidth(s, maxWidth) {
         out += ch;
         w += cw;
     }
-    // Always advance at least one character so we don't loop forever on
-    // a single zero-width or oversized glyph.
     if (out === '' && s.length > 0)
         out = [...s][0];
     return out;
@@ -128,7 +150,6 @@ function hardWrap(text, maxWidth) {
         }
         let current = '';
         let currentW = 0;
-        // Iterate by codepoint so emoji surrogate pairs stay intact.
         for (const ch of [...seg]) {
             const cw = stringWidth(ch);
             if (currentW + cw > maxWidth) {
@@ -146,44 +167,39 @@ function hardWrap(text, maxWidth) {
     return out;
 }
 // ── Frame buffer ─────────────────────────────────────────────────────────────
-let prevFrame = [];
-export function flush(lines) {
-    const { rows } = getTerminalSize();
-    process.stdout.write('\x1b[?2026h');
+export function diffFrame(prevFrame, nextLines, rows) {
+    const writes = [];
     for (let i = 0; i < rows; i++) {
-        const line = i < lines.length ? lines[i] : '';
+        const line = i < nextLines.length ? nextLines[i] : '';
         if (prevFrame[i] !== line) {
-            process.stdout.write(`${ESC}${i + 1};1H${ESC}2K${line}`);
+            writes.push(`${ESC}${i + 1};1H${ESC}2K${line}`);
         }
     }
-    process.stdout.write('\x1b[?2026l');
-    prevFrame = [...lines];
+    return { writes, nextPrevFrame: [...nextLines] };
 }
 // ── Renderers ────────────────────────────────────────────────────────────────
-export function renderOverview(state) {
-    const { cols, rows } = getTerminalSize();
+export function renderOverview(state, cols, rows) {
     const lines = [];
     const title = `${BOLD}${CYAN} Decisions ${RESET}`;
-    const progress = `${state.answers.size}/${state.questions.length} answered`;
+    const progress = `${state.responses.size}/${state.interactions.length} answered`;
     lines.push('');
     lines.push(`  ${title}  ${DIM}${progress}${RESET}`);
     lines.push(`  ${DIM}${hline(Math.min(cols - 4, 60))}${RESET}`);
     lines.push('');
     const rowsBuf = [];
-    for (let i = 0; i < state.questions.length; i++) {
-        const q = state.questions[i];
-        const answer = state.answers.get(q.id);
-        const icon = answer ? `${GREEN}✓${RESET}` : `${DIM}○${RESET}`;
-        const label = singleLine(q.type === 'validation' ? q.statement : q.question);
-        const typeTag = `${DIM}[${q.type}]${RESET}`;
+    for (let i = 0; i < state.interactions.length; i++) {
+        const interaction = state.interactions[i];
+        const response = state.responses.get(interaction.id);
+        const icon = response ? `${GREEN}✓${RESET}` : `${DIM}○${RESET}`;
+        const label = singleLine(interaction.title);
         const cursor = i === state.currentIndex ? `${CYAN}▸${RESET} ` : '  ';
-        const labelMax = Math.max(10, cols - 20);
+        const labelMax = Math.max(10, cols - 16);
         rowsBuf.push({
-            line: `  ${cursor}${icon} ${truncate(label, labelMax)} ${typeTag}`,
+            line: `  ${cursor}${icon} ${truncate(label, labelMax)}`,
             questionIndex: i,
         });
-        if (answer) {
-            const summary = singleLine(answerSummary(answer));
+        if (response) {
+            const summary = singleLine(responseSummary(response, interaction));
             const summaryMax = Math.max(10, cols - 10);
             rowsBuf.push({
                 line: `      ${DIM}${truncate(summary, summaryMax)}${RESET}`,
@@ -191,11 +207,9 @@ export function renderOverview(state) {
             });
         }
     }
-    // Reserve space for header (4 already pushed) + footer (3) + scroll hints (2).
     const reserved = 4 + 3 + 2;
     const available = Math.max(1, rows - reserved);
     let scroll = state.scrollOffset || 0;
-    // Find first row matching currentIndex; ensure it's in [scroll, scroll+available).
     const focusRow = rowsBuf.findIndex((r) => r.questionIndex === state.currentIndex);
     if (focusRow >= 0) {
         if (focusRow < scroll)
@@ -204,7 +218,6 @@ export function renderOverview(state) {
             scroll = focusRow - available + 1;
     }
     scroll = Math.max(0, Math.min(scroll, Math.max(0, rowsBuf.length - available)));
-    state.scrollOffset = scroll;
     if (scroll > 0) {
         lines.push(`  ${DIM}↑ ${scroll} more above${RESET}`);
     }
@@ -226,129 +239,169 @@ export function renderOverview(state) {
         lines.push('');
     return lines.slice(0, rows);
 }
-export function renderItemReview(state) {
-    const { cols, rows } = getTerminalSize();
-    const lines = [];
-    const q = state.questions[state.currentIndex];
-    const visual = state.visuals.get(q.id);
-    const answer = state.answers.get(q.id);
-    const maxW = Math.min(cols - 4, 76);
-    // Header
-    const pos = `${state.currentIndex + 1}/${state.questions.length}`;
-    lines.push('');
-    lines.push(`  ${BOLD}${CYAN}[${pos}]${RESET} ${DIM}${q.type}${RESET}`);
-    lines.push(`  ${DIM}${hline(maxW)}${RESET}`);
-    lines.push('');
-    // Question / Statement
-    const headline = sanitize(q.type === 'validation' ? q.statement : q.question);
-    for (const line of wrap(headline, maxW)) {
-        lines.push(`  ${BOLD}${line}${RESET}`);
+export function renderItemReview(state, cols, rows) {
+    const interaction = state.interactions[state.currentIndex];
+    const visual = state.visuals.get(interaction.id);
+    const response = state.responses.get(interaction.id);
+    const maxW = Math.min(cols - 4, 120);
+    // Pre-body: position, divider, title, subtitle (always visible)
+    const preLines = [];
+    const pos = `${state.currentIndex + 1}/${state.interactions.length}`;
+    preLines.push('');
+    preLines.push(`  ${BOLD}${CYAN}[${pos}]${RESET}`);
+    preLines.push(`  ${DIM}${hline(maxW)}${RESET}`);
+    preLines.push('');
+    for (const line of wrap(sanitize(interaction.title), maxW)) {
+        preLines.push(`  ${BOLD}${line}${RESET}`);
     }
-    for (const line of wrap(sanitize(q.rationale), maxW)) {
-        lines.push(`  ${ITALIC}${GRAY}${line}${RESET}`);
+    if (interaction.subtitle) {
+        for (const line of wrap(sanitize(interaction.subtitle), maxW)) {
+            preLines.push(`  ${DIM}${line}${RESET}`);
+        }
     }
-    lines.push('');
-    // Visual context
+    // Body: rendered question body + expanded visual block (scrollable)
+    const bodyLines = [];
+    if (interaction.body) {
+        bodyLines.push('');
+        for (const line of renderBody(interaction.body, maxW)) {
+            bodyLines.push(`  ${line}`);
+        }
+    }
+    if (visual && visual.status === 'ready' && state.detailExpanded) {
+        bodyLines.push('');
+        bodyLines.push(`  ${DIM}── context ${hline(maxW - 12)}${RESET}`);
+        for (const vl of visual.content.split('\n')) {
+            bodyLines.push(`  ${vl}`);
+        }
+        bodyLines.push(`  ${DIM}${hline(maxW)}${RESET}`);
+    }
+    // Post-body: visual status hint, input buffer or actions, footer (always visible)
+    const postLines = [];
+    postLines.push('');
     if (visual) {
         if (visual.status === 'loading') {
-            lines.push(`  ${DIM}loading context...${RESET}`);
+            postLines.push(`  ${DIM}loading context...${RESET}`);
+            postLines.push('');
         }
         else if (visual.status === 'error') {
-            lines.push(`  ${YELLOW}visual context unavailable${RESET}`);
+            postLines.push(`  ${YELLOW}visual context unavailable${RESET}`);
+            postLines.push('');
         }
-        else if (state.detailExpanded) {
-            lines.push(`  ${DIM}── context ${hline(maxW - 12)}${RESET}`);
-            for (const vl of visual.content.split('\n')) {
-                lines.push(`  ${vl}`);
-            }
-            lines.push(`  ${DIM}${hline(maxW)}${RESET}`);
+        else if (!state.detailExpanded) {
+            postLines.push(`  ${DIM}[space] expand context${RESET}`);
+            postLines.push('');
         }
-        else {
-            lines.push(`  ${DIM}[space] expand context${RESET}`);
-        }
-        lines.push('');
     }
-    // Input mode
     if (state.inputMode) {
-        lines.push(`  ${DIM}${hline(maxW)}${RESET}`);
-        const label = state.inputMode.kind === 'comment' ? 'Comment'
-            : state.inputMode.kind === 'freetext' ? 'Response'
-                : 'Custom option';
-        lines.push(`  ${YELLOW}${label}:${RESET}`);
+        postLines.push(`  ${DIM}${hline(maxW)}${RESET}`);
+        const label = interaction.freetextLabel !== undefined
+            ? interaction.freetextLabel
+            : state.inputMode.kind === 'comment' ? 'Comment' : 'Response';
+        // Show attached option (comment mode only) — Tab cycles
+        let attachedLine;
+        if (state.inputMode.kind === 'comment') {
+            const attachedId = state.inputMode.selectedOptionId;
+            const opts = interaction.options;
+            if (opts.length > 0) {
+                const attached = attachedId !== undefined
+                    ? opts.find((o) => o.id === attachedId)
+                    : undefined;
+                const valueText = attached !== undefined
+                    ? `${CYAN}${sanitize(attached.label)}${RESET}`
+                    : `${DIM}none${RESET}`;
+                attachedLine = `  ${DIM}attached:${RESET} ${valueText}  ${DIM}[tab to cycle]${RESET}`;
+            }
+        }
+        postLines.push(`  ${YELLOW}${label}:${RESET}`);
         const bufLines = hardWrap(state.inputMode.buffer, maxW - 1);
         for (let i = 0; i < bufLines.length; i++) {
             const isLast = i === bufLines.length - 1;
-            lines.push(`  ${bufLines[i]}${isLast ? '█' : ''}`);
+            postLines.push(`  ${bufLines[i]}${isLast ? '█' : ''}`);
         }
-        lines.push('');
-        lines.push(`  ${DIM}enter${RESET} submit  ${DIM}esc${RESET} cancel`);
+        if (attachedLine !== undefined) {
+            postLines.push('');
+            postLines.push(attachedLine);
+        }
+        postLines.push('');
+        postLines.push(`  ${DIM}enter${RESET} submit  ${DIM}esc${RESET} cancel`);
     }
     else {
-        // Actions
-        lines.push(...renderActions(q, state.selectedAction, answer));
+        postLines.push(...renderActions(interaction, state.selectedAction, response));
     }
-    // Footer
-    while (lines.length < rows - 1)
-        lines.push('');
+    // Window the body
+    const reservedRows = preLines.length + postLines.length + 1; // +1 for footer
+    const bodyHeight = Math.max(1, rows - reservedRows);
+    const overflows = bodyLines.length > bodyHeight;
+    let scroll = state.scrollOffset || 0;
+    const maxScroll = Math.max(0, bodyLines.length - bodyHeight);
+    scroll = Math.max(0, Math.min(scroll, maxScroll));
+    state.scrollOffset = scroll;
+    let visibleBody;
+    if (overflows) {
+        visibleBody = bodyLines.slice(scroll, scroll + bodyHeight);
+        if (scroll > 0) {
+            visibleBody[0] = `  ${DIM}↑ ${scroll} more above${RESET}`;
+        }
+        const remainingBelow = bodyLines.length - (scroll + bodyHeight);
+        if (remainingBelow > 0) {
+            visibleBody[visibleBody.length - 1] = `  ${DIM}↓ ${remainingBelow} more below${RESET}`;
+        }
+    }
+    else {
+        visibleBody = bodyLines;
+    }
+    // Footer hint — mention scroll keys when body overflows
     const footerParts = [
         `${DIM}n/p${RESET} prev/next`,
         `${DIM}space${RESET} expand`,
         `${DIM}q${RESET} overview`,
     ];
-    lines.push(`  ${footerParts.join('  ')}`);
-    // If the headline + visual + actions overflowed the viewport, the footer
-    // would otherwise scroll off the bottom. Clip to `rows` so flush() never
-    // writes more rows than the terminal has.
+    if (overflows)
+        footerParts.unshift(`${DIM}u/d${RESET} scroll`);
+    const footer = `  ${footerParts.join('  ')}`;
+    // Assemble — pad to fill rows so post-body sits at the bottom
+    const lines = [...preLines, ...visibleBody, ...postLines];
+    while (lines.length < rows - 1)
+        lines.push('');
+    lines.push(footer);
+    // Final clamp (safety net for very small terminals)
     if (lines.length > rows) {
-        return [...lines.slice(0, rows - 1), lines[lines.length - 1]];
+        return [...lines.slice(0, rows - 1), footer];
     }
     return lines;
 }
-function renderActions(q, selectedAction, existing) {
+function renderActions(interaction, selectedAction, existing) {
     const lines = [];
-    if (q.type === 'validation') {
-        const actions = [
-            { key: '1', label: 'Approve', desc: 'accept as stated' },
-            { key: '2', label: 'Approve + comment', desc: 'accept with note' },
-            { key: '3', label: 'Reject', desc: 'do not accept as stated' },
-            { key: '4', label: 'Comment', desc: 'feedback without decision' },
-        ];
-        for (let i = 0; i < actions.length; i++) {
-            const a = actions[i];
-            const cursor = i === selectedAction ? `${CYAN}▸${RESET}` : ' ';
-            const keyBadge = `${DIM}[${a.key}]${RESET}`;
-            lines.push(`  ${cursor} ${keyBadge} ${a.label} ${DIM}— ${a.desc}${RESET}`);
-        }
+    const opts = interaction.options;
+    for (let i = 0; i < opts.length; i++) {
+        const o = opts[i];
+        const cursor = i === selectedAction ? `${CYAN}▸${RESET}` : ' ';
+        const sc = o.shortcut ?? ' ';
+        const keyBadge = `${DIM}[${sc}]${RESET}`;
+        const desc = o.description ? ` ${DIM}— ${sanitize(o.description)}${RESET}` : '';
+        lines.push(`  ${cursor} ${keyBadge} ${sanitize(o.label)}${desc}`);
     }
-    else if (q.type === 'choice') {
-        for (let i = 0; i < q.options.length; i++) {
-            const cursor = i === selectedAction ? `${CYAN}▸${RESET}` : ' ';
-            // Numeric shortcut only for 1..9 — past that, the digit '1' would fire
-            // before the user can type the second digit, so we use a blank pad.
-            const keyBadge = i < 9 ? `${DIM}[${i + 1}]${RESET}` : `${DIM}   ${RESET}`;
-            lines.push(`  ${cursor} ${keyBadge} ${sanitize(q.options[i])}`);
-        }
-        const otherIdx = q.options.length;
-        const cursor = otherIdx === selectedAction ? `${CYAN}▸${RESET}` : ' ';
-        const otherBadge = otherIdx < 9 ? `${DIM}[${otherIdx + 1}]${RESET}` : `${DIM}   ${RESET}`;
-        lines.push(`  ${cursor} ${otherBadge} ${ITALIC}Other (custom)${RESET}`);
+    if (interaction.allowFreetext && opts.length > 0) {
+        const cursor = opts.length === selectedAction ? `${CYAN}▸${RESET}` : ' ';
+        const label = interaction.freetextLabel !== undefined ? interaction.freetextLabel : 'Add comment';
+        lines.push(`  ${cursor} ${DIM}[c]${RESET} ${label}`);
     }
-    else {
-        lines.push(`  ${DIM}[r]${RESET} Enter response`);
+    else if (interaction.allowFreetext && opts.length === 0) {
+        const ftLabel = interaction.freetextLabel !== undefined ? interaction.freetextLabel : 'Enter response';
+        lines.push(`  ${DIM}[r]${RESET} ${ftLabel}`);
     }
     if (existing) {
         lines.push('');
-        lines.push(`  ${GREEN}Current: ${answerSummary(existing)}${RESET}`);
+        lines.push(`  ${GREEN}Current: ${responseSummary(existing, interaction)}${RESET}`);
     }
     return lines;
 }
-export function renderFinal(state) {
-    const { cols, rows } = getTerminalSize();
+export function renderFinal(state, cols, rows) {
     const header = [];
     const footer = [];
     const maxW = Math.min(cols - 4, 60);
-    const total = state.questions.length;
-    const answered = state.answers.size;
+    const total = state.interactions.length;
+    const answered = state.responses.size;
     header.push('');
     header.push(`  ${BOLD}${CYAN} Summary ${RESET}`);
     header.push(`  ${DIM}${hline(maxW)}${RESET}`);
@@ -361,17 +414,14 @@ export function renderFinal(state) {
         footer.push(`  ${YELLOW}${total - answered} unanswered — press p to go back${RESET}`);
     }
     footer.push(`  ${DIM}enter${RESET} submit  ${DIM}p${RESET} go back`);
-    // Build per-question rows so we can clip to fit the viewport while
-    // keeping the header + footer always visible (the keybind hint at the
-    // bottom is essential — without it the user can't submit).
     const questionRows = [];
-    for (const q of state.questions) {
-        const answer = state.answers.get(q.id);
-        const icon = answer ? `${GREEN}✓${RESET}` : `${YELLOW}○${RESET}`;
-        const label = singleLine(q.type === 'validation' ? q.statement : q.question);
+    for (const interaction of state.interactions) {
+        const response = state.responses.get(interaction.id);
+        const icon = response ? `${GREEN}✓${RESET}` : `${YELLOW}○${RESET}`;
+        const label = singleLine(interaction.title);
         questionRows.push(`  ${icon} ${truncate(label, Math.max(10, maxW - 4))}`);
-        if (answer) {
-            questionRows.push(`    ${DIM}${truncate(singleLine(answerSummary(answer)), Math.max(10, maxW - 6))}${RESET}`);
+        if (response) {
+            questionRows.push(`    ${DIM}${truncate(singleLine(responseSummary(response, interaction)), Math.max(10, maxW - 6))}${RESET}`);
         }
     }
     const available = Math.max(1, rows - header.length - footer.length - 1);
@@ -387,15 +437,15 @@ export function renderFinal(state) {
         lines.push('');
     return lines.slice(0, rows);
 }
-function answerSummary(a) {
-    switch (a.type) {
-        case 'validation':
-            return a.approved
-                ? (a.comment ? `approved: "${sanitize(a.comment)}"` : 'approved')
-                : (a.comment ? `commented: "${sanitize(a.comment)}"` : 'commented');
-        case 'choice':
-            return a.isCustom ? `custom: "${sanitize(a.selected)}"` : sanitize(a.selected);
-        case 'freetext':
-            return sanitize(a.response);
-    }
+export function responseSummary(r, interaction) {
+    const opt = r.selectedOptionId
+        ? interaction.options.find((o) => o.id === r.selectedOptionId)
+        : undefined;
+    if (opt && r.freetext)
+        return `${sanitize(opt.label)}: "${sanitize(r.freetext)}"`;
+    if (opt)
+        return sanitize(opt.label);
+    if (r.freetext)
+        return sanitize(r.freetext);
+    return '(empty)';
 }

package/dist/tui/tmux.d.ts

@@ -1,6 +1,10 @@
-import type { DecisionsOutput } from '../types.js';
+import type { InteractionResponse } from '../types.js';
+export interface TuiOutput {
+    responses: InteractionResponse[];
+    completedAt: string;
+}
 export interface TmuxDispatchOpts {
     sessionId?: string;
     visuals: boolean;
 }
-export declare function dispatchToTmuxPane(file: string, opts: TmuxDispatchOpts): Promise<DecisionsOutput>;
+export declare function dispatchToTmuxPane(file: string, opts: TmuxDispatchOpts): Promise<TuiOutput>;

package/dist/types.d.ts

@@ -1,50 +1,36 @@
-export type QuestionType = 'validation' | 'choice' | 'freetext';
-export interface ValidationQuestion {
+import type { Key } from './tui/terminal.js';
+export type InteractionKind = 'notify' | 'validation' | 'decision' | 'context' | 'error';
+export interface InteractionOption {
     id: string;
-    type: 'validation';
-    statement: string;
-    rationale: string;
+    label: string;
+    description?: string;
+    shortcut?: string;
 }
-export interface ChoiceQuestion {
+export interface Interaction {
     id: string;
-    type: 'choice';
-    question: string;
-    rationale: string;
-    options: string[];
+    title: string;
+    subtitle?: string;
+    body?: string;
+    bodyPath?: string;
+    options: InteractionOption[];
+    allowFreetext?: boolean;
+    freetextLabel?: string;
+    kind?: InteractionKind;
 }
-export interface FreetextQuestion {
+export interface InteractionResponse {
     id: string;
-    type: 'freetext';
-    question: string;
-    rationale: string;
+    selectedOptionId?: string;
+    freetext?: string;
 }
-export type Question = ValidationQuestion | ChoiceQuestion | FreetextQuestion;
-export interface DecisionsInput {
-    title?: string;
-    questions: Question[];
-}
-export interface ValidationAnswer {
-    id: string;
-    type: 'validation';
-    approved: boolean;
-    comment?: string;
-}
-export interface ChoiceAnswer {
-    id: string;
-    type: 'choice';
-    selected: string;
-    isCustom: boolean;
-    comment?: string;
-}
-export interface FreetextAnswer {
-    id: string;
-    type: 'freetext';
-    response: string;
+export interface DeckSource {
+    sessionName?: string;
+    askedBy?: string;
+    blockedSince?: string;
 }
-export type Answer = ValidationAnswer | ChoiceAnswer | FreetextAnswer;
-export interface DecisionsOutput {
-    answers: Answer[];
-    completedAt: string;
+export interface Deck {
+    title?: string;
+    source?: DeckSource;
+    interactions: Interaction[];
 }
 export interface VisualBlock {
     questionId: string;
@@ -55,18 +41,16 @@ export type Phase = 'overview' | 'item-review' | 'final';
 export type InputMode = null | {
     kind: 'comment';
     buffer: string;
+    selectedOptionId?: string;
 } | {
     kind: 'freetext';
     buffer: string;
-} | {
-    kind: 'custom-option';
-    buffer: string;
 };
 export interface TuiState {
     phase: Phase;
     currentIndex: number;
-    questions: Question[];
-    answers: Map<string, Answer>;
+    interactions: Interaction[];
+    responses: Map<string, InteractionResponse>;
     visuals: Map<string, VisualBlock>;
     inputMode: InputMode;
     selectedAction: number;
@@ -74,3 +58,31 @@ export interface TuiState {
     scrollOffset: number;
     persist?: () => void;
 }
+export type GenerateVisual = (interaction: Interaction) => Promise<{
+    ok: true;
+    ansi: string;
+    markdown: string;
+} | {
+    ok: false;
+    error: string;
+}>;
+export interface MountedPanelOpts {
+    deck: Deck;
+    progressPath?: string;
+    generateVisual?: GenerateVisual;
+    cols: number;
+    rows: number;
+    onProgress?: (responses: InteractionResponse[]) => void;
+    onComplete?: (responses: InteractionResponse[]) => void;
+    onExit?: () => void;
+}
+export interface MountedPanel {
+    handleKey(input: string, key: Key): void;
+    render(): string[];
+    handleResize(cols: number, rows: number): string[];
+    unmount(): void;
+    loadDeck(deck: Deck, opts?: {
+        progressPath?: string;
+    }): void;
+    canAcceptHostKeys(): boolean;
+}

package/dist/types.js

@@ -1,2 +1,2 @@
-// ── Input: what the agent writes ─────────────────────────────────────────────
+// ── v2 shapes (v1 schema dropped per cycle-16 user pivot — humanloop is v2-only) ──
 export {};