@aragon-agent/cli 0.6.2 → 0.6.4

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

@@ -11,11 +11,23 @@
  * *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.
+ *
+ * AS OF tui-selection-and-scroll-follow THIS IS AN ADAPTER, NOT A POLICY OWNER.
+ * The two follow rules are pure and live in `follow-state.ts`; what stays here is
+ * measure → compute a tail delta → apply → arm a timer. `scroll.ts` is
+ * unchanged, so every existing scroll test keeps passing (R-10).
+ *
+ * The "N new lines · PgDn" hint used to take this viewport's LAST ROW. It now
+ * renders as a chip inside the composer's bordered input row (§4.2), which costs
+ * zero rows and removes the feedback loop where the hint's own presence shrank
+ * the viewport, which changed `overflowLines`, which was the number the hint
+ * displayed. The data still leaves through `onScrolledLinesChange`.
  */
 import React from 'react';
 import type { Theme } from '../theme.js';
 import type { TermCapabilities } from '../capabilities.js';
 import { type ScrollIntent } from './scroll.js';
+import { type TailSink } from './follow-state.js';
 export interface ScrollViewportProps {
     /**
      * Scroll intent. `nonce` is monotonic so pressing the same key twice re-fires.
@@ -30,6 +42,31 @@ export interface ScrollViewportProps {
     pinToBottomNonce?: number;
     /** Derived display value for the status bar's `↑N`. Must be referentially stable. */
     onScrolledLinesChange?: (lines: number) => void;
+    /**
+     * Rows hidden ABOVE the window, published on every change (§4.3.3).
+     *
+     * PUBLISHED, NOT LIFTED — the same shape as `onScrolledLinesChange`, so there
+     * is still exactly one owner of the offset. `shiftUp` changes exactly when the
+     * rows on screen move, which is the property the selection's clear-list was
+     * approximating by enumeration (I-9 / P1-4). Must be referentially stable.
+     */
+    onViewportShiftChange?: (shiftUp: number) => void;
+    /**
+     * The transcript's tail row counter (§4.3.1a), written during ITS render and
+     * therefore already current when this component's layout effect runs.
+     *
+     * ABSENT ⇒ NO ANCHORING AT ALL, deliberately: every existing caller and every
+     * existing test that does not supply it behaves exactly as it did before this
+     * feature, because `tailDelta` is then permanently 0.
+     */
+    tailRowsRef?: TailSink;
+    /**
+     * True while a selection drag is in progress (§4.4). It anchors the content
+     * even from a pinned viewport, and it suspends the resume timer.
+     */
+    hold?: boolean;
+    /** Idle delay before returning to the newest line, in ms; `0` disables (AC-9). */
+    resumeMs?: number;
     /** Reserve the right-edge scroll-position rail (mouse-wheel §4.8). */
     showScrollIndicator?: boolean;
     /**
@@ -37,15 +74,15 @@ export interface ScrollViewportProps {
      * (todo-plan-execution §3.9 / C-7).
      *
      * This component is the ONLY one inside the viewport subtree that reads
-     * `stdout.columns` directly, and both places it uses the number — the terse
-     * hint threshold and the `MIN_INDICATOR_COLS` gate — are about how much room
-     * THIS BOX has, not how wide the terminal is. Once the todo rail takes a fifth
-     * of the frame those two stop being the same number. Optional so every
-     * existing caller (and every test) is unchanged.
+     * `stdout.columns` directly, and the place it uses the number — the
+     * `MIN_INDICATOR_COLS` gate — is about how much room THIS BOX has, not how
+     * wide the terminal is. Once the todo rail takes a fifth of the frame those two
+     * stop being the same number. Optional so every existing caller (and every
+     * test) is unchanged.
      */
     cols?: number;
     theme: Theme;
     caps: TermCapabilities;
     children: React.ReactNode;
 }
-export declare function ScrollViewport({ intent, pinToBottomNonce, onScrolledLinesChange, showScrollIndicator, cols: colsProp, theme, caps, children, }: ScrollViewportProps): React.ReactElement;
+export declare function ScrollViewport({ intent, pinToBottomNonce, onScrolledLinesChange, onViewportShiftChange, tailRowsRef, hold, resumeMs, showScrollIndicator, cols: colsProp, theme, caps, children, }: ScrollViewportProps): React.ReactElement;

package/dist/ui/layout/ScrollViewport.js

@@ -12,34 +12,132 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * *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.
+ *
+ * AS OF tui-selection-and-scroll-follow THIS IS AN ADAPTER, NOT A POLICY OWNER.
+ * The two follow rules are pure and live in `follow-state.ts`; what stays here is
+ * measure → compute a tail delta → apply → arm a timer. `scroll.ts` is
+ * unchanged, so every existing scroll test keeps passing (R-10).
+ *
+ * The "N new lines · PgDn" hint used to take this viewport's LAST ROW. It now
+ * renders as a chip inside the composer's bordered input row (§4.2), which costs
+ * zero rows and removes the feedback loop where the hint's own presence shrank
+ * the viewport, which changed `overflowLines`, which was the number the hint
+ * displayed. The data still leaves through `onScrolledLinesChange`.
  */
-import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
-import { Box, Text, measureElement, useStdout } from 'ink';
-import { pickGlyphs } from '../glyphs.js';
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { Box, measureElement, useStdout } from 'ink';
 import { ViewportGeometryContext } from './viewport-geometry.js';
 import { applyScrollTimes, clampScroll, } from './scroll.js';
+import { reduceFollow, shouldArmResume } from './follow-state.js';
 import { thumbRange } from './scroll-indicator.js';
 import { MIN_INDICATOR_COLS, ScrollIndicator } from './ScrollIndicator.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, showScrollIndicator = false, cols: colsProp, theme, caps, children, }) {
+export function ScrollViewport({ intent, pinToBottomNonce = 0, onScrolledLinesChange, onViewportShiftChange, tailRowsRef, hold = false, resumeMs = 0, showScrollIndicator = false, cols: colsProp, theme, caps, children, }) {
     const { stdout } = useStdout();
     const cols = colsProp ?? 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 overflowLines = Math.max(0, metrics.content - metrics.viewport);
+    const offset = clampScroll(scroll.offset, overflowLines);
+    const shiftUp = overflowLines - offset;
     const metricsRef = useRef(metrics);
     metricsRef.current = metrics;
     const intentRef = useRef(intent);
     intentRef.current = intent;
+    /**
+     * The RENDERED (clamped) offset, assigned during render (P1-9).
+     *
+     * `scroll.offset` is raw state while everything on screen derives from
+     * `clampScroll(...)`; the two diverge after any content shrink (`/clear`, the
+     * retain ring, a re-wrap), and an accumulation against the raw value then yanks
+     * a viewport the user believes is pinned and shows a phantom chip.
+     */
+    const offsetRef = useRef(offset);
+    offsetRef.current = offset;
+    /** Read at timer FIRE time, not only at ARM time (I-6). */
+    const holdRef = useRef(hold);
+    holdRef.current = hold;
+    const resumeMsRef = useRef(resumeMs);
+    resumeMsRef.current = resumeMs;
+    /** Rows that arrived while paused; resets to 0 whenever the offset reaches 0. */
+    const newLinesRef = useRef(0);
+    const prevTail = useRef(0);
+    const resumeTimer = useRef(null);
+    const clearResumeTimer = useCallback(() => {
+        if (!resumeTimer.current)
+            return;
+        clearTimeout(resumeTimer.current);
+        resumeTimer.current = null;
+    }, []);
+    /**
+     * Rule B. Called from exactly three places and no others: the intent effect
+     * (after applying a scroll), the anchoring effect (after a non-zero
+     * `tailDelta`), and every `hold` transition.
+     *
+     * The re-check inside the callback is the same class of bug the wheel router's
+     * flush already guards: the decision that goes stale is the one taken when the
+     * timer was ARMED, and 5 seconds is an eternity next to a 16 ms coalescing
+     * window.
+     */
+    const armResume = useCallback(() => {
+        clearResumeTimer();
+        if (!shouldArmResume({
+            resumeMs: resumeMsRef.current,
+            offset: offsetRef.current,
+            newLinesWhilePaused: newLinesRef.current,
+            hold: holdRef.current,
+        })) {
+            return;
+        }
+        const timer = setTimeout(() => {
+            resumeTimer.current = null;
+            if (holdRef.current)
+                return; // I-6 — re-read at FIRE time.
+            setScroll({ offset: 0 });
+        }, resumeMsRef.current);
+        timer.unref?.();
+        resumeTimer.current = timer;
+    }, [clearResumeTimer]);
+    // A timer that outlives the component would fire `setScroll` on an unmounted
+    // tree; an overlay unmounts this component on every open.
+    useEffect(() => clearResumeTimer, [clearResumeTimer]);
     // Ink calculates yoga layout in `onRender`, which React runs BEFORE layout
     // effects, so the measurement below reflects the commit that just happened.
+    // The children have already rendered, so `tailRowsRef` is current too.
     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 }));
+        // RULE A. The input is the transcript's TAIL counter and never `content`
+        // (P0-1 / I-7) — see the header of `follow-state.ts` for the four things
+        // that move a measured height and the one that must move the offset.
+        const tail = tailRowsRef?.current.rows ?? 0;
+        const tailDelta = tail - prevTail.current;
+        prevTail.current = tail;
+        if (tailDelta === 0)
+            return; // the steady state, and R-8's loop guard
+        const overflow = Math.max(0, content - viewport);
+        // THE DECISION IS TAKEN OUTSIDE THE UPDATER (P1-9). React is free to invoke
+        // an updater more than once, and a `newLinesWhilePaused += delta` inside one
+        // double-counts when it does.
+        const out = reduceFollow({
+            offset: clampScroll(offsetRef.current, overflow),
+            overflowLines: overflow,
+            tailDelta,
+            hold: holdRef.current,
+            newLinesWhilePaused: newLinesRef.current,
+        });
+        newLinesRef.current = out.newLinesWhilePaused;
+        if (out.offset !== offsetRef.current) {
+            // Assigned eagerly so the `armResume()` below decides against the offset
+            // this frame is about to render, not the one it replaced. `out.offset` is
+            // already clamped against the freshly measured overflow, which is exactly
+            // what the next render will clamp against.
+            offsetRef.current = out.offset;
+            setScroll({ offset: out.offset });
+        }
+        armResume();
     });
     // I-9: seeded from the INCOMING nonce during the first render, so the effect
     // below cannot apply an intent on the mount that first observes it. A
@@ -61,6 +159,9 @@ export function ScrollViewport({ intent, pinToBottomNonce = 0, onScrolledLinesCh
         lastAppliedNonce.current = current.nonce;
         const repeat = current.repeat ?? 1;
         setScroll((prev) => applyScrollTimes(prev, current.kind, metricsRef.current, repeat));
+        // T-21 — "用户没动" is measured from the last GESTURE, so every applied
+        // intent restarts the countdown.
+        armResume();
         // 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
@@ -68,16 +169,28 @@ export function ScrollViewport({ intent, pinToBottomNonce = 0, onScrolledLinesCh
     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;
+    useEffect(() => {
+        onViewportShiftChange?.(shiftUp);
+    }, [shiftUp, onViewportShiftChange]);
+    // Reaching the bottom BY ANY ROUTE — the timer, `pinToBottomNonce`, PgDn, or
+    // `applyScroll`'s bottom snap — resets the paused counter and disarms. The
+    // anchoring route expresses the same reset inside `reduceFollow`, so the rule
+    // is stated once per route rather than once per gesture.
+    useEffect(() => {
+        if (offset !== 0)
+            return;
+        newLinesRef.current = 0;
+        armResume(); // clears; re-arming is refused at offset 0 by condition 1.
+    }, [offset, armResume]);
+    // Both `hold` edges. Rising suspends the countdown (condition 3); falling
+    // restarts it, which is what makes a released drag behave like any other
+    // finished gesture.
+    useEffect(() => {
+        armResume();
+    }, [hold, armResume]);
     // Suppressed below `MIN_INDICATOR_COLS`, where a column of content is worth
     // more than the affordance. The routing never reads this flag, which is what
     // keeps the indicator independently revertible (§13-Q3).
@@ -87,11 +200,5 @@ export function ScrollViewport({ intent, pinToBottomNonce = 0, onScrolledLinesCh
     // value hands them down without adding a second owner or a second measure
     // pass, which is exactly what this component's header (P1-7) forbids.
     const geometry = useMemo(() => ({ viewportRows: metrics.viewport, offset, contentRows: metrics.content }), [metrics.viewport, metrics.content, offset]);
-    return (_jsxs(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: [_jsxs(Box, { flexDirection: "row", 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: _jsx(ViewportGeometryContext.Provider, { value: geometry, children: children }) }) }), indicatorVisible && (_jsx(ScrollIndicator, { rows: metrics.viewport, thumb: thumbRange(metrics.viewport, metrics.content, offset), theme: theme, caps: caps }))] }), 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` }) }))] }));
+    return (_jsx(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: _jsxs(Box, { flexDirection: "row", 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: _jsx(ViewportGeometryContext.Provider, { value: geometry, children: children }) }) }), indicatorVisible && (_jsx(ScrollIndicator, { rows: metrics.viewport, thumb: thumbRange(metrics.viewport, metrics.content, offset), theme: theme, caps: caps }))] }) }));
 }

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

@@ -12,10 +12,17 @@
  * 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;
+ * Scope: the STATIC chrome only. One consumer is dynamic and is handled by the
+ * degradation ladder in §5.2 instead of being averaged in here:
  *  - `AutocompletePopup` expands the bottom chrome by up to 9 rows.
+ *
+ * `ScrollViewport`'s "N new lines" hint used to be listed here as a second
+ * dynamic consumer. It no longer exists: the number renders as a chip on the
+ * composer's input row (tui-selection-and-scroll-follow §4.2), which costs
+ * COLUMNS rather than rows. The arithmetic below is unchanged — the hint was
+ * never in the budget in the first place — but leaving the bullet in place would
+ * make this comment a true-sounding statement about a row that is gone (AC-12,
+ * and the `wheel-scrolls-transcript-only` RV-3 lesson).
  */
 /** Below this many rows the composer's hint line is dropped to buy back a row. */
 export declare const HINT_MIN_ROWS = 20;
@@ -23,11 +30,26 @@ 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. */
+    /**
+     * Round border (2) + the DRAFT's own rows, plus the hint row when it fits.
+     *
+     * The draft term used to be the constant 1 that the `3` / `4` below encode.
+     * That constant is what made a pasted 200-line draft draw the transcript 197
+     * rows shorter than every consumer of `viewportRows` believed -- the trap
+     * `BottomStatusRow.tsx:5-27` already documents at 1/200th the magnitude.
+     */
     composer: number;
     status: number;
 }
-export declare function chromeBudget(rows: number): ChromeBudget;
+/**
+ * The composer's draft rows, clamped to what this terminal height allows.
+ *
+ * Exported so the reporter and the budget clamp with ONE function: I-8 requires
+ * the rendered row count and the number handed to `viewportRows` to be the same
+ * number, and two clamps are how they stop being.
+ */
+export declare function clampDraftRows(rows: number, draftRows: number): number;
+export declare function chromeBudget(rows: number, draftRows?: number): ChromeBudget;
 /**
  * Rows available to the viewport at a given terminal height.
  *
@@ -35,8 +57,21 @@ export declare function chromeBudget(rows: number): ChromeBudget;
  * 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.
+ * `draftRows` IS NOT THAT ARGUMENT, and the distinction is the whole of D-12.
+ * A-4 forbids making the budget depend on TRANSCRIPT content, so that the first
+ * submitted message cannot move the layout. `draftRows` depends only on what the
+ * user is typing right now, and its whole purpose is that the jump is ALREADY
+ * HAPPENING -- Yoga takes the rows out of the transcript whether or not this
+ * function was told. `App` adds the hysteresis (grow now, shrink one tick later)
+ * that keeps it from becoming per-keystroke jitter.
+ *
+ * It DEFAULTS TO 1, i.e. to the constant this function used to assume, so every
+ * pre-existing caller and every pre-existing assertion is byte-identical -- and
+ * `viewportRows.length` stays 1, because a parameter with a default does not
+ * count toward it.
+ *
+ * Non-decreasing in `rows` at a fixed `draftRows = 1`: 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;
+export declare function viewportRows(rows: number, draftRows?: number): number;

package/dist/ui/layout/budget.js

@@ -12,19 +12,38 @@
  * 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;
+ * Scope: the STATIC chrome only. One consumer is dynamic and is handled by the
+ * degradation ladder in §5.2 instead of being averaged in here:
  *  - `AutocompletePopup` expands the bottom chrome by up to 9 rows.
+ *
+ * `ScrollViewport`'s "N new lines" hint used to be listed here as a second
+ * dynamic consumer. It no longer exists: the number renders as a chip on the
+ * composer's input row (tui-selection-and-scroll-follow §4.2), which costs
+ * COLUMNS rather than rows. The arithmetic below is unchanged — the hint was
+ * never in the budget in the first place — but leaving the bullet in place would
+ * make this comment a true-sounding statement about a row that is gone (AC-12,
+ * and the `wheel-scrolls-transcript-only` RV-3 lesson).
  */
+import { draftMaxRows } from '../composer-limits.js';
 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) {
+/**
+ * The composer's draft rows, clamped to what this terminal height allows.
+ *
+ * Exported so the reporter and the budget clamp with ONE function: I-8 requires
+ * the rendered row count and the number handed to `viewportRows` to be the same
+ * number, and two clamps are how they stop being.
+ */
+export function clampDraftRows(rows, draftRows) {
+    const wanted = Number.isFinite(draftRows) ? Math.floor(draftRows) : 1;
+    return Math.max(1, Math.min(wanted, draftMaxRows(rows)));
+}
+export function chromeBudget(rows, draftRows = 1) {
     return {
         header: 1,
         toast: 1,
-        composer: rows >= HINT_MIN_ROWS ? 4 : 3,
+        composer: 2 + clampDraftRows(rows, draftRows) + (rows >= HINT_MIN_ROWS ? 1 : 0),
         status: 1,
     };
 }
@@ -35,13 +54,26 @@ export function chromeBudget(rows) {
  * 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.
+ * `draftRows` IS NOT THAT ARGUMENT, and the distinction is the whole of D-12.
+ * A-4 forbids making the budget depend on TRANSCRIPT content, so that the first
+ * submitted message cannot move the layout. `draftRows` depends only on what the
+ * user is typing right now, and its whole purpose is that the jump is ALREADY
+ * HAPPENING -- Yoga takes the rows out of the transcript whether or not this
+ * function was told. `App` adds the hysteresis (grow now, shrink one tick later)
+ * that keeps it from becoming per-keystroke jitter.
+ *
+ * It DEFAULTS TO 1, i.e. to the constant this function used to assume, so every
+ * pre-existing caller and every pre-existing assertion is byte-identical -- and
+ * `viewportRows.length` stays 1, because a parameter with a default does not
+ * count toward it.
+ *
+ * Non-decreasing in `rows` at a fixed `draftRows = 1`: 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) {
+export function viewportRows(rows, draftRows = 1) {
     if (!Number.isFinite(rows) || rows < MIN_FULLSCREEN_ROWS)
         return 0;
-    const c = chromeBudget(rows);
+    const c = chromeBudget(rows, draftRows);
     return Math.max(0, frameHeight(rows) - c.header - c.toast - c.composer - c.status);
 }

package/dist/ui/layout/follow-state.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Follow rules for the self-drawn viewport (tui-selection-and-scroll-follow
+ * §4.3). PURE, React-free, unit-tested — the shape `scroll.ts`,
+ * `virtual-window.ts` and `frame-differ.ts` all already use.
+ *
+ * It lives here rather than inside `ScrollViewport` because
+ * `ink-testing-library`'s stdout stub reports no height, so a MOUNTED viewport
+ * measures `content === viewport`, `overflowLines === 0`, and neither rule below
+ * ever engages (`__tests__/render-at-width.ts`, and `transcript-virtual.test.tsx`
+ * records the same limitation and the same workaround). A state machine that can
+ * only be exercised through a box the test cannot size is a state machine with
+ * no tests (P1-10).
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * NOTHING IN THIS FILE MAY READ A MEASUREMENT (AC-17, and it is a `grep`).
+ *
+ * The gate is a `grep` for the name of Ink's element-measuring helper returning
+ * NOTHING from this file, so that name is deliberately left unspelled here and
+ * below, even where writing it would read more directly. A grep a COMMENT can
+ * trip is a grep whoever runs it learns to ignore, and then the import it exists
+ * to catch walks straight past it — the same reason `glyphs.test.ts` strips
+ * comments before judging a line.
+ *
+ * The transcript's MEASURED CONTENT HEIGHT — what `ScrollViewport` reads out of
+ * Ink's layout for the inner box — is the height of everything the transcript is
+ * currently drawing, and FOUR different things move it — only one of which is
+ * "the agent produced output":
+ *
+ *   1. rows appended at the tail                        <- Rule A must react
+ *   2. an entry ABOVE the reading position changing     <- must NOT move
+ *      height (Ctrl+T, Ctrl+O, a first real measurement
+ *      of an entry that stood on an estimate)
+ *   3. the scroll horizon dropping entries off the      <- must NOT move
+ *      FRONT (`Transcript.tsx`, `entries.slice(-size)`)
+ *   4. a re-wrap after a resize                         <- must NOT move
+ *
+ * For (2) and (3) `virtual-window.ts`'s invariant V-4 is explicit: counting the
+ * offset FROM THE BOTTOM makes an above-the-viewport height change
+ * self-compensating, and that is what buys virtualisation its "no
+ * scroll-anchoring compensation pass required". Reacting to total content growth
+ * would make Rule A that compensation pass, applied to changes that never needed
+ * compensating — and it would additionally make (3) look like new output and arm
+ * the idle timer on a transcript that produced nothing, the exact failure G6
+ * exists to prevent.
+ *
+ * There is a second, sharper reason. `selectWindow` TAKES `offset` AS AN INPUT,
+ * so the mounted set — and therefore which entries are measured rather than
+ * estimated — is a function of the offset. An offset that is in turn a function
+ * of the measured height closes a loop: offset -> mounted set -> measured
+ * heights -> content height -> offset. The loop is broken by the INPUT rather
+ * than by a convergence argument: `advanceTailRows` reads the height table and
+ * never the geometry context (P0-1 / D-13).
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
+export interface FollowInput {
+    /** Current RENDERED (already clamped) offset — see the caller's P1-9 note. */
+    offset: number;
+    overflowLines: number;
+    /** Signed: rows appended at (or removed from) the tail since the last frame. */
+    tailDelta: number;
+    /** True while a selection drag holds the viewport (§4.4). */
+    hold: boolean;
+    newLinesWhilePaused: number;
+}
+export interface FollowOutput {
+    offset: number;
+    newLinesWhilePaused: number;
+}
+/**
+ * Rule A. When rows are appended AT THE TAIL while the user is not pinned to the
+ * bottom, grow the offset by the same amount: `shiftUp = overflowLines - offset`
+ * is then constant and the rows on screen do not move.
+ *
+ * SIGNED, NOT GROWTH-ONLY (I-7). A tail SHRINK is rows that no longer exist
+ * below the reading position, so shrinking the offset by the same amount is what
+ * keeps the screen still — and it is self-correcting when the source of the
+ * delta was an upper-bound height estimate that a later measurement brings down
+ * (`estimateEntryRows` is deliberately an upper bound). An unsigned rule
+ * over-counts once and never finds its way back.
+ */
+export declare function reduceFollow(input: FollowInput): FollowOutput;
+export interface ResumeInput {
+    /** `scrollResumeMs`; `0` (or anything non-finite) disables auto-resume. */
+    resumeMs: number;
+    offset: number;
+    newLinesWhilePaused: number;
+    hold: boolean;
+}
+/**
+ * Rule B's three conditions, and they are three rather than one on purpose:
+ *
+ *  1. `offset > 0`   — there is somewhere to return FROM;
+ *  2. `newLines > 0` — something arrived that is worth returning TO. THIS IS
+ *     G6: a user reading a FINISHED transcript is never yanked to the bottom,
+ *     which is the new bug that a timing-only rule would ship wearing the fix's
+ *     clothes (D-3);
+ *  3. `!hold`        — no selection drag is in progress (§4.4).
+ *
+ * AC-9 rides on the first line: with `scrollResumeMs: 0` this returns `false`
+ * before anything else is considered, so no timer is ever created.
+ */
+export declare function shouldArmResume(input: ResumeInput): boolean;
+/**
+ * What the transcript publishes through a ref written during render.
+ *
+ * `lastHeight` is not decoration: §4.3.1a defines the per-frame delta as "heights
+ * of entries after the previously-last entry PLUS the delta of that entry's own
+ * height (a streaming entry grows in place)", and the second term cannot be
+ * computed without remembering what that height was.
+ */
+export interface TailState {
+    /** Monotonic-ish cumulative count of rows produced at the tail. Signed deltas. */
+    rows: number;
+    /** Identity anchor — the last entry's id when this state was written. */
+    lastId: string | null;
+    /** That entry's height when this state was written. */
+    lastHeight: number;
+}
+export interface TailSink {
+    current: TailState;
+}
+export declare function emptyTailState(): TailState;
+/**
+ * Advance the tail counter by one frame.
+ *
+ * `ids` are the entries the transcript is drawing, in order; `heightOf(index)`
+ * is the transcript's own per-entry height table (measured where it exists, an
+ * upper-bound estimate where it does not). NO GEOMETRY IS READ HERE, which is
+ * what breaks P0-1's loop by construction.
+ *
+ * RE-ANCHORING CONTRIBUTES ZERO (R-11). When the scroll horizon drops the entry
+ * this counter was anchored on, the anchor is simply moved to the new last entry
+ * and the frame contributes a delta of 0. Losing one frame of anchoring is a row
+ * of drift at worst; treating a FRONT-DROP as tail motion is a visible jump, and
+ * an unbounded one.
+ */
+export declare function advanceTailRows(prev: TailState, ids: readonly string[], heightOf: (index: number) => number): TailState;