@north-light/crouter 0.3.173 → 0.3.174

package/dist/clients/inbox/review/{document-region.js → document-surface.js}

@@ -1,22 +1,29 @@
 import { relative, resolve } from 'node:path';
-import { CURSOR_MARKER } from '@earendil-works/pi-tui';
+import { CURSOR_MARKER, Key, matchesKey } from '@earendil-works/pi-tui';
 import { documentLines } from '../../../core/document-lines.js';
 import { codeRenderedDoc } from '../../../core/termrender/code-doc.js';
 import { deriveAnchorUnits, remapUnitIndex, unitIndexForLine, unitRangeForSpan } from './anchors.js';
-import { centerHorizontal, clipLine, CYAN, DIM, RESET, REVERSE, sanitize, truncate, YELLOW } from '../tui/ansi.js';
+import { centerHorizontal, clipLine, CYAN, DIM, RESET, REVERSE, sanitize, truncate, visibleWidth, YELLOW } from '../tui/ansi.js';
 import { ReviewDocumentError } from './comments-client.js';
+import { closeCompanionPane, companionPaneLive, openCompanionPane } from './companion-pane.js';
 import { PAN_STEP, docSurface, maxHScroll, panBy, renderReviewDoc, renderReviewFrame, renderWidthForCols, reservedRows, } from './frame.js';
 import { matchReviewKey, reviewKeyText } from './keys.js';
 import { renderInputBuffer } from '../tui/render.js';
 import { openReviewedFileInEditor } from './nvim.js';
 import { buildLineMap, remapRange } from './remap.js';
 import { cleanPastedText, closeCompose, closeHelp, closeList, commitCompose, ensureAnchorVisible, initReviewState, moveActiveUnit, moveListIndex, openComposeEdit, openComposeNew, openHelp, openList, scrollBy, textBackspace, textDelete, textEnd, textHome, textInsert, textVerticalWrapped, textWordBackspace, textWordLeft, textWordRight, deleteAtListIndex, undoLast, } from './state.js';
-/** The reviewed document as a composed region: existing review rendering and
- *  navigation over a live file, with comments projected from the daemon and
- *  ranges remapped by this terminal as the file changes. */
-export class DocumentRegion {
+/** The widest the document is ever rendered, however wide the pane is. */
+const DOC_MAX_COLS = 126;
+/** The one mounted review surface: existing review rendering and navigation
+ *  over a live file, with comments projected from the daemon and ranges
+ *  remapped by this terminal as the file changes, plus a status row naming the
+ *  companion pane the conversation lives in. */
+export class ReviewDocumentSurface {
     absFile;
     fileLabel;
+    companionNodeId;
+    companionCwd;
+    callerPane;
     kind;
     source;
     comments;
@@ -24,25 +31,46 @@ export class DocumentRegion {
     unsubscribeComments;
     ready;
     cols = 0;
-    rows = 0;
-    focused = false;
+    /** Rows the host assigned this surface; the document frame renders one
+     *  fewer, because the last line is this surface's status row. */
+    hostRows = 0;
+    /** The `hostRows` the current state was last reflowed against. A height
+     *  change matters as much as a width one: `reflow` is what re-runs
+     *  `ensureAnchorVisible` against the new body height, so a pane shrink
+     *  cannot strand the active anchor below the visible body. */
+    flowedRows = -1;
+    _focused = false;
     closed = false;
     spaceArmed = false;
+    escapeConfirmArmed = false;
+    cancelArmed = false;
+    tornDown = false;
+    /** The disposition {@link teardown} stated, kept only while there was no
+     *  handle to close: the mount that follows disposes every standing notice,
+     *  so {@link setHandle} states it again once the surface is gone. */
+    tornDownNotice;
+    handle;
+    /** The companion pane this surface is bound to, and how it came to be.
+     *  `paneOrigin` is status-row copy only: teardown reads `paneId`. */
+    paneId;
+    paneOrigin;
     state;
     cache;
     /** Every non-deleted comment the daemon currently projects, newest last. */
     projection = [];
     status = 'preparing';
-    /** Region-local error/summary state — never a host notice (D1). */
+    /** This surface's own error/summary state — never a host notice (D1). */
     problem;
     composeAnchorLost = false;
-    dirty;
     /** Serializes base-hash transitions so B→C cannot overtake A→B. */
     remapChain = Promise.resolve();
     constructor(opts) {
-        this.absFile = opts.absFile;
-        this.fileLabel = labelFor(opts.cwd, opts.absFile);
-        this.kind = docSurface(opts.absFile);
+        this.absFile = opts.review.file;
+        this.fileLabel = labelFor(opts.review.cwd, opts.review.file);
+        this.companionNodeId = opts.review.companionNodeId;
+        this.companionCwd = opts.review.cwd;
+        this.callerPane = opts.callerPane;
+        this.kind = docSurface(opts.review.file);
         this.source = opts.source;
         this.comments = opts.comments;
         this.services = opts.services;
@@ -71,19 +99,40 @@ export class DocumentRegion {
         const state = this.state;
         return state?.mode === 'compose' && state.compose !== null && state.compose.buffer.length > 0;
     }
-    // ── SurfaceRegion ─────────────────────────────────────────────────────────
-    setViewport(cols, rows) {
-        const nextCols = Math.max(0, Math.floor(cols));
-        const nextRows = Math.max(0, Math.floor(rows));
-        if (nextCols === this.cols && nextRows === this.rows)
+    // ── SurfaceComponent ──────────────────────────────────────────────────────
+    get focused() {
+        return this._focused;
+    }
+    set focused(value) {
+        if (this._focused === value)
             return;
-        this.cols = nextCols;
-        this.rows = nextRows;
-        this.reflow();
+        this._focused = value;
+        this.repaint();
     }
-    render() {
-        if (this.rows <= 0 || this.cols <= 0)
+    setRows(rows) {
+        this.hostRows = Math.max(0, Math.floor(rows));
+    }
+    /** Exactly the rows the host assigned: the document frame, then this
+     *  surface's status row. The document is capped at {@link DOC_MAX_COLS} and
+     *  every line is padded out to the full pane width. */
+    render(width) {
+        const frameWidth = Math.max(0, Math.floor(width));
+        if (this.hostRows <= 0)
             return [];
+        const cols = Math.min(frameWidth, DOC_MAX_COLS);
+        if (cols !== this.cols || this.hostRows !== this.flowedRows) {
+            this.cols = cols;
+            this.flowedRows = this.hostRows;
+            this.reflow();
+        }
+        const body = this.rows <= 0 || this.cols <= 0 ? [] : this.renderDocument();
+        return [...exactRows(body, this.rows, frameWidth), this.statusRow(frameWidth)];
+    }
+    /** Rows the document frame itself owns. */
+    get rows() {
+        return Math.max(0, this.hostRows - 1);
+    }
+    renderDocument() {
         if (this.status !== 'ready' || this.state === undefined)
             return this.renderPlaceholder();
         const doc = this.document(this.cols, this.state.sourceRevision);
@@ -99,8 +148,51 @@ export class DocumentRegion {
             : grouped;
         return this.focused ? this.markCursorLocation(rendered, this.state) : rendered;
     }
+    /** The surface consumes every chunk: nothing typed into a mounted review may
+     *  reach the transcript beneath it. Esc is the one key this surface answers
+     *  itself — it closes the review unless an unsent comment holds it open. */
     handleInput(data) {
-        if (this.closed || this.status !== 'ready')
+        if (this.closed)
+            return;
+        // An armed cancel is answered before every other ladder, and disarms on
+        // any key: only a second `x` cancels, and anything else is the ordinary
+        // keypress it would have been. `escapeConfirmArmed` is left alone.
+        if (this.cancelArmed) {
+            this.cancelArmed = false;
+            const key = matchReviewKey(data);
+            if (key !== null && reviewKeyText(key) === 'x') {
+                this.services.cancel();
+                return;
+            }
+        }
+        if (matchesKey(data, Key.escape)) {
+            if (this.escapeConfirmArmed) {
+                this.escapeConfirmArmed = false;
+                if (this.consume(data))
+                    return;
+                this.services.requestClose();
+                return;
+            }
+            if (this.hasUnsentCompose()) {
+                this.escapeConfirmArmed = true;
+                this.services.notice('unsent comment — press esc again to discard');
+                this.repaint();
+                return;
+            }
+            // Compose mode owns Esc when its buffer is empty; view mode leaves it
+            // unconsumed so this surface can close.
+            if (this.consume(data))
+                return;
+            this.services.requestClose();
+            return;
+        }
+        if (this.escapeConfirmArmed)
+            this.escapeConfirmArmed = false;
+        this.consume(data);
+    }
+    /** True when the document's own modes took the chunk. */
+    consume(data) {
+        if (this.status !== 'ready')
             return false;
         const state = this.state;
         if (state === undefined)
@@ -137,22 +229,45 @@ export class DocumentRegion {
         }
         return this.handleViewKey(key);
     }
+    /** A mounted review consumes every notch, ready or not: the transcript
+     *  beneath it must never scroll while the document stands over it. */
     handleWheel(direction, lines) {
-        const state = this.state;
-        if (this.closed || this.status !== 'ready' || state === undefined)
+        if (this.closed)
             return false;
+        const state = this.state;
+        if (this.status !== 'ready' || state === undefined)
+            return true;
         const doc = this.document(this.cols, state.sourceRevision);
         const delta = (direction === 'up' ? -1 : 1) * Math.max(1, Math.floor(lines));
         this.state = scrollBy(state, delta, this.bodyHeight(state), doc.lines.length);
         this.repaint();
         return true;
     }
-    setFocused(value) {
-        if (this.focused === value)
+    /** Repaints are scheduled by the host; this surface never draws directly. */
+    invalidate() {
+        if (!this.closed)
+            this.handle?.invalidate();
+    }
+    /** The mounted handle is this surface's repaint and close channel, and the
+     *  host's close is what releases the document's resources. */
+    setHandle(handle) {
+        if (this.handle !== undefined)
             return;
-        this.focused = value;
-        this.repaint();
+        this.handle = handle;
+        handle.onClose(() => this.close());
+        // A teardown that landed before the mount had no handle to close, so the
+        // fresh one is closed the moment it arrives: a review settled elsewhere
+        // never stands mounted. Its disposition is stated after the close, which
+        // is what disposes the notice the earlier teardown raised.
+        if (this.tornDown) {
+            handle.close();
+            const notice = this.tornDownNotice;
+            this.tornDownNotice = undefined;
+            if (notice !== undefined)
+                this.services.notice(notice);
+        }
     }
+    /** The status row's left segment: this document's state in one line. */
     summary() {
         if (this.status === 'refused')
             return `${this.fileLabel} — unavailable`;
@@ -167,21 +282,82 @@ export class DocumentRegion {
             parts.push(`stale (${this.source.current().staleReason ?? 'unreadable'})`);
         return parts.join(' · ');
     }
-    onDirty(fn) {
-        this.dirty = fn;
+    /** The status row's right segment: where the companion conversation is. */
+    companionSegment() {
+        return this.paneOrigin === undefined ? 'companion none' : `companion ${this.paneOrigin}`;
+    }
+    statusRow(width) {
+        if (width <= 0)
+            return '';
+        const right = clipLine(this.companionSegment(), width);
+        const left = clipLine(this.summary(), Math.max(0, width - visibleWidth(right) - 1));
+        const gap = Math.max(0, width - visibleWidth(left) - visibleWidth(right));
+        return `${DIM}${left}${' '.repeat(gap)}${right}${RESET}`;
+    }
+    // ── Companion pane ────────────────────────────────────────────────
+    /** Bind the conversation's pane, opening one only when this surface holds no
+     *  live pane already and there is no live companion viewer to adopt. A second
+     *  call therefore keeps the bound pane, whatever state its viewer is in. */
+    openCompanion() {
+        if (this.closed || this.tornDown)
+            return;
+        // Adoption can only see a pane once its viewer has tagged it, so through
+        // the whole revive-and-connect window the recorded pane is the only thing
+        // that keeps this idempotent: without it a retry splits a second pane and
+        // orphans the first. A pane that has since died falls through and reopens.
+        if (this.paneId !== undefined && companionPaneLive(this.paneId))
+            return;
+        const result = openCompanionPane({
+            companionNodeId: this.companionNodeId,
+            cwd: this.companionCwd,
+            callerPane: this.callerPane,
+        });
+        if (result.ok) {
+            this.paneId = result.paneId;
+            this.paneOrigin = result.origin;
+            this.repaint();
+            return;
+        }
+        if (result.reason === 'split_refused') {
+            this.services.notice('tmux refused the companion split — press space a to retry');
+            return;
+        }
+        // Without tmux the person still has a way to reach the conversation, and
+        // that instruction has to outlive an auto-clearing notice.
+        this.services.notice(`The review companion needs tmux — run: crtr surface attach to ${this.companionNodeId}`, { sticky: true });
+    }
+    /** The one path out of a review that has reached a terminal state — approved,
+     *  canceled here, or decided elsewhere. The pane goes with the review, never
+     *  with Esc: closing the document leaves the conversation standing so the
+     *  review can be re-opened over it. Idempotent. The disposition is stated
+     *  only after the close, because the host's restoring close disposes every
+     *  notice raised over the closing surface — a notice raised first would die
+     *  with the surface and the disposition would never paint. */
+    teardown(notice) {
+        if (this.tornDown)
+            return;
+        this.tornDown = true;
+        if (this.paneId !== undefined)
+            closeCompanionPane(this.paneId, this.companionNodeId);
+        this.paneId = undefined;
+        this.paneOrigin = undefined;
+        if (this.handle === undefined)
+            this.tornDownNotice = notice;
+        this.handle?.close();
+        this.services.notice(notice);
     }
-    /** Releases this region's render cache and stops every projected repaint.
-     *  This region closes the source it was handed; that close stops its watcher. */
+    /** Releases this surface's render cache and stops every projected repaint.
+     *  This surface closes the source it was handed; that close stops its watcher.
+     *  The companion pane deliberately survives: only {@link teardown} closes it. */
     close() {
         if (this.closed)
             return;
         // Stop the only source of new synchronous callbacks before closing the
-        // region to every already-in-flight asynchronous continuation.
+        // surface to every already-in-flight asynchronous continuation.
         this.source.close();
         this.closed = true;
         this.unsubscribeComments();
         this.cache = undefined;
-        this.dirty = undefined;
     }
     // ── Open-time base alignment ──────────────────────────────────────────────
     /** Bring the daemon's comment coordinates onto the bytes now on disk, then
@@ -235,7 +411,7 @@ export class DocumentRegion {
         const current = this.source.current();
         return current.status === 'live' && current.sha256 !== snapshot.sha256;
     }
-    /** Re-derive this region from the daemon's own coordinate base. The only
+    /** Re-derive this surface from the daemon's own coordinate base. The only
      *  honest recovery once a batch is rejected: the local map that produced it
      *  is no longer a true description of what the daemon holds. */
     async realign() {
@@ -338,7 +514,7 @@ export class DocumentRegion {
         this.remapChain = this.remapChain.then(() => this.submitBatch(previous.sha256, next.sha256, commentRanges), () => this.submitBatch(previous.sha256, next.sha256, commentRanges));
     }
     /** One transaction covering every non-deleted comment. A rejection is stated
-     *  in this region's own footer and the projection is re-read from the
+     *  in this surface's own footer and the projection is re-read from the
      *  authority, which is the only thing that can still be true afterwards. */
     async submitBatch(fromDocHash, toDocHash, ranges) {
         if (this.closed)
@@ -551,8 +727,20 @@ export class DocumentRegion {
                 this.services.submit();
             }
         }
+        else if (input === 'a') {
+            this.openCompanion();
+        }
+        else if (input === 'x') {
+            this.armCancel();
+        }
         this.repaint();
     }
+    /** Cancelling discards the whole review, so it asks once. The armed state is
+     *  answered in {@link handleInput}, ahead of every mode's ladder. */
+    armCancel() {
+        this.cancelArmed = true;
+        this.services.notice('cancel this review? press x again to confirm');
+    }
     handleListKey(key) {
         const state = this.state;
         if (state === undefined)
@@ -620,8 +808,8 @@ export class DocumentRegion {
             this.state = openHelp(state);
         }
         else if (key.type === 'cancel' && key.text === undefined) {
-            // Esc from the document belongs to the composed owner, which decides
-            // whether an unsent comment should hold the surface open.
+            // Esc in view mode belongs to this surface's own ladder, which decides
+            // whether an unsent comment should hold the review open.
             return false;
         }
         else if (key.type === 'cancel') {
@@ -634,7 +822,7 @@ export class DocumentRegion {
         return true;
     }
     /** The reviewed file is the deliverable: the person's own editor writes it,
-     *  this region never does. The source is re-read the moment the editor exits
+     *  this surface never does. The source is re-read the moment the editor exits
      *  rather than waiting for the watcher's coalescing window. */
     editInEditor() {
         const state = this.state;
@@ -653,9 +841,9 @@ export class DocumentRegion {
         this.source.refreshNow();
     }
     // ── Geometry and rendering ────────────────────────────────────────────────
-    /** The composition owns cursor focus; its focused document region contributes
-     * exactly one whole marker at the same visual location the document already
-     * calls active. There is deliberately no synthetic fallback row: a marker is
+    /** The host owns cursor focus; a focused surface contributes exactly one
+     * whole marker at the same visual location the document already calls
+     * active. There is deliberately no synthetic fallback row: a marker is
      * only valid when it belongs to a rendered anchor or the compose/list cursor. */
     markCursorLocation(lines, state) {
         if (state.mode === 'compose')
@@ -723,7 +911,7 @@ export class DocumentRegion {
     gutterWidth() {
         return this.kind.doc === 'code' ? String(this.source.current().lines.length).length : 0;
     }
-    /** The region's own footer line: its error, then its stale verdict. */
+    /** The document frame's own footer line: its error, then its stale verdict. */
     footerLine() {
         if (this.problem !== undefined)
             return this.problem;
@@ -806,12 +994,28 @@ export class DocumentRegion {
         return 1;
     }
     repaint() {
-        if (this.closed)
-            return;
-        this.dirty?.();
+        this.invalidate();
     }
 }
 // ── Pure helpers ─────────────────────────────────────────────────────────────
+/** Exactly `rows` lines, each exactly `width` cells. */
+function exactRows(lines, rows, width) {
+    const frame = lines.slice(0, rows).map((line) => padTo(line, width));
+    while (frame.length < rows)
+        frame.push(' '.repeat(width));
+    return frame;
+}
+/** `string-width` correctly ignores ANSI but cannot know pi-tui's private
+ *  cursor marker is zero-width, so the marker is measured out of the line. */
+function padTo(line, width) {
+    const bare = line.split(CURSOR_MARKER).join('');
+    const cells = visibleWidth(bare);
+    if (cells > width) {
+        const clipped = clipLine(bare, width);
+        return clipped + ' '.repeat(Math.max(0, width - visibleWidth(clipped)));
+    }
+    return line + ' '.repeat(width - cells);
+}
 function labelFor(cwd, absFile) {
     const rel = relative(cwd, absFile);
     return rel === '' || rel.startsWith('..') ? absFile : rel;

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

@@ -133,13 +133,14 @@ export function renderReviewFrame(state, fileLabel, doc, cols, rows, opts) {
         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}space a${RESET}     open the companion pane`);
+        footer.push(`  ${DIM}space x${RESET}     cancel 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}`);
+        footer.push(`  ${DIM}space c${RESET} · ${DIM}space l${RESET} · ${DIM}space u${RESET} · ${DIM}space e${RESET} · ` +
+            `${DIM}space a${RESET} companion · ${DIM}space s${RESET} submit · ${DIM}space x${RESET} cancel · ` +
+            `${DIM}?${RESET} · ${DIM}esc${RESET}`);
     }
     if (opts?.notice !== undefined && footer.length > 0) {
         footer[footer.length - 1] = `  ${YELLOW}${opts.notice}${RESET}`;

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

@@ -1,10 +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;
+import { type ResolvedReview } from './review-client.js';
+export interface ReviewSurfaceOptions {
+    review: ResolvedReview;
 }
-/** Mount the canonical live-document and companion-conversation review. */
-export declare function openComposedReview(host: SurfaceHost, opts: ComposedReviewOptions): Promise<void>;
+/** Mount the review document. Both callers — the inbox's `ReviewAdapter` and
+ *  the viewer's `launchFileReview` — refuse a remote attach and resolve the
+ *  review record themselves, so this function is never reached from a remote
+ *  viewer and never reads a review record of its own. */
+export declare function openReviewSurface(host: SurfaceHost, opts: ReviewSurfaceOptions): Promise<void>;