@north-light/crouter 0.3.170 → 0.3.172

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

@@ -0,0 +1,176 @@
+// 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;
+/** 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',
+    'footer',
+];
+/** The TUI's ONE child. Renders exactly `terminal.rows` lines, every frame. */
+export class ViewerFrame {
+    terminal;
+    parts;
+    viewportRows = 0;
+    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;
+        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 = [];
+        const viewportRows = Math.max(0, rows - headerLines.length - bottomLines.length);
+        this.viewportRows = viewportRows;
+        let viewportLines = this.parts.viewport.renderSlice(width, viewportRows);
+        let frame = [...headerLines, ...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, ...viewportLines, ...bottomLines];
+        }
+        if (frame.length !== rows)
+            reportInvariant(`frame correction rendered ${frame.length} rows; expected ${rows}`);
+        return this.ensureCursorMarker(frame, editorLines, editorSlice, editorBottomOffset, bottomLines.length, rows);
+    }
+    invalidate() {
+        this.parts.header.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

@@ -2,6 +2,7 @@ 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';
 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. */
@@ -13,11 +14,13 @@ export interface FrameEffects {
             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;
     };
     setNotice: (message: string) => void;
     /** Repaint the status line — for the frames whose footer effect is NOT
@@ -32,7 +35,7 @@ export interface FrameEffects {
     setCommands: (next?: ReadonlyArray<PreviewableCommand>) => void;
     /** Clear + refetch the memory-ref inventory, superseding anything in flight. */
     resetMemoryRefs: () => void;
-    /** Re-read the node's persona/lifecycle from the canvas. */
+    /** 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;

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

@@ -81,7 +81,14 @@ export function createFrameHandler(ctx, fx) {
     /** A relayed AgentSessionEvent — everything not in the switch below. */
     const handleSessionEvent = (event) => {
         fx.chat.handleEvent(event);
-        if (event.type === 'thinking_level_changed') {
+        if (event.type === 'session_info_changed') {
+            // Recap title regeneration persists a new canvas icon before changing the
+            // pi session name. Refreshing here lets the identity owner's onChanged
+            // repaint normalize that name with the matching icon instead of keeping
+            // the icon cached when this viewer attached.
+            fx.refreshNodeIdentity();
+        }
+        else if (event.type === 'thinking_level_changed') {
             fx.setNotice(fx.modelThinkingLabel() ?? `Thinking level: ${event.level}`);
         }
         else if (event.type === 'tool_execution_start' || event.type === 'tool_execution_end') {
@@ -127,6 +134,12 @@ export function createFrameHandler(ctx, fx) {
                     fx.attachDialog(frame.pending_dialog);
                 break;
             }
+            case 'tool_group_summary':
+                fx.chat.applyToolGroupSummary(frame.key, frame.summary);
+                break;
+            case 'working_activity':
+                fx.chat.setWorkingActivity(frame.activity);
+                break;
             case 'model_changed': {
                 // The broker's own post-set_model/cycle_model announcement (pi emits no
                 // engine event for a model switch) already moved the footer's model

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

@@ -1,11 +1,12 @@
 // session/identity.ts — the OWNER of the attached node's canvas identity
-// (kind/mode/lifecycle), which the editor's context badge and lifecycle chip
+// (kind/mode/lifecycle/icon), which the editor's context badge and title chip
 // render from.
 //
 // It is the one connection fact that is NOT fixed at connect time: a remote
 // attach starts without an identity and fills it in from the relayed canvas,
-// and a fresh broker can report a new persona or lifecycle. Hence an owner with
-// a refresh verb rather than a value on `AttachSession`.
+// and a fresh broker or regenerated title can reflect a new persona, lifecycle,
+// or task icon. Hence an owner with a refresh verb rather than a value on
+// `AttachSession`.
 export function createNodeIdentity(ctx, initial, hooks) {
     let identity = initial;
     return {

package/dist/clients/attach/session/input-wiring.d.ts

@@ -1,5 +1,7 @@
 import { InputController } from '../input/controller.js';
+import type { ToolDisplayToggle } from '../render/chat-view.js';
 import type { KeybindingsManager } from '@earendil-works/pi-tui';
+import type { CopyTarget } from '../render/transcript-copy.js';
 import type { AttachSession } from './context.js';
 /** What the input layer needs from the rest of the session. Everything here is
  *  a getter or a command — never a value — so nothing can go stale. */
@@ -11,10 +13,10 @@ export interface InputWiringHooks {
     agentDir: () => string | undefined;
     /** True while the reconnect supervisor has classified the node as dormant. */
     isDormant: () => boolean;
-    /** The last assistant message, for `/copy` (ChatView holds it). */
-    lastAssistantText: () => string | undefined;
-    /** Ctrl+O — flip global tool-output expansion; returns the new state. */
-    toggleToolsExpanded: () => boolean;
+    /** Copy a viewer-local transcript target and surface its confirmation. */
+    copyTarget: (target: CopyTarget) => void;
+    /** Ctrl+O — toggles either collapsed summaries or tool-output expansion. */
+    toggleToolsExpanded: () => ToolDisplayToggle;
     /** `/fold-tools` — flip the fold-finished-tool-calls view setting; returns the
      *  new state. */
     toggleFoldTools: () => boolean;
@@ -22,6 +24,12 @@ export interface InputWiringHooks {
     toggleThinking: () => boolean;
     /** `/graph` and the graph keybinding. */
     toggleGraph: () => void;
+    /** `/inbox` and the inbox attach control. */
+    toggleInbox: () => void;
+    /** `/hotkeys` and the help keybinding. */
+    toggleHelp: () => void;
+    /** `/mouse` — flip mouse wheel reporting and return the new state. */
+    toggleMouse: () => boolean;
     /** `/node-metadata` — open the viewer-owned Inspector dossier popup. */
     openNodeMetadata: () => void;
     /** `/quit` — detach this viewer; the engine keeps running. Must tear down
@@ -29,6 +37,8 @@ export interface InputWiringHooks {
     quit: () => void;
     /** `/color` — recolor the editor's name chip (`null` clears to default). */
     setChipColor: (color: string | null) => void;
+    /** A prompt or steer was accepted from the editor. */
+    onPromptSent: () => void;
 }
 /** Build the viewer's InputController with every hook answered. */
 export declare function createInputController(ctx: Pick<AttachSession, 'nodeId' | 'remote' | 'role' | 'meta' | 'socket' | 'tui' | 'editor' | 'containers'>, km: KeybindingsManager, hooks: InputWiringHooks): InputController;

package/dist/clients/attach/session/input-wiring.js

@@ -13,7 +13,6 @@
 // can only be closed over from inside).
 import { InputController } from '../input/controller.js';
 import { cliClient } from '../../../commands/api-client.js';
-import { writeClipboardText } from '../../../core/clipboard-text.js';
 import { buildLoginPicker, buildLogoutPicker } from '../overlays/auth.js';
 import { defaultAgentDir } from '../config.js';
 /** Build the viewer's InputController with every hook answered. */
@@ -25,16 +24,6 @@ export function createInputController(ctx, km, hooks) {
     // mutate. Every mutating hook below is wired only when this is true; the
     // read-op channel (`onRequest`) and the read-only getters stay wired for all.
     const writable = !remote && role === 'controller';
-    // `/copy` — the last assistant message (ChatView keeps it current from both
-    // the welcome snapshot and the live stream) → the system clipboard.
-    const copyLastAssistant = () => {
-        const text = hooks.lastAssistantText();
-        if (!text) {
-            setNotice('Nothing to copy — no assistant message yet');
-            return;
-        }
-        setNotice(writeClipboardText(text) ? 'Copied last message to clipboard' : 'Copy failed — no clipboard tool found');
-    };
     // Auth pickers — viewer-local OAuth/API-key flows against the SAME auth.json
     // the broker uses (broker + viewer share a filesystem in the tmux-local attach
     // model), so they run entirely in this process and then tell the broker to
@@ -72,14 +61,27 @@ export function createInputController(ctx, km, hooks) {
         remote,
         role,
         onGraph: hooks.toggleGraph,
+        onInbox: hooks.toggleInbox,
+        onHelp: hooks.toggleHelp,
         onNodeMetadata: hooks.openNodeMetadata,
         onQuit: hooks.quit,
-        onCopy: copyLastAssistant,
+        onCopy: () => hooks.copyTarget('last-assistant'),
+        onCopyTarget: hooks.copyTarget,
+        onToggleMouse: () => {
+            const on = hooks.toggleMouse();
+            setNotice(on ? 'Mouse: wheel scrolling on' : 'Mouse: off — tmux drag-select and copy-mode restored');
+        },
         onColor: hooks.setChipColor,
+        onPromptSent: hooks.onPromptSent,
         // Global display toggles (Ctrl+O tools / Ctrl+T thinking) — pure render
         // state owned by ChatView, surfaced as a footer notice mirroring pi's
         // status line.
-        onToggleToolsExpand: () => setNotice(hooks.toggleToolsExpanded() ? 'Tool output: expanded' : 'Tool output: collapsed'),
+        onToggleToolsExpand: () => {
+            const result = hooks.toggleToolsExpanded();
+            setNotice(result.kind === 'summaries'
+                ? result.shown ? 'Tool calls: summarized' : 'Tool calls: shown'
+                : result.expanded ? 'Tool output: expanded' : 'Tool output: collapsed');
+        },
         onFoldTools: () => setNotice(hooks.toggleFoldTools()
             ? 'Finished tool calls: folded to one line'
             : 'Finished tool calls: shown in full'),

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

@@ -0,0 +1,9 @@
+/**
+ * The viewer owns the whole pane, so an invariant must never be written to the
+ * terminal: console output lands in the middle of the rendered frame, and a
+ * violation that repeats every render pushes real content into tmux scrollback
+ * — the exact corruption these invariants exist to catch. Records go to a
+ * rotating log beside the daemon's, one line per report:
+ * `~/.crouter/canvas/attach-invariants.log` (`CRTR_HOME`-relative).
+ */
+export declare function reportInvariant(scope: string, message: string): void;

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

@@ -0,0 +1,15 @@
+import { join } from 'node:path';
+import { crtrHome } from '../../../core/canvas/paths.js';
+import { appendRotatingRecord } from '../../../core/log.js';
+/**
+ * The viewer owns the whole pane, so an invariant must never be written to the
+ * terminal: console output lands in the middle of the rendered frame, and a
+ * violation that repeats every render pushes real content into tmux scrollback
+ * — the exact corruption these invariants exist to catch. Records go to a
+ * rotating log beside the daemon's, one line per report:
+ * `~/.crouter/canvas/attach-invariants.log` (`CRTR_HOME`-relative).
+ */
+export function reportInvariant(scope, message) {
+    const line = `${new Date().toISOString()} ${scope} ${message}`.replaceAll(/[\r\n]/g, ' ');
+    appendRotatingRecord(join(crtrHome(), 'attach-invariants.log'), line);
+}

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

@@ -1,4 +1,4 @@
-import { type AttachBindings } from './bindings.js';
+import { type AttachBindings, type AttachViewportActions } from './bindings.js';
 import type { AttachSession } from './context.js';
 export interface KeyHooks {
     /** The live binding snapshot — re-resolved by `/reload`, so read per key. */
@@ -7,18 +7,26 @@ export interface KeyHooks {
     detachHint: () => string | undefined;
     /** Terminal focus in/out — the roster owns the editor's cursor styling. */
     setPaneFocused: (focused: boolean) => void;
+    /** Whether a full-pane surface should receive all non-control input. */
+    hasExclusiveSurface: () => boolean;
+    /** Scroll actions for this session's transcript viewport. */
+    viewportActions: () => AttachViewportActions;
     /** The roster's chance at a chunk; true when it consumed it. */
     rosterHandleKey: (data: string) => boolean;
     setNotice: (message: string) => void;
     detach: () => void;
-    cycleMode: () => void;
     toggleGraph: () => void;
+    toggleHelp: () => void;
+    /** Toggle the mounted inbox surface. */
+    toggleInbox: () => void;
     cycleModelLadder: (direction: 'forward' | 'backward') => void;
     inspectLoadedCommand: () => void;
     /** The file-review chord — open the transcript-file picker + review surface. */
     openFileReview: () => void;
     /** Search the current node's local profile project files. */
     openProfileFiles: () => void;
+    /** Play the whip animation and interrupt the focused agent with a command. */
+    whip: () => void;
 }
 /** Install the listener; returns the remover, which teardown MUST call. */
 export declare function installGlobalKeys(ctx: Pick<AttachSession, 'tui' | 'editor'>, hooks: KeyHooks): () => void;

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

@@ -3,11 +3,12 @@
 // A TUI input listener fires BEFORE the focused component and before any dialog
 // overlay, so the configured attach actions work regardless of what has focus.
 // That privilege is also the hazard: anything consumed here never reaches the
-// editor. Only terminal focus reports, a private crouter control input, the
-// roster while it holds the cursor, and a configured crtr binding may claim a
-// chunk; each returns ordinary editor input untouched when it does not apply.
+// editor. Only terminal focus reports, a private crouter control input,
+// viewport scroll bindings while the editor has focus, the roster while it holds
+// the cursor, and a configured crtr binding may claim a chunk; each returns
+// ordinary editor input untouched when it does not apply.
 import { extractAttachControlInput } from '../../../core/keybindings/index.js';
-import { dispatchAttachAction, dispatchAttachBinding } from './bindings.js';
+import { dispatchAttachAction, dispatchAttachBinding, dispatchAttachViewportBinding, } from './bindings.js';
 import { FOCUS_IN, FOCUS_OUT } from './focus-events.js';
 /** Press the clear-or-detach binding twice inside this window to detach. */
 const CLEAR_OR_DETACH_MS = 1000;
@@ -29,14 +30,16 @@ export function installGlobalKeys(ctx, hooks) {
             hooks.setNotice(`Editor cleared — press ${hooks.detachHint()} again to detach`);
             tui.requestRender();
         },
-        'crtr.mode.cycle': hooks.cycleMode,
         'crtr.attach.graph.toggle': hooks.toggleGraph,
+        'crtr.attach.help.toggle': hooks.toggleHelp,
+        'crtr.attach.inbox.toggle': hooks.toggleInbox,
         // A plain broker frame, so this works locally and remotely alike; the broker gates observers on controller role.
         'crtr.attach.model-ladder.next': () => hooks.cycleModelLadder('forward'),
         'crtr.attach.model-ladder.previous': () => hooks.cycleModelLadder('backward'),
         'crtr.attach.command.inspect': hooks.inspectLoadedCommand,
         'crtr.attach.file-review': hooks.openFileReview,
         'crtr.attach.profile-files': hooks.openProfileFiles,
+        'crtr.attach.whip': hooks.whip,
     };
     return tui.addInputListener((data) => {
         // Terminal focus reporting (DECSET 1004, enabled after tui.start; tmux forwards it per-pane with `focus-events on`). Pane focus drives the editor's fake cursor — solid block focused, hollow outline blurred — so a wall of attach panes shows exactly which one keys go to. The events are stripped rather than blanket-consumed in case the chunk coalesced them with real keystrokes.
@@ -51,6 +54,11 @@ export function installGlobalKeys(ctx, hooks) {
             dispatchAttachAction(control.actionId, actions);
             return control.remaining.length > 0 ? { data: control.remaining } : { consume: true };
         }
+        if (hooks.hasExclusiveSurface())
+            return undefined;
+        // Let focused pickers and overlays retain their native page navigation.
+        if (editor.focused && dispatchAttachViewportBinding(hooks.bindings(), data, hooks.viewportActions()))
+            return { consume: true };
         // Inline subagent scroll+swap: once the editor hands off at its ↓ boundary, ↑/↓ move over the manager/report roster and Enter dives into a node. An inactive roster never intercepts editor input.
         if (hooks.rosterHandleKey(data))
             return { consume: true };

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

@@ -1,8 +1,9 @@
-import { ProcessTerminal, TUI } from '@earendil-works/pi-tui';
-import type { KeybindingsManager } from '@earendil-works/pi-tui';
+import { Container, type KeybindingsManager, type ProcessTerminal, type TUI } from '@earendil-works/pi-tui';
 import type { AttachPalette } from '../config.js';
 import { TitledEditor } from '../input/titled-editor.js';
+import type { TranscriptViewport } from '../render/viewport.js';
 import type { AttachContainers } from './context.js';
+import { ViewerFrame } from './frame.js';
 export interface AttachLayout {
     /** The process terminal behind the TUI — also the owner of the window title
      *  and the negotiated keyboard protocol, both of which the orchestrator uses. */
@@ -10,11 +11,12 @@ export interface AttachLayout {
     readonly tui: TUI;
     readonly containers: AttachContainers;
     readonly editor: TitledEditor;
-    /** Attach the containers to the TUI in render order and focus the editor.
-     *  Deferred to just before `tui.start()` so a signal landing mid-construction
-     *  cannot leave a half-mounted tree on screen. */
+    readonly frame: ViewerFrame;
+    /** Attach the single frame to the TUI and focus the editor. Deferred to just
+     *  before `tui.start()` so a signal landing mid-construction cannot leave a
+     *  half-mounted tree on screen. */
     mount(): void;
 }
-/** Build the TUI, its containers, and the editor. No behavior is wired here;
- *  the orchestrator owns every callback. */
-export declare function createLayout(pal: AttachPalette, km: KeybindingsManager): AttachLayout;
+/** Build the layout around the transcript viewport. The viewer creates the
+ * terminal and chat first because the viewport measures that chat source. */
+export declare function createLayout(procTerminal: ProcessTerminal, tui: TUI, chat: Container, activity: Container, pal: AttachPalette, km: KeybindingsManager, viewport: TranscriptViewport): AttachLayout;

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

@@ -1,56 +1,55 @@
-// session/layout.ts — the viewer's visual skeleton: the TUI, the nine
-// containers it paints into, and the editor.
+// session/layout.ts — the viewer's visual skeleton: its containers, editor,
+// and one full-pane frame.
 //
 // Pure construction. Nothing here reads session state, talks to the socket, or
 // handles a key — a reader chasing behavior can skip this file entirely, and a
 // reader asking "where does this line get painted?" needs only this one.
 //
-// The render order is the whole point of the file, and it is asserted in ONE
-// place (`mount`). Top to bottom: chat · rule · queued · above-editor extension
-// widgets · editor · picker panel · below-editor extension widgets · roster ·
-// status bar. pi-tui anchors the viewport to the cursor at the BOTTOM, so
-// everything except the scrolling chat lives in the bottom-anchored chrome
-// stack — a "topmost" badge would scroll off into scrollback the instant the
-// transcript exceeded one screen, which is why the mode badge and the two
-// canvas panels sit directly above the queued panel rather than at the top.
-import { Container, ProcessTerminal, TUI } from '@earendil-works/pi-tui';
-import { DynamicBorder, getSelectListTheme } from '@earendil-works/pi-coding-agent';
+// The render order is asserted in ONE place (`ViewerFrame`'s bottom list).
+// Top to bottom: pinned recap header · virtualized chat · cockpit padding · fixed activity ·
+// above-editor extension widgets · queued · editor · picker panel · below-editor
+// extension widgets · roster · status bar. The frame owns the pane rectangle,
+// so every region remains on screen and none can enter terminal scrollback.
+import { Container, Spacer } from '@earendil-works/pi-tui';
+import { getSelectListTheme } from '@earendil-works/pi-coding-agent';
 import { TitledEditor } from '../input/titled-editor.js';
-/** Build the TUI, its containers, and the editor. No behavior is wired here;
- *  the orchestrator owns every callback. */
-export function createLayout(pal, km) {
-    const procTerminal = new ProcessTerminal();
-    const tui = new TUI(procTerminal);
+import { ViewerFrame } from './frame.js';
+/** Build the layout around the transcript viewport. The viewer creates the
+ * terminal and chat first because the viewport measures that chat source. */
+export function createLayout(procTerminal, tui, chat, activity, pal, km, viewport) {
     const containers = {
-        chat: new Container(),
-        chrome: new Container(),
+        chat,
+        header: new Container(),
         aboveWidgets: new Container(),
+        activity,
         reports: new Container(),
         queued: new Container(),
         pickerPanel: new Container(),
         belowWidgets: new Container(),
         footer: new Container(),
     };
-    // The themed rule dividing the scrolling chat from the fixed chrome below it.
-    // `renderExtensionWidgets` re-derives this container's contents on every
-    // widget change (the passive recap replaces the rule), so this is the seed,
-    // not the sole writer.
-    containers.chrome.addChild(new DynamicBorder(pal.border));
     const editorTheme = { borderColor: pal.border, selectList: getSelectListTheme() };
     // TitledEditor paints the session name into its top border (solid-background
     // chip) and tracks a thinking-level border color, both set from live state.
     const editor = new TitledEditor(tui, editorTheme, km, { paddingX: 1 });
+    const frame = new ViewerFrame(procTerminal, {
+        header: containers.header,
+        viewport,
+        bottom: [
+            { slot: 'cockpitPadding', component: new Spacer(1) },
+            { slot: 'activity', component: containers.activity },
+            { slot: 'aboveWidgets', component: containers.aboveWidgets },
+            { slot: 'queued', component: containers.queued },
+            { slot: 'editor', component: editor },
+            { slot: 'pickerPanel', component: containers.pickerPanel },
+            { slot: 'belowWidgets', component: containers.belowWidgets },
+            { slot: 'reports', component: containers.reports },
+            { slot: 'footer', component: containers.footer },
+        ],
+    });
     const mount = () => {
-        tui.addChild(containers.chat);
-        tui.addChild(containers.chrome);
-        tui.addChild(containers.queued);
-        tui.addChild(containers.aboveWidgets);
-        tui.addChild(editor);
-        tui.addChild(containers.pickerPanel);
-        tui.addChild(containers.belowWidgets);
-        tui.addChild(containers.reports);
-        tui.addChild(containers.footer);
+        tui.addChild(frame);
         tui.setFocus(editor);
     };
-    return { procTerminal, tui, containers, editor, mount };
+    return { procTerminal, tui, containers, editor, frame, mount };
 }

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

@@ -0,0 +1,18 @@
+import type { TUI } from '@earendil-works/pi-tui';
+import type { MouseModeDefault } from '../../../types.js';
+/** Lines moved for one terminal wheel notch. */
+export declare const WHEEL_LINES = 3;
+export interface MouseReporting {
+    /** Reporting currently on. */
+    enabled(): boolean;
+    /** Flip, write the DECSET/DECRST, return the new state. */
+    toggle(): boolean;
+    /** Re-emit the current setting after another terminal program returned. */
+    reassert(): void;
+    /** Turn off unconditionally — teardown and process exit. */
+    disable(): void;
+    /** Install the SGR listener; returns the remover. */
+    install(tui: TUI, onWheel: (direction: 'up' | 'down', lines: number, column: number) => void): () => void;
+}
+/** Create per-viewer mouse reporting from the user's saved starting mode. */
+export declare function createMouseReporting(write: (data: string) => void, defaultMode: MouseModeDefault): MouseReporting;