@aragon-agent/cli 0.6.2 → 0.6.3

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;

package/dist/ui/layout/budget.js

@@ -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).
  */
 import { frameHeight, MIN_FULLSCREEN_ROWS } from './frame.js';
 /** Below this many rows the composer's hint line is dropped to buy back a row. */

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;

package/dist/ui/layout/follow-state.js

@@ -0,0 +1,150 @@
+/**
+ * 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).
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
+import { clampScroll } from './scroll.js';
+/**
+ * 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 function reduceFollow(input) {
+    const { offset, overflowLines, tailDelta, hold } = input;
+    // Pinned and not holding: anchoring is free — `offset` stays 0 and the
+    // existing arithmetic keeps showing the tail. `hold` LIFTS the precondition
+    // because a drag that starts while pinned must still freeze the rows under the
+    // pointer (S3), and freezing means the pin becomes an anchor for the duration
+    // of the drag (T-20).
+    if (offset === 0 && !hold)
+        return { offset, newLinesWhilePaused: 0 };
+    if (tailDelta === 0)
+        return { offset, newLinesWhilePaused: input.newLinesWhilePaused };
+    const next = clampScroll(offset + tailDelta, overflowLines);
+    return {
+        offset: next,
+        // Only real arrivals arm the resume timer, and reaching the bottom by ANY
+        // route resets the count (Rule B condition 2 / G6). Expressing the reset
+        // here is what keeps it one rule rather than two.
+        newLinesWhilePaused: next === 0 ? 0 : Math.max(0, input.newLinesWhilePaused + tailDelta),
+    };
+}
+/**
+ * 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 function shouldArmResume(input) {
+    if (!Number.isFinite(input.resumeMs) || input.resumeMs <= 0)
+        return false;
+    if (input.offset <= 0)
+        return false;
+    if (input.newLinesWhilePaused <= 0)
+        return false;
+    if (input.hold)
+        return false;
+    return true;
+}
+export function emptyTailState() {
+    return { rows: 0, lastId: null, lastHeight: 0 };
+}
+/**
+ * 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 function advanceTailRows(prev, ids, heightOf) {
+    if (ids.length === 0)
+        return { rows: prev.rows, lastId: null, lastHeight: 0 };
+    const lastIndex = ids.length - 1;
+    const lastId = ids[lastIndex];
+    const lastHeight = heightOf(lastIndex);
+    if (prev.lastId === null) {
+        // First frame: there is no "before", so there is no delta to attribute.
+        return { rows: prev.rows, lastId, lastHeight };
+    }
+    const anchor = ids.lastIndexOf(prev.lastId);
+    if (anchor === -1) {
+        // The anchor is gone (horizon front-drop, `/clear`, `/reset`, `/resume`).
+        return { rows: prev.rows, lastId, lastHeight };
+    }
+    // The anchor entry may have grown in place (a streaming tail entry), and
+    // everything after it is new. Both terms are signed.
+    let delta = heightOf(anchor) - prev.lastHeight;
+    for (let i = anchor + 1; i <= lastIndex; i += 1)
+        delta += heightOf(i);
+    return { rows: prev.rows + delta, lastId, lastHeight };
+}

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

@@ -20,6 +20,17 @@
  * `overflowLines`, while `offset` — and hence what the user is looking at — is
  * unchanged. No scroll-anchoring compensation pass is required. Do NOT
  * "simplify" `offset` to count from the top.
+ *
+ * V-4 AS AMENDED BY tui-selection-and-scroll-follow (§4.3.1a). There is now
+ * exactly ONE compensation pass — `follow-state.ts`'s Rule A — and it is
+ * deliberately restricted to rows appended AT THE TAIL, published by
+ * `Transcript.tsx` from the height table below. Everything the paragraph above
+ * describes still self-compensates and is still not compensated for again.
+ * The restriction is the whole of V-4's survival: an offset that reacted to
+ * TOTAL measured height would turn every above-the-viewport correction into a
+ * jump, would read a horizon front-drop as new output — and, because
+ * `selectWindow` takes `offset` as an INPUT, would close a loop from the offset
+ * through the mounted set and the measured heights back to the offset.
  */
 import type { Entry } from '../../agent/reducer.js';
 import type { DensityMode } from '../density.js';

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

@@ -20,8 +20,20 @@
  * `overflowLines`, while `offset` — and hence what the user is looking at — is
  * unchanged. No scroll-anchoring compensation pass is required. Do NOT
  * "simplify" `offset` to count from the top.
+ *
+ * V-4 AS AMENDED BY tui-selection-and-scroll-follow (§4.3.1a). There is now
+ * exactly ONE compensation pass — `follow-state.ts`'s Rule A — and it is
+ * deliberately restricted to rows appended AT THE TAIL, published by
+ * `Transcript.tsx` from the height table below. Everything the paragraph above
+ * describes still self-compensates and is still not compensated for again.
+ * The restriction is the whole of V-4's survival: an offset that reacted to
+ * TOTAL measured height would turn every above-the-viewport correction into a
+ * jump, would read a horizon front-drop as new output — and, because
+ * `selectWindow` takes `offset` as an INPUT, would close a loop from the offset
+ * through the mounted set and the measured heights back to the offset.
  */
 import { FAST_LIMITS } from '../../fast/limits.js';
+import { COMPACTION_LIMITS } from '../../compaction/limits.js';
 import { GUTTER_WIDTH } from './Gutter.js';
 export const VIRTUAL_LIMITS = {
     /**
@@ -101,6 +113,16 @@ export function entryRevision(entry) {
          */
         case 'fast':
             return `f${entry.status}.${entry.live ? 1 : 0}.${entry.text?.length ?? 0}.${entry.detail?.length ?? 0}`;
+        /**
+         * `live`, the SUMMARY LENGTH and `mode`, because all three change the rows the
+         * card draws: a live card renders a headline and no body, a settled one
+         * renders the summary (whose length decides how many rows it wraps to), and
+         * `mode` selects between the "summarized N messages" and "dropped N WITHOUT a
+         * summary" detail lines. `durationMs` is inside the `wrap="truncate"`
+         * headline, so it can never change the height.
+         */
+        case 'compaction':
+            return `c${entry.live ? 1 : 0}.${entry.summary?.length ?? 0}.${entry.mode}.${entry.applied ? 1 : 0}`;
         default:
             return 'x';
     }
@@ -243,6 +265,18 @@ export function estimateEntryRows(entry, cols, density, expanded, thinkingVisibl
                 : 1;
             return separation + 1 + body;
         }
+        // THE SECOND SWITCH, and adding the case to only one of the two yields a
+        // transcript whose scroll arithmetic disagrees with what it drew — drift
+        // rather than an error (C-9 / RV-13). Headline row, one detail row, then the
+        // summary clamped to `cardTextRows` (or unclamped when expanded) plus the
+        // `+N more lines` footer. An UPPER BOUND, which is what this function owes
+        // its caller.
+        case 'compaction': {
+            const lines = entry.summary ? wrappedRows(entry.summary, usable) : 0;
+            const body = expanded ? lines : Math.min(lines, COMPACTION_LIMITS.cardTextRows);
+            const footer = lines > body || (expanded && lines > COMPACTION_LIMITS.cardTextRows) ? 1 : 0;
+            return separation + 1 + 1 + body + footer;
+        }
         default:
             return separation + 1;
     }

package/dist/ui/overlays/HelpOverlay.js

@@ -21,6 +21,10 @@ function keyRows(times) {
         ['Shift+Up / Shift+Down', 'Scroll the transcript a line (full-screen mode)'],
         ['Wheel', 'Scroll the transcript (or the open overlay)'],
         ['Shift+Wheel', 'Scroll the transcript a page'],
+        // Drag-select is the one affordance here a user cannot discover by pressing
+        // a key, so it has to be named somewhere they can look it up. The one-shot
+        // startup notice is the other place, and it scrolls away.
+        ['Drag (left button)', 'Select text on screen; releasing copies it'],
         ['Up / Down', 'Prompt history (empty input)'],
     ];
 }
@@ -44,7 +48,8 @@ const COMMANDS = [
     ['/cwd [dir]', 'Show or change the tool working directory'],
     ['/save [file]', 'Save the session to JSON'],
     ['/resume [file]', 'Load a saved session'],
-    ['/copy', 'Copy the last answer to the clipboard'],
+    ['/copy', 'Copy the last answer to the clipboard (OSC 52, so it works over ssh)'],
+    ['/mouse [on|off]', 'Release the mouse to your terminal, or take it back'],
     ['/exit', 'Exit'],
 ];
 const SKILL_ROWS = [