@north-light/crouter 0.3.170 → 0.3.172

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

@@ -0,0 +1,45 @@
+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;
+/** 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,215 @@
+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;
+}
+/** 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 + 9; // help
+}
+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(`  ${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            ${DIM}shift-j/k${RESET}   extend selection`);
+        footer.push(`  ${DIM}u/d${RESET}         scroll document        ${DIM}h/l${RESET}         pan visible wide diagrams`);
+        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 e${RESET}     edit in $EDITOR`);
+        footer.push(`  ${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 {
+        footer.push(`  ${DIM}j/k${RESET} · ${DIM}shift-j/k${RESET} · ${DIM}u/d${RESET} · ${DIM}space c${RESET} · ${DIM}space l${RESET} · ` +
+            `${DIM}space u${RESET} · ${DIM}space e${RESET} · ${DIM}space s${RESET} submit · ${DIM}?${RESET} · ${DIM}esc${RESET}`);
+    }
+    if (opts?.notice !== undefined && footer.length > 0) {
+        footer[footer.length - 1] = `  ${YELLOW}${opts.notice}${RESET}`;
+    }
+    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,67 @@
+/** 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: 'leader';
+    text: ' ';
+} | {
+    type: 'help';
+    text: '?';
+} | {
+    type: 'listEdit';
+    text: 'e';
+} | {
+    type: 'cancel';
+    text?: 'q';
+} | {
+    type: 'confirm';
+} | {
+    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,130 @@
+import { Key, decodeKittyPrintable, matchesKey, parseKey } from '@earendil-works/pi-tui';
+/** pi-tui parses legacy ESC+lowercase as Alt+letter, but does not normalize
+ * the shifted uppercase form. Convert that complete two-byte form to the
+ * equivalent CSI-u key so all semantic matching stays in pi-tui. */
+function normalizeLegacyShiftedMeta(data) {
+    if (data.length !== 2 || data[0] !== '\x1b' || !/[A-Z]/.test(data[1]))
+        return data;
+    return `\x1b[${data.charCodeAt(1)};4u`;
+}
+/** 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 'leader':
+        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 = normalizeLegacyShiftedMeta(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 };
+    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' };
+    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: 'leader', 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,10 @@
+import type { TUI } from '@earendil-works/pi-tui';
+import type { CanvasSource } from '../../../core/canvas/source.js';
+import type { SurfaceHost } from '../../surfaces/host.js';
+export interface ComposedReviewOptions {
+    reviewId: string;
+    tui: TUI;
+    canvasSource: CanvasSource;
+}
+/** Mount the canonical live-document and companion-conversation review. */
+export declare function openComposedReview(host: SurfaceHost, opts: ComposedReviewOptions): Promise<void>;

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

@@ -0,0 +1,129 @@
+import { ApiError } from '../../../api/errors.js';
+import { CompanionRegion } from '../../conversation/region.js';
+import { createCommentAuthority } from './comments-client.js';
+import { ReviewCompositionComponent } from './composition.js';
+import { DocumentRegion } from './document-region.js';
+import { openLiveSource } from './live-source.js';
+import { createReviewClient, ReviewTerminalError } from './review-client.js';
+/** Mount the canonical live-document and companion-conversation review. */
+export async function openComposedReview(host, opts) {
+    if (host.capabilities.remote) {
+        host.notice('The composed review is unavailable in a remote attach — the file and companion live on the host.');
+        return;
+    }
+    const reviewClient = createReviewClient();
+    let opened;
+    try {
+        opened = await reviewClient.open(opts.reviewId);
+    }
+    catch (error) {
+        host.notice(error instanceof ReviewTerminalError
+            ? terminalRefusalNotice(error)
+            : `couldn't open review: ${describeError(error)}`);
+        return;
+    }
+    let source;
+    try {
+        source = openLiveSource(opened.file);
+    }
+    catch (error) {
+        host.notice(`couldn't open ${opened.file}: ${describeError(error)}`);
+        return;
+    }
+    const comments = createCommentAuthority(opened.reviewId);
+    let handle;
+    let composition;
+    let submitting = false;
+    const documentRegion = new DocumentRegion({
+        reviewId: opened.reviewId,
+        absFile: opened.file,
+        cwd: opened.cwd,
+        source,
+        comments,
+        services: {
+            notice: (text) => host.notice(text),
+            suspendForChild: () => {
+                const resumeHost = host.suspendForChild();
+                const resumeComposition = composition?.suspendForChild() ?? (() => { });
+                let resumed = false;
+                return () => {
+                    if (resumed)
+                        return;
+                    resumed = true;
+                    resumeComposition();
+                    resumeHost();
+                };
+            },
+            requestClose: () => handle?.close(),
+            submit: () => { void submit(); },
+        },
+    });
+    const companionRegion = new CompanionRegion({
+        companionNodeId: opened.companionNodeId,
+        tui: opts.tui,
+        canvasSource: opts.canvasSource,
+        reopenDormantCompanion: async () => {
+            await reviewClient.open(opened.reviewId);
+        },
+        onRequestClose: () => handle?.close(),
+    });
+    await documentRegion.open();
+    composition = new ReviewCompositionComponent({
+        document: documentRegion,
+        companion: companionRegion,
+        notice: (text) => host.notice(text),
+        onRequestClose: () => { },
+    });
+    handle = host.mount(composition);
+    composition.setHandle(handle);
+    void companionRegion.open();
+    async function submit() {
+        if (submitting)
+            return;
+        submitting = true;
+        try {
+            const result = await reviewClient.submit(opened.reviewId);
+            host.notice(approvalNotice(result));
+            handle?.close();
+        }
+        catch (error) {
+            const conflict = terminalConflictNotice(error);
+            if (conflict !== undefined) {
+                host.notice(conflict);
+                handle?.close();
+                return;
+            }
+            submitting = false;
+            host.notice(`couldn't submit review: ${describeError(error)}`);
+        }
+    }
+}
+function terminalRefusalNotice(error) {
+    if (error.state === 'approved')
+        return `This review was already approved. Result: ${error.resultPath ?? 'unknown'}`;
+    return error.reason === undefined || error.reason === '' ? 'This review was canceled.' : `This review was canceled: ${error.reason}`;
+}
+function approvalNotice(result) {
+    return result.changed
+        ? `Approved — the document changed during review. Result: ${result.resultPath}`
+        : `Approved — the document was not modified. Result: ${result.resultPath}`;
+}
+function terminalConflictNotice(error) {
+    if (!(error instanceof ApiError) || error.status !== 409 || error.code !== 'review_terminal_conflict')
+        return undefined;
+    const review = error.details?.review;
+    if (review === undefined)
+        return undefined;
+    if (review.state === 'approved')
+        return review.result_path === undefined
+            ? 'This review was already approved by someone else.'
+            : `This review was already approved by someone else. Result: ${review.result_path}`;
+    if (review.state === 'canceled')
+        return review.cancel_reason === undefined || review.cancel_reason === ''
+            ? 'This review was canceled before this submission landed.'
+            : `This review was canceled before this submission landed: ${review.cancel_reason}`;
+    return undefined;
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/clients/inbox/review/live-source.d.ts

@@ -0,0 +1,24 @@
+/** The trailing delay used to collapse an editor's write/rename burst. */
+export declare const COALESCE_MS = 120;
+export type StaleReason = 'missing' | 'unreadable' | 'too-large' | 'binary';
+export interface SourceSnapshot {
+    text: string;
+    lines: string[];
+    revision: number;
+    status: 'live' | 'stale';
+    staleReason?: StaleReason;
+    sha256: string;
+    loadedAt: string;
+}
+export interface LiveSource {
+    current(): SourceSnapshot;
+    /** The text captured when the surface opened. */
+    openText(): string;
+    /** Fires only when text changes or the live/stale status flips. */
+    onChange(fn: (next: SourceSnapshot, previous: SourceSnapshot) => void): void;
+    /** Read immediately, bypassing the directory watcher and coalescing timer. */
+    refreshNow(): void;
+    close(): void;
+}
+/** Watch the containing directory so atomic replacement of the file remains live. */
+export declare function openLiveSource(absFile: string): LiveSource;