@kolisachint/hoocode-tui 0.5.67 → 0.5.69

package/dist/tui.js

@@ -5,9 +5,11 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { performance } from "node:perf_hooks";
+import { stripVTControlCharacters } from "node:util";
 import { isKeyRelease, matchesKey } from "./keys.js";
+import { mouseSequenceLength, parseMouseEvent } from "./mouse.js";
 import { deleteKittyImage, getCapabilities, isImageLine, setCellDimensions } from "./terminal-image.js";
-import { extractSegments, normalizeTerminalOutput, sliceByColumn, sliceWithWidth, visibleWidth } from "./utils.js";
+import { extractSegments, normalizeTerminalOutput, sliceByColumn, sliceWithWidth, truncateToWidth, visibleWidth, } from "./utils.js";
 const KITTY_SEQUENCE_PREFIX = "\x1b_G";
 function extractKittyImageIds(line) {
     const sequenceStart = line.indexOf(KITTY_SEQUENCE_PREFIX);
@@ -47,6 +49,35 @@ export const CURSOR_MARKER = "\x1b_pi:c\x07";
  */
 const HIDE_CURSOR = "\x1b[?25l";
 const SHOW_CURSOR = "\x1b[?25h";
+/**
+ * How far one wheel notch moves the pinned view.
+ *
+ * Three lines is what terminals, pagers and browsers have settled on, and the
+ * agreement is the point: a wheel that moves a different distance here than in
+ * every other window is the kind of wrongness people feel without being able to
+ * name it.
+ */
+const WHEEL_LINES = 3;
+/**
+ * The indicator the tui draws when the app has not supplied its own.
+ *
+ * Reverse video rather than a colour, because this package has no theme and a
+ * hard-coded colour is the one thing guaranteed to clash with whichever one the
+ * app is using. It leads with the position — the question a pinned reader
+ * actually has — and spends what is left on the keys, dropping them on a narrow
+ * terminal rather than truncating the numbers.
+ */
+function defaultScrollStatus(status) {
+    const position = `${status.top}–${status.bottom}/${status.total}`;
+    const where = status.atTop ? " top" : "";
+    const keys = "↑↓ line · PgUp/PgDn page · esc live";
+    const left = ` ${position}${where} `;
+    // Measured in columns, not characters: the arrows and the separator are one
+    // cell each but a rebind could put anything in here, and a row that is one
+    // cell too wide wraps into the window above it.
+    const body = visibleWidth(left) + visibleWidth(keys) + 1 <= status.width ? `${left}${keys} ` : left;
+    return `\x1b[7m${truncateToWidth(body, status.width, "", true)}\x1b[0m`;
+}
 /** Parse a SizeValue into absolute value given a reference size */
 function parseSizeValue(value, referenceSize) {
     if (value === undefined)
@@ -95,6 +126,30 @@ export class Container {
             child.invalidate?.();
         }
     }
+    /**
+     * Where each direct child's output starts, in rows, from the last render.
+     *
+     * Read off the memo rather than recomputed, so asking is a walk over the
+     * children's cached line arrays and never a re-render. Undefined before the
+     * first render, or at a different width than the caller has in mind — both
+     * cases mean "no answer", not "zero".
+     *
+     * This is what lets something outside the tree point at a row inside it: a
+     * component's offset within its container, plus that container's offset at
+     * the root, is its absolute row in the buffer the viewport windows over.
+     */
+    childRowOffsets(width) {
+        const memo = this.renderMemo;
+        if (!memo || memo.width !== width)
+            return undefined;
+        const offsets = new Array(memo.refs.length);
+        let row = 0;
+        for (let i = 0; i < memo.refs.length; i++) {
+            offsets[i] = row;
+            row += memo.refs[i].length;
+        }
+        return offsets;
+    }
     render(width) {
         const n = this.children.length;
         const memo = this.renderMemo;
@@ -119,6 +174,70 @@ export class Container {
         return lines;
     }
 }
+/**
+ * A child that can be taken off screen without disturbing the diff.
+ *
+ * Hiding a component naively — returning `[]` from its render — is one of the
+ * more expensive things you can do to this renderer. `Container.render` and the
+ * root's flat cache both decide "did this subtree change" by **array identity**,
+ * so a fresh `[]` every frame reads as a change every frame: the memo is
+ * dropped, the buffer is re-flattened, and a dirty range is reported for a
+ * component that is not even drawn. One frozen array, returned every time,
+ * makes a hidden slot free instead.
+ *
+ * The child is not rendered at all while hidden, which is the other half of the
+ * saving — a hidden footer costs nothing to keep hidden. That means a child
+ * whose `render` advances an animation or maintains a cache will be paused, not
+ * merely invisible; it catches up when shown again. Chrome (footers, panels,
+ * status rows) is fine with that. A spinner is not, so do not wrap one.
+ */
+export class Slot {
+    component;
+    /** Shared across every hidden slot: identity is all the caches compare. */
+    static EMPTY = Object.freeze([]);
+    hidden = false;
+    constructor(component) {
+        this.component = component;
+    }
+    /** Whoever is in the slot right now. */
+    get child() {
+        return this.component;
+    }
+    /**
+     * Swap the occupant, keeping the slot itself in place.
+     *
+     * An extension replacing the footer used to remove one root child and append
+     * another, which both moved the footer to the end of the tree — behind the
+     * widgets meant to sit below it — and handed the root's per-child cache a
+     * changed child list every time. The slot is the stable root child; only what
+     * is inside it changes.
+     */
+    setChild(component) {
+        if (this.component === component)
+            return false;
+        this.component = component;
+        return true;
+    }
+    get visible() {
+        return !this.hidden;
+    }
+    /** Returns whether this changed anything, so callers can skip a render. */
+    setVisible(visible) {
+        const hidden = !visible;
+        if (this.hidden === hidden)
+            return false;
+        this.hidden = hidden;
+        return true;
+    }
+    invalidate() {
+        this.child.invalidate?.();
+    }
+    render(width) {
+        if (this.hidden)
+            return Slot.EMPTY;
+        return this.child.render(width);
+    }
+}
 /**
  * TUI - Main class for managing terminal UI with differential rendering
  */
@@ -165,6 +284,85 @@ export class TUI extends Container {
     previousViewportTop = 0; // Track previous viewport top for resize-aware cursor moves
     fullRedrawCount = 0;
     stopped = false;
+    /**
+     * The filler that keeps the app the size of the screen.
+     *
+     * ## Why the app is full-screen at all
+     *
+     * This renderer appends: a frame is the whole component tree flattened into
+     * a line buffer, written from wherever the cursor happens to be. On a fresh
+     * session that buffer is a dozen rows, so the banner sat halfway up a
+     * terminal with the prompt under it and forty rows of the user's shell
+     * history above — and the prompt walked down the screen as the conversation
+     * grew, only reaching the bottom row once the session was long enough to
+     * scroll. Two different layouts for the same app, and the one you meet first
+     * is the one that does not look like an app.
+     *
+     * ## What this does
+     *
+     * Before the frame is diffed, the root measures it and gives the leftover
+     * rows to one designated child. The buffer is therefore never shorter than
+     * the terminal, so the terminal's last row is always the buffer's last row:
+     * the header stays at the top, the prompt and the footer stay on the bottom,
+     * and everything between them is conversation. Nothing else changes — this
+     * is still the normal screen, so scrollback, selection and search all still
+     * work, and the session is still on screen after you quit.
+     *
+     * Set to `undefined` (no flex child) and the old append-only behaviour is
+     * exactly what you get back, which is what the tests that predate this and
+     * any embedder outside the app rely on.
+     */
+    flexSpacer;
+    /**
+     * The pinned viewport.
+     *
+     * ## What is wrong with letting the terminal do it
+     *
+     * This renderer keeps the entire transcript in its line buffer and writes it
+     * to the normal screen, so "scrolling" has always meant the terminal's own
+     * scrollback. That works exactly as long as the app does not repaint — and
+     * this one repaints the whole buffer whenever a line *above* the viewport
+     * changes, because a positional diff cannot address a row that has scrolled
+     * out of reach. The repaint is `\x1b[2J\x1b[H\x1b[3J` followed by the
+     * transcript again, and the `\x1b[3J` throws away the scrollback the reader
+     * was sitting in. From the reader's side the screen simply jumps to the
+     * bottom, for no reason they can see, at a moment they did not choose.
+     *
+     * ## What this does instead
+     *
+     * `scrollOffset` is the transcript row drawn at the top of the screen, and
+     * `null` means "follow the tail", which is the normal live behaviour and the
+     * path everything else in this file was written for. The moment it is a
+     * number the TUI switches to the alternate screen and paints a window of the
+     * buffer itself: a fixed grid, addressed row by row, with no scrollback for
+     * anything to fight over. New output still arrives and still lands in the
+     * buffer — it just does not move the window, which is the whole point. The
+     * indicator on the last row says how far down the transcript the window is,
+     * because a view that cannot move on its own needs to say where it stopped.
+     *
+     * Going back to live leaves the alternate screen, which restores the normal
+     * screen *and its scrollback* exactly as they were, and the next frame is an
+     * ordinary differential one that writes only what arrived while the reader
+     * was away — see `scrollToLive` for what has to be true for that to be safe.
+     * Not a clear-and-replay: on a long session that is a visible flash, a burst
+     * of output, and the loss of the scrollback that had just been handed back.
+     */
+    scrollOffset = null;
+    /** Transcript length measured by the last pinned paint; what clamping uses. */
+    scrollTotalLines = 0;
+    scrollStatusFormatter = defaultScrollStatus;
+    /** The running search: its query, the rows it matched, and where in them. */
+    scrollSearch = null;
+    /**
+     * Whether the view may pin right now.
+     *
+     * The wheel is answered wherever it is turned, including with a picker on
+     * screen — and a picker that lost its arrow keys to a pinned view it did not
+     * know about would be far worse than a wheel that did nothing. The app sets
+     * this because only the app knows which of its surfaces is asking a question.
+     * Unset means always.
+     */
+    canPinScroll;
     // Overlay stack for modal components rendered on top of base content
     focusOrderCounter = 0;
     overlayStack = [];
@@ -178,6 +376,317 @@ export class TUI extends Container {
     get fullRedraws() {
         return this.fullRedrawCount;
     }
+    // ── The pinned viewport ─────────────────────────────────────────────────
+    /** True while the view is pinned rather than following the tail. */
+    get scrollPinned() {
+        return this.scrollOffset !== null;
+    }
+    /** Where the pinned window sits, or null while live. */
+    getScrollPosition() {
+        if (this.scrollOffset === null)
+            return null;
+        return { top: this.scrollOffset, total: this.scrollTotalLines, viewHeight: this.scrollViewHeight() };
+    }
+    /** Let the app paint the indicator in its own theme. */
+    setScrollStatusFormatter(formatter) {
+        this.scrollStatusFormatter = formatter;
+    }
+    /**
+     * Nominate the child that absorbs the leftover rows (see `flexSpacer`).
+     *
+     * It must already be a child of the root, and it should sit between the part
+     * of the tree that flows from the top and the chrome that hangs off the
+     * bottom — everything after it is what gets pinned to the foot of the screen.
+     */
+    setFlexSpacer(spacer) {
+        this.flexSpacer = spacer;
+    }
+    /**
+     * Give the flex child whatever the frame did not use, at `height` rows.
+     *
+     * Returns true when the height moved, meaning the caller has to flatten
+     * again — the measurement can only be made from a finished frame, so the
+     * frame that answers it is always the second one. Both passes are cheap
+     * after the first: every other child returns its memoized array untouched.
+     */
+    fitFlexSpacer(lines, height) {
+        const spacer = this.flexSpacer;
+        if (!spacer)
+            return false;
+        return spacer.setHeight(height - (lines.length - spacer.currentHeight));
+    }
+    /**
+     * The screen rows a pinned window shows, the last one being the indicator.
+     *
+     * The indicator is not optional: a pinned view looks exactly like a live one
+     * that has gone quiet, and a reader who cannot tell the two apart will wait
+     * for output that is arriving perfectly well just out of sight.
+     */
+    scrollViewHeight() {
+        return Math.max(1, this.terminal.rows - 1);
+    }
+    /** Rows available to scroll through — the live buffer while live, the
+     * measured one while pinned. The filler is not transcript: counting it would
+     * let a session with nothing above the fold pin itself one row off the
+     * bottom and paint a screen of blanks. */
+    transcriptLength() {
+        if (this.scrollOffset !== null)
+            return this.scrollTotalLines;
+        return this.previousLines.length - (this.flexSpacer?.currentHeight ?? 0);
+    }
+    /**
+     * Move the view by `delta` rows; negative is towards the start.
+     *
+     * Returns whether anything moved, so a caller can let the key fall through
+     * to whatever else wants it when there is nothing to scroll.
+     */
+    scrollByLines(delta) {
+        if (delta === 0)
+            return false;
+        // Scrolling down while already live is not "scroll to somewhere", it is a
+        // request for content that does not exist yet. Doing nothing is right, and
+        // cheap: treating it as a move would drop out of scroll mode and force a
+        // full repaint on every wheel notch at the bottom of the transcript.
+        if (this.scrollOffset === null && delta > 0)
+            return false;
+        const viewHeight = this.scrollViewHeight();
+        const maxOffset = Math.max(0, this.transcriptLength() - viewHeight);
+        if (maxOffset === 0)
+            return false;
+        const next = (this.scrollOffset ?? maxOffset) + delta;
+        // Reaching the end is how the pin lets go: the reader has caught up, so
+        // give them the live screen back rather than a pinned view of the tail
+        // that silently stops following.
+        if (next >= maxOffset)
+            return this.scrollToLive();
+        this.setScrollOffset(next);
+        return true;
+    }
+    /**
+     * Move by pages, keeping two rows of overlap.
+     *
+     * A page that moves a full screen leaves nothing in common between before
+     * and after, and the reader has to find their place again on every press.
+     * The two kept rows are what makes the jump readable.
+     */
+    scrollByPages(delta) {
+        const page = Math.max(1, this.scrollViewHeight() - 2);
+        return this.scrollByLines(delta * page);
+    }
+    /** Pin the view to the very start of the transcript. */
+    scrollToTop() {
+        const maxOffset = Math.max(0, this.transcriptLength() - this.scrollViewHeight());
+        if (maxOffset === 0)
+            return false;
+        if (this.scrollOffset === 0)
+            return false;
+        this.setScrollOffset(0);
+        return true;
+    }
+    /** Release the pin and follow the tail again. */
+    scrollToLive() {
+        if (this.scrollOffset === null)
+            return false;
+        this.scrollOffset = null;
+        this.scrollSearch = null;
+        this.terminal.setAlternateScreen(false);
+        // `?1049l` restores the normal screen, its scrollback and the cursor
+        // exactly as they were at `?1049h`, and the snapshot taken on the way in
+        // says what that screen holds — so the next frame can be an ordinary
+        // differential one that writes only what arrived while we were reading.
+        // Dropping the flat cache is what makes it honest: the cache has been
+        // patched on every pinned frame, and a patch report describing rows that
+        // were painted to the *alternate* screen would leave the diff addressing
+        // the wrong ones.
+        this.flatCache = undefined;
+        this.lastCursorPos = undefined;
+        this.requestRender();
+        return true;
+    }
+    // ── Searching the pinned view ───────────────────────────────────────────
+    /**
+     * Find rows containing `query`, and pin the view to the nearest one above.
+     *
+     * Searching *backwards* first is the `ctrl+r` convention and it is the right
+     * one here: what you are looking for in a session is nearly always behind
+     * you, and the most recent occurrence is nearly always the one you meant.
+     *
+     * Matching is over the visible text, so it finds what the screen shows
+     * rather than the escape sequences underneath it — a query containing a
+     * colour code is not something anyone ever means.
+     *
+     * Returns how many rows matched.
+     */
+    setScrollSearch(query, options = {}) {
+        if (query.length === 0) {
+            this.scrollSearch = { query, matches: [], index: -1, measuredAt: -1, typing: options.typing ?? true };
+            this.requestRender();
+            this.expediteRender();
+            return 0;
+        }
+        const from = this.scrollOffset ?? Math.max(0, this.transcriptLength() - 1);
+        const matches = this.findScrollMatches(query);
+        // The nearest match at or above where the eye is, else wrap to the last.
+        let index = -1;
+        for (let i = matches.length - 1; i >= 0; i--) {
+            if (matches[i] <= from) {
+                index = i;
+                break;
+            }
+        }
+        if (index === -1 && matches.length > 0)
+            index = matches.length - 1;
+        this.scrollSearch = {
+            query,
+            matches,
+            index,
+            measuredAt: this.flatLines?.length ?? this.previousLines.length,
+            typing: options.typing ?? true,
+        };
+        if (index >= 0)
+            this.scrollToRow(matches[index]);
+        this.requestRender();
+        this.expediteRender();
+        return matches.length;
+    }
+    /**
+     * Step to the next match, `-1` being further back through the session.
+     *
+     * Wraps, because a search that stops dead at the last match makes you
+     * retype it to get back to the first.
+     */
+    scrollSearchStep(direction) {
+        const search = this.scrollSearch;
+        if (!search || search.matches.length === 0)
+            return false;
+        const next = (search.index + direction + search.matches.length) % search.matches.length;
+        search.index = next;
+        search.typing = false;
+        this.scrollToRow(search.matches[next]);
+        this.requestRender();
+        this.expediteRender();
+        return true;
+    }
+    /** Stop typing the query but keep the matches, so n/N can step them. */
+    commitScrollSearch() {
+        if (!this.scrollSearch)
+            return;
+        this.scrollSearch.typing = false;
+        this.requestRender();
+        this.expediteRender();
+    }
+    /** Drop the search, leaving the view where it is. */
+    clearScrollSearch() {
+        if (!this.scrollSearch)
+            return;
+        this.scrollSearch = null;
+        this.requestRender();
+        this.expediteRender();
+    }
+    get scrollSearchActive() {
+        return this.scrollSearch !== null;
+    }
+    /** The query being searched for, or "" when there is no search. */
+    get scrollSearchQuery() {
+        return this.scrollSearch?.query ?? "";
+    }
+    scrollSearchStatus() {
+        const search = this.scrollSearch;
+        if (!search)
+            return undefined;
+        return {
+            query: search.query,
+            count: search.matches.length,
+            index: search.index >= 0 ? search.index + 1 : 0,
+            typing: search.typing,
+        };
+    }
+    /**
+     * Rows whose visible text contains `query`, case-insensitively.
+     *
+     * One pass over the buffer, run when the query changes rather than per
+     * frame. The results are re-measured if the transcript has grown since —
+     * rare while someone is reading, and wrong in a way people notice if skipped.
+     */
+    findScrollMatches(query) {
+        const lines = this.flatLines ?? this.previousLines;
+        const needle = query.toLowerCase();
+        const matches = [];
+        for (let row = 0; row < lines.length; row++) {
+            const line = lines[row];
+            if (line.length === 0)
+                continue;
+            if (stripVTControlCharacters(line).toLowerCase().includes(needle))
+                matches.push(row);
+        }
+        return matches;
+    }
+    /** Re-run the search if the buffer grew under it. */
+    refreshScrollSearch(total) {
+        const search = this.scrollSearch;
+        if (!search || search.query.length === 0 || search.measuredAt === total)
+            return;
+        search.matches = this.findScrollMatches(search.query);
+        search.measuredAt = total;
+        if (search.index >= search.matches.length)
+            search.index = search.matches.length - 1;
+    }
+    /**
+     * Mark the query where it appears in a row about to be painted.
+     *
+     * Done at paint time, over the handful of rows on screen, rather than stored
+     * per match — highlighting the whole buffer to show a screenful would be the
+     * same work multiplied by the session's length.
+     *
+     * The row is sliced by display column so the styling already in it survives:
+     * a match inside a coloured span keeps its colour and gains the marker.
+     */
+    highlightScrollMatches(line, query) {
+        const plain = stripVTControlCharacters(line);
+        const needle = query.toLowerCase();
+        const haystack = plain.toLowerCase();
+        let at = haystack.indexOf(needle);
+        if (at === -1)
+            return line;
+        let out = "";
+        let cursor = 0;
+        while (at !== -1) {
+            const startCol = visibleWidth(plain.slice(0, at));
+            const endCol = startCol + visibleWidth(plain.slice(at, at + query.length));
+            const fromCol = visibleWidth(plain.slice(0, cursor));
+            out += sliceByColumn(line, fromCol, startCol - fromCol);
+            // 27 turns reverse off on its own, so whatever colour the row was
+            // wearing underneath the match carries on afterwards.
+            out += `\x1b[7m${sliceByColumn(line, startCol, endCol - startCol)}\x1b[27m`;
+            cursor = at + query.length;
+            at = haystack.indexOf(needle, cursor);
+        }
+        const tailCol = visibleWidth(plain.slice(0, cursor));
+        out += sliceByColumn(line, tailCol, Number.MAX_SAFE_INTEGER - tailCol);
+        return out;
+    }
+    setScrollOffset(offset) {
+        const entering = this.scrollOffset === null;
+        // Only entry is gated. A view that is already pinned keeps responding, so
+        // a surface opening underneath cannot strand the reader somewhere they
+        // have no key to leave.
+        if (entering && this.canPinScroll && !this.canPinScroll())
+            return;
+        this.scrollOffset = Math.max(0, offset);
+        if (entering) {
+            // What the normal screen is left showing, frozen. Without the copy this
+            // stays the same array the patching render() mutates in place, so on the
+            // way back out it would be diffed against itself and report that nothing
+            // arrived while the reader was away.
+            this.previousLines = this.previousLines.slice();
+            this.terminal.setAlternateScreen(true);
+            this.terminal.hideCursor();
+        }
+        this.requestRender();
+        // Scrolling is a direct manipulation: the view has to move under the
+        // gesture, not one animation frame behind it.
+        this.expediteRender();
+    }
     getShowHardwareCursor() {
         return this.showHardwareCursor;
     }
@@ -201,6 +710,48 @@ export class TUI extends Container {
     setClearOnShrink(enabled) {
         this.clearOnShrink = enabled;
     }
+    /** The component keystrokes are currently going to. */
+    get focused() {
+        return this.focusedComponent;
+    }
+    /**
+     * The root's own child offsets, which the flat cache already tracks.
+     *
+     * The base implementation reads `Container.renderMemo`, which the root does
+     * not keep — it has `flatCache` instead, holding exactly this. Falling
+     * through to the base would quietly return undefined forever.
+     */
+    childRowOffsets(width) {
+        const cache = this.flatCache;
+        if (!cache || cache.width !== width)
+            return undefined;
+        return cache.offsets;
+    }
+    /**
+     * Pin the view so `row` is on screen, without demanding it be at the top.
+     *
+     * A jump that always parks its target on the first row throws away whatever
+     * led up to it, and what led up to a message is most of what makes it
+     * readable. A row already comfortably in view is left where it is, so
+     * stepping through nearby landmarks does not make the screen lurch for each
+     * one.
+     */
+    scrollToRow(row, options = {}) {
+        const viewHeight = this.scrollViewHeight();
+        const maxOffset = Math.max(0, this.transcriptLength() - viewHeight);
+        if (maxOffset === 0)
+            return false;
+        const context = options.context ?? Math.min(3, Math.max(0, viewHeight - 1));
+        const target = Math.max(0, Math.min(row - context, maxOffset));
+        if (this.scrollOffset !== null) {
+            const top = this.scrollOffset;
+            // Already visible with room to read above it: leave it alone.
+            if (row >= top + context && row < top + viewHeight)
+                return false;
+        }
+        this.setScrollOffset(target);
+        return this.scrollOffset === target;
+    }
     setFocus(component) {
         // Clear focused flag on old component
         if (isFocusable(this.focusedComponent)) {
@@ -357,6 +908,12 @@ export class TUI extends Container {
         this.terminal.write("\x1b[16t");
     }
     stop() {
+        // Off the alternate screen before the exit bookkeeping below, which moves
+        // the cursor relative to content that lives on the normal screen.
+        if (this.scrollOffset !== null) {
+            this.scrollOffset = null;
+            this.terminal.setAlternateScreen(false);
+        }
         this.stopped = true;
         if (this.renderTimer) {
             clearTimeout(this.renderTimer);
@@ -426,6 +983,14 @@ export class TUI extends Container {
         }, delay);
     }
     handleInput(data) {
+        // Ahead of the listeners: a mouse report that reaches a text field is
+        // typed into it, and a paste-detecting listener has no reason to see one.
+        if (this.terminal.mouseReporting) {
+            const remaining = this.consumeMouseReports(data);
+            if (remaining === null)
+                return;
+            data = remaining;
+        }
         if (this.inputListeners.size > 0) {
             let current = data;
             for (const listener of this.inputListeners) {
@@ -480,6 +1045,56 @@ export class TUI extends Container {
             this.expediteRender();
         }
     }
+    /**
+     * Act on every mouse report in `data` and return what is left of it.
+     *
+     * Returns null when the chunk was nothing but reports. Reports arrive
+     * coalesced — a flick of the wheel delivers a run of them in one read, and a
+     * keystroke pressed during the flick rides along behind — so they are peeled
+     * off one at a time instead of the chunk being classified as a whole.
+     */
+    consumeMouseReports(data) {
+        // Neither introducer present is the overwhelmingly common case (every
+        // ordinary keystroke), and it costs one scan of a very short string.
+        if (!data.includes("\x1b[<") && !data.includes("\x1b[M"))
+            return data;
+        let rest = data;
+        let out = "";
+        let sawReport = false;
+        while (rest.length > 0) {
+            const length = mouseSequenceLength(rest);
+            if (length === 0) {
+                out += rest[0];
+                rest = rest.slice(1);
+                continue;
+            }
+            const event = parseMouseEvent(rest.slice(0, length));
+            if (event)
+                this.handleMouseEvent(event);
+            sawReport = true;
+            rest = rest.slice(length);
+        }
+        if (!sawReport)
+            return data;
+        return out.length > 0 ? out : null;
+    }
+    /**
+     * What the mouse does.
+     *
+     * Only the wheel is acted on. Clicks are swallowed rather than handled:
+     * reporting is on for the wheel's sake, and a click that fell through to the
+     * focused component would arrive as the raw report text in whatever field
+     * has focus.
+     */
+    handleMouseEvent(event) {
+        if (event.kind === "wheelUp") {
+            this.scrollByLines(-WHEEL_LINES);
+            return;
+        }
+        if (event.kind === "wheelDown") {
+            this.scrollByLines(WHEEL_LINES);
+        }
+    }
     /** Run a requested render now, bypassing the coalescing delay. Used for
      * input-driven frames where echo latency matters more than batching. */
     expediteRender() {
@@ -931,9 +1546,96 @@ export class TUI extends Container {
         this.lastPatch = low === Infinity && high === -1 ? null : { low: low === Infinity ? 0 : low, high, prevLength };
         return flat;
     }
+    /**
+     * Paint the pinned window onto the alternate screen.
+     *
+     * Deliberately not differential. The alternate screen is `rows` tall and
+     * nothing else writes to it, so a whole frame is at most a screenful of
+     * cells inside one synchronized-output pair — cheaper to emit than the
+     * bookkeeping a diff would need, and with nothing to get out of step with.
+     * The differential renderer's state is left exactly as the last live frame
+     * left it, because `scrollToLive` throws it away rather than resuming from it.
+     */
+    renderScrollView() {
+        const width = this.terminal.columns;
+        const height = this.terminal.rows;
+        // No fill while pinned: the window is already the height of the screen,
+        // and blank rows in the buffer would be rows of the transcript the reader
+        // has to scroll past. The next live frame puts it back.
+        this.flexSpacer?.setHeight(0);
+        let lines = this.render(width);
+        // A patch computed while pinned describes rows nothing painted to the
+        // normal screen, so the live path must never be handed it.
+        this.lastPatch = "full";
+        if (this.overlayStack.length > 0) {
+            lines = this.compositeOverlays(lines, width, height);
+        }
+        const viewHeight = this.scrollViewHeight();
+        this.scrollTotalLines = lines.length;
+        const maxOffset = Math.max(0, lines.length - viewHeight);
+        // The transcript can shrink under a pinned view — a pane closing, a tool
+        // block collapsing — so the offset is re-clamped every frame rather than
+        // only where it is set.
+        const top = Math.min(Math.max(0, this.scrollOffset ?? 0), maxOffset);
+        this.scrollOffset = top;
+        let buffer = "\x1b[?2026h"; // Begin synchronized output
+        buffer += HIDE_CURSOR;
+        // Autowrap off for the paint: a full-width row would otherwise wrap into
+        // the row below it and shift the rest of the window down by one.
+        buffer += "\x1b[?7l";
+        this.refreshScrollSearch(lines.length);
+        const query = this.scrollSearch?.query ?? "";
+        for (let row = 0; row < viewHeight; row++) {
+            buffer += `\x1b[${row + 1};1H\x1b[2K`;
+            const line = lines[top + row];
+            if (line !== undefined)
+                buffer += this.emitScrollLine(line, query);
+        }
+        buffer += `\x1b[${height};1H\x1b[2K`;
+        buffer += this.scrollStatusFormatter({
+            top: top + 1,
+            bottom: Math.min(top + viewHeight, lines.length),
+            total: lines.length,
+            viewHeight,
+            atTop: top === 0,
+            atBottom: top >= maxOffset,
+            width,
+            search: this.scrollSearchStatus(),
+        });
+        buffer += "\x1b[?7h";
+        buffer += "\x1b[?2026l"; // End synchronized output
+        this.terminal.write(buffer);
+        // `previousWidth` / `previousHeight` are deliberately left describing the
+        // last *live* frame. If the terminal was resized while pinned they will
+        // disagree with the real size on the way out, and the live path will take
+        // its full-redraw branch — which is exactly right, because the normal
+        // screen `?1049l` restored was drawn at the old size.
+    }
+    /**
+     * One transcript row, ready for the pinned window.
+     *
+     * Images are named rather than drawn. A kitty or iTerm image is placed by
+     * the cursor and sized in pixels, so the same escape replayed at a different
+     * screen row lands somewhere the window did not ask for and survives the
+     * frame that was supposed to replace it — a smear across the view that no
+     * later repaint can clear.
+     */
+    emitScrollLine(line, query = "") {
+        if (isImageLine(line))
+            return "\x1b[2m[image]\x1b[0m";
+        const marker = line.indexOf(CURSOR_MARKER);
+        let text = marker === -1 ? line : line.slice(0, marker) + line.slice(marker + CURSOR_MARKER.length);
+        if (query.length > 0)
+            text = this.highlightScrollMatches(text, query);
+        return normalizeTerminalOutput(text) + TUI.SEGMENT_RESET;
+    }
     doRender() {
         if (this.stopped)
             return;
+        if (this.scrollOffset !== null) {
+            this.renderScrollView();
+            return;
+        }
         const width = this.terminal.columns;
         const height = this.terminal.rows;
         const widthChanged = this.previousWidth !== 0 && this.previousWidth !== width;
@@ -950,6 +1652,15 @@ export class TUI extends Container {
         // Render all components to get new lines. The root render() reports what
         // it changed via lastPatch; consume it here (it is per-frame state).
         let newLines = this.render(width);
+        // The frame has to exist before its leftover rows can be counted, so the
+        // fill is settled by re-flattening rather than predicted. The second pass
+        // invalidates the first's patch — it describes the buffer from before the
+        // splice — so fall back to the full scan, which is always correct and only
+        // runs on frames where the content height actually changed.
+        if (this.fitFlexSpacer(newLines, height)) {
+            newLines = this.render(width);
+            this.lastPatch = "full";
+        }
         const patch = this.lastPatch;
         this.lastPatch = "full";
         // Composite overlays into the rendered lines (before differential compare)