@aragon-agent/tui 0.0.0-stage → 0.0.1

package/dist/ui/scrollback/settled-boundary.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Settled boundary — which transcript entries may be PRINTED
+ * (tui-native-terminal-scroll §4.4).
+ *
+ * Printed rows live in the host terminal's scrollback and can never be rewritten
+ * ("printed is forever"). So the only entries that may be printed are the ones the
+ * reducer will NEVER write to again. This module derives that from the reducer's
+ * real write set, one exhaustive `switch` per entry kind. Adding an `Entry` kind is
+ * a compile error here (`never`), which is the whole point; widening the write set
+ * of an EXISTING kind is not caught by the compiler, so `agent/reducer.ts` carries
+ * a pointer comment beside the `Entry` union and the unit tests pin each row.
+ *
+ * Three rules that are easy to "simplify" wrongly:
+ *  - A tool is stable only when `done` or `error`. `pending` is NOT stable: the
+ *    card is created at `pending` and `toolCallDelta` keeps rewriting `argsRaw`
+ *    while the model streams its arguments (RV-1).
+ *  - A trailing `Context length exceeded` error notice is NOT stable while a run is
+ *    active: `compactionStart` rewrites it in place into an info notice (RV-4).
+ *  - A non-terminal `service` card is neither printed nor a wall (RV-3). It is
+ *    rewritten for the whole session; the one-row `terminal: true` record the
+ *    reducer appends at the end is an ordinary stable entry and carries the news.
+ */
+import type { Entry } from '../../model/agent/reducer.js';
+/** Never printed and never a wall: rewritten for the whole session (RV-3). */
+export declare function isExcluded(entry: Entry): boolean;
+/** True when the reducer will never write to `entry` again. */
+export declare function isEntryStable(entry: Entry, runActive: boolean, isTail: boolean): boolean;
+/**
+ * Length of the printable PREFIX of `entries`.
+ *
+ * The first unstable (non-excluded) entry is a wall: everything before it may
+ * print, nothing after it may, which keeps scrollback order equal to conversation
+ * order (I-S3). Excluded entries are skipped, so a long-lived service card never
+ * blocks the conversation behind it.
+ */
+export declare function settledCount(entries: readonly Entry[], runActive: boolean): number;
+/**
+ * Everything printable at shutdown: all entries except those that never settle
+ * (`queued`, non-terminal services). The last answer must not be lost to a
+ * boundary that was waiting for a frame that will never come.
+ */
+export declare function settleAllEntries(entries: readonly Entry[]): Entry[];

package/dist/ui/scrollback/settled-boundary.js

@@ -0,0 +1,109 @@
+/**
+ * Settled boundary — which transcript entries may be PRINTED
+ * (tui-native-terminal-scroll §4.4).
+ *
+ * Printed rows live in the host terminal's scrollback and can never be rewritten
+ * ("printed is forever"). So the only entries that may be printed are the ones the
+ * reducer will NEVER write to again. This module derives that from the reducer's
+ * real write set, one exhaustive `switch` per entry kind. Adding an `Entry` kind is
+ * a compile error here (`never`), which is the whole point; widening the write set
+ * of an EXISTING kind is not caught by the compiler, so `agent/reducer.ts` carries
+ * a pointer comment beside the `Entry` union and the unit tests pin each row.
+ *
+ * Three rules that are easy to "simplify" wrongly:
+ *  - A tool is stable only when `done` or `error`. `pending` is NOT stable: the
+ *    card is created at `pending` and `toolCallDelta` keeps rewriting `argsRaw`
+ *    while the model streams its arguments (RV-1).
+ *  - A trailing `Context length exceeded` error notice is NOT stable while a run is
+ *    active: `compactionStart` rewrites it in place into an info notice (RV-4).
+ *  - A non-terminal `service` card is neither printed nor a wall (RV-3). It is
+ *    rewritten for the whole session; the one-row `terminal: true` record the
+ *    reducer appends at the end is an ordinary stable entry and carries the news.
+ */
+import { CONTEXT_OVERFLOW_NOTICE_PREFIX } from '../../model/agent/reducer.js';
+/** Kinds the reducer may still rewrite while a run is active, so a tail one is held. */
+const MUTABLE_TAIL_KINDS = new Set([
+    'assistant', 'tool', 'compaction', 'todo', 'team', 'fast', 'retry', 'queued',
+]);
+/** Never printed and never a wall: rewritten for the whole session (RV-3). */
+export function isExcluded(entry) {
+    return entry.kind === 'service' && entry.terminal !== true;
+}
+/** True when the reducer will never write to `entry` again. */
+export function isEntryStable(entry, runActive, isTail) {
+    switch (entry.kind) {
+        case 'user':
+            return true;
+        case 'notice':
+            return !(runActive &&
+                isTail &&
+                entry.level === 'error' &&
+                entry.text.startsWith(CONTEXT_OVERFLOW_NOTICE_PREFIX));
+        case 'assistant':
+            return !entry.streaming;
+        case 'tool':
+            return entry.status === 'done' || entry.status === 'error';
+        case 'compaction':
+            return entry.live !== true;
+        case 'todo':
+            return entry.live === false;
+        case 'team':
+            return entry.active === false;
+        case 'fast':
+            return entry.live === false;
+        case 'retry':
+            return (entry.phase === 'recovered' ||
+                entry.phase === 'exhausted' ||
+                entry.phase === 'interrupted');
+        case 'queued':
+            // Rewritten in place into a `user` entry by the matching receipt.
+            return false;
+        case 'service':
+            // Only the terminal record is ever a candidate; `isExcluded` filters the rest.
+            return entry.terminal === true;
+        case 'governance':
+            // A settlement card is appended once, already complete.
+            return true;
+        default: {
+            const exhaustive = entry;
+            return exhaustive;
+        }
+    }
+}
+/**
+ * Length of the printable PREFIX of `entries`.
+ *
+ * The first unstable (non-excluded) entry is a wall: everything before it may
+ * print, nothing after it may, which keeps scrollback order equal to conversation
+ * order (I-S3). Excluded entries are skipped, so a long-lived service card never
+ * blocks the conversation behind it.
+ */
+export function settledCount(entries, runActive) {
+    const last = entries.length - 1;
+    let count = entries.length;
+    for (let i = 0; i < entries.length; i += 1) {
+        const entry = entries[i];
+        if (isExcluded(entry))
+            continue;
+        if (!isEntryStable(entry, runActive, i === last)) {
+            count = i;
+            break;
+        }
+    }
+    // Hold a mutable TAIL while a run is active, but only a mutable one: a `user` or
+    // `notice` at the tail prints immediately (a submitted message must appear at once).
+    if (runActive && count === entries.length && count > 0) {
+        const tail = entries[last];
+        if (!isExcluded(tail) && MUTABLE_TAIL_KINDS.has(tail.kind))
+            return last;
+    }
+    return count;
+}
+/**
+ * Everything printable at shutdown: all entries except those that never settle
+ * (`queued`, non-terminal services). The last answer must not be lost to a
+ * boundary that was waiting for a frame that will never come.
+ */
+export function settleAllEntries(entries) {
+    return entries.filter((entry) => entry.kind !== 'queued' && !isExcluded(entry));
+}

package/dist/ui/scrollback/tail-anchor.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Where the live tail sits inside the band's preview box
+ * (tui-first-reply-bottom-aligned, plan A-prime).
+ *
+ * THE DEFECT THIS ANSWERS. The box is always the whole pool (`band.previewRows`, 24 rows
+ * on a 30-row terminal) while a first turn is four rows tall. A constant
+ * `justifyContent="flex-end"` therefore pushed those four rows against the composer and
+ * left every unused row ABOVE the conversation - the "the first reply starts at the
+ * bottom of the screen" report. The answer is conditional anchoring: top while the
+ * content fits, so the conversation is written downwards from the region's top row
+ * (`tui-header-leaks-into-scrollback` took the identity row off that row and put it
+ * below the composer, so the first line of the band is now the first line of the screen).
+ *
+ * WHY THE FALLBACK IS `bottom` AND NOT THE OTHER WAY ROUND. `flex-start` inside an
+ * `overflow="hidden"` box clips the NEWEST rows (Ink's clip rectangle is the box's
+ * `[top, top + height]`), and a streaming entry is never printable
+ * (`settled-boundary.ts` holds it unstable, and "printed is forever"). Overflowing to
+ * `flex-start` would hide the text the user is waiting for; overflowing to `flex-end`
+ * hides the oldest rows, which the tail window prints on its way out.
+ *
+ * THE THRESHOLD CARRIES A MARGIN. `rowOf` is an ESTIMATE, and the one available
+ * (`layout/virtual-window.ts::estimateEntryRows`) under-counts a `#` heading and a code
+ * block. The margin in `SCROLLBACK_LIMITS.tailAnchorSlackRows` absorbs that error on the
+ * `bottom` side, the only direction that cannot clip something new.
+ *
+ * PURE: no Ink, no I/O, no clock, and deliberately no import of `virtual-window.ts` (its
+ * import graph reaches a `.tsx` gutter). The row height is injected, so this stays three
+ * parameters and a unit test can drive it with any table it likes.
+ */
+import type { Entry } from '../../model/agent/reducer.js';
+/** `top` = content grows down from the region's top row; `bottom` = newest row hugs the
+ *  composer. */
+export type TailAnchor = 'top' | 'bottom';
+/**
+ * Which alignment the live tail should use for the entries it is about to render.
+ *
+ * @param entries The entries THIS FRAME renders (already windowed by `selectTailEntries`;
+ * summing the whole conversation would make every session past the entry cap overflow and
+ * anchor to the bottom forever).
+ * @param budgetRows Height of the box that will clip them, in rows.
+ * @param rowOf Estimated height of one entry, including its separation row.
+ * @returns `top` when the estimates plus `tailAnchorSlackRows` fit in `budgetRows`,
+ * `bottom` otherwise (and for the first entry that does not fit, so the loop stops early).
+ */
+export declare function tailAnchor(entries: readonly Entry[], budgetRows: number, rowOf: (entry: Entry) => number): TailAnchor;
+/**
+ * The anchor this frame really uses: MEASURED when the measurement exists, estimated
+ * otherwise.
+ *
+ * WHY A MEASURED ANSWER WINS (tui-final-reply-truncated-unscrollable). The estimate is an
+ * upper bound that charges a separation row this renderer may not draw, so it can claim the
+ * content overflows while it actually fits (the block sits at the bottom of a half-empty
+ * box - the very complaint `tui-first-reply-bottom-aligned` answered) and it under-counts a
+ * heading or a wrapped code block, so it can claim the content fits while the box is really
+ * clipping. The second error is the expensive one now: "top give-way" only prints while the
+ * box is bottom-anchored (that is the branch that clips the TOP), so a wrongly top-anchored
+ * box would clip the newest rows and print the oldest ones - the wrong half, twice.
+ *
+ * A measured total is available only when every window entry is stable AND already measured
+ * at the current geometry (`use-scrollback-view.ts` keeps that cache), which is exactly the
+ * frame on which a print decision is being made. Every other frame - streaming, resize,
+ * first sight of a new entry - falls back to the estimate, unchanged.
+ *
+ * @param measuredRows Measured height of the same entries, or `undefined` when unknown.
+ */
+export declare function resolveTailAnchor(input: {
+    entries: readonly Entry[];
+    budgetRows: number;
+    rowOf: (entry: Entry) => number;
+    measuredRows: number | undefined;
+}): TailAnchor;

package/dist/ui/scrollback/tail-anchor.js

@@ -0,0 +1,79 @@
+/**
+ * Where the live tail sits inside the band's preview box
+ * (tui-first-reply-bottom-aligned, plan A-prime).
+ *
+ * THE DEFECT THIS ANSWERS. The box is always the whole pool (`band.previewRows`, 24 rows
+ * on a 30-row terminal) while a first turn is four rows tall. A constant
+ * `justifyContent="flex-end"` therefore pushed those four rows against the composer and
+ * left every unused row ABOVE the conversation - the "the first reply starts at the
+ * bottom of the screen" report. The answer is conditional anchoring: top while the
+ * content fits, so the conversation is written downwards from the region's top row
+ * (`tui-header-leaks-into-scrollback` took the identity row off that row and put it
+ * below the composer, so the first line of the band is now the first line of the screen).
+ *
+ * WHY THE FALLBACK IS `bottom` AND NOT THE OTHER WAY ROUND. `flex-start` inside an
+ * `overflow="hidden"` box clips the NEWEST rows (Ink's clip rectangle is the box's
+ * `[top, top + height]`), and a streaming entry is never printable
+ * (`settled-boundary.ts` holds it unstable, and "printed is forever"). Overflowing to
+ * `flex-start` would hide the text the user is waiting for; overflowing to `flex-end`
+ * hides the oldest rows, which the tail window prints on its way out.
+ *
+ * THE THRESHOLD CARRIES A MARGIN. `rowOf` is an ESTIMATE, and the one available
+ * (`layout/virtual-window.ts::estimateEntryRows`) under-counts a `#` heading and a code
+ * block. The margin in `SCROLLBACK_LIMITS.tailAnchorSlackRows` absorbs that error on the
+ * `bottom` side, the only direction that cannot clip something new.
+ *
+ * PURE: no Ink, no I/O, no clock, and deliberately no import of `virtual-window.ts` (its
+ * import graph reaches a `.tsx` gutter). The row height is injected, so this stays three
+ * parameters and a unit test can drive it with any table it likes.
+ */
+import { SCROLLBACK_LIMITS } from './limits.js';
+/**
+ * Which alignment the live tail should use for the entries it is about to render.
+ *
+ * @param entries The entries THIS FRAME renders (already windowed by `selectTailEntries`;
+ * summing the whole conversation would make every session past the entry cap overflow and
+ * anchor to the bottom forever).
+ * @param budgetRows Height of the box that will clip them, in rows.
+ * @param rowOf Estimated height of one entry, including its separation row.
+ * @returns `top` when the estimates plus `tailAnchorSlackRows` fit in `budgetRows`,
+ * `bottom` otherwise (and for the first entry that does not fit, so the loop stops early).
+ */
+export function tailAnchor(entries, budgetRows, rowOf) {
+    const budget = Number.isFinite(budgetRows) ? Math.max(0, Math.floor(budgetRows)) : 0;
+    let rows = 0;
+    for (const entry of entries) {
+        rows += Math.max(0, rowOf(entry));
+        if (rows + SCROLLBACK_LIMITS.tailAnchorSlackRows > budget)
+            return 'bottom';
+    }
+    return 'top';
+}
+/**
+ * The anchor this frame really uses: MEASURED when the measurement exists, estimated
+ * otherwise.
+ *
+ * WHY A MEASURED ANSWER WINS (tui-final-reply-truncated-unscrollable). The estimate is an
+ * upper bound that charges a separation row this renderer may not draw, so it can claim the
+ * content overflows while it actually fits (the block sits at the bottom of a half-empty
+ * box - the very complaint `tui-first-reply-bottom-aligned` answered) and it under-counts a
+ * heading or a wrapped code block, so it can claim the content fits while the box is really
+ * clipping. The second error is the expensive one now: "top give-way" only prints while the
+ * box is bottom-anchored (that is the branch that clips the TOP), so a wrongly top-anchored
+ * box would clip the newest rows and print the oldest ones - the wrong half, twice.
+ *
+ * A measured total is available only when every window entry is stable AND already measured
+ * at the current geometry (`use-scrollback-view.ts` keeps that cache), which is exactly the
+ * frame on which a print decision is being made. Every other frame - streaming, resize,
+ * first sight of a new entry - falls back to the estimate, unchanged.
+ *
+ * @param measuredRows Measured height of the same entries, or `undefined` when unknown.
+ */
+export function resolveTailAnchor(input) {
+    const { entries, budgetRows, rowOf, measuredRows } = input;
+    if (measuredRows === undefined || !Number.isFinite(measuredRows)) {
+        return tailAnchor(entries, budgetRows, rowOf);
+    }
+    const budget = Number.isFinite(budgetRows) ? Math.max(0, Math.floor(budgetRows)) : 0;
+    return measuredRows > budget ? 'bottom' : 'top';
+}

package/dist/ui/scrollback/tail-window.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The TAIL WINDOW of the native-scroll live region
+ * (tui-full-height-live-region D6 / D7, I-F8 / I-F9).
+ *
+ * WHAT CHANGED AND WHY. The region used to show only the entries the reducer had not
+ * finished writing (`entries.slice(settledCount)`), and everything settled was printed
+ * into the terminal's scrollback the moment it settled. Once the region is the WHOLE
+ * screen (`liveRows = rows - 1`), a printed row is pushed off the top by the very next
+ * frame, so "print on settle" would leave the user staring at a screen of blanks with
+ * only the unfinished cards on it. So the region now shows the last `K` PRINTABLE
+ * entries - settled or not - and an entry is printed when it LEAVES that window.
+ *
+ * The window is defined by ENTRY COUNT, never by measured height; what a single entry
+ * taller than the region used to do is the whole subject of
+ * `overflow-print.ts` (tui-final-reply-truncated-unscrollable). The box still clips it
+ * from the top with `justifyContent="flex-end"`, but the rows it hides are now PRINTED
+ * into the terminal's scrollback, where the wheel already reaches, instead of waiting for
+ * `K` further entries (README, known limitation 2 - rewritten by that fix).
+ *
+ * PURE: no Ink, no I/O, no clock. `promote()` (the writer's only feeder) takes
+ * `printBoundary`'s result and keeps its own `printed` authority, so "printed is
+ * forward-only" (RV-7) is unchanged.
+ *
+ * PRINTABILITY != VISIBILITY. `isExcluded` entries (a non-terminal `service` card) never
+ * print and never take a slot in the window; an entry that is in the window may still be
+ * scrolled out of sight by a taller neighbour. That second gap is what the row-level plan
+ * closes, and `/perf`'s `window=<start>/<n> head=<rows>` is how it stays observable.
+ */
+import type { Entry } from '../../model/agent/reducer.js';
+/**
+ * Entries that take NO slot in the window: they neither print nor take a row.
+ *
+ * A LIVE DISPATCH CARD JOINS THE NON-TERMINAL SERVICE CARD HERE
+ * (tui-subagent-double-roster A-2'): the roster draws the live dispatch and the
+ * transcript draws nothing, so the window must not spend one of its slots on an
+ * entry that is not on screen. THE PRINT PUMP AND THE BOX MUST AGREE ABOUT SLOTS:
+ * so both window functions below skip it, and `LiveTail.selectTailEntries` - the
+ * window function the box renders - imports this one instead of spelling the
+ * composition out a second time.
+ */
+export declare function isSlotless(entry: Entry): boolean;
+export interface TailWindow {
+    /** First index of the window inside the full entry list. */
+    start: number;
+    /** Entries inside the window, oldest first (excluded entries already dropped). */
+    entries: readonly Entry[];
+}
+/**
+ * The index of the first entry that is still on screen: count backwards up to
+ * `maxEntries` PRINTABLE entries. Everything before it has left the region and is the
+ * writer's business.
+ *
+ * `maxEntries <= 0` returns `entries.length` - an empty window, which is the old
+ * behaviour ("everything printable may print") and the reason the guard is written as
+ * an early return rather than as a loop bound.
+ */
+export declare function tailWindowStart(entries: readonly Entry[], maxEntries: number): number;
+/** `entries.slice(start)` with the entries that never print dropped. */
+export declare function selectTailWindow(entries: readonly Entry[], maxEntries: number): TailWindow;
+/**
+ * The print boundary: never print what the region is still showing.
+ *
+ * THIS IS THE ONLY PLACE THAT COMBINES "settled" WITH "in the window" (RV-P2-13), which
+ * is why the composition lives here instead of at the pump: `promote()` must keep
+ * receiving one number, and the two authorities it is derived from - `settledCount`
+ * (what may print at all) and `tailWindowStart` (what is still visible) - then cannot
+ * drift apart in a future edit.
+ *
+ * `settleAllEntries` is the OTHER authority, not a duplicate: it answers "what must be
+ * printed when the conversation is being torn down", while this answers "how far may
+ * this frame print".
+ */
+export declare function printBoundary(entries: readonly Entry[], runActive: boolean, maxEntries: number): number;

package/dist/ui/scrollback/tail-window.js

@@ -0,0 +1,89 @@
+/**
+ * The TAIL WINDOW of the native-scroll live region
+ * (tui-full-height-live-region D6 / D7, I-F8 / I-F9).
+ *
+ * WHAT CHANGED AND WHY. The region used to show only the entries the reducer had not
+ * finished writing (`entries.slice(settledCount)`), and everything settled was printed
+ * into the terminal's scrollback the moment it settled. Once the region is the WHOLE
+ * screen (`liveRows = rows - 1`), a printed row is pushed off the top by the very next
+ * frame, so "print on settle" would leave the user staring at a screen of blanks with
+ * only the unfinished cards on it. So the region now shows the last `K` PRINTABLE
+ * entries - settled or not - and an entry is printed when it LEAVES that window.
+ *
+ * The window is defined by ENTRY COUNT, never by measured height; what a single entry
+ * taller than the region used to do is the whole subject of
+ * `overflow-print.ts` (tui-final-reply-truncated-unscrollable). The box still clips it
+ * from the top with `justifyContent="flex-end"`, but the rows it hides are now PRINTED
+ * into the terminal's scrollback, where the wheel already reaches, instead of waiting for
+ * `K` further entries (README, known limitation 2 - rewritten by that fix).
+ *
+ * PURE: no Ink, no I/O, no clock. `promote()` (the writer's only feeder) takes
+ * `printBoundary`'s result and keeps its own `printed` authority, so "printed is
+ * forward-only" (RV-7) is unchanged.
+ *
+ * PRINTABILITY != VISIBILITY. `isExcluded` entries (a non-terminal `service` card) never
+ * print and never take a slot in the window; an entry that is in the window may still be
+ * scrolled out of sight by a taller neighbour. That second gap is what the row-level plan
+ * closes, and `/perf`'s `window=<start>/<n> head=<rows>` is how it stays observable.
+ */
+import { isExcluded, settledCount } from './settled-boundary.js';
+import { isLiveTeamCard } from '../team-status.js';
+/**
+ * Entries that take NO slot in the window: they neither print nor take a row.
+ *
+ * A LIVE DISPATCH CARD JOINS THE NON-TERMINAL SERVICE CARD HERE
+ * (tui-subagent-double-roster A-2'): the roster draws the live dispatch and the
+ * transcript draws nothing, so the window must not spend one of its slots on an
+ * entry that is not on screen. THE PRINT PUMP AND THE BOX MUST AGREE ABOUT SLOTS:
+ * so both window functions below skip it, and `LiveTail.selectTailEntries` - the
+ * window function the box renders - imports this one instead of spelling the
+ * composition out a second time.
+ */
+export function isSlotless(entry) {
+    return isExcluded(entry) || isLiveTeamCard(entry);
+}
+/**
+ * The index of the first entry that is still on screen: count backwards up to
+ * `maxEntries` PRINTABLE entries. Everything before it has left the region and is the
+ * writer's business.
+ *
+ * `maxEntries <= 0` returns `entries.length` - an empty window, which is the old
+ * behaviour ("everything printable may print") and the reason the guard is written as
+ * an early return rather than as a loop bound.
+ */
+export function tailWindowStart(entries, maxEntries) {
+    const limit = Number.isFinite(maxEntries) ? Math.floor(maxEntries) : 0;
+    if (limit <= 0)
+        return entries.length;
+    let seen = 0;
+    for (let i = entries.length - 1; i >= 0; i -= 1) {
+        if (isSlotless(entries[i]))
+            continue;
+        seen += 1;
+        if (seen === limit)
+            return i;
+    }
+    // Fewer printable entries than the window holds: the whole conversation is on screen.
+    return 0;
+}
+/** `entries.slice(start)` with the entries that never print dropped. */
+export function selectTailWindow(entries, maxEntries) {
+    const start = tailWindowStart(entries, maxEntries);
+    return { start, entries: entries.slice(start).filter((entry) => !isSlotless(entry)) };
+}
+/**
+ * The print boundary: never print what the region is still showing.
+ *
+ * THIS IS THE ONLY PLACE THAT COMBINES "settled" WITH "in the window" (RV-P2-13), which
+ * is why the composition lives here instead of at the pump: `promote()` must keep
+ * receiving one number, and the two authorities it is derived from - `settledCount`
+ * (what may print at all) and `tailWindowStart` (what is still visible) - then cannot
+ * drift apart in a future edit.
+ *
+ * `settleAllEntries` is the OTHER authority, not a duplicate: it answers "what must be
+ * printed when the conversation is being torn down", while this answers "how far may
+ * this frame print".
+ */
+export function printBoundary(entries, runActive, maxEntries) {
+    return Math.min(settledCount(entries, runActive), tailWindowStart(entries, maxEntries));
+}

package/dist/ui/scrollback/use-scrollback-view.d.ts

@@ -0,0 +1,139 @@
+/**
+ * `useScrollbackView` — the promotion pipeline of native-scroll mode
+ * (tui-native-terminal-scroll §4.4 / §6.2, tui-full-height-live-region D3/D4/D7/D8,
+ * tui-final-reply-truncated-unscrollable A-prime).
+ *
+ * `App` calls it ALWAYS (hooks cannot be conditional); `enabled: false` makes every
+ * effect a no-op and keeps `scrollMode: 'app'` byte-identical to the pre-feature
+ * build (I-S9 / I-F10).
+ *
+ * What it does when enabled:
+ *  1. On every entries change, promotes each entry that has LEFT THE TAIL WINDOW:
+ *     renders it once through the offscreen renderer and enqueues the rows for the
+ *     writer. Entries still on screen are never printed - at `H = rows - 1` a printed
+ *     row is pushed back off the top by the next frame, and a second copy in the
+ *     scrollback would be a duplicate the user meets by scrolling up (I-F8).
+ *  2. Gives way at the TOP (tui-final-reply-truncated-unscrollable). The window is still
+ *     counted in ENTRIES, so a settled answer taller than the box used to sit inside the
+ *     window forever, clipped by `justifyContent="flex-end"`, in a mode whose wheel only
+ *     scrolls the terminal's scrollback: the clipped rows existed nowhere the user could
+ *     reach. The rows the box hides are now measured (`overflow-print.ts`) and printed, so
+ *     `scrollback + screen` covers every row exactly once. Screen unchanged, reachability
+ *     fixed.
+ *  3. Computes the live-region budget, the window and the tail rows for the shell.
+ *  4. Flushes the window before either reset path (`/clear`, `--resume`) and on exit,
+ *     so "on screen but not printed yet" can never become "lost" (D8 / I-F12).
+ *
+ * THE HEADER AND THE OPENER ARE NOT PRINTED HERE ANY MORE (D3/D4). They are slots of
+ * `ScrollbackShell` now, rendered inside the region: `H = rows - 1` means any printed
+ * row is immediately scrolled off the screen, so printing the banner would be the same
+ * as not drawing it. Their `renderNode` path, the `startedRef` latch that kept their
+ * element identities stable, and the `printBanner()` call in `settleAll()` are gone.
+ *
+ * THE PROMOTION RUNS IN A MICROTASK, NOT IN THE EFFECT. The offscreen renderer is a
+ * second Ink instance, and both instances share one React reconciler. A `rerender`
+ * issued from inside the main tree's commit (a layout effect) is deferred until that
+ * commit finishes, so its frame would not exist when the effect reads it. A microtask
+ * runs after the commit has unwound, where the offscreen render is synchronous again.
+ *
+ * THE PASS READS THE COMMITTED FRAME, NOT THE LATEST RENDER. `latest` is refreshed during
+ * render, so it can be a frame ahead of the screen; `committed` is written by a layout
+ * effect and therefore describes exactly the frame the user is looking at. With
+ * entry-granular bookkeeping the difference was harmless (printing was idempotent per
+ * entry); with ROW-granular bookkeeping it would slice this frame's picture with another
+ * frame's row numbers, and the result is a duplicate or a hole.
+ *
+ * `printed` is the ONLY authority on "already printed" (RV-7): a `Map` from entry id to
+ * the leading rows already handed to the writer, and the width they were measured at. The
+ * cursor is just a hint for where to resume scanning: entries leave the list by retain-ring
+ * trimming AND by reducer deletion (empty settled assistants, abandoned tool cards), so an
+ * id-keyed cursor can dangle, and then the only correct answer is to rescan and let
+ * `printed` skip.
+ */
+import type { Entry } from '../../model/agent/reducer.js';
+import type { TermCapabilities } from '../capabilities.js';
+import type { DensityMode } from '../density.js';
+import type { Theme } from '../theme.js';
+import { type ScrollbackBudget } from './budget.js';
+import type { ScrollbackDrain } from './drain.js';
+import type { ScrollbackWriter } from './scrollback-writer.js';
+/** The channel between `cli.tsx` (which owns the stream) and the React tree. */
+export interface ScrollbackBridge {
+    writer: ScrollbackWriter;
+    drain: ScrollbackDrain;
+    /** Installed by `cli.tsx`: schedule `writer.repaint()` soon. */
+    requestFlush: () => void;
+    /**
+     * Installed by the hook on mount (reads the latest entries through a ref).
+     * `restore()` calls it on every exit path; it is idempotent through `printed`
+     * and it releases the offscreen renderer when done.
+     */
+    settleAllNow: () => void;
+    /** Installed by `App`; at most `exitSummaryMaxRows` rows. Wrapped in try/catch by the caller. */
+    getSummaryRows: () => readonly string[];
+    /** Installed by `App`: the writer swallowed repeated tall frames (degrade to the placeholder). */
+    onGuardTrip: (() => void) | null;
+}
+export declare function createScrollbackBridge(parts: Pick<ScrollbackBridge, 'writer' | 'drain'> & {
+    requestFlush?: () => void;
+}): ScrollbackBridge;
+export type ScrollbackResetKind = 'clear' | 'restore';
+export interface UseScrollbackViewArgs {
+    /** `scrollMode === 'native'`. */
+    enabled: boolean;
+    bridge: ScrollbackBridge | undefined;
+    entries: readonly Entry[];
+    runActive: boolean;
+    theme: Theme;
+    caps: TermCapabilities;
+    density: DensityMode;
+    thinkingVisible: boolean;
+    reducedMotion: boolean;
+    /** Terminal size. */
+    rows: number;
+    cols: number;
+    overlayOpen: boolean;
+    draftRows: number;
+    popupRows: number;
+    statusExpanded: boolean;
+    /** Degrade the region to the placeholder (the writer's tall-frame guard tripped). */
+    forceInactive?: boolean;
+    /** `state.todos.items.length` - 0 means there is no plan, so the rail has no work to show. */
+    itemCount: number;
+    /** `cfg.todo.panel`: the user can switch the rail off entirely. */
+    panelEnabled: boolean;
+    /** `buildTeamPanelLayout().rowCount`; 0 when nothing is dispatched. */
+    teamRowsNatural: number;
+    /**
+     * `state.expandedToolIds` - REQUIRED, because the height of a window entry depends on it
+     * and a forgotten value would measure an expansion the region is not drawing.
+     */
+    expandedToolIds: Record<string, true>;
+}
+export interface ScrollbackView {
+    budget: ScrollbackBudget | null;
+    liveTailLines: string[];
+    /**
+     * The entries the region is showing, in order (excluded kinds already dropped).
+     * `windowStart` is their index in the full list - together they are what `/perf`
+     * reports as `window=<start>/<n>`, the number that makes the "visible vs printable"
+     * gap observable instead of a guess (known limitation 5).
+     */
+    tailEntries: readonly Entry[];
+    windowStart: number;
+    /**
+     * Measured height of `tailEntries`, once every one of them is stable AND measured at the
+     * current geometry; `undefined` otherwise. `LiveTail` prefers it over the estimate - see
+     * `tail-anchor.ts::resolveTailAnchor` for why the measured answer has to win.
+     */
+    measuredTailRows: number | undefined;
+    /** Rows the top give-way has printed this session; `/perf`'s `head=`. */
+    headRows: number;
+    /** Print a fresh EXPANDED copy of an entry; false when it cannot be found / rendered. */
+    reprintExpanded(entryId: string): boolean;
+    /** Promote everything still unprinted (shutdown) - `flushUnprinted(latest entries)`. */
+    settleAll(): void;
+    /** Called by `App`'s dispatch wrapper BEFORE a reset action reaches the reducer. */
+    notifyReset(kind: ScrollbackResetKind): void;
+}
+export declare function useScrollbackView(args: UseScrollbackViewArgs): ScrollbackView;