@aragon-agent/cli 0.4.3

package/dist/ui/layout/Gutter.js

@@ -0,0 +1,42 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+/** Columns reserved for the rail, glyph included. */
+export const GUTTER_WIDTH = 2;
+export function Gutter({ glyph, color, children }) {
+    return (_jsxs(Box, { flexDirection: "row", children: [_jsx(Box, { flexShrink: 0, width: GUTTER_WIDTH, children: _jsx(Text, { color: color, children: glyph }) }), _jsx(Box, { flexDirection: "column", flexShrink: 0, children: children })] }));
+}
+/**
+ * The one-row gap between turns: a dim rail stub rather than a blank line, so
+ * the eye still follows a continuous left edge across the turn boundary.
+ */
+export function RailSpacer({ continuation, color, }) {
+    return (_jsx(Text, { color: color, children: continuation }));
+}
+/**
+ * A left-only border whose vertical character is the rail glyph.
+ *
+ * Used where a block owns its own lines (tool preview, fenced code) and used to
+ * be wrapped in a round box: the border cost 2 rows plus 2 columns of padding
+ * and nested visibly inside other round boxes. Ink repeats `box.left` for the
+ * measured height of the child, so this is a continuous rail that costs 1 column
+ * and 0 rows.
+ */
+export function railBorderProps(rail, color) {
+    return {
+        borderStyle: {
+            topLeft: rail,
+            top: '',
+            topRight: '',
+            right: '',
+            bottomRight: '',
+            bottom: '',
+            bottomLeft: rail,
+            left: rail,
+        },
+        borderTop: false,
+        borderBottom: false,
+        borderRight: false,
+        borderLeft: true,
+        borderColor: color,
+    };
+}

package/dist/ui/layout/OverlayFrame.d.ts

@@ -0,0 +1,62 @@
+/**
+ * OverlayFrame (spec §4.4) — the shared shell for all four overlays.
+ *
+ * TWO CONTENT MODES, and the distinction is load-bearing:
+ *
+ *  - mode A (`rows`): the caller hands over an array of elements that are each
+ *    exactly one row and `wrap="truncate"`. The frame slices them and OWNS the
+ *    scroll keys. Used by Help and Settings.
+ *
+ *  - mode B (`children`): the content manages itself. The frame draws the title,
+ *    the border and the footer, and touches NOTHING else — no slicing, no
+ *    arrow-key handling, no position indicator.
+ *
+ * Mode B exists because of `ink-select-input`: it already windows itself via
+ * `limit` and registers its own `useInput` with `isFocused` defaulting to true.
+ * Ink dispatches a key to EVERY mounted input handler, so a frame that also
+ * claimed the arrow keys would move the model picker's selection twice per press
+ * — breaking a feature that already works. Slicing it by element would be worse
+ * still, since it is a single component rather than a list of rows.
+ *
+ * `maxRows` may be `Infinity` (the inline render path, which has no fixed frame
+ * and therefore no height to fit): the frame then renders everything and shows
+ * no position indicator.
+ */
+import React from 'react';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+interface OverlayFrameBase {
+    title: string;
+    /** Footer text. Written by the CALLER so each overlay names its own keys. */
+    hint: string;
+    /** Viewport rows the overlay may occupy; `Infinity` in inline mode. */
+    maxRows: number;
+    cols?: number;
+    theme: Theme;
+    caps: TermCapabilities;
+}
+interface OverlayFrameControlled extends OverlayFrameBase {
+    /** One element per row, each already `wrap="truncate"`. */
+    rows: readonly React.ReactElement[];
+    scrollOffset: number;
+    /**
+     * Report the offset back after clamping.
+     *
+     * `sliceWindow` clamps for DISPLAY, but the owner of the state does not learn
+     * about it. A caller that just keeps adding a page per `PgDn` therefore ends
+     * up parked far past the end, and the first several `PgUp` presses then move a
+     * counter nobody can see while the screen sits still — the overlay reads as
+     * frozen. Feeding the clamped value back keeps the two in step.
+     */
+    onScrollClamp?: (offset: number) => void;
+    children?: undefined;
+}
+interface OverlayFrameSelfManaged extends OverlayFrameBase {
+    rows?: undefined;
+    scrollOffset?: undefined;
+    onScrollClamp?: undefined;
+    children: React.ReactNode;
+}
+export type OverlayFrameProps = OverlayFrameControlled | OverlayFrameSelfManaged;
+export declare function OverlayFrame(props: OverlayFrameProps): React.ReactElement;
+export {};

package/dist/ui/layout/OverlayFrame.js

@@ -0,0 +1,92 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * OverlayFrame (spec §4.4) — the shared shell for all four overlays.
+ *
+ * TWO CONTENT MODES, and the distinction is load-bearing:
+ *
+ *  - mode A (`rows`): the caller hands over an array of elements that are each
+ *    exactly one row and `wrap="truncate"`. The frame slices them and OWNS the
+ *    scroll keys. Used by Help and Settings.
+ *
+ *  - mode B (`children`): the content manages itself. The frame draws the title,
+ *    the border and the footer, and touches NOTHING else — no slicing, no
+ *    arrow-key handling, no position indicator.
+ *
+ * Mode B exists because of `ink-select-input`: it already windows itself via
+ * `limit` and registers its own `useInput` with `isFocused` defaulting to true.
+ * Ink dispatches a key to EVERY mounted input handler, so a frame that also
+ * claimed the arrow keys would move the model picker's selection twice per press
+ * — breaking a feature that already works. Slicing it by element would be worse
+ * still, since it is a single component rather than a list of rows.
+ *
+ * `maxRows` may be `Infinity` (the inline render path, which has no fixed frame
+ * and therefore no height to fit): the frame then renders everything and shows
+ * no position indicator.
+ */
+import { useEffect } from 'react';
+import { Box, Text } from 'ink';
+import { pickGlyphs } from '../glyphs.js';
+import { sliceWindow } from './overlay-window.js';
+/** Below this width the round border costs more than it conveys (§5.2). */
+const BORDERLESS_COLS = 48;
+/** Title + footer + top and bottom border. */
+const CHROME_ROWS = 4;
+/**
+ * The frame's own `marginTop`, which is spent out of the SAME `maxRows` budget.
+ *
+ * Leaving it out makes the box render one row taller than the viewport it sits
+ * in, and the viewport's `overflow: hidden` then eats the bottom border — an
+ * overlay silently clipped by exactly the mechanism this round exists to remove.
+ * Verified by `overlay-frame-height.test.tsx`.
+ */
+const MARGIN_ROWS = 1;
+export function OverlayFrame(props) {
+    const { title, hint, maxRows, cols = 80, theme, caps } = props;
+    const glyphs = pickGlyphs(caps);
+    const bordered = cols >= BORDERLESS_COLS;
+    const unbounded = !Number.isFinite(maxRows);
+    let body;
+    let position = '';
+    /** Set only in controlled mode; `null` means "nothing to report back". */
+    let overflowOffset = null;
+    if (props.rows) {
+        const chrome = MARGIN_ROWS + (bordered ? CHROME_ROWS : CHROME_ROWS - 2);
+        const height = unbounded ? props.rows.length : Math.max(1, Math.floor(maxRows) - chrome);
+        const win = sliceWindow(props.rows.length, props.scrollOffset, height);
+        body = props.rows.slice(win.start, win.start + win.visible);
+        if (win.clamped !== props.scrollOffset)
+            overflowOffset = win.clamped;
+        if (!unbounded && win.visible < win.total) {
+            const up = win.start > 0 ? glyphs.arrowUp : ' ';
+            const down = win.start + win.visible < win.total ? glyphs.arrowDown : ' ';
+            position = `  ${up}${down} ${win.start + 1}-${win.start + win.visible}/${win.total}`;
+        }
+    }
+    else {
+        body = props.children;
+    }
+    // In an effect, not in the branch above: calling the owner's setter mid-render
+    // updates another component while this one renders. Clamping is idempotent, so
+    // this settles after one extra pass.
+    const onScrollClamp = props.onScrollClamp;
+    useEffect(() => {
+        if (overflowOffset !== null)
+            onScrollClamp?.(overflowOffset);
+    }, [overflowOffset, onScrollClamp]);
+    const inner = (_jsxs(_Fragment, { children: [_jsx(Text, { wrap: "truncate", color: theme.primary, bold: true, children: title }), body, _jsxs(Text, { wrap: "truncate", color: theme.hintFg ?? theme.muted, children: [hint, position] })] }));
+    if (!bordered) {
+        // Narrow terminals trade the box for a rail: same grouping, 2 fewer rows
+        // and 4 fewer columns (§5.2).
+        return (_jsx(Box, { flexDirection: "column", flexShrink: 0, marginTop: 1, children: _jsx(Box, { flexDirection: "column", flexShrink: 0, borderStyle: {
+                    topLeft: glyphs.railVertical,
+                    top: '',
+                    topRight: '',
+                    right: '',
+                    bottomRight: '',
+                    bottom: '',
+                    bottomLeft: glyphs.railVertical,
+                    left: glyphs.railVertical,
+                }, borderTop: false, borderBottom: false, borderRight: false, borderColor: theme.primary, paddingLeft: 1, children: inner }) }));
+    }
+    return (_jsx(Box, { flexDirection: "column", flexShrink: 0, borderStyle: glyphs.boxStyle, borderColor: theme.primary, paddingX: 1, marginTop: 1, children: inner }));
+}

package/dist/ui/layout/ScrollViewport.d.ts

@@ -0,0 +1,33 @@
+/**
+ * ScrollViewport (spec §4.5) — a self-drawn scrolling window built from Ink's
+ * negative `marginTop` + `overflow: hidden` + `measureElement`.
+ *
+ * Once the frame occupies the whole screen, `<Static>` history is pushed above
+ * the frame where only one line is visible, so native scrollback stops being a
+ * usable mechanism and the app has to own scrolling. That is why this exists.
+ *
+ * SINGLE SOURCE OF TRUTH (review P1-7): both the metrics and the scroll offset
+ * live here. The parent only pushes an *intent* down and receives one derived
+ * *display* number back. Holding the offset in the parent as well would create a
+ * measure → setState → re-render → measure loop whose convergence is provable
+ * but whose frame count is not — expensive inside a 33 ms streaming window.
+ */
+import React from 'react';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+import { type ScrollIntent } from './scroll.js';
+export interface ScrollViewportProps {
+    /** Scroll intent. `nonce` is monotonic so pressing the same key twice re-fires. */
+    intent?: {
+        kind: ScrollIntent;
+        nonce: number;
+    };
+    /** Bumped by the parent to force a pin to the newest output (e.g. on submit). */
+    pinToBottomNonce?: number;
+    /** Derived display value for the status bar's `↑N`. Must be referentially stable. */
+    onScrolledLinesChange?: (lines: number) => void;
+    theme: Theme;
+    caps: TermCapabilities;
+    children: React.ReactNode;
+}
+export declare function ScrollViewport({ intent, pinToBottomNonce, onScrolledLinesChange, theme, caps, children, }: ScrollViewportProps): React.ReactElement;

package/dist/ui/layout/ScrollViewport.js

@@ -0,0 +1,71 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * ScrollViewport (spec §4.5) — a self-drawn scrolling window built from Ink's
+ * negative `marginTop` + `overflow: hidden` + `measureElement`.
+ *
+ * Once the frame occupies the whole screen, `<Static>` history is pushed above
+ * the frame where only one line is visible, so native scrollback stops being a
+ * usable mechanism and the app has to own scrolling. That is why this exists.
+ *
+ * SINGLE SOURCE OF TRUTH (review P1-7): both the metrics and the scroll offset
+ * live here. The parent only pushes an *intent* down and receives one derived
+ * *display* number back. Holding the offset in the parent as well would create a
+ * measure → setState → re-render → measure loop whose convergence is provable
+ * but whose frame count is not — expensive inside a 33 ms streaming window.
+ */
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { Box, Text, measureElement, useStdout } from 'ink';
+import { pickGlyphs } from '../glyphs.js';
+import { applyScroll, clampScroll, } from './scroll.js';
+/** Below this the full hint sentence wraps and eats a second viewport row. */
+const TERSE_HINT_COLS = 42;
+export function ScrollViewport({ intent, pinToBottomNonce = 0, onScrolledLinesChange, theme, caps, children, }) {
+    const { stdout } = useStdout();
+    const cols = stdout?.columns ?? 80;
+    const glyphs = pickGlyphs(caps);
+    const clipRef = useRef(null);
+    const innerRef = useRef(null);
+    const [metrics, setMetrics] = useState({ viewport: 0, content: 0 });
+    const [scroll, setScroll] = useState({ offset: 0 });
+    const metricsRef = useRef(metrics);
+    metricsRef.current = metrics;
+    const intentRef = useRef(intent);
+    intentRef.current = intent;
+    // Ink calculates yoga layout in `onRender`, which React runs BEFORE layout
+    // effects, so the measurement below reflects the commit that just happened.
+    useLayoutEffect(() => {
+        const viewport = clipRef.current ? measureElement(clipRef.current).height : 0;
+        const content = innerRef.current ? measureElement(innerRef.current).height : 0;
+        setMetrics((prev) => (prev.viewport === viewport && prev.content === content ? prev : { viewport, content }));
+    });
+    const intentNonce = intent?.nonce ?? 0;
+    useEffect(() => {
+        const current = intentRef.current;
+        if (!current)
+            return;
+        setScroll((prev) => applyScroll(prev, current.kind, metricsRef.current));
+        // Keyed on the nonce alone: `intent` is a fresh object on every parent
+        // render, so depending on it directly would re-scroll on every keystroke.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [intentNonce]);
+    useEffect(() => {
+        setScroll({ offset: 0 });
+    }, [pinToBottomNonce]);
+    const overflowLines = Math.max(0, metrics.content - metrics.viewport);
+    const offset = clampScroll(scroll.offset, overflowLines);
+    const shiftUp = overflowLines - offset;
+    useEffect(() => {
+        onScrolledLinesChange?.(offset);
+    }, [offset, onScrolledLinesChange]);
+    // `offset` is exactly the count of rows hidden below the viewport — that is
+    // what "N new lines you have not scrolled down to" means.
+    const hiddenBelow = offset;
+    const showHint = hiddenBelow > 0;
+    return (_jsxs(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: [_jsx(Box, { ref: clipRef, flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: _jsx(Box, { ref: innerRef, flexDirection: "column", flexShrink: 0, marginTop: -shiftUp, children: children }) }), showHint && (
+            // Not an overlay — Ink has no absolute positioning or z-index. This takes
+            // the viewport's last row, trading one line of content for a hint that
+            // cannot drift. Cheaper than stacking with negative margins.
+            _jsx(Box, { flexShrink: 0, justifyContent: "flex-end", children: _jsx(Text, { wrap: "truncate", color: theme.hintFg ?? theme.muted, children: cols < TERSE_HINT_COLS
+                        ? `${glyphs.arrowDown}${hiddenBelow}`
+                        : `${glyphs.arrowDown} ${hiddenBelow} new ${hiddenBelow === 1 ? 'line' : 'lines'} ${glyphs.midDot} PgDn for the latest` }) }))] }));
+}

package/dist/ui/layout/budget.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Layout budget (spec §4.2a) — the ONE function that says how many rows the
+ * viewport gets.
+ *
+ * Before v0.4.0 this number was computed nowhere and assumed in three places,
+ * which is how the viewport ended up NON-MONOTONIC in `rows`: growing the
+ * terminal from 27 to 28 rows promoted the header to the 8-row wordmark tier and
+ * the visible content SHRANK from 18 rows to 13. Making the brand region a
+ * constant 1 row (§4.2) is what fixes that, and this module is where the fix is
+ * expressed as arithmetic so `budget.test.ts` can pin it.
+ *
+ * Deliberately NOT part of `frame.ts`: that file is the read-only foundation
+ * (invariant I-1) and this is content-layer policy.
+ *
+ * Scope: the STATIC chrome only. Two consumers are dynamic and are handled by
+ * the degradation ladder in §5.2 instead of being averaged in here:
+ *  - `ScrollViewport`'s "N new lines" hint takes the viewport's own last row;
+ *  - `AutocompletePopup` expands the bottom chrome by up to 9 rows.
+ */
+/** Below this many rows the composer's hint line is dropped to buy back a row. */
+export declare const HINT_MIN_ROWS = 20;
+export interface ChromeBudget {
+    /** Brand bar. Constant 1 in full-screen — this is what makes A-3 hold. */
+    header: number;
+    toast: number;
+    /** Round border (2) + input row (1), plus the hint row when it fits. */
+    composer: number;
+    status: number;
+}
+export declare function chromeBudget(rows: number): ChromeBudget;
+/**
+ * Rows available to the viewport at a given terminal height.
+ *
+ * Note what is NOT a parameter: whether the transcript is empty. The absence of
+ * that argument is the guarantee that the first submitted message cannot make
+ * the layout jump (A-4). Do not add it back.
+ *
+ * Non-decreasing in `rows`: the one step where chrome grows (the hint row at
+ * `HINT_MIN_ROWS`) coincides with `rows` growing by one, so the net change is 0
+ * rather than -1.
+ */
+export declare function viewportRows(rows: number): number;

package/dist/ui/layout/budget.js

@@ -0,0 +1,47 @@
+/**
+ * Layout budget (spec §4.2a) — the ONE function that says how many rows the
+ * viewport gets.
+ *
+ * Before v0.4.0 this number was computed nowhere and assumed in three places,
+ * which is how the viewport ended up NON-MONOTONIC in `rows`: growing the
+ * terminal from 27 to 28 rows promoted the header to the 8-row wordmark tier and
+ * the visible content SHRANK from 18 rows to 13. Making the brand region a
+ * constant 1 row (§4.2) is what fixes that, and this module is where the fix is
+ * expressed as arithmetic so `budget.test.ts` can pin it.
+ *
+ * Deliberately NOT part of `frame.ts`: that file is the read-only foundation
+ * (invariant I-1) and this is content-layer policy.
+ *
+ * Scope: the STATIC chrome only. Two consumers are dynamic and are handled by
+ * the degradation ladder in §5.2 instead of being averaged in here:
+ *  - `ScrollViewport`'s "N new lines" hint takes the viewport's own last row;
+ *  - `AutocompletePopup` expands the bottom chrome by up to 9 rows.
+ */
+import { frameHeight, MIN_FULLSCREEN_ROWS } from './frame.js';
+/** Below this many rows the composer's hint line is dropped to buy back a row. */
+export const HINT_MIN_ROWS = 20;
+export function chromeBudget(rows) {
+    return {
+        header: 1,
+        toast: 1,
+        composer: rows >= HINT_MIN_ROWS ? 4 : 3,
+        status: 1,
+    };
+}
+/**
+ * Rows available to the viewport at a given terminal height.
+ *
+ * Note what is NOT a parameter: whether the transcript is empty. The absence of
+ * that argument is the guarantee that the first submitted message cannot make
+ * the layout jump (A-4). Do not add it back.
+ *
+ * Non-decreasing in `rows`: the one step where chrome grows (the hint row at
+ * `HINT_MIN_ROWS`) coincides with `rows` growing by one, so the net change is 0
+ * rather than -1.
+ */
+export function viewportRows(rows) {
+    if (!Number.isFinite(rows) || rows < MIN_FULLSCREEN_ROWS)
+        return 0;
+    const c = chromeBudget(rows);
+    return Math.max(0, frameHeight(rows) - c.header - c.toast - c.composer - c.status);
+}

package/dist/ui/layout/frame.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Frame geometry + render-mode decision (spec §4.1 / §4.2).
+ *
+ * Two pure functions with zero React dependency so the load-bearing invariant
+ * I-1 (`frameHeight(r) < r`) can be pinned by a unit test rather than by hope.
+ */
+export type RenderMode = 'fullscreen' | 'inline';
+/** Below this many rows a full-screen frame has no usable viewport left. */
+export declare const MIN_FULLSCREEN_ROWS = 12;
+/** Below this many columns the chrome (composer + status bar) cannot line-wrap sanely. */
+export declare const MIN_FULLSCREEN_COLS = 40;
+/** Used when `stdout.rows` is missing (pipes, test stubs, some PTYs). */
+export declare const FALLBACK_ROWS = 24;
+/** Used when `stdout.columns` is missing. */
+export declare const FALLBACK_COLS = 80;
+/**
+ * Frame height. MUST stay strictly below `rows`:
+ *  - `>= rows` hits ink.js:121, which drops incremental `eraseLines` updates and
+ *    writes `clearTerminal + <all Static history> + output` on EVERY frame —
+ *    30×/s under a 33 ms streaming window, with write amplification that grows
+ *    monotonically with the session;
+ *  - `== rows` lets the trailing '\n' log-update appends scroll the buffer by one
+ *    line, so `eraseLines(previousLineCount)` drifts and the frame slowly eats
+ *    the content above it.
+ * `frame.test.ts` asserts `frameHeight(r) < r` for every r in [1, 200].
+ *
+ * The lower clamp is 0 — NEVER `MIN_FULLSCREEN_ROWS - 1` (returns 11 for
+ * rows ∈ [1, 11], i.e. `>= rows`: precisely the clearTerminal disaster this
+ * function exists to prevent) and NEVER 1 either, because `Math.max(1, r - 1)`
+ * returns 1 for r = 1 and `1 >= 1` violates the invariant all the same. That
+ * range IS reachable: §4.11 keeps the alt-screen and renders a "terminal too
+ * small" placeholder when a resize drops below MIN_FULLSCREEN_ROWS, so a user
+ * dragging their window down lands in it. The placeholder takes its height from
+ * this same function. A 0-height frame renders nothing, which on a 1-row
+ * terminal is strictly better than a per-frame full-screen repaint.
+ */
+export declare function frameHeight(rows: number | undefined): number;
+interface StdoutLike {
+    isTTY?: boolean;
+    rows?: number;
+    columns?: number;
+}
+/**
+ * Decide the render mode once, at startup (never re-decided at run time —
+ * entering/leaving the alt-screen mid-session is a state machine we do not want).
+ *
+ * Order is semantics, not style:
+ *  1. an explicit opt-out always wins (users can always get v0.2.0 back);
+ *  2. `isTTY` is the one gate `--fullscreen` cannot override — writing ANSI into
+ *     a pipe or a redirected file is a contract violation, whereas a heuristic
+ *     misfire only costs polish;
+ *  3. the explicit force comes next so it can beat the heuristics below;
+ *  4. heuristics (TERM/CI/size), all overridable by `--fullscreen`.
+ */
+export declare function decideRenderMode(flags: {
+    fullscreen?: boolean;
+}, env: Record<string, string | undefined>, stdout: StdoutLike | undefined): RenderMode;
+export {};

package/dist/ui/layout/frame.js

@@ -0,0 +1,75 @@
+/**
+ * Frame geometry + render-mode decision (spec §4.1 / §4.2).
+ *
+ * Two pure functions with zero React dependency so the load-bearing invariant
+ * I-1 (`frameHeight(r) < r`) can be pinned by a unit test rather than by hope.
+ */
+/** Below this many rows a full-screen frame has no usable viewport left. */
+export const MIN_FULLSCREEN_ROWS = 12;
+/** Below this many columns the chrome (composer + status bar) cannot line-wrap sanely. */
+export const MIN_FULLSCREEN_COLS = 40;
+/** Used when `stdout.rows` is missing (pipes, test stubs, some PTYs). */
+export const FALLBACK_ROWS = 24;
+/** Used when `stdout.columns` is missing. */
+export const FALLBACK_COLS = 80;
+/**
+ * Frame height. MUST stay strictly below `rows`:
+ *  - `>= rows` hits ink.js:121, which drops incremental `eraseLines` updates and
+ *    writes `clearTerminal + <all Static history> + output` on EVERY frame —
+ *    30×/s under a 33 ms streaming window, with write amplification that grows
+ *    monotonically with the session;
+ *  - `== rows` lets the trailing '\n' log-update appends scroll the buffer by one
+ *    line, so `eraseLines(previousLineCount)` drifts and the frame slowly eats
+ *    the content above it.
+ * `frame.test.ts` asserts `frameHeight(r) < r` for every r in [1, 200].
+ *
+ * The lower clamp is 0 — NEVER `MIN_FULLSCREEN_ROWS - 1` (returns 11 for
+ * rows ∈ [1, 11], i.e. `>= rows`: precisely the clearTerminal disaster this
+ * function exists to prevent) and NEVER 1 either, because `Math.max(1, r - 1)`
+ * returns 1 for r = 1 and `1 >= 1` violates the invariant all the same. That
+ * range IS reachable: §4.11 keeps the alt-screen and renders a "terminal too
+ * small" placeholder when a resize drops below MIN_FULLSCREEN_ROWS, so a user
+ * dragging their window down lands in it. The placeholder takes its height from
+ * this same function. A 0-height frame renders nothing, which on a 1-row
+ * terminal is strictly better than a per-frame full-screen repaint.
+ */
+export function frameHeight(rows) {
+    const r = rows && rows > 0 ? rows : FALLBACK_ROWS;
+    return Math.max(0, r - 1);
+}
+/** `CI=` / `CI=0` / `CI=false` are not CI; anything else non-empty is. */
+function isTruthyEnv(value) {
+    if (value === undefined)
+        return false;
+    const v = value.trim().toLowerCase();
+    return v.length > 0 && v !== '0' && v !== 'false';
+}
+/**
+ * Decide the render mode once, at startup (never re-decided at run time —
+ * entering/leaving the alt-screen mid-session is a state machine we do not want).
+ *
+ * Order is semantics, not style:
+ *  1. an explicit opt-out always wins (users can always get v0.2.0 back);
+ *  2. `isTTY` is the one gate `--fullscreen` cannot override — writing ANSI into
+ *     a pipe or a redirected file is a contract violation, whereas a heuristic
+ *     misfire only costs polish;
+ *  3. the explicit force comes next so it can beat the heuristics below;
+ *  4. heuristics (TERM/CI/size), all overridable by `--fullscreen`.
+ */
+export function decideRenderMode(flags, env, stdout) {
+    if (flags.fullscreen === false)
+        return 'inline';
+    if (!stdout?.isTTY)
+        return 'inline';
+    if (flags.fullscreen === true)
+        return 'fullscreen';
+    if (env.TERM === 'dumb')
+        return 'inline';
+    if (isTruthyEnv(env.CI))
+        return 'inline';
+    if ((stdout.rows ?? 0) < MIN_FULLSCREEN_ROWS)
+        return 'inline';
+    if ((stdout.columns ?? 0) < MIN_FULLSCREEN_COLS)
+        return 'inline';
+    return 'fullscreen';
+}

package/dist/ui/layout/overlay-window.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Overlay windowing (spec §4.4) — pure arithmetic for `OverlayFrame`.
+ *
+ * Overlays used to be dropped into `<Box overflow="hidden">` with no scrolling
+ * and no indication that anything had been cut: `/help` needs 29 rows, a 30-row
+ * terminal gave it 15, and everything from `/clear` downward was simply invisible.
+ *
+ * This does NOT reuse `ScrollViewport`. That component owns its offset in its own
+ * state as a deliberate single-source-of-truth decision, so routing an overlay
+ * through the same instance would leave the transcript parked at the overlay's
+ * offset after closing. Overlay content is finite and already in memory, so
+ * slicing an array is both cheaper and free of a second `measureElement` loop.
+ */
+export interface OverlayWindow {
+    /** First visible index. */
+    start: number;
+    /** How many rows are visible. */
+    visible: number;
+    total: number;
+    /** The requested offset after clamping — feed this back to keep state sane. */
+    clamped: number;
+}
+/**
+ * Slice `total` single-row items to a `height`-row window at `offset`.
+ *
+ * Guarantees for every input, including negative / absurd offsets and
+ * non-finite heights: `0 <= start` and `start + visible <= total` (A-2).
+ */
+export declare function sliceWindow(total: number, offset: number, height: number): OverlayWindow;
+/**
+ * Visible-row budget for a self-managed (mode B) overlay list — i.e. the `limit`
+ * handed to `ink-select-input` in the model picker.
+ *
+ * A pure function rather than an inline expression because the test stack only
+ * returns rendered strings: there is no way to read a child's props back, so the
+ * only way to pin this behaviour (A-11) is to test the arithmetic directly.
+ *
+ * The 5 rows subtracted are the frame's own chrome: title, footer, the top and
+ * bottom border, and the frame's `marginTop` — which is spent out of the same
+ * budget, so leaving it out pushes the bottom border past the viewport where
+ * `overflow: hidden` silently eats it.
+ */
+export declare function overlayListLimit(maxRows: number): number;

package/dist/ui/layout/overlay-window.js

@@ -0,0 +1,51 @@
+/**
+ * Overlay windowing (spec §4.4) — pure arithmetic for `OverlayFrame`.
+ *
+ * Overlays used to be dropped into `<Box overflow="hidden">` with no scrolling
+ * and no indication that anything had been cut: `/help` needs 29 rows, a 30-row
+ * terminal gave it 15, and everything from `/clear` downward was simply invisible.
+ *
+ * This does NOT reuse `ScrollViewport`. That component owns its offset in its own
+ * state as a deliberate single-source-of-truth decision, so routing an overlay
+ * through the same instance would leave the transcript parked at the overlay's
+ * offset after closing. Overlay content is finite and already in memory, so
+ * slicing an array is both cheaper and free of a second `measureElement` loop.
+ */
+/**
+ * Slice `total` single-row items to a `height`-row window at `offset`.
+ *
+ * Guarantees for every input, including negative / absurd offsets and
+ * non-finite heights: `0 <= start` and `start + visible <= total` (A-2).
+ */
+export function sliceWindow(total, offset, height) {
+    const t = Number.isFinite(total) ? Math.max(0, Math.floor(total)) : 0;
+    const h = Number.isFinite(height) ? Math.max(0, Math.floor(height)) : t;
+    const visible = Math.min(t, h);
+    const maxOffset = Math.max(0, t - visible);
+    const raw = Number.isFinite(offset) ? Math.floor(offset) : 0;
+    const clamped = Math.min(maxOffset, Math.max(0, raw));
+    return { start: clamped, visible, total: t, clamped };
+}
+/** Smallest list window worth showing before scrolling stops helping. */
+const MIN_LIST_LIMIT = 3;
+/** Beyond this a picker is a scroll problem, not a list problem. */
+const MAX_LIST_LIMIT = 20;
+/**
+ * Visible-row budget for a self-managed (mode B) overlay list — i.e. the `limit`
+ * handed to `ink-select-input` in the model picker.
+ *
+ * A pure function rather than an inline expression because the test stack only
+ * returns rendered strings: there is no way to read a child's props back, so the
+ * only way to pin this behaviour (A-11) is to test the arithmetic directly.
+ *
+ * The 5 rows subtracted are the frame's own chrome: title, footer, the top and
+ * bottom border, and the frame's `marginTop` — which is spent out of the same
+ * budget, so leaving it out pushes the bottom border past the viewport where
+ * `overflow: hidden` silently eats it.
+ */
+export function overlayListLimit(maxRows) {
+    if (!Number.isFinite(maxRows))
+        return MAX_LIST_LIMIT;
+    const usable = Math.floor(maxRows) - 5;
+    return Math.min(MAX_LIST_LIMIT, Math.max(MIN_LIST_LIMIT, usable));
+}

package/dist/ui/layout/scroll.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Scroll maths for the self-drawn viewport (spec §4.5). Pure, React-free.
+ *
+ * `offset` counts LINES FROM THE BOTTOM — equivalently, the number of rows
+ * currently hidden BELOW the viewport. `0` means pinned to the newest output;
+ * `overflowLines` means parked at the very top. Counting from the bottom is what
+ * makes auto-follow free: when new content arrives `overflowLines` grows while
+ * `offset` stays 0, so the viewport keeps showing the tail without anyone
+ * calling a "scroll to bottom" routine.
+ *
+ * The rows hidden ABOVE are therefore `overflowLines - offset`. Mixing the two
+ * up inverts both the bottom-snap test and the "N new lines" hint.
+ */
+export interface ScrollState {
+    offset: number;
+}
+export interface ViewportMetrics {
+    /** Visible height of the clipping box, in rows. */
+    viewport: number;
+    /** Natural (unclipped) height of the content, in rows. */
+    content: number;
+}
+export type ScrollIntent = 'lineUp' | 'lineDown' | 'pageUp' | 'pageDown' | 'toTop' | 'toBottom';
+export declare const BOTTOM_SNAP_TOLERANCE = 2;
+export declare function clampScroll(offset: number, overflowLines: number): number;
+export declare function pageSize(viewportHeight: number): number;
+export declare function isPinnedToBottom(state: ScrollState): boolean;
+export declare function applyScroll(state: ScrollState, intent: ScrollIntent, metrics: ViewportMetrics): ScrollState;