@north-light/api 0.3.580 → 0.3.587

package/dist/clients/attach/session/editor-inventory.js

@@ -0,0 +1,156 @@
+// session/editor-inventory.ts — what the editor knows it can complete against:
+// the slash-command list, the loaded-command preview, and the broker's
+// memory-ref inventory. `createEditorInventory` OWNS that state — nothing
+// outside this module writes it.
+//
+// Both inventories arrive independently (a command reply and a ref reply race
+// each other), so neither may rebuild the editor's provider having silently
+// dropped the other — everything funnels through one `syncEditorInventories`
+// seam. The builders below stay pure so that contract is testable without a
+// socket, TUI, or broker.
+import { CombinedAutocompleteProvider } from '@earendil-works/pi-tui';
+import { formatBinding } from '../../../core/keybindings/index.js';
+import { inTmux } from '../../../core/runtime/placement-tmux.js';
+import { RefAwareAutocompleteProvider } from '../input/ref-autocomplete.js';
+import { CANVAS_SLASH_COMMANDS, locallyConsumedCommandNames, slashCommandList } from '../slash/dispatch.js';
+import { loadedCommandPreview } from '../slash/prompt-preview.js';
+import { openReadonlyPopup } from './readonly-popup.js';
+export function buildAttachAutocompleteProvider(cwd, fdPath, commands, capabilities, createProvider = (items, cwd, path) => new CombinedAutocompleteProvider([...items], cwd, path)) {
+    return createProvider([...slashCommandList(commands, capabilities)], cwd, fdPath);
+}
+export function createMemoryRefRefreshCoordinator(setMemoryRefs, request) {
+    let epoch = 0;
+    return {
+        reset: () => {
+            const myEpoch = ++epoch;
+            setMemoryRefs([], []);
+            void request({ type: 'list_memory_refs' })
+                .then((data) => {
+                if (myEpoch !== epoch)
+                    return; // a newer reset (reconnect/reload) superseded this one
+                if (data.kind !== 'list_memory_refs')
+                    return; // malformed/mismatched reply — stay empty
+                setMemoryRefs(data.refs, data.engineLeadingCommandNames);
+            })
+                .catch(() => {
+                // Timeout / rejected request — the immediate clear above already left
+                // the inventory empty; no retry, no local fallback.
+            });
+        },
+    };
+}
+/** Owns everything the editor can complete against — the merged slash-command
+ *  list, the loaded-command preview, the broker's raw command metadata, and the
+ *  memory-ref inventory — plus the popup that inspects the loaded template.
+ *  Input wiring supplies the session capability before first render, seeding
+ *  builtins-only autocomplete before the broker's first `get_commands` ack. */
+export function createEditorInventory(ctx, capabilities, hooks) {
+    const { meta, socket, tui, editor } = ctx;
+    let commands = [];
+    let commandPreview;
+    // The broker's RAW command metadata (`undefined` until the first get_commands
+    // ack — kept distinct from `[]`, same undefined-vs-empty contract
+    // `buildAttachAutocompleteProvider` already relies on) and the broker's raw
+    // memory-ref inventory, kept SEPARATE from each other and from the merged
+    // `commands` preview list above: a late reply to one inventory must rebuild
+    // the provider/highlight sets from the CURRENT value of the other, never
+    // drop it. `syncEditorInventories` is the single place that reads both.
+    let brokerCommands;
+    let memoryRefs = [];
+    // The broker's `engineLeadingCommandNames` from the latest `list_memory_refs`
+    // reply — leading tokens the ENGINE independently consumes, kept separate
+    // from the viewer-local
+    // `locallyConsumedCommandNames()` set and fed to the editor's untrimmed
+    // engine-suppression rule via `setEngineCommandNames`.
+    let engineLeadingCommandNames = [];
+    const commandInspectHint = () => {
+        const bindings = hooks.bindings();
+        return bindings.gestures('crtr.attach.command.inspect').length > 0
+            ? `${formatBinding(bindings, 'crtr.attach.command.inspect')} inspect`
+            : 'inspect binding disabled';
+    };
+    const syncCommandPreview = (text) => {
+        commandPreview = loadedCommandPreview(text, commands);
+        editor.loadedCommand = commandPreview === undefined
+            ? undefined
+            : { name: commandPreview.name, content: commandPreview.content, inspectHint: commandInspectHint() };
+    };
+    // Atomically rebuild the editor's provider/highlight state from whatever
+    // command + ref inventory is CURRENTLY known — the one seam `setCommands` and
+    // `setMemoryRefs` both call, so a command-only or ref-only response can never
+    // rebuild the provider having silently dropped the other inventory. This
+    // module owns command metadata, ref metadata, provider rebuild, and editor
+    // highlight sets in one place. Command-only
+    // autocomplete is unchanged: `RefAwareAutocompleteProvider` fully delegates
+    // leading-slash and every non-ref context to the wrapped command provider, so
+    // refs never enter command completion or the loaded-command preview (which
+    // reads only `commands`, never `memoryRefs`).
+    const syncEditorInventories = () => {
+        const commandProvider = buildAttachAutocompleteProvider(meta.cwd, hooks.fdPath, brokerCommands, capabilities);
+        editor.setAutocompleteProvider(new RefAwareAutocompleteProvider(memoryRefs, commandProvider, hooks.frecency));
+        editor.setResolvedRefNames(memoryRefs.map((ref) => ref.name));
+        // Two independent suppression inventories: the viewer-local
+        // set (everything `dispatchSlashCommand` handles entirely locally, trimmed
+        // rule) and the broker's own `engineLeadingCommandNames` (untrimmed rule) —
+        // never the merged display/completion list `slashCommandList` returns.
+        editor.setLocalCommandNames(locallyConsumedCommandNames());
+        editor.setEngineCommandNames(engineLeadingCommandNames);
+        syncCommandPreview(editor.getText());
+    };
+    // Slash-command autocomplete starts with builtins + native canvas commands,
+    // then incorporates engine commands and prompt templates from get_commands.
+    // Template bodies stay alongside their autocomplete metadata so the editor can
+    // reveal the exact expanded payload before the user submits it. Responsible
+    // ONLY for the command side of the inventory — always ends with
+    // `syncEditorInventories()` so a command update never rebuilds the provider
+    // without the current ref inventory.
+    const setCommands = (next) => {
+        brokerCommands = next;
+        // Viewer-owned commands are intercepted before anything reaches the broker,
+        // so they must lead preview lookup too. Their lack of expansion metadata
+        // deliberately suppresses any shadowed extension/template disclosure.
+        commands = [
+            ...CANVAS_SLASH_COMMANDS.map((command) => ({ ...command, source: 'builtin' })),
+            ...(next ?? []),
+        ];
+        syncEditorInventories();
+    };
+    // Responsible ONLY for the ref side of the inventory — mirrors `setCommands`,
+    // always ending with the same `syncEditorInventories()` seam. Ref arrival
+    // must repaint decoration on already-typed prose immediately (the design's
+    // "gains decoration immediately" contract), so this is the one place that
+    // requests a render after an inventory change.
+    const setMemoryRefs = (next, nextEngineLeadingCommandNames) => {
+        memoryRefs = next;
+        engineLeadingCommandNames = nextEngineLeadingCommandNames;
+        syncEditorInventories();
+        tui.requestRender();
+    };
+    // The correlated ref-inventory lifecycle (design: inline memory references,
+    // T3 terminal integration). `socket.request` is the same observer-safe
+    // read-op channel local and remote attach already share, so this is
+    // transport-agnostic for free. Reset from `welcome` and a successful
+    // `/reload` — see the frames wiring in `runAttach`.
+    const memoryRefRefresh = createMemoryRefRefreshCoordinator(setMemoryRefs, (f) => socket.request(f));
+    const inspectLoadedCommand = () => {
+        if (commandPreview === undefined) {
+            hooks.setNotice('No prompt-template command is loaded in the editor');
+            return;
+        }
+        if (!inTmux()) {
+            hooks.setNotice('Command inspection requires tmux');
+            return;
+        }
+        openReadonlyPopup({
+            name: commandPreview.name,
+            content: `# /${commandPreview.name}\n\nInvocation: \`${commandPreview.invocation.replaceAll('`', '\\`')}\`\n\n${commandPreview.content}\n`,
+            noNvim: 'nvim is required to inspect loaded commands. Install Neovim and retry.',
+        });
+    };
+    return {
+        setCommands,
+        resetMemoryRefs: () => memoryRefRefresh.reset(),
+        syncCommandPreview,
+        inspectLoadedCommand,
+    };
+}

package/dist/clients/attach/session/file-links.d.ts

@@ -0,0 +1,22 @@
+/** A local file requested through iTerm Semantic History. */
+export interface FileOpenInput {
+    file: string | undefined;
+    remaining: string;
+}
+/**
+ * Strip the private iTerm Semantic History input and return its local path.
+ * iTerm expands `\\1` as a shell-escaped word, so decode that representation
+ * without ever evaluating it as shell input.
+ */
+export declare function extractFileOpenInput(data: string): FileOpenInput | undefined;
+export type LinkedFileOpenResult = 'opened' | 'missing' | 'no_nvim' | 'failed';
+/** Replace this local viewer pane with Neovim, then reattach it when Neovim exits. */
+export declare function openLinkedFileInPane(opts: {
+    file: string;
+    pane: string;
+    cwd: string;
+    nodeId: string;
+    observer: boolean;
+    /** Clear viewer-local pane identity immediately before the pane runs Neovim. */
+    beforeRespawn: () => void;
+}): LinkedFileOpenResult;

package/dist/clients/attach/session/file-links.js

@@ -0,0 +1,73 @@
+// session/file-links.ts — iTerm Semantic History file-open bridge.
+//
+// iTerm sends the clicked path through a private input sequence. The viewer
+// validates it, replaces its pane with Neovim, then reattaches after exit.
+import { existsSync } from 'node:fs';
+import { nvimAvailable, nvimShellCommand } from '../../../core/nvim-launch.js';
+import { respawnPaneInBackground, shellQuote, viewerSplitEnv } from '../../../core/runtime/placement-tmux.js';
+const FILE_OPEN_PREFIX = '\x1b_crtr-file-open;';
+const STRING_TERMINATOR = '\x1b\\';
+/**
+ * Strip the private iTerm Semantic History input and return its local path.
+ * iTerm expands `\\1` as a shell-escaped word, so decode that representation
+ * without ever evaluating it as shell input.
+ */
+export function extractFileOpenInput(data) {
+    const start = data.indexOf(FILE_OPEN_PREFIX);
+    if (start === -1)
+        return undefined;
+    const pathStart = start + FILE_OPEN_PREFIX.length;
+    const end = data.indexOf(STRING_TERMINATOR, pathStart);
+    if (end === -1)
+        return undefined;
+    const file = decodeShellEscapedPath(data.slice(pathStart, end));
+    return { file, remaining: data.slice(0, start) + data.slice(end + STRING_TERMINATOR.length) };
+}
+function decodeShellEscapedPath(value) {
+    const decoded = value.startsWith("'") ? decodeSingleQuotedPath(value) : decodeBackslashPath(value);
+    return decoded !== undefined && decoded.startsWith('/') && !/[\x00-\x1f\x7f]/.test(decoded) ? decoded : undefined;
+}
+function decodeSingleQuotedPath(value) {
+    let result = '';
+    let index = 1;
+    while (true) {
+        const end = value.indexOf("'", index);
+        if (end === -1)
+            return undefined;
+        result += value.slice(index, end);
+        index = end + 1;
+        if (index === value.length)
+            return result;
+        if (value.slice(index, index + 3) !== "\\''")
+            return undefined;
+        result += "'";
+        index += 3;
+    }
+}
+function decodeBackslashPath(value) {
+    let result = '';
+    for (let index = 0; index < value.length; index++) {
+        if (value[index] !== '\\') {
+            result += value[index];
+            continue;
+        }
+        const escaped = value[++index];
+        if (escaped === undefined)
+            return undefined;
+        result += escaped;
+    }
+    return result;
+}
+/** Replace this local viewer pane with Neovim, then reattach it when Neovim exits. */
+export function openLinkedFileInPane(opts) {
+    if (!existsSync(opts.file))
+        return 'missing';
+    // Checked before the pane is handed over: respawning without nvim would flash
+    // `command not found` and drop straight back into the viewer.
+    if (!nvimAvailable())
+        return 'no_nvim';
+    const attach = `crtr surface attach to ${shellQuote(opts.nodeId)}${opts.observer ? ' --observer' : ''}`;
+    const command = `${nvimShellCommand('edit', [opts.file])} || :; exec ${attach}`;
+    opts.beforeRespawn();
+    return respawnPaneInBackground({ pane: opts.pane, cwd: opts.cwd, env: viewerSplitEnv(), command }) ? 'opened' : 'failed';
+}

package/dist/clients/attach/session/focus-events.d.ts

@@ -0,0 +1,4 @@
+export declare const FOCUS_REPORTING_ON = "\u001B[?1004h";
+export declare const FOCUS_REPORTING_OFF = "\u001B[?1004l";
+export declare const FOCUS_IN = "\u001B[I";
+export declare const FOCUS_OUT = "\u001B[O";

package/dist/clients/attach/session/focus-events.js

@@ -0,0 +1,12 @@
+// session/focus-events.ts — terminal focus reporting (DECSET 1004).
+//
+// The terminal (or tmux, per pane, with `focus-events on`) sends FOCUS_IN /
+// FOCUS_OUT as the viewer gains and loses focus. The viewer enables reporting
+// after `tui.start()`, reads the events in its global input listener to drive
+// the editor's hollow cursor, and DISABLES reporting again during terminal
+// restore — so the enable and the disable live in different modules and share
+// these constants rather than re-spelling the escape sequences.
+export const FOCUS_REPORTING_ON = '\x1b[?1004h';
+export const FOCUS_REPORTING_OFF = '\x1b[?1004l';
+export const FOCUS_IN = '\x1b[I';
+export const FOCUS_OUT = '\x1b[O';

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

@@ -0,0 +1,46 @@
+import { type Component, type Terminal } from '@earendil-works/pi-tui';
+import type { TranscriptViewport } from '../render/viewport.js';
+export declare const MIN_TRANSCRIPT_ROWS = 3;
+export declare const HEADER_MAX_ROWS = 12;
+export declare const EDITOR_MIN_ROWS = 1;
+export declare const STATUS_ROWS = 1;
+export declare const SEARCH_ROWS = 1;
+export type BottomSlot = 'queued' | 'aboveWidgets' | 'activity' | 'cockpitPadding' | 'editor' | 'pickerPanel' | 'belowWidgets' | 'reports' | 'search' | 'footer';
+/** Crop `lines` to `alloc` rows, guaranteeing the CURSOR_MARKER row survives
+ * (§2.1). No marker → the tail is kept. */
+export declare function cropAroundCursor(lines: readonly string[], alloc: number): string[];
+export interface ViewerFrameParts {
+    /** Rendered above the transcript; 0 rows when empty. */
+    header: Component;
+    /** The inline ticket page, directly beneath the header — the expanded form
+     *  of the strip's notification row. It grows downward to whatever the page
+     *  needs, squeezing the transcript to zero before the cockpit gives a row. */
+    ticket: Component;
+    viewport: TranscriptViewport;
+    /** The bottom slots, in VISUAL order, tagged with their allocation identity
+     * so the allocator can apply the §2.1 priority table. */
+    bottom: readonly {
+        slot: BottomSlot;
+        component: Component;
+    }[];
+}
+/** The TUI's ONE child. Renders exactly `terminal.rows` lines, every frame. */
+export declare class ViewerFrame implements Component {
+    private readonly terminal;
+    private readonly parts;
+    private viewportRows;
+    private lastFrame;
+    private overlay;
+    constructor(terminal: Terminal, parts: ViewerFrameParts);
+    render(width: number): string[];
+    /** Paint attributes over the composed frame — mouse selection highlight. The
+     *  overlay may restyle rows but must return the same number of them. */
+    setOverlay(overlay: (frame: readonly string[]) => string[]): void;
+    /** The physical rows returned by the most recent render, before any overlay. */
+    lastRenderedFrame(): readonly string[];
+    invalidate(): void;
+    /** Rows the transcript viewport got in the last frame — the page size. */
+    lastViewportRows(): number;
+    /** Retain exactly one editor marker if the focused editor rendered one. */
+    private ensureCursorMarker;
+}

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

@@ -0,0 +1,214 @@
+// session/frame.ts — the attach viewer's single full-pane TUI child.
+//
+// The frame owns the pane rectangle: transcript rows are virtualized between a
+// bounded recap header and a cursor-first cockpit. Nothing mounted beneath this
+// component may reach pi-tui as a separate child, or it can reintroduce terminal
+// scrollback and lose the editor's hardware cursor.
+import { CURSOR_MARKER } from '@earendil-works/pi-tui';
+import { reportInvariant as report } from './invariant.js';
+export const MIN_TRANSCRIPT_ROWS = 3;
+export const HEADER_MAX_ROWS = 12;
+export const EDITOR_MIN_ROWS = 1;
+export const STATUS_ROWS = 1;
+export const SEARCH_ROWS = 1;
+/** Crop `lines` to `alloc` rows, guaranteeing the CURSOR_MARKER row survives
+ * (§2.1). No marker → the tail is kept. */
+export function cropAroundCursor(lines, alloc) {
+    const rows = Math.max(0, Math.floor(alloc));
+    if (lines.length <= rows)
+        return lines.slice();
+    if (rows === 0)
+        return [];
+    const marker = lines.findIndex((line) => line.includes(CURSOR_MARKER));
+    if (marker === -1)
+        return lines.slice(-rows);
+    const start = clamp(marker - Math.floor((rows - 1) / 2), 0, lines.length - rows);
+    const cropped = lines.slice(start, start + rows);
+    if (!cropped.some((line) => line.includes(CURSOR_MARKER))) {
+        // This should be unreachable for a positive allocation. Keep the cursor
+        // row rather than silently making pi-tui lose the hardware cursor.
+        reportInvariant('cursor crop discarded CURSOR_MARKER');
+        return [lines[marker]];
+    }
+    return cropped;
+}
+const SLOT_PRIORITY = [
+    'activity',
+    'queued',
+    'aboveWidgets',
+    'belowWidgets',
+    'reports',
+    'cockpitPadding',
+];
+const SLOT_VISUAL_ORDER = [
+    'cockpitPadding',
+    'activity',
+    'aboveWidgets',
+    'queued',
+    'editor',
+    'pickerPanel',
+    'belowWidgets',
+    'reports',
+    'search',
+    'footer',
+];
+/** The TUI's ONE child. Renders exactly `terminal.rows` lines, every frame. */
+export class ViewerFrame {
+    terminal;
+    parts;
+    viewportRows = 0;
+    lastFrame = [];
+    overlay;
+    constructor(terminal, parts) {
+        this.terminal = terminal;
+        this.parts = parts;
+    }
+    render(width) {
+        const rows = Math.max(0, this.terminal.rows);
+        const rendered = new Map();
+        for (const { slot, component } of this.parts.bottom)
+            rendered.set(slot, component.render(width));
+        const allocations = new Map();
+        const linesFor = (slot) => rendered.get(slot) ?? [];
+        const allocate = (slot, lines) => {
+            allocations.set(slot, lines);
+        };
+        let remaining = Math.min(rows, Math.max(EDITOR_MIN_ROWS + STATUS_ROWS, rows - MIN_TRANSCRIPT_ROWS));
+        const footerLines = linesFor('footer');
+        const statusAlloc = footerLines.length > 0 && remaining > EDITOR_MIN_ROWS ? STATUS_ROWS : 0;
+        allocate('footer', statusAlloc === 0 ? [] : footerLines.slice(-statusAlloc));
+        remaining -= statusAlloc;
+        // Search sits with the status line rather than in the priority table: while
+        // it is up it owns typed input, so a frame that drops it would leave the
+        // user typing into an invisible mode.
+        const searchLines = linesFor('search');
+        const searchAlloc = searchLines.length > 0 && remaining > EDITOR_MIN_ROWS ? SEARCH_ROWS : 0;
+        allocate('search', searchAlloc === 0 ? [] : searchLines.slice(-searchAlloc));
+        remaining -= searchAlloc;
+        const pickerLines = linesFor('pickerPanel');
+        const pickerReserve = pickerLines.length === 0 ? 0 : Math.min(pickerLines.length, Math.floor(remaining / 2));
+        const editorLines = linesFor('editor');
+        const editorAlloc = clamp(editorLines.length, EDITOR_MIN_ROWS, Math.max(EDITOR_MIN_ROWS, remaining - pickerReserve));
+        const editorSlice = cropAroundCursor(editorLines, editorAlloc);
+        allocate('editor', editorSlice);
+        remaining -= editorAlloc;
+        const pickerAlloc = Math.min(pickerLines.length, remaining);
+        allocate('pickerPanel', pickerLines.slice(0, pickerAlloc));
+        remaining -= pickerAlloc;
+        for (const slot of SLOT_PRIORITY) {
+            const lines = linesFor(slot);
+            if (lines.length <= remaining) {
+                allocate(slot, lines);
+                remaining -= lines.length;
+            }
+            else {
+                allocate(slot, []);
+            }
+        }
+        const bottomLines = SLOT_VISUAL_ORDER.flatMap((slot) => allocations.get(slot) ?? []);
+        const editorBottomOffset = SLOT_VISUAL_ORDER
+            .slice(0, SLOT_VISUAL_ORDER.indexOf('editor'))
+            .reduce((count, slot) => count + (allocations.get(slot)?.length ?? 0), 0);
+        let headerLines = this.parts.header.render(width).slice(0, HEADER_MAX_ROWS);
+        if (rows - bottomLines.length - headerLines.length < MIN_TRANSCRIPT_ROWS)
+            headerLines = [];
+        // The ticket page takes every row the header and cockpit left, before the
+        // transcript sees any — a tall page legitimately drives the viewport to 0.
+        const ticketAll = this.parts.ticket.render(width);
+        const ticketLines = ticketAll.slice(0, Math.max(0, rows - headerLines.length - bottomLines.length));
+        const viewportRows = Math.max(0, rows - headerLines.length - ticketLines.length - bottomLines.length);
+        this.viewportRows = viewportRows;
+        let viewportLines = this.parts.viewport.renderSlice(width, viewportRows);
+        let frame = [...headerLines, ...ticketLines, ...viewportLines, ...bottomLines];
+        // A misbehaving viewport is repaired in its own region only: transcript
+        // padding goes directly beneath the header, while excess drops from its top.
+        // The cockpit, including the editor's marker row, is never sliced here.
+        if (frame.length !== rows) {
+            reportInvariant(`frame rendered ${frame.length} rows; expected ${rows}`);
+            viewportLines = fitTranscript(viewportLines, viewportRows);
+            frame = [...headerLines, ...ticketLines, ...viewportLines, ...bottomLines];
+        }
+        if (frame.length !== rows)
+            reportInvariant(`frame correction rendered ${frame.length} rows; expected ${rows}`);
+        const finalFrame = this.ensureCursorMarker(frame, editorLines, editorSlice, editorBottomOffset, bottomLines.length, rows);
+        // This is the exact physical screen content used for OSC-8 mouse hit tests
+        // and for the text a mouse selection copies, so it is kept BEFORE the
+        // overlay paints attributes over it. Keep a copy because terminal rendering
+        // is allowed to retain the returned array.
+        this.lastFrame = finalFrame.slice();
+        if (this.overlay === undefined)
+            return finalFrame;
+        const painted = this.overlay(finalFrame);
+        if (painted.length !== finalFrame.length) {
+            reportInvariant(`frame overlay returned ${painted.length} rows; expected ${finalFrame.length}`);
+            return finalFrame;
+        }
+        return painted;
+    }
+    /** Paint attributes over the composed frame — mouse selection highlight. The
+     *  overlay may restyle rows but must return the same number of them. */
+    setOverlay(overlay) {
+        this.overlay = overlay;
+    }
+    /** The physical rows returned by the most recent render, before any overlay. */
+    lastRenderedFrame() {
+        return this.lastFrame;
+    }
+    invalidate() {
+        this.parts.header.invalidate();
+        this.parts.ticket.invalidate();
+        for (const { component } of this.parts.bottom)
+            component.invalidate();
+        this.parts.viewport.invalidate();
+    }
+    /** Rows the transcript viewport got in the last frame — the page size. */
+    lastViewportRows() {
+        return this.viewportRows;
+    }
+    /** Retain exactly one editor marker if the focused editor rendered one. */
+    ensureCursorMarker(frame, editorLines, editorSlice, editorBottomOffset, bottomRows, rows) {
+        const editorMarker = editorLines.find((line) => line.includes(CURSOR_MARKER));
+        const markerCount = countMarkers(frame);
+        if (editorMarker === undefined ? markerCount <= 1 : markerCount === 1)
+            return frame;
+        reportInvariant(editorMarker === undefined
+            ? `frame contains ${markerCount} CURSOR_MARKER sequences without one from the editor`
+            : `frame contains ${markerCount} CURSOR_MARKER sequences; expected exactly one`);
+        const repaired = frame.map(stripCursorMarkers);
+        if (editorMarker === undefined)
+            return repaired;
+        const markerLine = editorSlice.findIndex((line) => line.includes(CURSOR_MARKER));
+        const frameIndex = rows - bottomRows + editorBottomOffset + markerLine;
+        if (markerLine === -1 || frameIndex < 0 || frameIndex >= repaired.length) {
+            reportInvariant('unable to restore editor CURSOR_MARKER in composed frame');
+            return repaired;
+        }
+        const markerAt = editorSlice[markerLine].indexOf(CURSOR_MARKER);
+        const line = repaired[frameIndex];
+        repaired[frameIndex] = `${line.slice(0, markerAt)}${CURSOR_MARKER}${line.slice(markerAt)}`;
+        return repaired;
+    }
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+/** Correct only the viewport allocation: top-pad short content or retain its tail. */
+function fitTranscript(lines, rows) {
+    if (rows === 0)
+        return [];
+    if (lines.length === rows)
+        return lines.slice();
+    if (lines.length > rows)
+        return lines.slice(-rows);
+    return [...Array(rows - lines.length).fill(''), ...lines];
+}
+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 must surface in development without taking down an attached pane. */
+function reportInvariant(message) {
+    report('attach-frame', message);
+}

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

@@ -0,0 +1,51 @@
+import type { AgentSessionEvent } from '@earendil-works/pi-coding-agent';
+import type { BrokerToClient, RpcExtensionUIRequest } from '../../../core/runtime/broker-protocol.js';
+import { type PreviewableCommand } from '../slash/prompt-preview.js';
+import type { AttachSession } from './context.js';
+import type { ToolGroupSummary } from '../../../shared/tool-groups.js';
+import type { TurnReply } from '../../../shared/turn-replies.js';
+export interface FrameEffects {
+    /** Fold the frame through the shared reducer and repaint whatever slice of
+     *  chrome changed. Runs FIRST for every frame, before any case below. */
+    foldState: (frame: BrokerToClient) => void;
+    /** The transcript. Only the writes this switch performs are listed, so a
+     *  reader can see the whole render coupling from the type. */
+    chat: {
+        applySnapshot: (snapshot: Extract<BrokerToClient, {
+            type: 'welcome';
+        }>['snapshot']) => Promise<void> | void;
+        handleEvent: (event: AgentSessionEvent) => void;
+        setWorkingActivity: (activity: string) => void;
+        bashStart: (command: string, excludeFromContext?: boolean) => void;
+        bashOutput: (chunk: string) => void;
+        bashEnd: (frame: Extract<BrokerToClient, {
+            type: 'bash_end';
+        }>) => void;
+        applyToolGroupSummary: (key: string, summary: ToolGroupSummary) => void;
+        applyTurnReply: (key: string, reply: TurnReply) => void;
+        showError: (message: string) => void;
+    };
+    setNotice: (message: string) => void;
+    /** Repaint the status line — for the frames whose footer effect is NOT
+     *  derivable from session state (the on-disk bash-job scan). */
+    renderFooter: () => void;
+    /** Put the editor's text back (tree navigation restores it for re-editing). */
+    setEditorText: (text: string) => void;
+    /** Show/dismiss a blocking extension dialog. */
+    attachDialog: (req: RpcExtensionUIRequest) => void;
+    dismissDialog: (id: string) => void;
+    /** Replace the command inventory (`undefined` clears it pending a fresh ack). */
+    setCommands: (next?: ReadonlyArray<PreviewableCommand>) => void;
+    /** Clear + refetch the memory-ref inventory, superseding anything in flight. */
+    resetMemoryRefs: () => void;
+    /** Re-read the node's persona/lifecycle/icon from the canvas. */
+    refreshNodeIdentity: () => void;
+    /** Re-resolve user keybindings after a `/reload` (and re-install the tmux side). */
+    reloadBindings: () => void;
+    /** Schedule tmux binding reconciliation after a welcome has been handled. */
+    onWelcome?: () => void;
+    /** "sonnet medium" — the label a model or thinking change announces. */
+    modelThinkingLabel: () => string | undefined;
+}
+/** Build the single `frame` handler the socket is wired to. */
+export declare function createFrameHandler(ctx: Pick<AttachSession, 'socket'>, fx: FrameEffects): (frame: BrokerToClient) => void;