@north-light/api 0.3.580 → 0.3.587

package/dist/clients/inbox/tui/panel.js

@@ -0,0 +1,84 @@
+import { projectPageDisplayMarkdown } from '../../../core/human/page-markdown.js';
+import { projectHtmlDocumentMarkdown } from '../../../core/human/page-html-markdown.js';
+import { handleKeypress } from './input.js';
+import { clampItemReviewScroll, renderFinal, renderItemReview, renderOverview } from './render.js';
+import { pageComplete, slotAnswered } from './slots.js';
+/** Same projection the inline chat block reads (page-block.ts) — the authored
+ *  prose outside slot tags, or the whole document for an HTML page, which has
+ *  no slots to carry it. A malformed or unreadable document just yields no
+ *  display content here, same as the inline block's own reload() fallback. */
+function displayMarkdownOf(manifest, document) {
+    if (document === undefined)
+        return '';
+    try {
+        return manifest.dialect === 'html' ? projectHtmlDocumentMarkdown(document) : projectPageDisplayMarkdown(document, manifest);
+    }
+    catch {
+        return '';
+    }
+}
+function buildInitialState(manifest, document, initialResponses, productKinds, editorAvailable, wrapWidth) {
+    const responses = new Map();
+    const validIds = new Set(manifest.slots.flatMap((slot) => slot.id === undefined ? [] : [slot.id]));
+    for (const [id, response] of Object.entries(initialResponses ?? {}))
+        if (validIds.has(id))
+            responses.set(id, response);
+    const displayMarkdown = displayMarkdownOf(manifest, document);
+    // Single-slot pages skip straight to item-review to save a step — but only
+    // when there is no display prose to show first; otherwise that prose would
+    // never be seen.
+    const phase = manifest.slots.length === 1 && displayMarkdown === '' ? 'item-review' : 'overview';
+    const state = { phase, currentIndex: 0, manifest, displayMarkdown, slots: manifest.slots, responses, productKinds, inputMode: null, selectedAction: 0, scrollOffset: 0, followSelection: true, hscrollOffset: 0, hscrollMax: 0, wrapWidth, editorAvailable };
+    const first = manifest.slots.findIndex((slot) => slot.id !== undefined && !slotAnswered(state, slot));
+    if (first >= 0)
+        state.currentIndex = first;
+    return state;
+}
+export function collectResponses(state) { return Object.fromEntries(state.responses); }
+function rebindPersist(internals) { internals.state.persist = () => internals.callbacks.onProgress?.(collectResponses(internals.state)); }
+export function mountPanel(opts) {
+    const internals = { state: buildInitialState(opts.manifest, opts.document, opts.initialResponses, opts.productKinds ?? [], opts.onEditorRequest !== undefined, opts.cols), cols: opts.cols, rows: opts.rows, mounted: true, callbacks: { onProgress: opts.onProgress, onComplete: opts.onComplete, onExit: opts.onExit, onDirty: opts.onDirty, onEditorRequest: opts.onEditorRequest } };
+    rebindPersist(internals);
+    const renderLines = () => {
+        if (internals.state.phase === 'overview')
+            return renderOverview(internals.state, internals.cols, internals.rows);
+        if (internals.state.phase === 'final')
+            return renderFinal(internals.state, internals.cols, internals.rows);
+        clampItemReviewScroll(internals.state, internals.cols, internals.rows);
+        return renderItemReview(internals.state, internals.cols, internals.rows);
+    };
+    return {
+        handleKey(input, key) {
+            if (!internals.mounted)
+                return;
+            if (key.ctrl && input === 'o' && internals.state.inputMode !== null && internals.callbacks.onEditorRequest !== undefined) {
+                internals.callbacks.onEditorRequest();
+                return;
+            }
+            handleKeypress(input, key, internals.state, () => internals.callbacks.onDirty?.(), (submit) => {
+                const responses = collectResponses(internals.state);
+                if (submit === true && pageComplete(internals.state))
+                    internals.callbacks.onComplete?.(responses);
+                else
+                    internals.callbacks.onExit?.();
+            });
+            internals.callbacks.onDirty?.();
+        },
+        render: () => internals.mounted ? renderLines() : [],
+        handleResize(cols, rows) { internals.cols = cols; internals.rows = rows; internals.state.wrapWidth = cols; return renderLines(); },
+        unmount() { internals.mounted = false; internals.state.persist = undefined; },
+        loadPage(manifest, loadOpts) {
+            if (!internals.mounted)
+                return;
+            const prior = collectResponses(internals.state);
+            const merged = { ...(loadOpts?.initialResponses ?? {}), ...prior };
+            internals.state = buildInitialState(manifest, loadOpts?.document, merged, loadOpts?.productKinds ?? internals.state.productKinds, internals.callbacks.onEditorRequest !== undefined, internals.cols);
+            rebindPersist(internals);
+        },
+        canAcceptHostKeys: () => internals.mounted && internals.state.inputMode === null,
+        atPageTop: () => !internals.mounted || (internals.state.phase === 'overview' && internals.state.inputMode === null),
+        getInputBuffer: () => !internals.mounted || internals.state.inputMode === null ? undefined : internals.state.inputMode.buffer,
+        setInputBuffer(text) { if (!internals.mounted || internals.state.inputMode === null)
+            return; internals.state.inputMode.buffer = text; internals.state.inputMode.cursor = [...text].length; },
+    };
+}

package/dist/clients/inbox/tui/render.d.ts

@@ -0,0 +1,23 @@
+import type { TuiState } from './types.js';
+export declare function renderOverview(state: TuiState, cols: number, rows: number): string[];
+/** Wrap an input buffer and paint the cursor the way a terminal does: the
+ *  character under it is drawn in reverse video, occupying its own cell rather
+ *  than pushing the rest of the line across by one. Only past the end of a row
+ *  does the cursor need a cell of its own, and there it is a reversed space.
+ *  Wrapping runs over the plain buffer, so the rows here are exactly the rows
+ *  `verticalCursor` moves between. */
+export declare function renderInputBuffer(buffer: string, cursor: number, maxWidth: number): string[];
+/** Start of the word before the cursor (alt+left / readline alt-b). The one
+ *  implementation of word motion for every inbox input buffer. */
+export declare function wordLeftIndex(buffer: string, cursor: number): number;
+/** Just past the end of the word after the cursor (alt+right / readline alt-f). */
+export declare function wordRightIndex(buffer: string, cursor: number): number;
+export declare function wrappedRowBounds(buffer: string, width: number): {
+    start: number;
+    end: number;
+}[];
+export declare function verticalCursor(buffer: string, cursor: number, delta: number, width: number): number;
+export declare function clampItemReviewScroll(state: TuiState, cols: number, rows: number): void;
+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[];

package/dist/clients/inbox/tui/render.js

@@ -0,0 +1,378 @@
+import stringWidth from 'string-width';
+import { isResponseBearingSlot } from '../../../core/human/page-schema.js';
+import { answerCommentAnchorLabel, describePageAnswer } from '../../../core/human/answer.js';
+import { renderMarkdownBlockAwareLines } from '../../../core/termrender/termrender.js';
+import { rewriteMarkdownDocLinks } from '../../attach/render/markdown-source.js';
+import { commentAnchors, describeSlot, pageComplete, slotActions, slotAnswered, tableMarkdown, terminalAnswerable } from './slots.js';
+import { RESET, BOLD, DIM, GREEN, YELLOW, CYAN, REVERSE, sanitize, singleLine, truncate, hline, wrap, centerHorizontal, clipLine, panLine, visibleWidth } from './ansi.js';
+const PAN_STEP = 8;
+const mdLines = (md, maxW, paneW) => renderMarkdownBlockAwareLines(rewriteMarkdownDocLinks(md), maxW, paneW);
+function pageAnswer(state) {
+    return describePageAnswer(state.manifest, Object.fromEntries(state.responses), { completedAt: '' });
+}
+function answerSlot(answer, slot) {
+    return slot.id === undefined ? undefined : answer.slots.find((candidate) => candidate.id === slot.id);
+}
+function answerSummary(slot) {
+    if (slot === undefined || slot.state === 'unanswered')
+        return 'unanswered';
+    if (slot.raw !== undefined)
+        return 'custom response';
+    const groups = slot.text !== undefined ? [slot.text.edited ? 'edited' : 'accepted'] : slot.groups.map((group) => group.picked.length === 0 ? 'none' : group.picked.map((item) => item.label).join(', '));
+    if (slot.freetext !== undefined)
+        groups.push(slot.freetext);
+    if (slot.comments.length > 0)
+        groups.push(`${slot.comments.length} comment${slot.comments.length === 1 ? '' : 's'}`);
+    return groups.join('; ') || 'answered';
+}
+function commentLabel(slot, anchor) {
+    return answerCommentAnchorLabel(slot, anchor);
+}
+export function renderOverview(state, cols, rows) {
+    const maxW = Math.min(Math.max(20, cols - 4), 120);
+    const paneW = Math.max(20, cols - 4);
+    const lines = ['', ...hangingWrap(singleLine(state.manifest.title), maxW, '', 0, `${BOLD}${CYAN}`)];
+    if (state.manifest.subtitle)
+        for (const line of wrap(sanitize(state.manifest.subtitle), maxW))
+            lines.push(`  ${DIM}${line}${RESET}`);
+    if (state.displayMarkdown !== '') {
+        lines.push('');
+        for (const line of mdLines(state.displayMarkdown, maxW, paneW))
+            lines.push(`  ${line}`);
+    }
+    else if (state.manifest.dialect === 'html') {
+        // An HTML page has no slots, so an unreadable document would otherwise
+        // leave the reader dismissing a title with nothing under it.
+        lines.push('', `  ${DIM}HTML page — open in Northlight to read this${RESET}`);
+    }
+    const hasBody = state.slots.length > 0;
+    if (hasBody)
+        lines.push(`  ${DIM}${hline(maxW)}${RESET}`, '');
+    const answer = pageAnswer(state);
+    let priorStep = -1;
+    let cursorLine;
+    for (let i = 0; i < state.slots.length; i++) {
+        const slot = state.slots[i];
+        if (state.manifest.steps > 1 && slot.step !== priorStep) {
+            if (priorStep !== -1)
+                lines.push('');
+            lines.push(`  ${BOLD}Step ${slot.step + 1}/${state.manifest.steps}${RESET}`);
+            priorStep = slot.step;
+        }
+        const response = slot.id === undefined ? undefined : state.responses.get(slot.id);
+        const icon = isResponseBearingSlot(slot) ? (slotAnswered(state, slot) ? `${GREEN}✓${RESET}` : `${DIM}○${RESET}`) : `${DIM}·${RESET}`;
+        const cursor = i === state.currentIndex ? `${CYAN}▸${RESET} ` : '  ';
+        if (i === state.currentIndex)
+            cursorLine = lines.length;
+        lines.push(`  ${cursor}${icon} ${truncate(singleLine(describeSlot(slot)), Math.max(10, cols - 16))}`);
+        if (response !== undefined)
+            lines.push(`      ${DIM}${truncate(singleLine(answerSummary(answerSlot(answer, slot))), Math.max(10, cols - 10))}${RESET}`);
+    }
+    // A page whose question the terminal cannot author can never be submitted
+    // here, so it says so on the way in rather than letting the reader answer
+    // everything else and meet a submit gate that never opens.
+    if (state.manifest.slots.some((slot) => isResponseBearingSlot(slot) && !terminalAnswerable(slot))) {
+        lines.push('');
+        for (const line of wrap('This page must be answered in Northlight. Leaving it here keeps it in your inbox; x on the list cancels it.', maxW - 2))
+            lines.push(`  ${YELLOW}${line}${RESET}`);
+    }
+    if (hasBody)
+        lines.push('');
+    lines.push(`  ${DIM}${hline(maxW)}${RESET}`);
+    const display = !state.manifest.slots.some(isResponseBearingSlot);
+    const footer = display ? `  ${DIM}u/d${RESET} scroll  ${DIM}q${RESET} dismiss` : `  ${DIM}enter${RESET} review  ${DIM}↑↓/jk${RESET} navigate  ${DIM}u/d${RESET} scroll  ${DIM}q${RESET} close`;
+    return centeredWindow(lines, footer, state, cols, rows, maxW + 2, state.followSelection ? cursorLine : undefined);
+}
+/** Wrap an input buffer and paint the cursor the way a terminal does: the
+ *  character under it is drawn in reverse video, occupying its own cell rather
+ *  than pushing the rest of the line across by one. Only past the end of a row
+ *  does the cursor need a cell of its own, and there it is a reversed space.
+ *  Wrapping runs over the plain buffer, so the rows here are exactly the rows
+ *  `verticalCursor` moves between. */
+export function renderInputBuffer(buffer, cursor, maxWidth) {
+    const chars = [...buffer];
+    const at = Math.max(0, Math.min(cursor, chars.length));
+    const rows = wrappedRowBounds(buffer, maxWidth);
+    let cursorRow = 0;
+    for (let i = 0; i < rows.length; i++)
+        if (rows[i].start <= at)
+            cursorRow = i;
+    const lines = rows.map((row, index) => {
+        if (index !== cursorRow)
+            return chars.slice(row.start, row.end).join('');
+        const head = chars.slice(row.start, at).join('');
+        const under = at < row.end ? chars[at] : ' ';
+        const tail = at < row.end ? chars.slice(at + 1, row.end).join('') : '';
+        return `${head}${REVERSE}${under}${RESET}${tail}`;
+    });
+    // A cursor past the end of an already-full row has no cell left on it, so it
+    // takes the first cell of the next row instead of overflowing the wrap width.
+    const last = rows[cursorRow];
+    if (at === last.end && stringWidth(chars.slice(last.start, last.end).join('')) >= maxWidth) {
+        lines[cursorRow] = chars.slice(last.start, last.end).join('');
+        lines.splice(cursorRow + 1, 0, `${REVERSE} ${RESET}`);
+    }
+    return lines;
+}
+/** Start of the word before the cursor (alt+left / readline alt-b). The one
+ *  implementation of word motion for every inbox input buffer. */
+export function wordLeftIndex(buffer, cursor) {
+    const chars = [...buffer];
+    let i = Math.max(0, Math.min(cursor, chars.length));
+    while (i > 0 && /\s/.test(chars[i - 1]))
+        i--;
+    while (i > 0 && !/\s/.test(chars[i - 1]))
+        i--;
+    return i;
+}
+/** Just past the end of the word after the cursor (alt+right / readline alt-f). */
+export function wordRightIndex(buffer, cursor) {
+    const chars = [...buffer];
+    let i = Math.max(0, Math.min(cursor, chars.length));
+    while (i < chars.length && /\s/.test(chars[i]))
+        i++;
+    while (i < chars.length && !/\s/.test(chars[i]))
+        i++;
+    return i;
+}
+export function wrappedRowBounds(buffer, width) {
+    const chars = [...buffer];
+    const w = Math.max(1, width);
+    const rows = [];
+    let start = 0;
+    let rowW = 0;
+    for (let i = 0; i < chars.length; i++) {
+        const ch = chars[i];
+        if (ch === '\n') {
+            rows.push({ start, end: i });
+            start = i + 1;
+            rowW = 0;
+            continue;
+        }
+        const cw = stringWidth(ch);
+        if (rowW + cw > w) {
+            rows.push({ start, end: i });
+            start = i;
+            rowW = cw;
+        }
+        else
+            rowW += cw;
+    }
+    rows.push({ start, end: chars.length });
+    return rows;
+}
+export function verticalCursor(buffer, cursor, delta, width) {
+    const rows = wrappedRowBounds(buffer, width);
+    const at = Math.max(0, Math.min(cursor, [...buffer].length));
+    let r = 0;
+    for (let i = 0; i < rows.length; i++)
+        if (rows[i].start <= at)
+            r = i;
+    const target = rows[r + delta];
+    return target === undefined ? at : Math.min(target.start + (at - rows[r].start), target.end);
+}
+function responseComments(state, slot) {
+    if (slot.id === undefined)
+        return [];
+    const response = state.responses.get(slot.id);
+    return response?.comments ?? [];
+}
+/** A heading that wraps to the column instead of running off the pane: the
+ *  first row carries `prefix` (already styled, `prefixW` cells wide) and the
+ *  continuation rows hang under the text, not under the prefix. */
+function hangingWrap(text, maxW, prefix, prefixW, style) {
+    return wrap(text, Math.max(10, maxW - prefixW)).map((line, i) => `  ${i === 0 ? prefix : ' '.repeat(prefixW)}${style}${line}${RESET}`);
+}
+function selected(state, slot, group, id) {
+    if (slot.id === undefined)
+        return false;
+    const r = state.responses.get(slot.id);
+    if (group === 'option')
+        return r?.selectedOptionIds?.includes(id) === true;
+    if (group === 'card')
+        return r?.selectedCardIds?.includes(id) === true;
+    if (group === 'row')
+        return r?.selectedRowIds?.includes(id) === true;
+    return r?.selectedColumnIds?.includes(id) === true;
+}
+function itemLines(state, cols) {
+    const slot = state.slots[state.currentIndex];
+    const maxW = Math.min(Math.max(20, cols - 4), 120);
+    const paneW = Math.max(20, cols - 4);
+    const counter = `[${state.currentIndex + 1}/${state.slots.length}]`;
+    const lines = ['', ...hangingWrap(singleLine(state.manifest.title), maxW, `${BOLD}${CYAN}${counter}${RESET}  `, stringWidth(counter) + 2, DIM), `  ${DIM}${hline(maxW)}${RESET}`, '', ...hangingWrap(singleLine(describeSlot(slot)), maxW, '', 0, BOLD)];
+    const body = slot.config.body;
+    if (typeof body === 'string' && body.length > 0) {
+        lines.push('');
+        for (const line of mdLines(body, maxW, paneW))
+            lines.push(`  ${line}`);
+    }
+    if (!terminalAnswerable(slot)) {
+        lines.push('');
+        for (const line of wrap(`${sanitize(slot.kind)} — must be answered in Northlight; the terminal cannot submit this page`, Math.max(10, maxW - 2)))
+            lines.push(`  ${YELLOW}${line}${RESET}`);
+        lines.push(`  ${DIM}q leaves it in your inbox; x on the list cancels it${RESET}`);
+    }
+    else if (slot.kind === 'chart') {
+        const c = slot.config;
+        const title = c.title ?? `${c.x} vs ${(c.y ?? []).map((y) => y.label ?? y.field).join(', ')}`;
+        lines.push('', `  ${DIM}chart — ${sanitize(c.kind)}: ${sanitize(title)}${RESET}`);
+    }
+    else if (slot.kind === 'table') {
+        lines.push('');
+        for (const line of mdLines(tableMarkdown(slot.config), maxW, paneW))
+            lines.push(`  ${line}`);
+        const label = slot.config.label;
+        if (label)
+            lines.push(`  ${DIM}${sanitize(label)}${RESET}`);
+    }
+    else if (slot.kind === 'text') {
+        const response = slot.id === undefined ? undefined : state.responses.get(slot.id);
+        const text = response?.text ?? slot.config.initialText;
+        lines.push('');
+        for (const line of mdLines(text, maxW, paneW))
+            lines.push(`  ${line}`);
+    }
+    lines.push('', `  ${DIM}${hline(maxW)}${RESET}`);
+    let footer;
+    if (state.inputMode !== null) {
+        const label = state.inputMode.kind === 'comment' ? `Comment on ${commentLabel(slot, state.inputMode.anchor)}` : state.inputMode.kind === 'text' ? 'Edit text' : 'Other response';
+        lines.push(`  ${BOLD}${label}${RESET}`);
+        for (const line of renderInputBuffer(state.inputMode.buffer, state.inputMode.cursor, Math.max(10, maxW - 4)))
+            lines.push(`  ${line}`);
+        footer = `  ${DIM}enter save  esc cancel${state.editorAvailable ? '  ^o editor' : ''}${RESET}`;
+    }
+    else {
+        const actions = slotActions(slot);
+        actions.forEach((action, index) => {
+            const cursor = index === state.selectedAction ? `${CYAN}▸${RESET}` : ' ';
+            if (action.kind === 'select') {
+                const mark = selected(state, slot, action.group, action.id) ? `${GREEN}✓${RESET}` : ' ';
+                const shortcut = action.shortcut ? `[${action.shortcut}] ` : '';
+                const shortcutW = stringWidth(shortcut);
+                wrap(sanitize(action.label), Math.max(10, maxW - 6 - shortcutW)).forEach((line, i) => lines.push(i === 0 ? `  ${cursor} [${mark}] ${shortcut}${line}` : `${' '.repeat(8 + shortcutW)}${line}`));
+                if (action.description)
+                    for (const line of wrap(sanitize(action.description), Math.max(10, maxW - 6)))
+                        lines.push(`        ${DIM}${line}${RESET}`);
+            }
+            else {
+                const key = action.kind === 'freetext' ? 'r' : action.kind === 'edit' ? 'e' : 'a';
+                wrap(sanitize(action.label), Math.max(10, maxW - 6)).forEach((line, i) => lines.push(i === 0 ? `  ${cursor} [${key}] ${line}` : `        ${line}`));
+            }
+        });
+        for (const comment of responseComments(state, slot))
+            for (const line of wrap(`attached: ${commentLabel(slot, comment.anchor)} — ${sanitize(comment.text)}`, Math.max(10, maxW - 2)))
+                lines.push(`  ${DIM}${line}${RESET}`);
+        if (state.hint)
+            lines.push(`  ${YELLOW}${sanitize(state.hint)}${RESET}`);
+        footer = `  ${DIM}n/p next/previous  ↑↓/jk actions${commentAnchors(slot).length > 0 ? '  c comment' : ''}  u/d scroll  ←→/hl pan  q close${RESET}`;
+    }
+    const maxLine = Math.max(0, ...lines.map(visibleWidth));
+    return { lines, footer, maxW, maxH: Math.max(0, maxLine - Math.max(1, cols)) };
+}
+export function clampItemReviewScroll(state, cols, rows) {
+    if (state.slots[state.currentIndex] === undefined) {
+        state.scrollOffset = 0;
+        state.hscrollOffset = 0;
+        state.hscrollMax = 0;
+        return;
+    }
+    const layout = itemLines(state, cols);
+    state.hscrollMax = layout.maxH;
+    state.hscrollOffset = Math.max(0, Math.min(state.hscrollOffset, state.hscrollMax));
+    state.scrollOffset = Math.max(0, Math.min(state.scrollOffset, Math.max(0, layout.lines.length - bodyRows(rows))));
+}
+export function panItemReview(state, direction) {
+    state.hscrollOffset = Math.max(0, Math.min(state.hscrollMax, state.hscrollOffset + direction * PAN_STEP));
+}
+export function renderItemReview(state, cols, rows) {
+    const layout = itemLines(state, cols);
+    const body = bodyRows(rows);
+    const start = state.scrollOffset;
+    const sliced = layout.lines.slice(start, start + body);
+    while (sliced.length < body)
+        sliced.push('');
+    const panned = state.hscrollOffset > 0 ? sliced.map((line) => panLine(line, state.hscrollOffset, cols)) : sliced;
+    const width = Math.min(cols, layout.maxW + 2);
+    // The key hints never pan: a horizontal pan moves the content the user is
+    // reading, not the controls they steer it with.
+    if (body < rows)
+        panned.push(pinnedFooter(layout.footer, scrollBadge(start, body, layout.lines.length), layout.maxW + 2));
+    return centerHorizontal(panned.map((line) => clipLine(line, cols)), cols, width);
+}
+export function renderFinal(state, cols, rows) {
+    const maxW = Math.min(Math.max(20, cols - 4), 120);
+    const lines = ['', ...hangingWrap(`${singleLine(state.manifest.title)} — Summary`, maxW, '', 0, `${BOLD}${CYAN}`), `  ${DIM}${hline(maxW)}${RESET}`, ''];
+    const answer = pageAnswer(state);
+    for (const slot of answer.slots) {
+        const manifestSlot = state.manifest.slots.find((candidate) => candidate.id === slot.id);
+        const answered = manifestSlot !== undefined && slotAnswered(state, manifestSlot);
+        const mark = answered ? `${GREEN}✓${RESET}` : `${YELLOW}○${RESET}`;
+        lines.push(`  ${mark} ${BOLD}${sanitize(manifestSlot === undefined ? slot.kind : describeSlot(manifestSlot))}${RESET}  ${DIM}${sanitize(answerSummary(slot))}${RESET}`);
+    }
+    const complete = pageComplete(state);
+    if (!complete) {
+        lines.push('', `  ${YELLOW}Cannot submit yet.${RESET}`);
+        for (const slot of state.slots.filter(isResponseBearingSlot))
+            if (!slotAnswered(state, slot)) {
+                lines.push(`  ${DIM}${slot.id ?? slot.kind} is unanswered${RESET}`);
+                if (!terminalAnswerable(slot))
+                    lines.push(`  ${DIM}${slot.id} must be answered in Northlight${RESET}`);
+            }
+    }
+    lines.push('', `  ${DIM}${hline(maxW)}${RESET}`);
+    const footer = complete ? `  ${DIM}enter${RESET} submit  ${DIM}u/d${RESET} scroll  ${DIM}q${RESET} back` : `  ${DIM}u/d${RESET} scroll  ${DIM}q${RESET} back`;
+    return centeredWindow(lines, footer, state, cols, rows, maxW + 2);
+}
+/** Rows left for content once the pinned key-hint row is reserved. Below two
+ *  rows there is nothing to pin a footer against, so the whole pane is body. */
+function bodyRows(rows) { return rows >= 2 ? rows - 1 : rows; }
+/** How much of the content this window is showing, and which directions still
+ *  have more. Without it a long page looks like a short one: the scroll keys
+ *  exist but nothing says there is anything to scroll to. The arrow cells are
+ *  held even when empty so the badge does not change width as it moves. */
+function scrollBadge(offset, visibleRows, total) {
+    if (visibleRows <= 0 || total <= visibleRows)
+        return { marks: '', full: '' };
+    const end = Math.min(total, offset + visibleRows);
+    const marks = `${offset > 0 ? '▴' : ' '}${end < total ? '▾' : ' '}`;
+    return { marks: `${DIM}${marks}${RESET}`, full: `${DIM}${marks} ${offset + 1}–${end}/${total}${RESET}` };
+}
+/** The key hints with the scroll badge trailing at the right edge of the
+ *  column. A row too narrow for both drops the counts and keeps the arrows,
+ *  and one too narrow even for those moves them ahead of the hints — the keys
+ *  themselves are never the thing that gets clipped away. */
+function pinnedFooter(footer, badge, width) {
+    if (badge.full === '')
+        return footer;
+    const room = (candidate) => width - visibleWidth(footer) - visibleWidth(candidate) - 2;
+    for (const candidate of [badge.full, badge.marks])
+        if (room(candidate) >= 2)
+            return `${footer}${' '.repeat(room(candidate))}${candidate}`;
+    return `  ${badge.marks} ${footer.trimStart()}`;
+}
+/** Window `lines` to the pane, clamping the shared scroll offset to what this
+ *  screen actually rendered, and pinning `footer` to the bottom row. The key
+ *  hints are durable controls, so they hold the same row instead of scrolling
+ *  out of reach with the content they describe. `focusLine`, when given, is a
+ *  row the user is steering with j/k, so the window is nudged to keep it on
+ *  screen — otherwise a long page lets the selection wander out of view while
+ *  it still moves. It is passed only while the window is following the
+ *  selection, so a window the user scrolled themselves is never dragged back. */
+function centeredWindow(lines, footer, state, cols, rows, width, focusLine) {
+    const body = bodyRows(rows);
+    const max = Math.max(0, lines.length - body);
+    state.scrollOffset = Math.max(0, Math.min(state.scrollOffset, max));
+    if (focusLine !== undefined && body > 0) {
+        if (focusLine < state.scrollOffset)
+            state.scrollOffset = focusLine;
+        else if (focusLine >= state.scrollOffset + body)
+            state.scrollOffset = Math.min(max, focusLine - body + 1);
+    }
+    const out = lines.slice(state.scrollOffset, state.scrollOffset + body);
+    while (out.length < body)
+        out.push('');
+    if (body < rows)
+        out.push(pinnedFooter(footer, scrollBadge(state.scrollOffset, body, lines.length), width));
+    return centerHorizontal(out.map((line) => clipLine(line, cols)), cols, Math.min(cols, width));
+}

package/dist/clients/inbox/tui/slots.d.ts

@@ -0,0 +1,33 @@
+import type { PageCommentAnchor, PageSlot, SlotResponse, TableConfig } from '../../../core/human/page-schema.js';
+import type { TuiState } from './types.js';
+export type SelectGroup = 'option' | 'card' | 'row' | 'column';
+export type ActionRow = {
+    kind: 'select';
+    group: SelectGroup;
+    id: string;
+    label: string;
+    description?: string;
+    shortcut?: string;
+    mode: 'single' | 'multi';
+} | {
+    kind: 'freetext';
+    label: string;
+} | {
+    kind: 'accept';
+    label: string;
+} | {
+    kind: 'edit';
+    label: string;
+};
+export declare function describeSlot(slot: PageSlot): string;
+/** False when this component's response cannot be authored here: an unvalidated product kind, or a source-backed cards component whose cards the terminal never sees. */
+export declare function terminalAnswerable(slot: PageSlot): boolean;
+export declare function slotActions(slot: PageSlot): ActionRow[];
+export declare function tableMarkdown(config: TableConfig): string;
+/** Whether this value would be accepted as the slot's answer — the same reading crtrd applies on submit. */
+export declare function responseAnswers(state: Pick<TuiState, 'manifest'>, slot: PageSlot, response: SlotResponse): boolean;
+export declare function slotAnswered(state: TuiState, slot: PageSlot): boolean;
+export declare function pageComplete(state: Pick<TuiState, 'manifest' | 'responses'>): boolean;
+export declare function commentIdFor(anchor: PageCommentAnchor): string;
+/** The response-comment anchors this component may author: options take per-option, tables take rows only. */
+export declare function commentAnchors(slot: PageSlot): PageCommentAnchor[];

package/dist/clients/inbox/tui/slots.js

@@ -0,0 +1,134 @@
+import { isResponseBearingSlot, validatePageResponses, validatePartialPageResponses } from '../../../core/human/page-schema.js';
+const RESERVED = new Set(['c', 'r', 'e', 'a', 'n', 'p', 'q', 'j', 'k', 'u', 'd', ' ']);
+export function describeSlot(slot) {
+    const label = slot.config.label;
+    if (typeof label === 'string' && label !== '')
+        return label;
+    if (slot.unvalidated === true)
+        return slot.kind;
+    if (slot.kind === 'options')
+        return 'Options';
+    if (slot.kind === 'text')
+        return 'Text';
+    if (slot.kind === 'table')
+        return 'Table';
+    if (slot.kind === 'cards')
+        return 'Cards';
+    if (slot.kind === 'chart')
+        return 'Chart';
+    return slot.kind;
+}
+/** False when this component's response cannot be authored here: an unvalidated product kind, or a source-backed cards component whose cards the terminal never sees. */
+export function terminalAnswerable(slot) {
+    if (slot.unvalidated === true)
+        return false;
+    if (slot.kind === 'cards' && slot.config.cards === undefined)
+        return false;
+    return true;
+}
+export function slotActions(slot) {
+    if (!terminalAnswerable(slot))
+        return [];
+    let rows = [];
+    if (slot.kind === 'options') {
+        const config = slot.config;
+        rows = config.options.map((option) => ({ kind: 'select', group: 'option', id: option.id, label: option.label, ...(option.description === undefined ? {} : { description: option.description }), mode: config.mode }));
+        if (config.allowFreetext === true)
+            rows.push({ kind: 'freetext', label: config.freetextLabel ?? 'Something else' });
+    }
+    else if (slot.kind === 'cards') {
+        const config = slot.config;
+        rows = (config.cards ?? []).map((card) => ({ kind: 'select', group: 'card', id: card.id, label: card.subtitle === undefined ? card.title : `${card.title} — ${card.subtitle}`, ...(card.body === undefined ? {} : { description: card.body }), mode: config.mode }));
+    }
+    else if (slot.kind === 'text') {
+        // Text is always a writing surface — the same contract the page kit presents. Accepting
+        // the draft as written is the other half of that answer, not a separate read-only mode.
+        rows.push({ kind: 'edit', label: 'Edit' });
+        rows.push({ kind: 'accept', label: 'Accept as-is' });
+    }
+    else if (slot.kind === 'table') {
+        const config = slot.config;
+        if (config.rowSelect !== 'none') {
+            const first = config.columns[0];
+            rows.push(...(config.rows ?? []).map((row) => ({ kind: 'select', group: 'row', id: row.id, label: first === undefined ? row.id : String(row.cells[first.id] ?? row.id), mode: config.rowSelect })));
+        }
+        if (config.columnSelect !== 'none')
+            rows.push(...config.columns.map((column) => ({ kind: 'select', group: 'column', id: column.id, label: column.label, mode: config.columnSelect })));
+    }
+    const used = new Set();
+    return rows.map((row) => {
+        if (row.kind !== 'select')
+            return row;
+        let shortcut;
+        for (const letter of [...row.label.toLowerCase()].filter((c) => /[a-z]/.test(c))) {
+            if (!used.has(letter) && !RESERVED.has(letter)) {
+                shortcut = letter;
+                break;
+            }
+        }
+        if (shortcut === undefined)
+            for (let d = 1; d <= 9; d++)
+                if (!used.has(String(d))) {
+                    shortcut = String(d);
+                    break;
+                }
+        if (shortcut !== undefined)
+            used.add(shortcut);
+        return { ...row, ...(shortcut === undefined ? {} : { shortcut }) };
+    });
+}
+function escapeCell(value, mono = false) {
+    if (value === null || value === undefined)
+        return '';
+    const text = String(value).replaceAll('|', '\\|').replaceAll('\n', '<br>');
+    return mono && text !== '' ? `\`${text.replaceAll('`', '\\`')}\`` : text;
+}
+export function tableMarkdown(config) {
+    const header = `| ${config.columns.map((column) => escapeCell(column.label)).join(' | ')} |`;
+    const divider = `| ${config.columns.map((column) => column.align === 'right' ? '---:' : '---').join(' | ')} |`;
+    return [header, divider, ...(config.rows ?? []).map((row) => `| ${config.columns.map((column) => escapeCell(row.cells[column.id], column.mono === true)).join(' | ')} |`)].join('\n');
+}
+/** Whether this value would be accepted as the slot's answer — the same reading crtrd applies on submit. */
+export function responseAnswers(state, slot, response) {
+    if (slot.id === undefined)
+        return false;
+    try {
+        validatePartialPageResponses(state.manifest, { [slot.id]: response });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function slotAnswered(state, slot) {
+    if (!terminalAnswerable(slot) || slot.id === undefined || !state.responses.has(slot.id))
+        return false;
+    return responseAnswers(state, slot, state.responses.get(slot.id));
+}
+export function pageComplete(state) {
+    if (state.manifest.slots.some((slot) => isResponseBearingSlot(slot) && !terminalAnswerable(slot)))
+        return false;
+    try {
+        validatePageResponses(state.manifest, Object.fromEntries(state.responses));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function commentIdFor(anchor) {
+    switch (anchor.kind) {
+        case 'option': return `option:${anchor.optionId}`;
+        case 'row': return `row:${anchor.rowId}`;
+    }
+}
+/** The response-comment anchors this component may author: options take per-option, tables take rows only. */
+export function commentAnchors(slot) {
+    if (!terminalAnswerable(slot))
+        return [];
+    if (slot.kind === 'options')
+        return slot.config.options.map((option) => ({ kind: 'option', optionId: option.id }));
+    if (slot.kind === 'table')
+        return (slot.config.rows ?? []).map((row) => ({ kind: 'row', rowId: row.id }));
+    return [];
+}