@north-light/api 0.3.580 → 0.3.587

package/dist/clients/attach/session/readonly-popup.d.ts

@@ -0,0 +1,15 @@
+export interface ReadonlyPopup {
+    /** The file name inside the temp dir; non-portable characters are replaced. */
+    name: string;
+    /** Page content written before the popup opens. Omit it when `produce` writes the file. */
+    content?: string;
+    /** A shell fragment run inside the popup that writes the page to `$PAGE` (e.g. `crtr canvas read x > "$PAGE"`). */
+    produce?: (page: string) => string;
+    /** Popup title; omitted leaves tmux's default. */
+    title?: string;
+    /** What the person sees when nvim is not installed. */
+    noNvim: string;
+    onClose?: () => void;
+}
+/** Open the page in a read-only nvim popup (90% × 85%). Requires tmux — callers gate on `inTmux()` first. */
+export declare function openReadonlyPopup(spec: ReadonlyPopup): void;

package/dist/clients/attach/session/readonly-popup.js

@@ -0,0 +1,25 @@
+// session/readonly-popup.ts — one read-only nvim popup for the viewer: a page of
+// markdown (a loaded command, a watched object's `crtr canvas read`) shown in a
+// tmux display-popup that closes back onto this pane. The temp file the page
+// lives in is removed when the popup closes, whatever happened inside it.
+import { execFile } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { nvimShellCommand } from '../../../core/nvim-launch.js';
+import { shellQuote } from '../../../core/runtime/placement-tmux.js';
+import { surfaceTmuxStyleArgs } from '../../../core/runtime/surface-bg.js';
+/** Open the page in a read-only nvim popup (90% × 85%). Requires tmux — callers gate on `inTmux()` first. */
+export function openReadonlyPopup(spec) {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-page-'));
+    const path = join(dir, `${spec.name.replace(/[^A-Za-z0-9_.-]/g, '-')}.md`);
+    if (spec.content !== undefined)
+        writeFileSync(path, spec.content, 'utf8');
+    const produce = spec.produce === undefined ? '' : `${spec.produce(shellQuote(path))}; `;
+    const cmd = `${produce}if command -v nvim >/dev/null 2>&1; then exec ${nvimShellCommand('readonly', [path])}; else cat ${shellQuote(path)}; printf '%s\\n' ${shellQuote(spec.noNvim)}; printf 'Press Enter to close.'; read _; fi`;
+    const title = spec.title === undefined ? [] : ['-T', ` ${spec.title} `];
+    execFile('tmux', ['display-popup', '-E', ...title, '-w', '90%', '-h', '85%', ...surfaceTmuxStyleArgs(), cmd], () => {
+        rmSync(dir, { recursive: true, force: true });
+        spec.onClose?.();
+    });
+}

package/dist/clients/attach/session/reconnect.d.ts

@@ -0,0 +1,46 @@
+import type { ClientRole } from '../../../core/runtime/broker-protocol.js';
+import type { BrokerToClient } from '../../../core/runtime/broker-protocol.js';
+import type { AttachSession } from './context.js';
+export interface ReconnectHooks {
+    /** This viewer's fixed role, resolved from the original attach flags. */
+    role: ClientRole;
+    /** A `--canvas` attach: crtrd closes a controller hello it does not authorize. */
+    remote: boolean;
+    /** This viewer's stable client id, echoed by the broker in the hello. */
+    clientId: string;
+    /** Every broker frame, in wire order. */
+    onFrame: (frame: BrokerToClient) => void;
+    setNotice: (msg: string, opts?: {
+        sticky?: boolean;
+    }) => void;
+    /** True once teardown has begun — the supervisor loop's exit condition. */
+    isTornDown: () => boolean;
+    /** End the session. `node-done` is a clean finalize (the node pushed its
+     *  final report) and closes the pane; `broker-gone` freezes the corpse. */
+    teardown: (reason: 'node-done' | 'broker-gone') => void;
+    /** The viewer was bootstrapped from a saved parked snapshot before any socket
+     * connection. */
+    initialDormant?: boolean;
+    /** Called once each time the node is first seen as dormant. A stopped broker
+     * will relay no final session event, so the viewer clears live-only display. */
+    onEnterDormancy: () => void;
+}
+export interface ReconnectSupervisor {
+    /** Send the hello handshake. Called once after `tui.start()`, then again on
+     *  every successful redial. */
+    sendHello: () => void;
+    /** Begin redialing an offline parked viewer after its saved snapshot paints. */
+    startDormant: () => void;
+    /** True while the node has no live broker — the input layer routes a
+     *  submitted prompt through a wake message rather than a dead socket. */
+    isDormant: () => boolean;
+    /** The last socket-level error, for a broker-gone teardown message. */
+    lastSocketError: () => string | undefined;
+    /** Install the permanent frame/error/close handlers. Call once, AFTER the
+     *  connect race is settled and its temporary listeners are gone. */
+    install: () => void;
+    /** Cancel the current delay/redial wait. Ordinary attach never calls this;
+     *  bounded companion surfaces call it before closing their socket. */
+    stop: () => void;
+}
+export declare function createReconnect(ctx: Pick<AttachSession, 'nodeId' | 'socket' | 'canvasSource'>, hooks: ReconnectHooks): ReconnectSupervisor;

package/dist/clients/attach/session/reconnect.js

@@ -0,0 +1,195 @@
+// session/reconnect.ts — staying on the broker: the hello handshake, the
+// permanent socket handlers, and the redial supervisor behind them.
+//
+// The viewer's socket is not a one-shot. A resident node that yields EXITS its
+// broker and is revived FRESH by the daemon on the SAME `view.sock` path; an
+// idle-released node's broker is gone until its next wake. Both look identical
+// from here — a `close` — so this module decides whether to hold the pane and
+// keep redialing or to let the viewer die, and it is the ONLY thing that
+// decides that.
+import { AttachRefusedError, reconnectShouldGiveUp } from '../../../core/broker-client/index.js';
+/** A refresh/revive is imminent — redial briskly. */
+const RECONNECT_ACTIVE_DELAY_CAP_MS = 1_000;
+/** Dormant by choice — low-rate patience. */
+const RECONNECT_DORMANT_DELAY_MS = 3_000;
+export function createReconnect(ctx, hooks) {
+    const { nodeId, socket, canvasSource } = ctx;
+    let lastSocketError;
+    let reconnecting = false;
+    let viewerDormant = hooks.initialDormant === true;
+    // Captured at give-up: a terminal `done` is a CLEAN finalize — the viewer
+    // closes its pane instead of freezing a scary "broker gone" corpse.
+    // `dead`/`canceled` keep the corpse.
+    let finalizedDone = false;
+    let stopped = false;
+    let resolveStopped = () => { };
+    let retryTimer;
+    let cancelRetry;
+    const stoppedSignal = new Promise((resolve) => {
+        resolveStopped = resolve;
+    });
+    const waitForRetry = (ms) => {
+        if (stopped)
+            return Promise.resolve(false);
+        return new Promise((resolve) => {
+            const settle = (elapsed) => {
+                retryTimer = undefined;
+                cancelRetry = undefined;
+                resolve(elapsed);
+            };
+            retryTimer = setTimeout(() => settle(true), ms);
+            cancelRetry = () => {
+                if (retryTimer !== undefined)
+                    clearTimeout(retryTimer);
+                settle(false);
+            };
+        });
+    };
+    // The handshake the viewer sends on connect AND on every successful redial.
+    // After a broker refresh / crash-revive the fresh process has no memory of
+    // this client, so re-`hello` resumes the role chosen at the original attach
+    // and the `welcome` snapshot repaints full scrollback/state. The role is
+    // deliberately fixed for the lifetime of this viewer: local writable attaches
+    // stay writable, while observers stay observers across every redial.
+    // `welcomed`: this session has been welcomed at least once. `refusedByRelay`: the relay closed the current connection as unavailable.
+    let welcomed = false;
+    let refusedByRelay = false;
+    const sendHello = () => {
+        refusedByRelay = false;
+        socket.send({
+            type: 'hello',
+            role: hooks.role,
+            client_id: hooks.clientId,
+            term: { cols: process.stdout.columns ?? 80, rows: process.stdout.rows ?? 24 },
+        });
+    };
+    // On close we HOLD the pane and keep re-dialing for as long as the canvas
+    // source says the node can come back, giving up ONLY when it is genuinely
+    // terminal (done/dead/canceled or row reaped). There is deliberately NO
+    // wall-clock give-up: a fixed deadline races the daemon's legitimate relaunch
+    // latency (a slow supervision tick on a big canvas, the 20s crash-revive
+    // grace, a slow pi boot), and losing that race dumped the user to a shell
+    // ("broker gone") seconds before the fresh broker bound its socket. A
+    // successful redial re-sends `hello`; the new broker's `welcome` runs
+    // applySnapshot, which resetChat()s the pane and rebuilds from the persisted
+    // .jsonl — a clean "clear + continuation" for free.
+    const attemptReconnect = async () => {
+        reconnecting = true;
+        hooks.setNotice('↻ node refreshing — reconnecting…', { sticky: true });
+        let delay = 200;
+        try {
+            while (!stopped && !hooks.isTornDown()) {
+                // The row read is advisory: a transient canvas-source error must never
+                // kill the supervisor loop — treat it as "keep trying" and read again
+                // on the next attempt. `canvasSource` is genuinely remote-backed under
+                // `--canvas`, so `getRow` works for both cases — always attempt it.
+                let row;
+                try {
+                    row = await canvasSource.getRow(nodeId);
+                }
+                catch {
+                    row = undefined;
+                }
+                if (row !== undefined && reconnectShouldGiveUp(row)) {
+                    finalizedDone = row?.status === 'done'; // clean finalize vs dead/canceled
+                    break; // genuinely gone → clean close (done) or broker-gone corpse
+                }
+                // A dormant node has NO broker until its next wake. We still track that
+                // (the dormant flag routes a submitted prompt through the wake path
+                // instead of a dead socket), but we DON'T shout about it: a parked pane
+                // is a normal state, not an error. Typing just works — the dormant
+                // submit shows "waking node…" the moment you send — so a persistent
+                // "node dormant" banner is pure noise. Clear the footer when dormant;
+                // keep the reconnecting notice only for a transient broker relaunch.
+                const dormant = row?.status === 'idle'
+                    || row?.intent === 'idle-release'
+                    || (row?.lifecycle === 'resident'
+                        && row.status === 'done'
+                        && row.intent === 'parked'
+                        && row.final_report == null);
+                const enteredDormancy = dormant && !viewerDormant;
+                viewerDormant = dormant;
+                if (enteredDormancy)
+                    hooks.onEnterDormancy();
+                hooks.setNotice(dormant ? '' : '↻ node refreshing — reconnecting…', { sticky: !dormant });
+                try {
+                    const redialed = await Promise.race([
+                        socket.redial({ brokerUnavailableIsExpected: dormant }).then(() => true),
+                        stoppedSignal.then(() => false),
+                    ]);
+                    if (!redialed || stopped || hooks.isTornDown())
+                        return;
+                    sendHello();
+                    viewerDormant = false;
+                    hooks.setNotice('');
+                    return; // reconnected; the welcome snapshot clears + continues the pane
+                }
+                catch {
+                    // ENOENT (socket not recreated yet) / ECONNREFUSED (listen not ready) → retry.
+                    const elapsed = await waitForRetry(dormant ? RECONNECT_DORMANT_DELAY_MS : Math.min(delay, RECONNECT_ACTIVE_DELAY_CAP_MS));
+                    if (!elapsed)
+                        return;
+                    delay *= 2;
+                }
+            }
+        }
+        finally {
+            // However the loop exits — give-up, teardown mid-await, or an unexpected
+            // throw — the supervisor must never stay latched "reconnecting" (a stuck
+            // latch eats every future close event and hangs the viewer forever).
+            reconnecting = false;
+        }
+        if (!stopped && !hooks.isTornDown())
+            hooks.teardown(finalizedDone ? 'node-done' : 'broker-gone');
+    };
+    const install = async () => {
+        socket.on('frame', (frame) => {
+            if (frame.type === 'welcome')
+                welcomed = true;
+            hooks.onFrame(frame);
+        });
+        socket.on('error', (err) => {
+            // Stash the reason; a 'close' follows and teardown converges there, where
+            // a broker-gone message prefers this over the generic text.
+            lastSocketError = err.message;
+            if (err instanceof AttachRefusedError)
+                refusedByRelay = true;
+        });
+        socket.on('close', () => {
+            if (hooks.isTornDown())
+                return; // a real detach/signal already won
+            if (reconnecting)
+                return; // the dead socket's own close during the redial loop
+            // crtrd closes a controller hello from a caller without `message`
+            // permission 1008 before the hello reaches the broker, and the relay
+            // transport reports that close as AttachRefusedError. A writable remote
+            // attach closed that way before the session's first welcome is a refusal,
+            // not a broker to redial; a plain drop or a 1011 "no running broker" is redialed.
+            if (hooks.remote && hooks.role === 'controller' && refusedByRelay && !welcomed) {
+                lastSocketError = `the remote canvas refused the attach to ${nodeId}. A writable attach needs message permission on the node; with read permission only, attach with --observer.`;
+                hooks.teardown('broker-gone');
+                return;
+            }
+            void attemptReconnect();
+        });
+    };
+    return {
+        sendHello,
+        startDormant: () => {
+            if (reconnecting || stopped || hooks.isTornDown())
+                return;
+            hooks.onEnterDormancy();
+            void attemptReconnect();
+        },
+        isDormant: () => viewerDormant,
+        lastSocketError: () => lastSocketError,
+        install,
+        stop: () => {
+            if (stopped)
+                return;
+            stopped = true;
+            cancelRetry?.();
+            resolveStopped();
+        },
+    };
+}

package/dist/clients/attach/session/selection.d.ts

@@ -0,0 +1,28 @@
+export type SelectionRelease = {
+    kind: 'click';
+    column: number;
+    row: number;
+} | {
+    kind: 'selection';
+    notice: string;
+};
+export interface FrameSelection {
+    /** Primary button pressed: anchor here and drop any previous highlight. */
+    begin(column: number, row: number): void;
+    /** Drag to a new cell. Returns true when the highlight changed. */
+    extend(column: number, row: number): boolean;
+    /** Primary button released. `click` means the press never moved, so the
+     *  caller's click handling (file links) still owns the gesture. */
+    release(): SelectionRelease | undefined;
+    /** Drop the highlight. Returns true when something was showing. */
+    clear(): boolean;
+    /** A highlight is on screen. */
+    active(): boolean;
+    /** Paint the highlight onto a composed frame; identity when nothing is selected. */
+    apply(frame: readonly string[]): string[];
+}
+export declare function createFrameSelection(deps: {
+    /** The physical rows of the last render, unhighlighted. */
+    frame: () => readonly string[];
+    width: () => number;
+}): FrameSelection;

package/dist/clients/attach/session/selection.js

@@ -0,0 +1,108 @@
+// session/selection.ts — mouse drag-select and copy over the rendered frame.
+//
+// While the viewer reports mouse events, the terminal hands presses and drags to
+// this process, so the terminal's own drag-select is unavailable: the viewer has
+// to do the selecting. It selects the way a terminal does — over the physical
+// rows last handed to the screen, not over transcript records — so wrapping,
+// folds, the pinned header, and the cockpit all select exactly as they look.
+// Releasing the button copies the selection to the clipboard (and, in tmux, the
+// paste buffer); the highlight stays up as confirmation until the next keypress,
+// wheel notch, or press.
+import { highlightCells, sliceCells } from '../ansi-cells.js';
+import { writeClipboardTextEverywhere } from '../../../core/clipboard-text.js';
+function before(a, b) {
+    return a.row < b.row || (a.row === b.row && a.column <= b.column);
+}
+/** The per-row cell ranges covered by a drag, in terminal selection geometry:
+ *  the first row runs to the pane edge, whole rows in between, the last row up
+ *  to and including the cell under the pointer. */
+function spans(anchor, head, width) {
+    const [start, end] = before(anchor, head) ? [anchor, head] : [head, anchor];
+    const rows = [];
+    for (let row = start.row; row <= end.row; row++) {
+        const from = row === start.row ? start.column - 1 : 0;
+        const to = row === end.row ? end.column : width;
+        if (to > from)
+            rows.push({ row, from, to });
+    }
+    return rows;
+}
+export function createFrameSelection(deps) {
+    let anchor;
+    let head;
+    const selected = () => anchor !== undefined && head !== undefined ? { anchor, head } : undefined;
+    const selectionText = () => {
+        const current = selected();
+        if (!current)
+            return '';
+        const frame = deps.frame();
+        const rows = spans(current.anchor, current.head, deps.width())
+            .map((span) => sliceCells(frame[span.row - 1] ?? '', span.from, span.to).trimEnd());
+        // A trailing blank row is an artifact of where the button came up; leading
+        // blanks inside the span are real content the user dragged across.
+        while (rows.length > 0 && rows[rows.length - 1] === '')
+            rows.pop();
+        return rows.join('\n');
+    };
+    return {
+        begin(column, row) {
+            anchor = { row, column };
+            head = undefined;
+        },
+        extend(column, row) {
+            if (anchor === undefined)
+                return false;
+            if (head !== undefined && head.row === row && head.column === column)
+                return false;
+            head = { row, column };
+            return true;
+        },
+        release() {
+            const press = anchor;
+            if (press === undefined)
+                return undefined;
+            if (head === undefined) {
+                anchor = undefined;
+                return { kind: 'click', column: press.column, row: press.row };
+            }
+            const text = selectionText();
+            if (text === '') {
+                anchor = undefined;
+                head = undefined;
+                return { kind: 'selection', notice: 'Nothing to copy — selection is empty' };
+            }
+            const { system, tmux } = writeClipboardTextEverywhere(text);
+            const destination = system && tmux ? 'clipboard + tmux buffer' : system ? 'clipboard' : tmux ? 'tmux buffer' : undefined;
+            const lines = text.split('\n').length;
+            return {
+                kind: 'selection',
+                notice: destination === undefined
+                    ? 'Copy failed — no clipboard tool found'
+                    : `Copied selection (${lines} ${lines === 1 ? 'line' : 'lines'}) — ${destination}`,
+            };
+        },
+        clear() {
+            const showing = head !== undefined;
+            anchor = undefined;
+            head = undefined;
+            return showing;
+        },
+        active() {
+            return head !== undefined;
+        },
+        apply(frame) {
+            const current = selected();
+            if (!current)
+                return frame.slice();
+            const width = deps.width();
+            const painted = frame.slice();
+            for (const span of spans(current.anchor, current.head, width)) {
+                const index = span.row - 1;
+                if (index < 0 || index >= painted.length)
+                    continue;
+                painted[index] = highlightCells(painted[index], span.from, span.to, width);
+            }
+            return painted;
+        },
+    };
+}

package/dist/clients/attach/session/state-sync.d.ts

@@ -0,0 +1,38 @@
+import { type SessionState } from '../../../core/session-model/session-state.js';
+import type { BrokerToClient, ClientRole } from '../../../core/runtime/broker-protocol.js';
+/** The repaints a state delta can trigger. Each is a lazy closure so the
+ *  collaborators that answer them may be built after this owner. */
+export interface StateSyncEffects {
+    /** Feed engine state to the input controller — steer-vs-prompt routing reads
+     *  `isStreaming`, so it must stay current. */
+    setEngineState: (engine: NonNullable<SessionState['engine']>) => void;
+    /** The task name lives in the editor's top border; the border color tracks
+     *  the agent's thinking level. Both follow live state. */
+    setEditorTitle: (name: string | undefined) => void;
+    paintEditorFrame: () => void;
+    renderExtensionWidgets: () => void;
+    renderQueued: () => void;
+    renderFooter: () => void;
+    setTerminalTitle: (title: string) => void;
+    /** Panel liveness rides the relayed event stream (agent_start/agent_end/
+     *  queue_update/session_info_changed all move engine state) plus the viewer's
+     *  low-rate poll for changes that emit no event (child status flips). */
+    refreshChrome: () => void;
+}
+export interface SessionStateSync {
+    /** The live folded state. Read it; never hold it across an await. */
+    state: () => SessionState;
+    /** Fold one broker frame through the shared reducer and repaint the slices
+     *  that actually changed. */
+    fold: (frame: BrokerToClient) => void;
+    /** The ONE place this viewer writes session state without a broker frame: an
+     *  idle-released broker has settled its turn and will relay no final event,
+     *  so the viewer must clear the live-only spinner itself. Everything else
+     *  must go through `fold`. */
+    patchLocal: (patch: Partial<NonNullable<SessionState['engine']>>) => void;
+    /** The combined model + thinking-level label a model/thinking change
+     *  announces (e.g. "sonnet medium", "fable x high"). Reads live state, so
+     *  callers fold first, then notice. `off` collapses to the bare model name. */
+    modelThinkingLabel: () => string | undefined;
+}
+export declare function createSessionStateSync(role: ClientRole, fx: StateSyncEffects): SessionStateSync;

package/dist/clients/attach/session/state-sync.js

@@ -0,0 +1,67 @@
+// session/state-sync.ts — the OWNER of this viewer's folded `SessionState`,
+// and the only place that decides what a state change repaints.
+//
+// Everything this viewer knows because the broker told it — role, pi's engine
+// state, context tokens, the queue, the retained display levels — lives in ONE
+// value folded by the shared pure reducer (`core/session-model`), not in a
+// handful of mutable locals patched from a frame switch.
+//
+// The dirty tracking IS identity comparison: `reduce` returns the same
+// reference for any frame that changes nothing, and the same sub-object for any
+// slice it leaves alone, so each repaint below is gated on a `!==` against the
+// previous value. No change flags, no repaint-everything.
+import { initialSessionState, reduce } from '../../../core/session-model/session-state.js';
+export function createSessionStateSync(role, fx) {
+    let session = initialSessionState(role);
+    /** Repaint exactly the chrome whose SLICE of session state changed. */
+    const renderDelta = (prev) => {
+        const next = session;
+        if (next === prev)
+            return;
+        const engineChanged = next.engine !== prev.engine;
+        if (engineChanged && next.engine !== undefined) {
+            fx.setEngineState(next.engine);
+            fx.setEditorTitle(next.engine.sessionName);
+        }
+        if (engineChanged)
+            fx.paintEditorFrame();
+        if (next.display.widgets !== prev.display.widgets)
+            fx.renderExtensionWidgets();
+        if (next.display.title !== prev.display.title && next.display.title !== undefined) {
+            fx.setTerminalTitle(next.display.title);
+        }
+        if (next.queued !== prev.queued)
+            fx.renderQueued();
+        if (engineChanged ||
+            next.role !== prev.role ||
+            next.contextTokens !== prev.contextTokens ||
+            next.display.statuses !== prev.display.statuses) {
+            fx.renderFooter();
+        }
+        if (engineChanged)
+            fx.refreshChrome();
+    };
+    return {
+        state: () => session,
+        fold: (frame) => {
+            const prev = session;
+            session = reduce(session, frame);
+            renderDelta(prev);
+        },
+        patchLocal: (patch) => {
+            const engine = session.engine;
+            if (engine === undefined)
+                return;
+            const prev = session;
+            session = { ...session, engine: { ...engine, ...patch } };
+            renderDelta(prev);
+        },
+        modelThinkingLabel: () => {
+            const model = session.engine?.model?.id;
+            if (model === undefined)
+                return undefined;
+            const level = session.engine?.thinkingLevel;
+            return level !== undefined && level !== 'off' ? `${model} ${level}` : model;
+        },
+    };
+}

package/dist/clients/attach/session/surface-frame.d.ts

@@ -0,0 +1,20 @@
+import { type Component } from '@earendil-works/pi-tui';
+import type { SurfaceComponent } from '../../surfaces/host.js';
+/**
+ * The opaque rectangle wrapper used for every viewer surface. Rows are read
+ * and pushed inside the render pass: a surface hidden beneath another surface
+ * is not rendered, and therefore never observes a stale height when restored.
+ */
+export declare class SurfaceFrame implements Component {
+    private readonly surface;
+    private readonly focusTarget;
+    private readonly getRows;
+    private _focused;
+    constructor(surface: SurfaceComponent, focusTarget: Component, getRows: () => number);
+    get focused(): boolean;
+    set focused(value: boolean);
+    get wantsKeyRelease(): boolean;
+    render(width: number): string[];
+    handleInput(data: string): void;
+    invalidate(): void;
+}

package/dist/clients/attach/session/surface-frame.js

@@ -0,0 +1,73 @@
+import { CURSOR_MARKER, isFocusable, sliceByColumn, truncateToWidth, visibleWidth, } from '@earendil-works/pi-tui';
+import { reportInvariant as report } from './invariant.js';
+/**
+ * The opaque rectangle wrapper used for every viewer surface. Rows are read
+ * and pushed inside the render pass: a surface hidden beneath another surface
+ * is not rendered, and therefore never observes a stale height when restored.
+ */
+export class SurfaceFrame {
+    surface;
+    focusTarget;
+    getRows;
+    _focused = false;
+    constructor(surface, focusTarget, getRows) {
+        this.surface = surface;
+        this.focusTarget = focusTarget;
+        this.getRows = getRows;
+    }
+    get focused() {
+        return this._focused;
+    }
+    set focused(value) {
+        this._focused = value;
+        if (isFocusable(this.focusTarget))
+            this.focusTarget.focused = value;
+    }
+    get wantsKeyRelease() {
+        return this.focusTarget.wantsKeyRelease ?? this.surface.wantsKeyRelease ?? false;
+    }
+    render(width) {
+        const rows = Math.max(0, Math.floor(this.getRows()));
+        const columns = Math.max(0, Math.floor(width));
+        this.surface.setRows(rows);
+        const rendered = this.surface.render(columns);
+        if (rendered.length !== rows) {
+            reportInvariant(`surface rendered ${rendered.length} rows; expected ${rows}`);
+        }
+        const frame = rendered.slice(0, rows).map((line) => {
+            if (visibleWidth(line) > columns) {
+                reportInvariant(`surface row is ${visibleWidth(line)} cells wide; expected at most ${columns}`);
+                return padToWidth(sliceByColumn(line, 0, columns, true), columns);
+            }
+            return padToWidth(line, columns);
+        });
+        while (frame.length < rows)
+            frame.push(' '.repeat(columns));
+        const markerCount = countMarkers(frame);
+        if (markerCount > 1) {
+            reportInvariant(`surface frame contains ${markerCount} CURSOR_MARKER sequences; expected at most one`);
+            return frame.map(stripCursorMarkers);
+        }
+        return frame;
+    }
+    handleInput(data) {
+        const handler = this.focusTarget.handleInput ?? this.surface.handleInput;
+        handler?.call(this.focusTarget.handleInput === undefined ? this.surface : this.focusTarget, data);
+    }
+    invalidate() {
+        this.surface.invalidate();
+    }
+}
+function padToWidth(line, width) {
+    return truncateToWidth(line, width, '', true);
+}
+function countMarkers(lines) {
+    return lines.reduce((count, line) => count + line.split(CURSOR_MARKER).length - 1, 0);
+}
+function stripCursorMarkers(line) {
+    return line.split(CURSOR_MARKER).join('');
+}
+/** Invariants are reported without taking down the attached viewer. */
+function reportInvariant(message) {
+    report('surface-frame', message);
+}