@aragon-agent/cli 0.6.2 → 0.6.3

package/dist/ui/entries/CompactionCard.js

@@ -0,0 +1,158 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * CompactionCard — one context compaction in the transcript
+ * (context-auto-compaction §6.3).
+ *
+ * ASCII ONLY: every glyph comes from `pickGlyphs`, INCLUDING THE ARROW. The mock
+ * in the design shows `112 -> 9 messages`; that arrow is `glyphs.arrowRight`, the
+ * one `StatusBar` already uses, not a literal — `ui/` is inside
+ * `glyphs.test.ts::inScope`, so a literal here fails the scan (P2-7).
+ *
+ * EXPANDABLE, UNLIKE `FastCard`. A critique is already clamped to
+ * `fast.reviewMaxChars` before it reaches its card, so there is nothing hidden
+ * for Ctrl+O to reveal; a summary is up to `summaryMaxChars` and there genuinely
+ * is more to see. That is why `App`'s Ctrl+O predicate had to learn about this
+ * kind — without it the card renders a hint that does nothing and expands an
+ * older tool card instead (C-15 / P1-8 / AC-21).
+ *
+ * EVERY STRING DESCRIBES THE HISTORY, NEVER THE SCREEN (§6.4 / P2-9). `/clear`
+ * empties the transcript view but not `messages`, so this card can legitimately
+ * report "112 -> 9 messages" with nine visible rows above it. Nothing here says
+ * "above" or "earlier in this transcript".
+ */
+import React from 'react';
+import { Box, Text } from 'ink';
+import Spinner from 'ink-spinner';
+import { pickGlyphs } from '../glyphs.js';
+import { railBorderProps } from '../layout/Gutter.js';
+import { formatDuration, formatTokens } from '../../agent/usage.js';
+import { COMPACTION_LIMITS } from '../../compaction/limits.js';
+/**
+ * The card's colour.
+ *
+ * `truncated` is a WARNING rather than the accent, because it is a real and
+ * bounded data loss the user is entitled to notice; `applied: false` is an error
+ * because the run is still at the occupancy that triggered it.
+ */
+export function compactionCardColor(props, theme) {
+    if (props.live)
+        return theme.toolRunning;
+    if (!props.applied)
+        return theme.toolError;
+    if (props.mode === 'truncated' || props.mode === 'relieved')
+        return theme.noticeWarn;
+    return theme.accent;
+}
+/** The one-line summary of what the compaction did, or why it did not. */
+function headline(props, arrow, dot) {
+    const { index, live } = props;
+    // The model is `''` when no summarizer resolves (no key for the provider), and
+    // the separator has to go with it — a headline ending in a dangling `  -  `
+    // reads as a rendering fault rather than as the missing model it is.
+    if (live) {
+        // ELAPSED IN THE SAME POSITION `durationMs` TAKES ONCE SETTLED, so the number
+        // does not jump across the line when the card settles. Between second 0 and
+        // second 45 this was the only changing information on the card, and there was
+        // none.
+        const elapsed = props.elapsedMs === undefined ? '' : `${dot}${formatDuration(props.elapsedMs)}`;
+        return props.model
+            ? `compacting context #${index}${dot}${props.model}${elapsed}`
+            : `compacting context #${index}${elapsed}`;
+    }
+    if (!props.applied) {
+        const why = props.reason ? `: ${props.reason}` : '';
+        return `context not compacted #${index}${why}`;
+    }
+    const messages = `${props.messagesBefore} ${arrow} ${props.messagesAfter} messages`;
+    const tokens = `${formatTokens(props.tokensBefore)} ${arrow} ${formatTokens(props.tokensAfter)} tokens`;
+    const duration = props.durationMs === undefined ? '' : `${dot}${formatDuration(props.durationMs)}`;
+    return `context compacted${dot}${messages}${dot}${tokens}${duration}`;
+}
+/**
+ * The muted second line: how it was done, and with what.
+ *
+ * THE LIVE BRANCH NAMES THE ESCAPE (§3.6 / E-10). `AgentController.abort()` has
+ * always called `this.compaction?.abort()` before `agent.abort()`, so Esc has
+ * always cancelled an in-flight summarization - and no surface has ever said so
+ * during the forty-five seconds it matters. The hint goes with the model for the
+ * same reason the separator does: with no summarizer resolved there is no call to
+ * cancel.
+ *
+ * THE `relieved` BRANCH COMES BEFORE `truncated`, AND IT EXISTS BECAUSE THE
+ * `summarized` LINE WOULD OTHERWISE LIE. Relief drops no messages, so the
+ * fall-through would render "summarized 0 messages with <model>" for a
+ * compaction in which no model was called - in the rare, alarming case the user
+ * most needs to read correctly.
+ */
+function detailLine(props) {
+    if (props.live) {
+        if (!props.model)
+            return '';
+        return `summarizing with ${props.model} - esc to cancel`;
+    }
+    if (!props.applied)
+        return props.mode === 'none' && !props.reason ? 'nothing was changed' : '';
+    const dropped = Math.max(0, props.messagesBefore - props.messagesAfter);
+    if (props.mode === 'relieved') {
+        const n = props.tailRelief?.messages ?? 0;
+        return `clipped ${n} tool ${n === 1 ? 'result' : 'results'} in the retained turns - nothing could be dropped`;
+    }
+    if (props.mode === 'truncated') {
+        return `dropped ${dropped} messages WITHOUT a summary - summarization failed`;
+    }
+    const via = props.trigger === 'overflow' ? ' after a context overflow' : '';
+    return `summarized ${dropped} messages with ${props.model}${via}`;
+}
+/**
+ * The relief disclosure, on a settled card that ALSO summarized.
+ *
+ * A BOUNDED, ANNOUNCED DATA LOSS THE USER IS ENTITLED TO NOTICE, in the same
+ * voice §6.4's honesty rules use for `truncated`. Suppressed on the `relieved`
+ * card, where `detailLine` has already said it and a second line would be the
+ * same sentence twice.
+ */
+function reliefLine(props) {
+    if (props.live || !props.applied || !props.tailRelief || props.mode === 'relieved')
+        return '';
+    const n = props.tailRelief.messages;
+    return (`clipped ${n} tool ${n === 1 ? 'result' : 'results'} in the retained turns ` +
+        `(${formatTokens(props.tailRelief.charsRemoved)} characters) - ` +
+        'the recent turns alone exceeded the window');
+}
+/**
+ * Split the summary into rows.
+ *
+ * A ROW budget, not a character one: `summaryMaxChars` already bounded the text,
+ * and this only decides how much of it the COLLAPSED card shows. Ink wraps the
+ * rest.
+ */
+function summaryRows(text, expanded) {
+    const lines = text.split('\n').filter((l) => l.trim().length > 0);
+    return expanded ? lines : lines.slice(0, COMPACTION_LIMITS.cardTextRows);
+}
+function CompactionCardImpl(props) {
+    const { live, summary, expanded, reducedMotion, theme, caps } = props;
+    const glyphs = pickGlyphs(caps);
+    const color = compactionCardColor(props, theme);
+    const dot = `  ${glyphs.midDot}  `;
+    const head = headline(props, glyphs.arrowRight, dot);
+    const detail = detailLine(props);
+    const relief = reliefLine(props);
+    const rows = summary ? summaryRows(summary, expanded === true) : [];
+    const totalRows = summary ? summary.split('\n').filter((l) => l.trim().length > 0).length : 0;
+    const hidden = Math.max(0, totalRows - rows.length);
+    // COLOUR TRACKS `live`, MOTION TRACKS `animate` — one headline, two separate
+    // decisions, and the split is the one `FastCard` records at length: `App`
+    // widens `reducedMotion` to "this frame does not animate here" for the whole of
+    // every run, and folding the two together would grey out every live card for
+    // the whole run, losing the status colour along with the motion.
+    const animate = live && reducedMotion !== true && caps.unicode;
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { color: theme.accent, bold: true, children: "compact" }), _jsxs(Text, { color: live ? color : theme.muted, wrap: "truncate", children: ['  ', animate ? (_jsxs(_Fragment, { children: [_jsx(Spinner, { type: "dots" }), ' '] })) : live ? (`${glyphs.spinnerStill} `) : (''), head] })] }), detail.length > 0 && (_jsx(Box, { flexDirection: "column", flexShrink: 0, paddingLeft: 1, children: _jsx(Text, { color: color, wrap: "truncate", children: detail }) })), relief.length > 0 && (_jsx(Box, { flexDirection: "column", flexShrink: 0, paddingLeft: 1, children: _jsx(Text, { color: theme.noticeWarn, children: relief }) })), rows.length > 0 && (_jsxs(Box, { flexDirection: "column", flexShrink: 0, paddingLeft: 1, ...railBorderProps(glyphs.railVertical, theme.border), children: [rows.map((line, index) => (_jsx(Text, { color: theme.primary, children: line }, index))), hidden > 0 && (_jsxs(Text, { color: theme.muted, children: [glyphs.railEnd, " +", hidden, " more lines (ctrl+o to expand)"] })), hidden === 0 && expanded === true && totalRows > COMPACTION_LIMITS.cardTextRows && (_jsxs(Text, { color: theme.muted, children: [glyphs.railEnd, " ctrl+o to collapse"] }))] }))] }));
+}
+/**
+ * `React.memo` with the DEFAULT comparator (tui-render-performance L2 / R3).
+ * `mapEntry` already preserves object identity for untouched entries, so the
+ * props below are stable references on a settled card, and `theme` / `caps` are
+ * `useMemo`d in `App.tsx` (I-L2-1).
+ */
+export const CompactionCard = React.memo(CompactionCardImpl);

package/dist/ui/frame-differ.d.ts

@@ -58,6 +58,31 @@ export interface FrameDifferOptions {
     rows: () => number | undefined;
     /** Raised once, on the 0→1 edge of `fallbacks` (§5.6). */
     onFirstFallback?: () => void;
+    /**
+     * Raw frame lines in, lines to PAINT out. Identity when absent, and absent is
+     * the default — a session without drag-select never allocates a second array.
+     *
+     * Called AFTER the geometry stand-down and BEFORE the cache comparison, so a
+     * frame this module refuses to address never reaches the selection layer, and
+     * the diff below still compares what is actually on the screen (I-2).
+     *
+     * It MUST return the same number of lines it was given; a decorator that
+     * changes the count would desynchronise absolute addressing, so the result is
+     * discarded if it does.
+     */
+    decorate?: (lines: string[]) => string[];
+    /**
+     * Raised whenever the cache is dropped — a foreign write, a resize, a geometry
+     * stand-down, an explicit `invalidate()`.
+     *
+     * P1-7: on every one of those paths the RAW Ink frame reaches the screen
+     * verbatim, so any highlight is wiped off the terminal while the selection
+     * controller still believes it is painted and its mirror still holds the rows
+     * of the last DECORATED frame. A release would then copy text that is not on
+     * screen. I-4's "by construction" argument has exactly this hole, and one
+     * callback closes it: the controller clears the selection.
+     */
+    onInvalidate?: () => void;
 }
 export interface FrameWriterStats {
     /** Frames the differ EMITTED — `framesDiffed + framesFull`, never pass-throughs. */
@@ -78,6 +103,15 @@ export interface FrameWriterStats {
      * to stdout behind Ink's back" and is what raises the §5.6 notice.
      */
     fallbacks: number;
+    /**
+     * Self-initiated repaints — `repaint()` calls that emitted at least one row.
+     *
+     * A COUNTER OF ITS OWN, deliberately kept out of `framesTotal` /
+     * `framesDiffed` (P2-6). Those count frames INK PRODUCED, and folding a drag's
+     * highlight repaints into them would make `/perf`'s frame rate a function of
+     * how much the user moved the mouse.
+     */
+    repaints: number;
 }
 export interface FrameDiffer {
     /**
@@ -91,5 +125,17 @@ export interface FrameDiffer {
     invalidate(): void;
     /** Single owner of the counters (P2-2); the writer re-exports this. */
     stats(): FrameWriterStats;
+    /**
+     * Re-run `decorate` over the LAST RAW FRAME and emit only the rows whose paint
+     * changed; `''` when there is nothing safe to do.
+     *
+     * This is what makes a drag cost 1-3 addressed rows instead of a React commit
+     * and a whole-tree Yoga layout (D-6). `''` is a REAL state rather than an error
+     * — after an `invalidate()` there is no cache to diff against and no origin to
+     * address from — and the caller's fallback is `App`'s existing `redrawNonce`:
+     * ask for a React redraw, the next commit runs `decorate`, and the highlight
+     * appears one frame later instead of never.
+     */
+    repaint(): string;
 }
 export declare function createFrameDiffer(options: FrameDifferOptions): FrameDiffer;

package/dist/ui/frame-differ.js

@@ -92,8 +92,23 @@ function countErases(prefix) {
     return prefix.split(ERASE_LINE).length - 1;
 }
 export function createFrameDiffer(options) {
-    /** Last frame, one entry per row. `null` = no cache, next frame is a full repaint. */
+    /**
+     * Last frame AS PAINTED — what is actually on the screen.
+     *
+     * `null` = no cache, next frame is a full repaint. THE DIFF COMPARES PAINTED
+     * LINES (I-2): diffing raw against a painted screen would leave the highlight
+     * burned into rows the next frame never repaints, because those rows' RAW text
+     * did not change.
+     */
     let prev = null;
+    /**
+     * The same frame UNDECORATED — `repaint()`'s input.
+     *
+     * Two caches rather than one, because a repaint has to re-run `decorate` over
+     * the ORIGINAL rows: painting an already-painted row would nest the selection
+     * escapes and the highlight would never come off.
+     */
+    let rawPrev = null;
     /**
      * Whether any chunk has been seen at all.
      *
@@ -111,9 +126,37 @@ export function createFrameDiffer(options) {
         linesWritten: 0,
         bytesWritten: 0,
         fallbacks: 0,
+        repaints: 0,
     };
+    /**
+     * Re-entrancy guard for `onInvalidate`. The listener clears the selection,
+     * which asks for a repaint, which can reach `invalidate()` again; one flag is
+     * cheaper than reasoning about how deep that can go.
+     */
+    let notifying = false;
     const invalidate = () => {
         prev = null;
+        rawPrev = null;
+        if (notifying || !options.onInvalidate)
+            return;
+        notifying = true;
+        try {
+            options.onInvalidate();
+        }
+        finally {
+            notifying = false;
+        }
+    };
+    /**
+     * `decorate`, with the line-count contract enforced. A decorator that returned
+     * a different number of rows would shift every absolute address below it for
+     * the rest of the session, so its answer is discarded rather than trusted.
+     */
+    const applyDecorate = (lines) => {
+        if (!options.decorate)
+            return lines;
+        const painted = options.decorate(lines);
+        return painted.length === lines.length ? painted : lines;
     };
     /**
      * Write `chunk` verbatim — today's behaviour, and the only failure mode.
@@ -132,8 +175,9 @@ export function createFrameDiffer(options) {
         return null;
     };
     const wrapSync = (payload) => options.sync ? SYNC_BEGIN + payload + SYNC_END : payload;
-    const emit = (payload, lines, addressed, full) => {
+    const emit = (payload, lines, raw, addressed, full) => {
         prev = lines;
+        rawPrev = raw;
         counters.framesTotal += 1;
         if (full)
             counters.framesFull += 1;
@@ -175,16 +219,16 @@ export function createFrameDiffer(options) {
      * is no unchanged content that has to survive, and full repaints are rare by
      * construction — one per session, one per resize, one per invalidation.
      */
-    const fullRepaint = (lines) => {
+    const fullRepaint = (lines, raw) => {
         const payload = cursorTo(1) +
             SGR_RESET +
             ERASE_DOWN +
             lines.join('\r\n') +
             '\r\n' +
             cursorTo(lines.length + 1);
-        return emit(wrapSync(payload), lines, lines.length, true);
+        return emit(wrapSync(payload), lines, raw, lines.length, true);
     };
-    const diffRepaint = (lines, previous) => {
+    const diffRepaint = (lines, raw, previous) => {
         const out = [];
         for (let i = 0; i < lines.length; i += 1) {
             // I-4: paint, THEN clear the tail. Never `ERASE_LINE` first.
@@ -196,10 +240,45 @@ export function createFrameDiffer(options) {
         // on an identical frame, so a chunk that reaches here differs by at least one
         // line; the only way to observe zero is a cache that disagrees with the
         // screen, which is the state `invalidate()` exists to prevent.
+        //
+        // With a `decorate` hook it stops being unreachable in one direction and
+        // stays correct: a frame whose RAW rows changed only where the highlight
+        // already covers them paints identically, and writing nothing is right.
         if (out.length === 0)
-            return emit('', lines, 0, false);
+            return emit('', lines, raw, 0, false);
         out.push(cursorTo(lines.length + 1)); // I-5
-        return emit(wrapSync(out.join('')), lines, out.length - 1, false);
+        return emit(wrapSync(out.join('')), lines, raw, out.length - 1, false);
+    };
+    /**
+     * Re-paint the last frame's rows through `decorate` again, emitting only what
+     * changed. Called when the SELECTION moved rather than when Ink produced a
+     * frame — hence its own counter and no touch of the frame ones (P2-6).
+     *
+     * It carries the same DEC 2026 sync envelope and parks on row `H + 1` as every
+     * other batch, because it is addressed exactly like a diff frame and a
+     * half-applied highlight tears the same way a half-applied frame does.
+     */
+    const repaint = () => {
+        if (prev === null || rawPrev === null)
+            return '';
+        const rows = usableRows();
+        if (rows === undefined)
+            return ''; // I-9 — geometry we cannot address safely
+        if (rawPrev.length + 1 > rows)
+            return '';
+        const painted = applyDecorate(rawPrev);
+        const out = [];
+        for (let i = 0; i < painted.length; i += 1) {
+            if (painted[i] !== prev[i]) {
+                out.push(cursorTo(i + 1) + SGR_RESET + painted[i] + SGR_RESET + ERASE_TO_EOL);
+            }
+        }
+        prev = painted;
+        if (out.length === 0)
+            return '';
+        out.push(cursorTo(painted.length + 1)); // I-5
+        counters.repaints += 1;
+        return wrapSync(out.join(''));
     };
     const transform = (chunk) => {
         const firstChunk = !seenAnyChunk;
@@ -217,14 +296,19 @@ export function createFrameDiffer(options) {
         const lines = body.slice(0, -1).split('\n');
         if (lines.length + 1 > rows)
             return passThrough(false); // I-9
-        if (prev === null || prev.length !== lines.length || matched.erased !== prev.length + 1) {
-            return fullRepaint(lines);
+        // AFTER the geometry stand-down, BEFORE the cache comparison: a frame this
+        // module refuses to address never reaches the selection layer, and what is
+        // compared below is what the screen will hold.
+        const painted = applyDecorate(lines);
+        if (prev === null || prev.length !== painted.length || matched.erased !== prev.length + 1) {
+            return fullRepaint(painted, lines);
         }
-        return diffRepaint(lines, prev);
+        return diffRepaint(painted, lines, prev);
     };
     return {
         transform,
         invalidate,
+        repaint,
         stats: () => ({ ...counters }),
     };
 }

package/dist/ui/gauge.d.ts

@@ -17,8 +17,23 @@ export interface Gauge {
     /** Clamped percentage 0–100. */
     pct: number;
 }
+/**
+ * Where the bar changes colour, as percentages.
+ *
+ * The defaults are the values this function hardcoded before context compaction
+ * existed, so every existing call site and test is byte-identical (§6.2).
+ */
+export interface GaugeMarks {
+    /** Amber at or above this. */
+    warn: number;
+    /** Red strictly above this. */
+    high: number;
+}
 /**
  * Build a `width`-cell gauge for `pct` (0–100). Uses block glyphs on Unicode
  * terminals and `#`/`-` otherwise (e.g. `[######----]`).
+ *
+ * `marks` is OPTIONAL and defaults to today's values, so omitting it produces
+ * byte-identical output to the pre-compaction build.
  */
-export declare function buildGauge(pct: number, width: number, theme: Theme, caps: TermCapabilities): Gauge;
+export declare function buildGauge(pct: number, width: number, theme: Theme, caps: TermCapabilities, marks?: GaugeMarks): Gauge;

package/dist/ui/gauge.js

@@ -4,19 +4,38 @@
  * has no Unicode. Kept out of the `.tsx` so it is unit-testable without Ink.
  */
 import { pickGlyphs } from './glyphs.js';
-/** Pick the fill colour by threshold: <60 low · 60–85 mid · >85 high. */
-function thresholdColor(pct, theme) {
-    if (pct > 85)
+const DEFAULT_MARKS = { warn: 60, high: 85 };
+/**
+ * Pick the fill colour by threshold: `< warn` low · `>= warn` mid · `> high` high.
+ *
+ * THE TWO OPERATORS ARE PRESERVED EXACTLY (`> high`, `>= warn`), and that is not
+ * cosmetic: changing either would move the default 85 or 60 boundary and break
+ * the byte-identity claim that makes the `marks` parameter a free change.
+ *
+ * WHAT RED MEANS, PRECISELY (P2-4). The compaction trigger is
+ * `ratio >= threshold` (INCLUSIVE) while this fill is `pct > high` (EXCLUSIVE),
+ * so with `high = threshold` any occupancy that would render red has ALREADY
+ * triggered compaction, and the gauge repaints downward in the same frame. The
+ * red band is therefore only ever OBSERVABLE when compaction did not or could
+ * not run — the feature is off, it self-disabled, or the failure ladder ended at
+ * its last rung. That is a genuinely more useful meaning than "imminent", and it
+ * is the one the README and the settings screen state.
+ */
+function thresholdColor(pct, theme, marks) {
+    if (pct > marks.high)
         return theme.gauge.high;
-    if (pct >= 60)
+    if (pct >= marks.warn)
         return theme.gauge.mid;
     return theme.gauge.low;
 }
 /**
  * Build a `width`-cell gauge for `pct` (0–100). Uses block glyphs on Unicode
  * terminals and `#`/`-` otherwise (e.g. `[######----]`).
+ *
+ * `marks` is OPTIONAL and defaults to today's values, so omitting it produces
+ * byte-identical output to the pre-compaction build.
  */
-export function buildGauge(pct, width, theme, caps) {
+export function buildGauge(pct, width, theme, caps, marks = DEFAULT_MARKS) {
     const clamped = Math.max(0, Math.min(100, Math.round(pct)));
     const cells = Math.max(1, width);
     const filledCells = Math.max(0, Math.min(cells, Math.round((clamped / 100) * cells)));
@@ -29,7 +48,7 @@ export function buildGauge(pct, width, theme, caps) {
     return {
         filled: full.repeat(filledCells),
         empty: empty.repeat(cells - filledCells),
-        fillColor: thresholdColor(clamped, theme),
+        fillColor: thresholdColor(clamped, theme, marks),
         trackColor: theme.gauge.track,
         pct: clamped,
     };

package/dist/ui/glyphs.d.ts

@@ -117,6 +117,17 @@ export interface Glyphs {
      * scan fails the build if either spelling appears anywhere else.
      */
     retry: string;
+    /**
+     * Context compaction (context-auto-compaction §6.3). The rail marker on the
+     * compaction card.
+     *
+     * HERE RATHER THAN IN `CompactionCard`, for the reason this file's header
+     * gives: a literal in a component bypasses `pickGlyphs` entirely and shows
+     * mojibake on a legacy console whatever the capability probe said.
+     * `glyphs.test.ts`'s static scan fails the build if either spelling appears
+     * anywhere else — and `src/compaction/**` is inside that scan's scope too.
+     */
+    compaction: string;
     /**
      * Ink `borderStyle` name for every boxed region (composer, completion popup,
      * overlay frame).

package/dist/ui/glyphs.js

@@ -65,6 +65,7 @@ const UNICODE_GLYPHS = {
     todoActive: '▸',
     todoDone: '✔',
     retry: '↻',
+    compaction: '⤓',
     tool: {
         read_file: '▤',
         write_file: '✎',
@@ -127,6 +128,7 @@ const ASCII_GLYPHS = {
     todoActive: '>',
     todoDone: '[x]',
     retry: '[r]',
+    compaction: '[c]',
     tool: {
         read_file: '=',
         write_file: '+',

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;