@north-light/api 0.3.580 → 0.3.588

package/dist/clients/inbox/review/frame.d.ts

@@ -0,0 +1,57 @@
+import type { RenderedDoc } from '../../../core/termrender/termrender.js';
+import type { ReviewState } from './state.js';
+/** Width prose is rendered at for a given terminal width: 2-col left
+ *  margin + 2-col gutter before the content, capped for readability. */
+export declare function renderWidthForCols(cols: number): number;
+/** The body rectangle a rendered row is painted into: the terminal minus the
+ *  4-col gutter prefix. Diagram blocks render at this width (no prose cap),
+ *  and every emitted body row is contained within it. */
+export declare function contentWidthForCols(cols: number): number;
+/** Body width left after an optional line-number gutter. */
+export declare function bodyWidth(cols: number, gutterW?: number): number;
+/** The mapped render this surface paints: prose at the readability cap,
+ *  diagrams at the full body width. */
+export declare function renderReviewDoc(content: string, cols: number): RenderedDoc;
+/** Widest painted row, in display cells, for a body window. */
+export declare function widestVisibleRow(doc: RenderedDoc, scroll: number, bodyHeight: number): number;
+/** How far the body can pan right, given what is currently on screen. Zero
+ *  when nothing visible overflows — which is also what makes h/l contextual:
+ *  the keys only pan while an overflowing row is in view. */
+export declare function maxHScroll(state: ReviewState, doc: RenderedDoc, cols: number, rows: number, gutterW?: number): number;
+/** Pan the body horizontally, clamped to what is currently reachable. The
+ *  stored offset is only ever clamped against the live window, so vertical
+ *  scrolling and resize can never leave it pointing past the content. */
+export declare function panBy(state: ReviewState, delta: number, doc: RenderedDoc, cols: number, rows: number, gutterW?: number): ReviewState;
+/** Cells one h/l press pans by — a chunk large enough to cross a diagram in a
+ *  few presses, small enough to keep orientation. */
+export declare const PAN_STEP = 8;
+/** One labeled key. A key is never shown without what it does. */
+export interface KeyHint {
+    key: string;
+    label: string;
+    /** Lower survives a narrow pane longer. */
+    priority: number;
+}
+/** The hints that fit `width`, in their declared order. When they do not all
+ *  fit, the least important are dropped whole — never cut mid-label. */
+export declare function fitHints(hints: readonly KeyHint[], width: number): KeyHint[];
+/** The comment list's key bar, for the grouped list the surface paints itself. */
+export declare function listHintBar(width: number): string;
+/** 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 — the
+ *  compose case counts the same hard-wrapped input lines the frame renders. */
+export declare function reservedRows(state: ReviewState, cols: number): number;
+export declare function renderReviewFrame(state: ReviewState, fileLabel: string, doc: RenderedDoc, cols: number, rows: number, opts?: {
+    lineNumbers?: boolean;
+    notice?: string;
+}): string[];
+export interface ReviewSurfaceKind {
+    /** `markdown` renders the file AS a document; `code` renders it as a
+     *  syntax-highlighted source panel with a line-number gutter. */
+    doc: 'markdown' | 'code';
+    /** Fence language for `doc: 'code'` (see `fenceLanguageFor`). */
+    language?: string;
+}
+/** How a reviewed file is presented: markdown renders as a document, anything
+ * else as a syntax-highlighted source panel. */
+export declare function docSurface(absFile: string): ReviewSurfaceKind;

package/dist/clients/inbox/review/frame.js

@@ -0,0 +1,309 @@
+import stringWidth from 'string-width';
+import { renderMarkdownBlockAware } from '../../../core/termrender/termrender.js';
+import { fenceLanguageFor, isMarkdownFile } from '../../../core/termrender/code-doc.js';
+import { renderInputBuffer } from '../tui/render.js';
+import { BOLD, CYAN, DIM, ESC, RESET, YELLOW, centerHorizontal, clipLine, hline, panLine, sanitize, truncate, visibleWidth } from '../tui/ansi.js';
+import { commentedUnitSet, selectedUnitBounds } from './state.js';
+// ── Rendering (pure) ─────────────────────────────────────────────────────────
+/** Width prose is rendered at for a given terminal width: 2-col left
+ *  margin + 2-col gutter before the content, capped for readability. */
+export function renderWidthForCols(cols) {
+    return Math.min(Math.max(20, cols - 6), 120);
+}
+/** The body rectangle a rendered row is painted into: the terminal minus the
+ *  4-col gutter prefix. Diagram blocks render at this width (no prose cap),
+ *  and every emitted body row is contained within it. */
+export function contentWidthForCols(cols) {
+    return Math.max(20, cols - 4);
+}
+/** Body width left after an optional line-number gutter. */
+export function bodyWidth(cols, gutterW = 0) {
+    return Math.max(1, contentWidthForCols(cols) - (gutterW > 0 ? gutterW + 1 : 0));
+}
+/** The mapped render this surface paints: prose at the readability cap,
+ *  diagrams at the full body width. */
+export function renderReviewDoc(content, cols) {
+    return renderMarkdownBlockAware(content, renderWidthForCols(cols), contentWidthForCols(cols));
+}
+/** Body rows as they are actually painted. Vertical-scroll indicators replace
+ * their endpoint rows, so content behind one cannot advertise or claim h/l. */
+function paintedBodyRows(doc, scroll, bodyHeight) {
+    const rows = [];
+    for (let i = 0; i < bodyHeight; i++) {
+        const abs = scroll + i;
+        rows.push(abs < doc.lines.length ? { abs, line: doc.lines[abs] } : { abs: null, line: '' });
+    }
+    if (scroll > 0 && rows.length > 0)
+        rows[0] = { abs: null, line: `  ${DIM}↑ ${scroll} more above${RESET}` };
+    const remaining = doc.lines.length - (scroll + bodyHeight);
+    if (remaining > 0 && rows.length > 0)
+        rows[rows.length - 1] = { abs: null, line: `  ${DIM}↓ ${remaining} more below${RESET}` };
+    return rows;
+}
+/** Widest painted row, in display cells, for a body window. */
+export function widestVisibleRow(doc, scroll, bodyHeight) {
+    let widest = 0;
+    for (const row of paintedBodyRows(doc, scroll, bodyHeight))
+        widest = Math.max(widest, visibleWidth(row.line));
+    return widest;
+}
+/** How far the body can pan right, given what is currently on screen. Zero
+ *  when nothing visible overflows — which is also what makes h/l contextual:
+ *  the keys only pan while an overflowing row is in view. */
+export function maxHScroll(state, doc, cols, rows, gutterW = 0) {
+    const bodyHeight = Math.max(1, rows - reservedRows(state, cols));
+    const maxScroll = Math.max(0, doc.lines.length - bodyHeight);
+    const scroll = Math.max(0, Math.min(state.scroll, maxScroll));
+    return Math.max(0, widestVisibleRow(doc, scroll, bodyHeight) - bodyWidth(cols, gutterW));
+}
+/** Pan the body horizontally, clamped to what is currently reachable. The
+ *  stored offset is only ever clamped against the live window, so vertical
+ *  scrolling and resize can never leave it pointing past the content. */
+export function panBy(state, delta, doc, cols, rows, gutterW = 0) {
+    const max = maxHScroll(state, doc, cols, rows, gutterW);
+    const next = Math.max(0, Math.min(state.hscroll + delta, max));
+    return next === state.hscroll ? state : { ...state, hscroll: next };
+}
+/** Cells one h/l press pans by — a chunk large enough to cross a diagram in a
+ *  few presses, small enough to keep orientation. */
+export const PAN_STEP = 8;
+// Single-hue anchor tint (a dark neutral step below the CYAN gutter bar).
+// termrender's only reset is `\x1b[0m`, so re-arming the background after each
+// reset keeps the tint alive across inner styling. Heading rows carry their
+// own background and won't show the tint — the gutter bar still marks them.
+const TINT_BG = `${ESC}48;5;236m`;
+function tintRow(row, width) {
+    const pad = Math.max(0, width - stringWidth(sanitize(row)));
+    return TINT_BG + row.replaceAll(RESET, RESET + TINT_BG) + ' '.repeat(pad) + RESET;
+}
+/** Background for the review's own chrome — the key bar and the help panel —
+ *  one step lighter than the selection tint so the two never read as one. */
+const CHROME_BG = `${ESC}48;5;237m`;
+/** A row of chrome: `text` padded to `width` cells on {@link CHROME_BG}. The
+ *  background is re-armed after every reset so inner styling cannot end it. */
+function chromeRow(text, width) {
+    const clipped = clipLine(text, width);
+    const pad = Math.max(0, width - visibleWidth(clipped));
+    return `  ${CHROME_BG}${clipped.replaceAll(RESET, RESET + CHROME_BG)}${' '.repeat(pad)}${RESET}`;
+}
+const VIEW_HINTS = [
+    { key: 'c', label: 'comment', priority: 0 },
+    { key: 'C', label: 'all comments', priority: 2 },
+    { key: 'U', label: 'undo', priority: 6 },
+    { key: 'a', label: 'agent pane', priority: 3 },
+    { key: 'e', label: '$EDITOR', priority: 7 },
+    { key: 's', label: 'submit', priority: 4 },
+    { key: 'x', label: 'cancel', priority: 8 },
+    { key: '?', label: 'all keys', priority: 1 },
+    { key: 'esc', label: 'close', priority: 5 },
+];
+const COMPOSE_HINTS = [
+    { key: 'enter', label: 'save', priority: 0 },
+    { key: '^⏎/^F', label: 'save + hand to its own agent', priority: 2 },
+    { key: '^J/⌥⏎', label: 'newline', priority: 3 },
+    { key: 'esc', label: 'discard', priority: 1 },
+];
+const LIST_HINTS = [
+    { key: '↑↓/jk', label: 'move', priority: 1 },
+    { key: 'enter/e', label: 'edit', priority: 0 },
+    { key: 'd', label: 'delete', priority: 2 },
+    { key: 'c', label: 'new comment', priority: 3 },
+    { key: 'esc', label: 'back', priority: 0 },
+];
+function hintText(hint) {
+    return `${BOLD}${CYAN}${hint.key}${RESET} ${hint.label}`;
+}
+/** The hints that fit `width`, in their declared order. When they do not all
+ *  fit, the least important are dropped whole — never cut mid-label. */
+export function fitHints(hints, width) {
+    const sep = 3; // ' · '
+    const cost = (set) => 1 + set.reduce((sum, hint, i) => sum + visibleWidth(`${hint.key} ${hint.label}`) + (i === 0 ? 0 : sep), 0);
+    let kept = [...hints];
+    const byDropOrder = [...hints].sort((a, b) => b.priority - a.priority);
+    for (const drop of byDropOrder) {
+        if (cost(kept) <= width)
+            break;
+        kept = kept.filter((hint) => hint !== drop);
+    }
+    return kept;
+}
+function hintBar(hints, width) {
+    const fitted = fitHints(hints, width);
+    return chromeRow(` ${fitted.map(hintText).join(` ${DIM}·${RESET} `)}`, width);
+}
+/** The comment list's key bar, for the grouped list the surface paints itself. */
+export function listHintBar(width) {
+    return hintBar(LIST_HINTS, width);
+}
+/** The help panel: every key, each beside what it does, grouped by task. */
+const HELP_SECTIONS = [
+    {
+        title: 'Comment',
+        rows: [
+            ['c / enter', 'comment on the highlighted block (J/K widens it)'],
+            ['C', 'all comments — edit or delete them there'],
+            ['U', 'undo your last comment'],
+            ['^⏎ / ^F', 'while writing: save + hand to its own agent'],
+        ],
+    },
+    {
+        title: 'Read',
+        rows: [
+            ['↑↓ / j k', 'next / previous block'],
+            ['J / K', 'extend the highlight down / up'],
+            ['u / d', 'half a page up / down'],
+            ['←→ / h l', 'pan a diagram wider than the pane'],
+        ],
+    },
+    {
+        title: 'Finish',
+        rows: [
+            ['a', 'open the agent pane beside the document'],
+            ['e', 'edit the document yourself in $EDITOR'],
+            ['s s', 'approve and submit the review'],
+            ['x x', 'cancel the review'],
+            ['esc', 'leave — the review stays open in the inbox'],
+        ],
+    },
+];
+const HELP_KEY_COL = 12;
+function helpPanel(width) {
+    const lines = [chromeRow(` ${BOLD}Keys${RESET}  ${DIM}? or esc closes this${RESET}`, width)];
+    for (const section of HELP_SECTIONS) {
+        lines.push(chromeRow('', width));
+        lines.push(chromeRow(` ${YELLOW}${section.title}${RESET}`, width));
+        for (const [key, label] of section.rows) {
+            lines.push(chromeRow(`   ${BOLD}${CYAN}${key.padEnd(HELP_KEY_COL)}${RESET}${label}`, width));
+        }
+    }
+    return lines;
+}
+const HELP_ROWS = 1 + HELP_SECTIONS.reduce((sum, section) => sum + 2 + section.rows.length, 0);
+/** 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 — the
+ *  compose case counts the same hard-wrapped input lines the frame renders. */
+export function reservedRows(state, cols) {
+    const header = 3; // blank, title, divider
+    if (state.mode === 'view')
+        return header + 1;
+    if (state.mode === 'compose') {
+        const c = state.compose;
+        const maxW = Math.min(Math.max(20, cols - 4), 120);
+        const bufLines = c ? renderInputBuffer(c.buffer, c.cursor, Math.max(10, maxW - 2)).length : 1;
+        return header + 3 + bufLines;
+    }
+    if (state.mode === 'list')
+        return header + Math.max(1, state.comments.length) + 2;
+    return header + HELP_ROWS;
+}
+export function renderReviewFrame(state, fileLabel, doc, cols, rows, opts) {
+    const maxW = Math.min(Math.max(20, cols - 4), 120);
+    const docW = renderWidthForCols(cols);
+    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(hintBar(COMPOSE_HINTS, maxW));
+    }
+    else if (state.mode === 'list') {
+        if (state.comments.length === 0) {
+            footer.push(`  ${DIM}(no comments yet — press c to comment on the highlighted block)${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(hintBar(LIST_HINTS, maxW));
+    }
+    else if (state.mode === 'help') {
+        footer.push(...helpPanel(maxW));
+    }
+    else {
+        footer.push(hintBar(VIEW_HINTS, maxW));
+    }
+    if (opts?.notice !== undefined && footer.length > 0) {
+        footer[footer.length - 1] = chromeRow(` ${YELLOW}${opts.notice}${RESET}`, maxW);
+    }
+    const reserved = header.length + footer.length;
+    const bodyHeight = Math.max(1, rows - reserved);
+    const maxScroll = Math.max(0, doc.lines.length - bodyHeight);
+    const scroll = Math.max(0, Math.min(state.scroll, maxScroll));
+    const gutterW = opts?.lineNumbers === true ? String(doc.lines.length).length : 0;
+    const contentW = bodyWidth(cols, gutterW);
+    // Effective pan: the stored offset, clamped to what this window can reach.
+    // Scrolling into narrow content parks the diagram offset rather than losing
+    // it, so scrolling back restores the same horizontal position.
+    const widest = widestVisibleRow(doc, scroll, bodyHeight);
+    const overflow = Math.max(0, widest - contentW);
+    const hscroll = Math.max(0, Math.min(state.hscroll, overflow));
+    const { lo, hi } = selectedUnitBounds(state);
+    const commented = commentedUnitSet(state);
+    const body = [];
+    for (const source of paintedBodyRows(doc, scroll, bodyHeight)) {
+        if (source.abs === null) {
+            // Indicator/fill rows reserve the same 4-col marker prefix and gutter a
+            // source row does, so the content column never shifts while scrolling.
+            body.push(`  ${' '.repeat(gutterW > 0 ? gutterW + 1 : 0)}${source.line}`);
+            continue;
+        }
+        // Every body row is windowed into the body rectangle: a diagram wider than
+        // the pane pans instead of spilling past the right edge.
+        const row = panLine(source.line, hscroll, contentW);
+        const u = state.rowUnits[source.abs] ?? null;
+        // A row with no span is chrome (the code panel's border), not a source
+        // line — it gets blank gutter width rather than an invented line number.
+        const gutterLine = doc.spans[source.abs]?.[0];
+        const gutter = gutterW > 0
+            ? (gutterLine === undefined ? ' '.repeat(gutterW + 1) : `${DIM}${String(gutterLine).padStart(gutterW)}${RESET} `)
+            : '';
+        // Tint the prose column at minimum, and a wide row across what it occupies.
+        const tintW = Math.min(contentW, Math.max(docW, visibleWidth(row)));
+        if (u !== null && u >= lo && u <= hi)
+            body.push(`  ${CYAN}▌${RESET} ${gutter}${tintRow(row, tintW)}`);
+        else if (u !== null && commented.has(u))
+            body.push(`  ${YELLOW}▎${RESET} ${gutter}${row}`);
+        else
+            body.push(`    ${gutter}${row}`);
+    }
+    while (body.length < bodyHeight)
+        body.push('');
+    // Keep the header, footer, and readable body rows in one stable centered
+    // column. A full-width diagram drops only its own row padding, so it can use
+    // the pane without shifting the surrounding review as it scrolls into view.
+    const readableFrameW = Math.min(cols, Math.max(maxW + 2, docW + 4 + (gutterW > 0 ? gutterW + 1 : 0)));
+    const centeredBody = body.map((line) => {
+        const frameW = visibleWidth(line) > readableFrameW ? cols : readableFrameW;
+        return centerHorizontal([line], cols, frameW)[0] ?? '';
+    });
+    const lines = [
+        ...centerHorizontal(header, cols, readableFrameW),
+        ...centeredBody,
+        ...centerHorizontal(footer, cols, readableFrameW),
+    ];
+    while (lines.length < rows)
+        lines.push('');
+    // The frame is contained by construction: no row may exceed the terminal, or
+    // it wraps and breaks the differ's one-line-per-row model.
+    return lines.slice(0, rows).map((line) => clipLine(line, cols));
+}
+/** How a reviewed file is presented: markdown renders as a document, anything
+ * else as a syntax-highlighted source panel. */
+export function docSurface(absFile) {
+    return isMarkdownFile(absFile)
+        ? { doc: 'markdown' }
+        : { doc: 'code', language: fenceLanguageFor(absFile) };
+}

package/dist/clients/inbox/review/keys.d.ts

@@ -0,0 +1,69 @@
+/** A semantic keypress for the review surface. Textual commands retain their
+ * text because their meaning is mode-dependent: `j` navigates in view/list
+ * mode and inserts in compose mode, for example. */
+export type ReviewKey = {
+    type: 'moveUnit';
+    delta: -1 | 1;
+    text: 'j' | 'k';
+} | {
+    type: 'extendUnit';
+    delta: -1 | 1;
+    text: 'J' | 'K';
+} | {
+    type: 'scrollPage';
+    delta: -1 | 1;
+    text?: 'u' | 'd';
+} | {
+    type: 'pan';
+    delta: -1 | 1;
+    text?: 'h' | 'l';
+} | {
+    type: 'space';
+    text: ' ';
+} | {
+    type: 'help';
+    text: '?';
+} | {
+    type: 'listEdit';
+    text: 'e';
+} | {
+    type: 'cancel';
+    text?: 'q';
+} | {
+    type: 'confirm';
+} | {
+    type: 'confirmFork';
+} | {
+    type: 'tab';
+    reverse: boolean;
+} | {
+    type: 'composeNewline';
+} | {
+    type: 'composeBackspace';
+} | {
+    type: 'composeWordBackspace';
+} | {
+    type: 'composeDelete';
+} | {
+    type: 'composeHome';
+} | {
+    type: 'composeEnd';
+} | {
+    type: 'composeMove';
+    direction: 'wordLeft' | 'wordRight';
+} | {
+    type: 'arrow';
+    direction: 'left' | 'right' | 'up' | 'down';
+} | {
+    type: 'printable';
+    text: string;
+} | {
+    type: 'paste';
+    text: string;
+};
+/** Return text that compose mode inserts. Semantic textual commands deliberately
+ * retain their payload so compose can preserve the old branch order. */
+export declare function reviewKeyText(key: ReviewKey): string | undefined;
+/** Match one complete pi-tui input chunk. pi-tui owns ESC/meta disambiguation;
+ * this function has neither terminal state nor a fallback raw-sequence parser. */
+export declare function matchReviewKey(data: string): ReviewKey | null;

package/dist/clients/inbox/review/keys.js

@@ -0,0 +1,133 @@
+import { Key, decodeKittyPrintable, matchesKey, parseKey } from '@earendil-works/pi-tui';
+import { normalizeShiftedMeta } from '../../../core/keybindings/index.js';
+/** Return text that compose mode inserts. Semantic textual commands deliberately
+ * retain their payload so compose can preserve the old branch order. */
+export function reviewKeyText(key) {
+    switch (key.type) {
+        case 'moveUnit':
+        case 'extendUnit':
+        case 'space':
+        case 'help':
+        case 'listEdit':
+        case 'printable':
+        case 'paste':
+            return key.text;
+        case 'scrollPage':
+        case 'pan':
+        case 'cancel':
+            return key.text;
+        default:
+            return undefined;
+    }
+}
+/** Match one complete pi-tui input chunk. pi-tui owns ESC/meta disambiguation;
+ * this function has neither terminal state nor a fallback raw-sequence parser. */
+export function matchReviewKey(data) {
+    const normalized = normalizeShiftedMeta(data);
+    // Compose-only chords precede their unmodified forms. The surface applies
+    // these only while composing, preserving the terminal-review mode ladder.
+    if (matchesKey(normalized, Key.ctrl('j')) || matchesKey(normalized, Key.alt('enter')))
+        return { type: 'composeNewline' };
+    if (matchesKey(normalized, Key.alt('backspace')) || matchesKey(normalized, Key.ctrl('w')))
+        return { type: 'composeWordBackspace' };
+    if (matchesKey(normalized, Key.backspace))
+        return { type: 'composeBackspace' };
+    if (matchesKey(normalized, Key.delete))
+        return { type: 'composeDelete' };
+    if (matchesKey(normalized, Key.alt('left')) || matchesKey(normalized, Key.ctrl('left')) || matchesKey(normalized, Key.super('left')) || matchesKey(normalized, Key.alt('b'))) {
+        return { type: 'composeMove', direction: 'wordLeft' };
+    }
+    if (matchesKey(normalized, Key.alt('right')) || matchesKey(normalized, Key.ctrl('right')) || matchesKey(normalized, Key.super('right')) || matchesKey(normalized, Key.alt('f'))) {
+        return { type: 'composeMove', direction: 'wordRight' };
+    }
+    if (matchesKey(normalized, Key.home) || matchesKey(normalized, Key.ctrl('a')))
+        return { type: 'composeHome' };
+    if (matchesKey(normalized, Key.end) || matchesKey(normalized, Key.ctrl('e')))
+        return { type: 'composeEnd' };
+    if (matchesKey(normalized, Key.shift('tab')))
+        return { type: 'tab', reverse: true };
+    if (matchesKey(normalized, Key.tab))
+        return { type: 'tab', reverse: false };
+    // Ctrl+Enter is only distinguishable from Enter under the kitty keyboard
+    // protocol, so it is paired with a chord every terminal delivers.
+    if (matchesKey(normalized, Key.ctrl('enter')) || matchesKey(normalized, Key.ctrl('f')))
+        return { type: 'confirmFork' };
+    if (matchesKey(normalized, Key.enter))
+        return { type: 'confirm' };
+    if (matchesKey(normalized, Key.escape))
+        return { type: 'cancel' };
+    // Arrow keys remain distinct because each mode gives them its own meaning.
+    if (matchesKey(normalized, Key.up))
+        return { type: 'arrow', direction: 'up' };
+    if (matchesKey(normalized, Key.down))
+        return { type: 'arrow', direction: 'down' };
+    if (matchesKey(normalized, Key.left))
+        return { type: 'arrow', direction: 'left' };
+    if (matchesKey(normalized, Key.right))
+        return { type: 'arrow', direction: 'right' };
+    if (matchesKey(normalized, Key.pageUp))
+        return { type: 'scrollPage', delta: -1 };
+    if (matchesKey(normalized, Key.pageDown))
+        return { type: 'scrollPage', delta: 1 };
+    if (matchesKey(normalized, Key.shift('j')))
+        return { type: 'extendUnit', delta: 1, text: 'J' };
+    if (matchesKey(normalized, Key.shift('k')))
+        return { type: 'extendUnit', delta: -1, text: 'K' };
+    // Shift+C and Shift+U are view-mode commands. Matched explicitly, like J/K,
+    // because a kitty report of either decodes to its unshifted letter.
+    if (matchesKey(normalized, Key.shift('c')))
+        return { type: 'printable', text: 'C' };
+    if (matchesKey(normalized, Key.shift('u')))
+        return { type: 'printable', text: 'U' };
+    if (matchesKey(normalized, 'j'))
+        return { type: 'moveUnit', delta: 1, text: 'j' };
+    if (matchesKey(normalized, 'k'))
+        return { type: 'moveUnit', delta: -1, text: 'k' };
+    if (matchesKey(normalized, 'u'))
+        return { type: 'scrollPage', delta: -1, text: 'u' };
+    if (matchesKey(normalized, 'd'))
+        return { type: 'scrollPage', delta: 1, text: 'd' };
+    if (matchesKey(normalized, 'h'))
+        return { type: 'pan', delta: -1, text: 'h' };
+    if (matchesKey(normalized, 'l'))
+        return { type: 'pan', delta: 1, text: 'l' };
+    if (matchesKey(normalized, Key.space))
+        return { type: 'space', text: ' ' };
+    if (matchesKey(normalized, Key.question))
+        return { type: 'help', text: '?' };
+    if (matchesKey(normalized, 'e'))
+        return { type: 'listEdit', text: 'e' };
+    if (matchesKey(normalized, 'q'))
+        return { type: 'cancel', text: 'q' };
+    const parsed = parseKey(normalized);
+    const text = printableText(data, parsed);
+    // Kitty reports question mark as Shift+Slash, so the unmodified-key matcher
+    // above cannot recognize it. Keep its text for compose through reviewKeyText.
+    if (text === '?')
+        return { type: 'help', text };
+    if (text !== undefined)
+        return { type: 'printable', text };
+    // A recognized but unhandled modified key (notably Alt+I) is not text or a
+    // paste. Its viewer-level owner may already have consumed it.
+    if (parsed !== undefined)
+        return null;
+    if ([...data].length > 1)
+        return { type: 'paste', text: data };
+    return null;
+}
+function printableText(data, parsed) {
+    const kitty = decodeKittyPrintable(data);
+    if (kitty !== undefined && isPrintable(kitty))
+        return kitty;
+    if (parsed !== undefined) {
+        const shifted = parsed.startsWith('shift+');
+        const candidate = shifted ? parsed.slice('shift+'.length) : parsed;
+        if ([...candidate].length === 1 && isPrintable(candidate)) {
+            return shifted && /^[a-z]$/.test(candidate) ? candidate.toUpperCase() : candidate;
+        }
+    }
+    return [...data].length === 1 && isPrintable(data) ? data : undefined;
+}
+function isPrintable(text) {
+    return !/\p{C}/u.test(text);
+}

package/dist/clients/inbox/review/launch.d.ts

@@ -0,0 +1,16 @@
+import type { SurfaceHost } from '../../surfaces/host.js';
+import { type ResolvedReview } from './review-client.js';
+export interface ReviewSurfaceOptions {
+    review: ResolvedReview;
+}
+/** Open a dedicated viewer window for a review without replacing the caller's
+ *  conversation window. The fresh viewer consumes the review id at startup. */
+export declare function openReviewWindow(host: SurfaceHost, review: ResolvedReview): boolean;
+/** The status-line toast shown once a review window opens. */
+export declare function reviewOpenedMessage(toIndex: number, windowName: string, fromIndex: number | null): string;
+/** Consume the review id handed to a dedicated attach viewer. */
+export declare function takeStartupReviewId(): string | undefined;
+/** Resolve and mount the review seeded into a dedicated viewer window. */
+export declare function openReviewSurfaceById(host: SurfaceHost, reviewId: string): Promise<void>;
+/** Mount the review document inside its dedicated viewer window. */
+export declare function openReviewSurface(host: SurfaceHost, opts: ReviewSurfaceOptions): Promise<void>;