@north-light/api 0.3.580 → 0.3.588

package/dist/clients/inbox/review/companion-pane.js

@@ -0,0 +1,109 @@
+// companion-pane.ts — review-side tmux policy for the companion pane.
+//
+// Pure placement over the existing tmux driver verbs; no daemon calls, no
+// review knowledge beyond the ids it is handed.
+import { inTmux, liveViewerPanes, paneRunning, paneSize, splitWindow, paneExists, getPaneOption, closePane, } from '../../../core/runtime/placement-tmux.js';
+import { viewerEnv } from '../../../commands/surface/node/placement.js';
+// Constants
+export const SPLIT_MIN_COLS = 99;
+export const MIN_COMPANION_COLS = 40;
+export const MIN_COMPANION_ROWS = 12;
+export const COMPANION_WIDTH_RATIO = 0.42;
+export const COMPANION_HEIGHT_RATIO = 0.40;
+// Types
+/** A fork column narrower than this cannot hold a readable conversation, so the
+ *  split is refused rather than shipping an unusable pane. */
+export const MIN_FORK_COLS = 52;
+// Pane lifecycle
+/** Open or adopt a companion pane for a review. Adoption succeeds only when
+ *  an existing validated-live companion viewer pane exists; otherwise, a
+ *  fresh pane is split beside the caller. */
+export function openCompanionPane(args) {
+    const { companionNodeId, cwd, callerPane } = args;
+    // 1. Check if we're in tmux.
+    if (!inTmux())
+        return { ok: false, reason: 'no_tmux' };
+    // 2. Adopt: scan for an existing live companion viewer pane.
+    const allPanes = liveViewerPanes();
+    const candidatePanes = allPanes
+        .filter((p) => p.nodeId === companionNodeId && paneRunning(p.pane))
+        .sort((a, b) => b.stampMs - a.stampMs);
+    if (candidatePanes.length > 0) {
+        const adopted = candidatePanes[0];
+        return { ok: true, paneId: adopted.pane, origin: 'adopted' };
+    }
+    // 3. Check for a valid caller pane.
+    if (callerPane === undefined || callerPane === '') {
+        return { ok: false, reason: 'no_caller_pane' };
+    }
+    // 4. Get the caller pane's size.
+    const size = paneSize(callerPane);
+    if (size === null) {
+        return { ok: false, reason: 'split_refused' };
+    }
+    // 5. Decide direction and companion size.
+    let vertical;
+    let companionSize;
+    if (size.cols >= SPLIT_MIN_COLS) {
+        // Horizontal split: companion on the right.
+        vertical = false;
+        companionSize = Math.max(MIN_COMPANION_COLS, Math.round(size.cols * COMPANION_WIDTH_RATIO));
+    }
+    else {
+        // Vertical split: companion below.
+        vertical = true;
+        companionSize = Math.max(MIN_COMPANION_ROWS, Math.round(size.rows * COMPANION_HEIGHT_RATIO));
+    }
+    // 6. Split the window and get the new pane id.
+    const newPaneId = splitWindow(callerPane, {
+        cwd,
+        env: viewerEnv(),
+        command: `crtr surface attach to ${companionNodeId}`,
+        vertical,
+        size: companionSize,
+    });
+    if (newPaneId === null) {
+        return { ok: false, reason: 'split_refused' };
+    }
+    return { ok: true, paneId: newPaneId, origin: 'opened' };
+}
+/** Open a column for a comment's fork, splitting the rightmost review pane —
+ *  the newest fork, else the companion — so columns accumulate to the right and
+ *  the document keeps its width. */
+export function openForkPane(args) {
+    const { nodeId, cwd, splitFrom } = args;
+    if (!inTmux())
+        return { ok: false, reason: 'no_tmux' };
+    if (splitFrom === undefined || splitFrom === '')
+        return { ok: false, reason: 'no_caller_pane' };
+    const size = paneSize(splitFrom);
+    if (size === null)
+        return { ok: false, reason: 'split_refused' };
+    if (Math.floor(size.cols / 2) < MIN_FORK_COLS)
+        return { ok: false, reason: 'no_room' };
+    const paneId = splitWindow(splitFrom, {
+        cwd,
+        env: viewerEnv(),
+        command: `crtr surface attach to ${nodeId}`,
+        vertical: false,
+        size: Math.floor(size.cols / 2),
+    });
+    return paneId === null ? { ok: false, reason: 'split_refused' } : { ok: true, paneId };
+}
+/** True while tmux can still describe `paneId` and its process is alive.
+ *  Deliberately tag-free: a companion pane carries `@crtr_node` only once its
+ *  viewer has connected, so a tag check would call a still-booting pane dead
+ *  and let a duplicate be split beside it. */
+export function companionPaneLive(paneId) {
+    return paneExists(paneId) && paneRunning(paneId);
+}
+/** Kill the pane only when it still exists AND still carries
+ *  `@crtr_node === companionNodeId`. */
+export function closeCompanionPane(paneId, companionNodeId) {
+    if (!paneExists(paneId))
+        return;
+    const currentNodeId = getPaneOption(paneId, '@crtr_node');
+    if (currentNodeId !== companionNodeId)
+        return;
+    closePane(paneId);
+}

package/dist/clients/inbox/review/document-surface.d.ts

@@ -0,0 +1,212 @@
+import type { SurfaceComponent, SurfaceHandle, SurfaceNoticeOptions } from '../../surfaces/host.js';
+import { type CommentAuthority } from './comments-client.js';
+import type { LiveSource } from './live-source.js';
+import type { ResolvedReview } from './review-client.js';
+/** What the surface's owner supplies for everything outside the document.
+ *
+ *  `submit` exists because the `s` key lives on the document while the review lifecycle adapter belongs to the owner: the
+ *  surface reports the intent, the owner runs `reviewClient.submit`. */
+export interface ReviewSurfaceServices {
+    notice(text: string, opts?: SurfaceNoticeOptions): void;
+    suspendForChild(): () => void;
+    requestClose(): void;
+    submit(): void;
+    cancel(): void;
+}
+export interface ReviewDocumentSurfaceOptions {
+    review: ResolvedReview;
+    source: LiveSource;
+    comments: CommentAuthority;
+    /** `host.capabilities.selfPane` — the pane the companion splits against. */
+    callerPane: string | undefined;
+    services: ReviewSurfaceServices;
+}
+/** 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 declare class ReviewDocumentSurface implements SurfaceComponent {
+    private readonly absFile;
+    private readonly fileLabel;
+    private readonly companionNodeId;
+    private readonly companionCwd;
+    private readonly callerPane;
+    private readonly kind;
+    private readonly source;
+    private readonly comments;
+    private readonly services;
+    private readonly unsubscribeComments;
+    private readonly ready;
+    private cols;
+    /** Rows the host assigned this surface; the document frame renders one
+     *  fewer, because the last line is this surface's status row. */
+    private hostRows;
+    /** 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. */
+    private flowedRows;
+    private _focused;
+    private closed;
+    private escapeConfirmArmed;
+    private cancelArmed;
+    private submitArmed;
+    private tornDown;
+    /** 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. */
+    private tornDownNotice;
+    private handle;
+    /** The companion pane this surface is bound to, and how it came to be.
+     *  `paneOrigin` is status-row copy only: teardown reads `paneId`. */
+    private paneId;
+    private paneOrigin;
+    /** Fork columns this surface opened, oldest first. The newest live one is
+     *  what the next fork splits against, so columns accumulate rightward. */
+    private forkPanes;
+    /** Row increments of a half-page move still to be painted, and the timer
+     *  walking them. A fresh press settles whatever is in flight before starting
+     *  its own move, so a held key cannot pile up overlapping animations. */
+    private scrollSteps;
+    private scrollTimer;
+    private state;
+    private cache;
+    /** Every non-deleted comment the daemon currently projects, newest last. */
+    private projection;
+    private status;
+    /** This surface's own error/summary state — never a host notice (D1). */
+    private problem;
+    private composeAnchorLost;
+    /** Serializes base-hash transitions so B→C cannot overtake A→B. */
+    private remapChain;
+    constructor(opts: ReviewDocumentSurfaceOptions);
+    /** Resolves once the daemon coordinate base has been aligned to the file on
+     *  disk. The owner may await it so the first painted frame already carries
+     *  current ranges; painting earlier shows only a preparing line, never a
+     *  comment at a coordinate the daemon has not accepted. */
+    open(): Promise<void>;
+    hasUnsentCompose(): boolean;
+    get focused(): boolean;
+    set focused(value: boolean);
+    setRows(rows: number): void;
+    /** 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: number): string[];
+    /** Rows the document frame itself owns. */
+    private get rows();
+    private renderDocument;
+    /** 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: string): void;
+    /** True when the document's own modes took the chunk. */
+    private consume;
+    /** A mounted review consumes every notch, ready or not: the transcript
+     *  beneath it must never scroll while the document stands over it. */
+    handleWheel(direction: 'up' | 'down', lines: number): boolean;
+    /** A half-page move of the view and the selection together, painted at three
+     *  midpoints before its destination so the document slides rather than jumps.
+     *  Whatever is still in flight lands first, keeping every press exact. */
+    private startScrollAnimation;
+    private scheduleScrollStep;
+    /** Land every step still to be painted on the state at once. */
+    private settleScrollAnimation;
+    private stopScrollAnimation;
+    private applyScrollRows;
+    /** Repaints are scheduled by the host; this surface never draws directly. */
+    invalidate(): void;
+    /** 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: SurfaceHandle): void;
+    /** The status row's left segment: this document's state in one line. */
+    private summary;
+    /** The status row's right segment: where the companion conversation is. */
+    private companionSegment;
+    private statusRow;
+    /** 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(): void;
+    /** The pane a new fork column splits from: the newest live fork, else the
+     *  companion, else this viewer. */
+    private rightmostReviewPane;
+    /** Hand one comment to its own fork of the companion and place its column.
+     *  The comment is already saved by the time this runs, so every failure here
+     *  is stated as a notice rather than failing the comment. */
+    private forkComment;
+    /** 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: string, opts?: SurfaceNoticeOptions): void;
+    /** 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(): void;
+    /** Bring the daemon's comment coordinates onto the bytes now on disk, then
+     *  build the first state from what the daemon accepted. The zero-comment case
+     *  still submits its batch: the base digest itself is what advances, and a
+     *  later create against current bytes is rejected until it does. */
+    private align;
+    private movedSince;
+    /** 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. */
+    private realign;
+    private buildState;
+    private onSourceChanged;
+    /** One transaction covering every non-deleted comment. A rejection is stated
+     *  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. */
+    private submitBatch;
+    private refreshProjection;
+    private mutate;
+    private handleComposeKey;
+    /** The document's single-key commands, shared by view mode. Returns false
+     *  for a key that is not one of them. Space was once a prefix for these; it
+     *  is now ignored, so a remembered `space c` still lands on `c`. */
+    private handleCommandKey;
+    private submit;
+    /** Submitting ends the review, so it asks once. The armed state is answered
+     *  in {@link handleInput}, ahead of every mode's ladder. */
+    private armSubmit;
+    /** Cancelling discards the whole review, so it asks once. The armed state is
+     *  answered in {@link handleInput}, ahead of every mode's ladder. */
+    private armCancel;
+    private handleListKey;
+    private handleViewKey;
+    /** The reviewed file is the deliverable: the person's own editor writes it,
+     *  this surface never does. The source is re-read the moment the editor exits
+     *  rather than waiting for the watcher's coalescing window. */
+    private editInEditor;
+    /** 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. */
+    private markCursorLocation;
+    /** The frame paints source rows after its three-line header. Scroll indicators
+     * replace their source rows, so they are never cursor targets. */
+    private activeAnchorFrameRow;
+    private reflow;
+    private document;
+    private bodyHeight;
+    private composeWidth;
+    private gutterWidth;
+    /** The document frame's own footer line: its error, then its stale verdict. */
+    private footerLine;
+    private renderPlaceholder;
+    /** `frame.ts` renders the ordinary list. Detached anchors need stronger
+     *  treatment: their own leading group plus the original range and snippet,
+     *  because no document marker can lead a person back to them. */
+    private renderGroupedList;
+    /** The compose header states a lost anchor where the person is already
+     *  looking, leaving the footer's compose keys intact. */
+    private statedComposeAnchor;
+    private commentListRow;
+    private topVisibleSourceLine;
+    private repaint;
+}