@north-light/api 0.3.580 → 0.3.588

package/dist/clients/inbox/review/review-client.js

@@ -0,0 +1,123 @@
+import { randomUUID } from 'node:crypto';
+import { ApiError } from '../../../api/errors.js';
+import { cliClient } from '../../../commands/api-client.js';
+import { createCommentAuthority } from './comments-client.js';
+export class ReviewTerminalError extends Error {
+    state;
+    resultPath;
+    reason;
+    constructor(state, detail) {
+        if (state === 'approved') {
+            if (detail === undefined || detail === '')
+                throw new Error('approved review omitted its canonical result path');
+            super(`review is already approved; see ${detail}`);
+            this.resultPath = detail;
+        }
+        else {
+            super(detail === undefined || detail === '' ? 'review is already canceled' : `review is already canceled: ${detail}`);
+            if (detail !== undefined && detail !== '')
+                this.reason = detail;
+        }
+        this.name = 'ReviewTerminalError';
+        this.state = state;
+    }
+}
+/** The terminal's complete daemon seam for review lifecycle and comment operations. */
+export function createReviewClient(opts = {}) {
+    const request = async (operation) => {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            const notice = terminalConflictNotice(error);
+            if (notice !== undefined)
+                opts.onTerminalConflict?.(notice);
+            throw error;
+        }
+    };
+    return {
+        async byId(reviewId) {
+            const review = await request(() => cliClient().getReview(reviewId));
+            return await resolveReview(review, review.companion_node_id, request);
+        },
+        async createInline(p) {
+            const review = await request(() => cliClient().createReview({
+                origin_kind: 'inline',
+                origin_node_id: p.originNodeId,
+                ...('file' in p ? { file: p.file } : { document: p.document }),
+                idempotency_key: randomUUID(),
+            }));
+            return await resolveReview(review, review.companion_node_id, request);
+        },
+        comments(reviewId) {
+            return createCommentAuthority(reviewId, request);
+        },
+        async submit(reviewId) {
+            const submitted = await request(() => cliClient().submitReview(reviewId));
+            if (submitted.outcome === 'awaiting_companion')
+                return { outcome: 'awaiting_companion' };
+            return {
+                outcome: 'approved',
+                changed: requireChanged(submitted.review),
+                resultPath: requireResultPath(submitted.review),
+            };
+        },
+        async cancel(reviewId, reason) {
+            // The recipient surface: closing a review here is a dismissal, never the
+            // requester withdrawing it.
+            await request(() => cliClient().cancelReview(reviewId, { reason, actor: 'human', disposition: 'dismissed' }));
+        },
+    };
+}
+async function resolveReview(review, companionNodeId, request) {
+    if (review.state !== 'open')
+        throw terminalError(review);
+    const companion = await request(() => cliClient().getNode(companionNodeId));
+    return {
+        reviewId: review.review_id,
+        companionNodeId,
+        file: review.file,
+        cwd: companion.cwd,
+    };
+}
+function terminalError(review) {
+    if (review.state !== 'approved' && review.state !== 'canceled') {
+        throw new Error(`terminal review ${review.review_id} has invalid state ${review.state}`);
+    }
+    return review.state === 'approved'
+        ? new ReviewTerminalError('approved', requireResultPath(review))
+        : new ReviewTerminalError('canceled', review.cancel_reason);
+}
+function requireChanged(review) {
+    if (typeof review.changed !== 'boolean') {
+        throw new Error(`approved review ${review.review_id} omitted its changed disposition`);
+    }
+    return review.changed;
+}
+function requireResultPath(review) {
+    if (typeof review.result_path !== 'string' || review.result_path === '') {
+        throw new Error(`terminal review ${review.review_id} omitted its canonical result path`);
+    }
+    return review.result_path;
+}
+export 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}`;
+}
+export 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;
+}

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

@@ -0,0 +1,5 @@
+/** Run $EDITOR against a temporary buffer. Terminal ownership stays with the host. */
+export declare function editBufferInEditor(buffer: string): {
+    text: string;
+    error?: string;
+};

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

@@ -0,0 +1,41 @@
+import { readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { announceFallbackEditor, NO_EDITOR_MESSAGE, resolveEditor } from '../../../core/editor-resolver.js';
+/** Run $EDITOR against a temporary buffer. Terminal ownership stays with the host. */
+export function editBufferInEditor(buffer) {
+    const tmpFile = join(tmpdir(), `crtr-input-${randomUUID()}.txt`);
+    const resolved = resolveEditor();
+    if (resolved === null)
+        return { text: buffer, error: NO_EDITOR_MESSAGE };
+    const editor = resolved.command;
+    try {
+        writeFileSync(tmpFile, buffer);
+        announceFallbackEditor(resolved);
+        // $EDITOR may be a shell fragment such as "code --wait".
+        const result = spawnSync('/bin/sh', ['-c', `${editor} "$1"`, 'sh', tmpFile], { stdio: 'inherit' });
+        if (result.error)
+            return { text: buffer, error: `$EDITOR ("${editor}") failed to launch: ${result.error.message}` };
+        if (result.signal !== null)
+            return { text: buffer, error: `$EDITOR ("${editor}") was killed by signal ${result.signal}` };
+        if (result.status === 127 || result.status === 126)
+            return { text: buffer, error: `$EDITOR ("${editor}") failed to launch (shell exit ${result.status})` };
+        if (result.status !== 0)
+            return { text: buffer, error: `$EDITOR ("${editor}") exited with status ${result.status}` };
+        let text = readFileSync(tmpFile, 'utf8');
+        if (text.endsWith('\n') && !buffer.endsWith('\n'))
+            text = text.slice(0, -1);
+        return { text };
+    }
+    catch (error) {
+        return { text: buffer, error: `$EDITOR round-trip failed: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    finally {
+        try {
+            unlinkSync(tmpFile);
+        }
+        catch { /* best-effort cleanup */ }
+    }
+}

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

@@ -0,0 +1,153 @@
+import type { AnchoredComment } from './comments-client.js';
+import type { RenderedDoc } from '../../../core/termrender/termrender.js';
+import { type AnchorDoc, type AnchorUnit } from './anchors.js';
+export interface ComposeState {
+    buffer: string;
+    cursor: number;
+    /** Id of the comment being edited, or null when composing a new comment. */
+    editingId: string | null;
+    /** Submode to return to once compose closes (Escape or a successful save). */
+    returnMode: 'view' | 'list';
+    anchor: {
+        line: number;
+        endLine: number;
+    };
+}
+export interface ReviewState {
+    sourceLines: string[];
+    /** Ordered leaf anchor units. Never empty. */
+    units: AnchorUnit[];
+    /** Per rendered row: owning unit index, or null for separator rows. */
+    rowUnits: (number | null)[];
+    /** Current comment projection supplied by the daemon. */
+    comments: AnchoredComment[];
+    /** Revision of the live source snapshot the rendered units came from. */
+    sourceRevision: number;
+    /** Original ranges for comments whose current source range no longer survives. */
+    detached: Record<string, {
+        line: number;
+        endLine: number;
+    }>;
+    /** 0-based index of the anchored unit. */
+    activeUnit: number;
+    /** Set while a Shift+j/k range is being extended from this unit. */
+    selectionAnchor: number | null;
+    /** Scroll offset into the rendered (termrender) lines. */
+    scroll: number;
+    /** Horizontal pan offset, in display cells, for rows wider than the body
+     *  rectangle (diagrams). Rows that fit never move. */
+    hscroll: number;
+    mode: 'view' | 'list' | 'compose' | 'help';
+    compose: ComposeState | null;
+    listIndex: number;
+}
+/** Best unit for a source line: the NARROWEST unit containing it — code/table
+ *  chrome units carry their whole block's range and sit before the per-line
+ *  content units in rendered order, so "first whose end reaches the line"
+ *  would wrongly pick the chrome over the exact code line. A line no unit
+ *  contains (a blank separator) snaps forward to the next unit; past the end
+ *  clamps to the last. */
+export declare function initReviewState(sourceLines: string[], anchor: AnchorDoc, comments: AnchoredComment[], sourceRevision: number): ReviewState;
+export declare function selectedUnitBounds(state: ReviewState): {
+    lo: number;
+    hi: number;
+};
+/** Source-line anchor of the current unit selection — what a committed
+ *  comment records as `line`/`endLine`. Whole-block chrome units can carry a
+ *  wider range than their neighbors, so take the min/max over the selection
+ *  rather than trusting the endpoints alone. */
+export declare function currentAnchor(state: ReviewState): {
+    line: number;
+    endLine: number;
+};
+export declare function moveActiveUnit(state: ReviewState, delta: number, extend: boolean): ReviewState;
+/** Unit indices overlapped by any existing comment's source range. A projected
+ *  range lying wholly past the last unit (the file shrank before its range was
+ *  remapped) still gets a marker on its clamped unit, so every comment is
+ *  visible somewhere in the document. */
+export declare function commentedUnitSet(state: ReviewState): Set<number>;
+/** First/last rendered-row indices spanned by units `lo..hi`, or null when
+ *  the indices fall outside the unit list. */
+export declare function anchorRowRange(units: AnchorUnit[], lo: number, hi: number): {
+    first: number;
+    last: number;
+} | null;
+/** Minimal scroll adjustment that keeps rows `first..last` visible with
+ *  `margin` rows of context (the margin yields whenever honoring it would push
+ *  either edge of the span out of view); a taller-than-view span pins `first`
+ *  at the top — one row down when scrolled, so the `↑ more above` indicator
+ *  overwrites the preceding row, never the pinned one. Always returns a scroll
+ *  clamped to the document. */
+export declare function scrollToReveal(scroll: number, first: number, last: number, bodyHeight: number, total: number, margin?: number): number;
+/** Auto-scroll so the active unit (the moving edge of a selection) is
+ *  visible. The wheel free-scrolls and is untouched until the next anchor move. */
+export declare function ensureAnchorVisible(state: ReviewState, doc: RenderedDoc, bodyHeight: number): ReviewState;
+export declare function scrollBy(state: ReviewState, delta: number, bodyHeight: number, totalLines: number): ReviewState;
+/** Rows one `u`/`d` press travels: half the visible body, and never fewer than
+ *  one row, so a diagram taller than the pane cannot hold the document still. */
+export declare function halfPageRows(bodyHeight: number): number;
+/** Move the view by `rows` and carry the anchored unit the same distance, so
+ *  the selection keeps its place on screen rather than being left behind. The
+ *  selection lands on the unit owning the row it would occupy after the move,
+ *  clamped into the rows the frame actually paints; at the end of the document,
+ *  where the view can no longer move, the selection walks the rest on its own. */
+export declare function moveViewRows(state: ReviewState, rows: number, bodyHeight: number, totalRows: number): ReviewState;
+export declare function openComposeNew(state: ReviewState): ReviewState;
+export declare function openComposeEdit(state: ReviewState, index: number): ReviewState;
+export declare function closeCompose(state: ReviewState): ReviewState;
+export interface ComposeCommit {
+    editingId: string | null;
+    anchor: {
+        line: number;
+        endLine: number;
+    };
+    text: string;
+}
+/** Closes compose and returns the daemon mutation payload. The daemon projection, not this reducer, repaints comments. */
+export declare function commitCompose(state: ReviewState): {
+    state: ReviewState;
+    commit: ComposeCommit | null;
+};
+export declare function openList(state: ReviewState): ReviewState;
+export declare function closeList(state: ReviewState): ReviewState;
+export declare function moveListIndex(state: ReviewState, delta: number): ReviewState;
+export declare function deleteAtListIndex(state: ReviewState): {
+    state: ReviewState;
+    id: string | null;
+};
+export declare function undoLast(state: ReviewState): {
+    state: ReviewState;
+    id: string | null;
+};
+export declare function openHelp(state: ReviewState): ReviewState;
+export declare function closeHelp(state: ReviewState): ReviewState;
+export declare function cleanPastedText(input: string): string;
+export declare function textInsert(buffer: string, cursor: number, text: string): {
+    buffer: string;
+    cursor: number;
+};
+export declare function textBackspace(buffer: string, cursor: number): {
+    buffer: string;
+    cursor: number;
+};
+export declare function textDelete(buffer: string, cursor: number): {
+    buffer: string;
+    cursor: number;
+};
+export declare function textHome(buffer: string, cursor: number): number;
+export declare function textEnd(buffer: string, cursor: number): number;
+export declare function textVertical(buffer: string, cursor: number, delta: number): number;
+/** Vertical motion by *visual* row (what up/down mean in a wrapped compose box):
+ *  a long soft-wrapped comment has many rows even though it is one logical
+ *  line. Shares `verticalCursor` with the frame renderer's own wrap. */
+export declare function textVerticalWrapped(buffer: string, cursor: number, delta: number, width: number): number;
+/** Start of the word before the cursor (readline alt-b / alt+left). Shares one
+ *  word-motion implementation with the page compose box. */
+export declare function textWordLeft(buffer: string, cursor: number): number;
+/** Just past the end of the word after the cursor (readline alt-f / alt+right). */
+export declare function textWordRight(buffer: string, cursor: number): number;
+/** Delete back to the start of the previous word (alt+backspace / ctrl+w). */
+export declare function textWordBackspace(buffer: string, cursor: number): {
+    buffer: string;
+    cursor: number;
+};

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

@@ -0,0 +1,315 @@
+import { verticalCursor, wordLeftIndex, wordRightIndex } from '../tui/render.js';
+import { unitIndexForLine, unitRangeForSpan } from './anchors.js';
+/** Best unit for a source line: the NARROWEST unit containing it — code/table
+ *  chrome units carry their whole block's range and sit before the per-line
+ *  content units in rendered order, so "first whose end reaches the line"
+ *  would wrongly pick the chrome over the exact code line. A line no unit
+ *  contains (a blank separator) snaps forward to the next unit; past the end
+ *  clamps to the last. */
+export function initReviewState(sourceLines, anchor, comments, sourceRevision) {
+    const safe = anchor.units.length > 0
+        ? anchor
+        : { units: [{ start: 1, end: Math.max(1, sourceLines.length), firstRow: 0, lastRow: 0 }], rowUnits: anchor.rowUnits };
+    return {
+        sourceLines,
+        units: safe.units,
+        rowUnits: safe.rowUnits,
+        comments: [...comments],
+        sourceRevision,
+        detached: Object.fromEntries(comments.flatMap((comment) => comment.anchorStatus === 'detached'
+            ? [[comment.id, comment.originalRange ?? { line: comment.line, endLine: comment.endLine }]]
+            : [])),
+        activeUnit: comments.length > 0 ? unitIndexForLine(safe.units, comments[0].line) : 0,
+        selectionAnchor: null,
+        scroll: 0,
+        hscroll: 0,
+        mode: 'view',
+        compose: null,
+        listIndex: 0,
+    };
+}
+export function selectedUnitBounds(state) {
+    const sel = state.selectionAnchor ?? state.activeUnit;
+    return { lo: Math.min(state.activeUnit, sel), hi: Math.max(state.activeUnit, sel) };
+}
+/** Source-line anchor of the current unit selection — what a committed
+ *  comment records as `line`/`endLine`. Whole-block chrome units can carry a
+ *  wider range than their neighbors, so take the min/max over the selection
+ *  rather than trusting the endpoints alone. */
+export function currentAnchor(state) {
+    const { lo, hi } = selectedUnitBounds(state);
+    let line = Number.POSITIVE_INFINITY;
+    let endLine = 0;
+    for (let i = lo; i <= hi; i++) {
+        const u = state.units[i];
+        if (u === undefined)
+            continue;
+        line = Math.min(line, u.start);
+        endLine = Math.max(endLine, u.end);
+    }
+    if (!Number.isFinite(line))
+        return { line: 1, endLine: Math.max(1, state.sourceLines.length) };
+    return { line, endLine: Math.max(line, endLine) };
+}
+export function moveActiveUnit(state, delta, extend) {
+    const last = Math.max(0, state.units.length - 1);
+    const next = Math.max(0, Math.min(last, state.activeUnit + delta));
+    if (!extend)
+        return { ...state, activeUnit: next, selectionAnchor: null };
+    return { ...state, activeUnit: next, selectionAnchor: state.selectionAnchor ?? state.activeUnit };
+}
+/** Unit indices overlapped by any existing comment's source range. A projected
+ *  range lying wholly past the last unit (the file shrank before its range was
+ *  remapped) still gets a marker on its clamped unit, so every comment is
+ *  visible somewhere in the document. */
+export function commentedUnitSet(state) {
+    const out = new Set();
+    for (const c of state.comments) {
+        if (c.status === 'deleted' || c.anchorStatus === 'detached')
+            continue;
+        let hit = false;
+        state.units.forEach((u, i) => {
+            if (u.start <= c.endLine && u.end >= c.line) {
+                out.add(i);
+                hit = true;
+            }
+        });
+        if (!hit)
+            out.add(unitIndexForLine(state.units, c.line));
+    }
+    return out;
+}
+/** First/last rendered-row indices spanned by units `lo..hi`, or null when
+ *  the indices fall outside the unit list. */
+export function anchorRowRange(units, lo, hi) {
+    const a = units[lo];
+    const b = units[hi];
+    if (a === undefined || b === undefined)
+        return null;
+    return { first: a.firstRow, last: b.lastRow };
+}
+/** Minimal scroll adjustment that keeps rows `first..last` visible with
+ *  `margin` rows of context (the margin yields whenever honoring it would push
+ *  either edge of the span out of view); a taller-than-view span pins `first`
+ *  at the top — one row down when scrolled, so the `↑ more above` indicator
+ *  overwrites the preceding row, never the pinned one. Always returns a scroll
+ *  clamped to the document. */
+export function scrollToReveal(scroll, first, last, bodyHeight, total, margin = 2) {
+    const maxScroll = Math.max(0, total - bodyHeight);
+    let next = Math.max(0, Math.min(scroll, maxScroll));
+    if (last - first + 1 >= bodyHeight)
+        return Math.max(0, Math.min(Math.max(0, first - 1), maxScroll));
+    if (first - margin < next)
+        next = Math.max(first - margin, last - (bodyHeight - 1));
+    else if (last + margin > next + bodyHeight - 1)
+        next = Math.min(last + margin - (bodyHeight - 1), first);
+    return Math.max(0, Math.min(next, maxScroll));
+}
+/** Auto-scroll so the active unit (the moving edge of a selection) is
+ *  visible. The wheel free-scrolls and is untouched until the next anchor move. */
+export function ensureAnchorVisible(state, doc, bodyHeight) {
+    const range = anchorRowRange(state.units, state.activeUnit, state.activeUnit);
+    if (range === null)
+        return state;
+    const scroll = scrollToReveal(state.scroll, range.first, range.last, bodyHeight, doc.lines.length);
+    return scroll === state.scroll ? state : { ...state, scroll };
+}
+export function scrollBy(state, delta, bodyHeight, totalLines) {
+    const maxScroll = Math.max(0, totalLines - bodyHeight);
+    return { ...state, scroll: Math.max(0, Math.min(state.scroll + delta, maxScroll)) };
+}
+/** Rows one `u`/`d` press travels: half the visible body, and never fewer than
+ *  one row, so a diagram taller than the pane cannot hold the document still. */
+export function halfPageRows(bodyHeight) {
+    return Math.max(1, Math.floor(bodyHeight / 2));
+}
+/** Move the view by `rows` and carry the anchored unit the same distance, so
+ *  the selection keeps its place on screen rather than being left behind. The
+ *  selection lands on the unit owning the row it would occupy after the move,
+ *  clamped into the rows the frame actually paints; at the end of the document,
+ *  where the view can no longer move, the selection walks the rest on its own. */
+export function moveViewRows(state, rows, bodyHeight, totalRows) {
+    if (rows === 0)
+        return state;
+    const direction = rows > 0 ? 1 : -1;
+    const maxScroll = Math.max(0, totalRows - bodyHeight);
+    const scroll = Math.max(0, Math.min(state.scroll + rows, maxScroll));
+    // The frame overwrites the first and last body rows with its `more above` /
+    // `more below` indicators, and an indicator row carries no cursor, so the
+    // selection is kept inside the rows that remain the document's own.
+    const lo = scroll + (scroll > 0 ? 1 : 0);
+    const hi = Math.max(lo, scroll + bodyHeight - 1 - (scroll + bodyHeight < totalRows ? 1 : 0));
+    const anchorRow = state.units[state.activeUnit]?.firstRow ?? state.scroll;
+    const target = Math.max(lo, Math.min(anchorRow + rows, hi));
+    const activeUnit = unitNearRow(state, target, lo, hi, direction) ?? state.activeUnit;
+    if (scroll === state.scroll && activeUnit === state.activeUnit)
+        return state;
+    return { ...state, scroll, activeUnit, selectionAnchor: null };
+}
+/** The unit owning the row nearest `row` within `lo..hi`, preferring the
+ *  direction of travel. Separator rows own no unit, hence the search. */
+function unitNearRow(state, row, lo, hi, direction) {
+    const last = Math.max(0, state.units.length - 1);
+    for (let step = 0; step <= hi - lo; step++) {
+        for (const candidate of [row + step * direction, row - step * direction]) {
+            if (candidate < lo || candidate > hi)
+                continue;
+            const unit = state.rowUnits[candidate];
+            if (unit === null || unit === undefined)
+                continue;
+            return Math.max(0, Math.min(last, unit));
+        }
+    }
+    return null;
+}
+export function openComposeNew(state) {
+    return { ...state, mode: 'compose', compose: { buffer: '', cursor: 0, editingId: null, returnMode: 'view', anchor: currentAnchor(state) } };
+}
+export function openComposeEdit(state, index) {
+    const comment = state.comments[index];
+    if (comment === undefined)
+        return state;
+    const buffer = comment.comment;
+    const { lo, hi } = unitRangeForSpan(state.units, comment.line, comment.endLine);
+    return {
+        ...state,
+        activeUnit: hi,
+        selectionAnchor: lo === hi ? null : lo,
+        mode: 'compose',
+        compose: { buffer, cursor: [...buffer].length, editingId: comment.id, returnMode: 'list', anchor: { line: comment.line, endLine: comment.endLine } },
+    };
+}
+export function closeCompose(state) {
+    const returnMode = state.compose?.returnMode ?? 'view';
+    return { ...state, mode: returnMode, compose: null };
+}
+/** Closes compose and returns the daemon mutation payload. The daemon projection, not this reducer, repaints comments. */
+export function commitCompose(state) {
+    const c = state.compose;
+    if (c === null || c === undefined)
+        return { state, commit: null };
+    const text = c.buffer.trim();
+    if (text.length === 0)
+        return { state: closeCompose(state), commit: null };
+    return {
+        state: closeCompose(state),
+        commit: { editingId: c.editingId, anchor: c.anchor, text },
+    };
+}
+export function openList(state) {
+    return { ...state, mode: 'list', listIndex: Math.max(0, Math.min(state.listIndex, state.comments.length - 1)) };
+}
+export function closeList(state) {
+    return { ...state, mode: 'view' };
+}
+export function moveListIndex(state, delta) {
+    if (state.comments.length === 0)
+        return state;
+    const next = Math.max(0, Math.min(state.comments.length - 1, state.listIndex + delta));
+    return { ...state, listIndex: next };
+}
+export function deleteAtListIndex(state) {
+    const comment = state.comments[state.listIndex];
+    return { state, id: comment?.id ?? null };
+}
+export function undoLast(state) {
+    return { state, id: state.comments.at(-1)?.id ?? null };
+}
+export function openHelp(state) {
+    return { ...state, mode: 'help' };
+}
+export function closeHelp(state) {
+    return { ...state, mode: 'view' };
+}
+// ── Multi-line text-buffer helpers (flat string + code-point cursor) ────────
+function codePoints(s) {
+    return [...s];
+}
+// A single physical keypress (including Enter) almost always arrives as its
+// own 'data' event, so parseKeypress's per-event key flags cover the normal
+// typing path. A chunk longer than one character is a paste (or, rarely,
+// several keystrokes the OS coalesced into one read) and is never re-parsed
+// for key semantics — an embedded CR there means a pasted newline, not a
+// commit. Mirrors tui/input.ts's paste cleaning: strip escape sequences,
+// normalize CR/CRLF to LF, drop remaining control bytes, keep LF.
+export function cleanPastedText(input) {
+    return input
+        .replace(/\x1b\[20[01]~/g, '')
+        .replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '')
+        .replace(/\r\n?/g, '\n')
+        .replace(/[\x00-\x09\x0B-\x1F\x7F]/g, '');
+}
+export function textInsert(buffer, cursor, text) {
+    const chars = codePoints(buffer);
+    const at = Math.max(0, Math.min(cursor, chars.length));
+    const next = [...chars.slice(0, at), ...codePoints(text), ...chars.slice(at)].join('');
+    return { buffer: next, cursor: at + codePoints(text).length };
+}
+export function textBackspace(buffer, cursor) {
+    if (cursor <= 0)
+        return { buffer, cursor };
+    const chars = codePoints(buffer);
+    return { buffer: [...chars.slice(0, cursor - 1), ...chars.slice(cursor)].join(''), cursor: cursor - 1 };
+}
+export function textDelete(buffer, cursor) {
+    const chars = codePoints(buffer);
+    if (cursor >= chars.length)
+        return { buffer, cursor };
+    return { buffer: [...chars.slice(0, cursor), ...chars.slice(cursor + 1)].join(''), cursor };
+}
+function lineBoundsAt(chars, cursor) {
+    let start = cursor;
+    while (start > 0 && chars[start - 1] !== '\n')
+        start--;
+    let end = cursor;
+    while (end < chars.length && chars[end] !== '\n')
+        end++;
+    return { start, end };
+}
+export function textHome(buffer, cursor) {
+    return lineBoundsAt(codePoints(buffer), cursor).start;
+}
+export function textEnd(buffer, cursor) {
+    return lineBoundsAt(codePoints(buffer), cursor).end;
+}
+export function textVertical(buffer, cursor, delta) {
+    const chars = codePoints(buffer);
+    const { start, end } = lineBoundsAt(chars, cursor);
+    const col = cursor - start;
+    if (delta < 0) {
+        if (start === 0)
+            return cursor;
+        const prevEnd = start - 1; // the '\n' just before this line
+        const prevStart = lineBoundsAt(chars, prevEnd).start;
+        return Math.min(prevEnd, prevStart + col);
+    }
+    if (end >= chars.length)
+        return cursor;
+    const nextStart = end + 1;
+    const nextEnd = lineBoundsAt(chars, nextStart).end;
+    return Math.min(nextEnd, nextStart + col);
+}
+/** Vertical motion by *visual* row (what up/down mean in a wrapped compose box):
+ *  a long soft-wrapped comment has many rows even though it is one logical
+ *  line. Shares `verticalCursor` with the frame renderer's own wrap. */
+export function textVerticalWrapped(buffer, cursor, delta, width) {
+    return verticalCursor(buffer, cursor, delta, width);
+}
+/** Start of the word before the cursor (readline alt-b / alt+left). Shares one
+ *  word-motion implementation with the page compose box. */
+export function textWordLeft(buffer, cursor) {
+    return wordLeftIndex(buffer, cursor);
+}
+/** Just past the end of the word after the cursor (readline alt-f / alt+right). */
+export function textWordRight(buffer, cursor) {
+    return wordRightIndex(buffer, cursor);
+}
+/** Delete back to the start of the previous word (alt+backspace / ctrl+w). */
+export function textWordBackspace(buffer, cursor) {
+    const chars = codePoints(buffer);
+    const at = Math.max(0, Math.min(cursor, chars.length));
+    const to = textWordLeft(buffer, at);
+    if (to === at)
+        return { buffer, cursor: at };
+    return { buffer: [...chars.slice(0, to), ...chars.slice(at)].join(''), cursor: to };
+}

package/dist/clients/inbox/review-adapter.d.ts

@@ -0,0 +1,17 @@
+import type { SurfaceHost } from '../surfaces/host.js';
+export interface ReviewAdapterOptions {
+    host: SurfaceHost;
+    /** The review request's own id — the same id its inbox row carries. */
+    reviewId: string;
+}
+/** Resolve a durable review ticket and open it in its own tmux window. */
+export declare class ReviewAdapter {
+    private readonly opts;
+    private running;
+    private stopped;
+    constructor(opts: ReviewAdapterOptions);
+    /** Resolves true once the review window has opened and been selected. */
+    start(): Promise<boolean>;
+    stop(): Promise<void>;
+    private run;
+}