@aragon-agent/cli 0.6.7 → 0.6.8

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

@@ -1,14 +1,4 @@
-/**
- * AppShell (spec §4.3) — the frame that makes R2 true.
- *
- * In `fullscreen` the root box has a FIXED height of `frameHeight(rows)` and the
- * middle viewport is the only `flexGrow` child, so the bottom chrome (toast /
- * composer / status bar) is physically the last thing on the screen from the
- * very first frame — empty session, long session, mid-scroll, overlay open.
- *
- * In `inline` the same children are emitted in the same order with no height
- * constraint, i.e. byte-for-byte the v0.2.0 document-flow behavior.
- */
+/** Stable fullscreen slots preserve the editor during overlays and small resizes. */
 import React from 'react';
 import { type RenderMode } from './frame.js';
 export interface AppShellProps {
@@ -17,51 +7,16 @@ export interface AppShellProps {
     cols: number;
     header: React.ReactNode;
     viewport: React.ReactNode;
-    /**
-     * The live subagent roster (team-subagents §6.1), or nothing.
-     *
-     * IT RENDERS IN THE BOTTOM CHROME OF THE FULL-SCREEN BRANCH, above `toast` and
-     * below the viewport: the roster is transient status about the run in progress,
-     * so it belongs with the other transient rows rather than inside the scrolling
-     * transcript, where it would be interleaved with history and scroll away.
-     */
+    /** Legacy inline footer; fullscreen assembles these slots inside its viewport. */
     team?: React.ReactNode;
-    /**
-     * The right-hand region of the MIDDLE band (todo-plan-execution §3.9), or
-     * nothing.
-     *
-     * NAMED FOR ITS POSITION, NOT ITS CONTENT (D-18): this file is a layout
-     * primitive and has no business knowing what a todo is. `team` above already
-     * leaks content vocabulary in here; there is no reason to repeat it.
-     *
-     * IT MUST BE RENDERED IN THE MIDDLE BAND, BESIDE THE VIEWPORT (C-6 / I-4) —
-     * that is what makes it a rail rather than another row of bottom chrome. Moved
-     * down into the bottom box it would stop being a column beside the transcript
-     * and start eating viewport height, growing and shrinking the transcript every
-     * time the list changed length.
-     *
-     * The INLINE branch does not include it at all — a structural guarantee rather
-     * than a promise that the caller passes `null` (non-goal 4).
-     */
+    /** Kept source-compatible; fullscreen rail is owned by ScrollViewport. */
     rail?: React.ReactNode;
-    /**
-     * The one-row plan strip for INLINE mode (todo-plan-followthrough §3.7), or
-     * nothing.
-     *
-     * THE STRUCTURAL MIRROR OF `rail` ABOVE, in the opposite direction: the
-     * FULL-SCREEN branch does not reference it at all. The reason is the same one
-     * `rail`'s inline omission records — a prop that is merely SUPPOSED to be null
-     * in one mode becomes non-null eventually, and then the rail and the strip are
-     * both on screen showing the same list (I-6). Fullscreen has the rail; that is
-     * the whole design.
-     *
-     * It sits between `viewport` and `team`, mirroring where the rail sits in the
-     * other branch: last thing above the bottom chrome, so the strip and the
-     * roster read top-to-bottom in the same order in both modes.
-     */
+    /** Inline-only plan strip. */
     strip?: React.ReactNode;
     toast: React.ReactNode;
     composer: React.ReactNode;
     status: React.ReactNode;
+    inactive?: boolean;
+    placeholder?: React.ReactNode;
 }
-export declare function AppShell({ mode, rows, cols, header, viewport, team, rail, strip, toast, composer, status, }: AppShellProps): React.ReactElement;
+export declare function AppShell({ mode, rows, cols, header, viewport, team, strip, toast, composer, status, inactive, placeholder, }: AppShellProps): React.ReactElement;

package/dist/ui/layout/AppShell.js

@@ -1,9 +1,9 @@
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 import { Box } from 'ink';
 import { frameHeight } from './frame.js';
-export function AppShell({ mode, rows, cols, header, viewport, team, rail, strip, toast, composer, status, }) {
+export function AppShell({ mode, rows, cols, header, viewport, team, strip, toast, composer, status, inactive = false, placeholder, }) {
     if (mode === 'inline') {
         return (_jsxs(Box, { flexDirection: "column", children: [header, viewport, strip, team, toast, composer, status] }));
     }
-    return (_jsxs(Box, { flexDirection: "column", height: frameHeight(rows), width: cols, overflow: "hidden", children: [_jsx(Box, { flexDirection: "column", flexShrink: 0, children: header }), _jsxs(Box, { flexDirection: "row", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: [_jsx(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: viewport }), rail] }), _jsxs(Box, { flexDirection: "column", flexShrink: 0, children: [team, toast, composer, status] })] }));
+    return (_jsxs(Box, { flexDirection: "column", height: frameHeight(rows), width: cols, overflow: "hidden", children: [_jsxs(Box, { display: inactive ? 'none' : 'flex', flexDirection: "column", height: frameHeight(rows), width: cols, overflow: "hidden", children: [_jsx(Box, { height: 1, flexShrink: 0, overflow: "hidden", children: header }), _jsx(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: viewport }), _jsx(Box, { height: 1, flexShrink: 0, overflow: "hidden", children: toast }), _jsx(Box, { height: 1, flexShrink: 0, overflow: "hidden", children: status })] }), _jsx(Box, { display: inactive ? 'flex' : 'none', height: frameHeight(rows), overflow: "hidden", children: placeholder })] }));
 }

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

@@ -18,14 +18,15 @@ import React from 'react';
 import type { Theme } from '../theme.js';
 import type { TermCapabilities } from '../capabilities.js';
 import type { ThumbRange } from './scroll-indicator.js';
-/** Below this width a column of content is worth more than the affordance. */
-export declare const MIN_INDICATOR_COLS = 50;
+/** Smallest supported fullscreen width; every usable chat frame reserves the column. */
+export declare const MIN_INDICATOR_COLS = 40;
 export interface ScrollIndicatorProps {
     /** Viewport height in rows, as measured by `ScrollViewport`. */
     rows: number;
     /** `null` when the content fits — the rail is drawn as bare track. */
     thumb: ThumbRange | null;
+    dragging?: boolean;
     theme: Theme;
     caps: TermCapabilities;
 }
-export declare function ScrollIndicator({ rows, thumb, theme, caps, }: ScrollIndicatorProps): React.ReactElement;
+export declare function ScrollIndicator({ rows, thumb, dragging, theme, caps, }: ScrollIndicatorProps): React.ReactElement;

package/dist/ui/layout/ScrollIndicator.js

@@ -1,15 +1,15 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Box, Text } from 'ink';
 import { pickGlyphs } from '../glyphs.js';
-/** Below this width a column of content is worth more than the affordance. */
-export const MIN_INDICATOR_COLS = 50;
-export function ScrollIndicator({ rows, thumb, theme, caps, }) {
+/** Smallest supported fullscreen width; every usable chat frame reserves the column. */
+export const MIN_INDICATOR_COLS = 40;
+export function ScrollIndicator({ rows, thumb, dragging = false, theme, caps, }) {
     const glyphs = pickGlyphs(caps);
     const count = Math.max(0, Math.floor(rows) || 0);
     const cells = [];
     for (let i = 0; i < count; i += 1) {
         const onThumb = !!thumb && i >= thumb.start && i < thumb.start + thumb.size;
-        cells.push(_jsx(Text, { color: onThumb ? theme.primary : theme.border, children: onThumb ? glyphs.scrollThumb : glyphs.scrollTrack }, i));
+        cells.push(_jsx(Text, { color: onThumb ? theme.primary : theme.muted, bold: onThumb && dragging, children: onThumb ? glyphs.scrollThumb : glyphs.scrollTrack }, i));
     }
     return (_jsx(Box, { flexDirection: "column", flexShrink: 0, width: 1, children: cells }));
 }

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

@@ -1,88 +1,35 @@
-/**
- * ScrollViewport (spec §4.5) — a self-drawn scrolling window built from Ink's
- * negative `marginTop` + `overflow: hidden` + `measureElement`.
- *
- * Once the frame occupies the whole screen, `<Static>` history is pushed above
- * the frame where only one line is visible, so native scrollback stops being a
- * usable mechanism and the app has to own scrolling. That is why this exists.
- *
- * SINGLE SOURCE OF TRUTH (review P1-7): both the metrics and the scroll offset
- * live here. The parent only pushes an *intent* down and receives one derived
- * *display* number back. Holding the offset in the parent as well would create a
- * measure → setState → re-render → measure loop whose convergence is provable
- * but whose frame count is not — expensive inside a 33 ms streaming window.
- *
- * 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 DOMElement } from 'ink';
 import type { Theme } from '../theme.js';
 import type { TermCapabilities } from '../capabilities.js';
+import { type ScrollbarBridge } from '../scrollbar-controller.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.
-     * `repeat` folds a coalesced wheel burst into one state update (defaults 1).
-     */
     intent?: {
         kind: ScrollIntent;
         nonce: number;
         repeat?: number;
     };
-    /** Bumped by the parent to force a pin to the newest output (e.g. on submit). */
     pinToBottomNonce?: number;
-    /** Derived display value for the status bar's `↑N`. Must be referentially stable. */
+    resetKey?: unknown;
     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.
-     */
+    onViewportShiftChange?: (shift: number) => void;
     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;
-    /**
-     * The viewport's own width, when it is narrower than the terminal
-     * (todo-plan-execution §3.9 / C-7).
-     *
-     * This component is the ONLY one inside the viewport subtree that reads
-     * `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 its responsive share of the frame those two
-     * stop being the same number. Optional so every existing caller (and every
-     * test) is unchanged.
-     */
     cols?: number;
+    footer?: React.ReactNode;
+    rail?: React.ReactNode;
+    overlay?: React.ReactNode;
+    active?: boolean;
+    scrollbar?: ScrollbarBridge;
+    composerRef?: React.RefObject<DOMElement>;
+    onComposerVisibilityChange?: (visible: boolean) => void;
     theme: Theme;
     caps: TermCapabilities;
     children: React.ReactNode;
 }
-export declare function ScrollViewport({ intent, pinToBottomNonce, onScrolledLinesChange, onViewportShiftChange, tailRowsRef, hold, resumeMs, showScrollIndicator, cols: colsProp, theme, caps, children, }: ScrollViewportProps): React.ReactElement;
+/** One offset for messages, padding and editor; hidden trees keep their local state. */
+export declare function ScrollViewport(props: ScrollViewportProps): React.ReactElement;

package/dist/ui/layout/ScrollViewport.js

@@ -1,204 +1,202 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-/**
- * ScrollViewport (spec §4.5) — a self-drawn scrolling window built from Ink's
- * negative `marginTop` + `overflow: hidden` + `measureElement`.
- *
- * Once the frame occupies the whole screen, `<Static>` history is pushed above
- * the frame where only one line is visible, so native scrollback stops being a
- * usable mechanism and the app has to own scrolling. That is why this exists.
- *
- * SINGLE SOURCE OF TRUTH (review P1-7): both the metrics and the scroll offset
- * live here. The parent only pushes an *intent* down and receives one derived
- * *display* number back. Holding the offset in the parent as well would create a
- * measure → setState → re-render → measure loop whose convergence is provable
- * but whose frame count is not — expensive inside a 33 ms streaming window.
- *
- * 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 { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import { Box, measureElement, useStdout } from 'ink';
+import { createScrollbarController } from '../scrollbar-controller.js';
 import { ViewportGeometryContext } from './viewport-geometry.js';
-import { applyScrollTimes, clampScroll, } from './scroll.js';
+import { applyScrollTimes } from './scroll.js';
 import { reduceFollow, shouldArmResume } from './follow-state.js';
 import { thumbRange } from './scroll-indicator.js';
-import { MIN_INDICATOR_COLS, ScrollIndicator } from './ScrollIndicator.js';
-export function ScrollViewport({ intent, pinToBottomNonce = 0, onScrolledLinesChange, onViewportShiftChange, tailRowsRef, hold = false, resumeMs = 0, showScrollIndicator = false, cols: colsProp, theme, caps, children, }) {
+import { ScrollIndicator } from './ScrollIndicator.js';
+import { buildDocumentLayout } from './document-layout.js';
+function composerVisible(composer, clip) {
+    if (!composer || !clip)
+        return true;
+    let top = 0;
+    let current = composer;
+    while (current && current !== clip) {
+        top += current.yogaNode?.getComputedTop() ?? 0;
+        current = current.parentNode;
+    }
+    return current === clip && top >= 0 &&
+        top + measureElement(composer).height <= measureElement(clip).height;
+}
+/** One offset for messages, padding and editor; hidden trees keep their local state. */
+export function ScrollViewport(props) {
     const { stdout } = useStdout();
-    const cols = colsProp ?? stdout?.columns ?? 80;
+    const { active = true, hold = false, resumeMs = 0, scrollbar } = props;
+    const cols = props.cols ?? stdout?.columns ?? 80;
     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 bodyRef = useRef(null);
+    const footerRef = useRef(null);
+    const [{ metrics, offset }, setGeometry] = useState({
+        metrics: { viewport: 0, content: 0, padding: 0, footer: 0 }, offset: 0,
+    });
+    const pendingMetrics = useRef(metrics);
+    const geometryScheduled = useRef(false);
+    const mounted = useRef(true);
+    const [dragging, setDragging] = useState(false);
+    const offsetRef = useRef(0);
+    const baseline = useRef(null);
+    const latest = useRef({ active, hold, resumeMs, metrics, scrollbar });
+    latest.current = { active, hold, resumeMs, metrics, scrollbar };
+    const pausedLines = useRef(0);
     const resumeTimer = useRef(null);
-    const clearResumeTimer = useCallback(() => {
-        if (!resumeTimer.current)
-            return;
-        clearTimeout(resumeTimer.current);
+    const lastIntent = useRef(props.intent?.nonce);
+    const lastPin = useRef(props.pinToBottomNonce);
+    const lastReset = useRef(props.resetKey);
+    const lastVisible = useRef();
+    const previousActive = useRef(active);
+    const geometryRevision = useRef(0);
+    const geometryBounds = useRef('');
+    const clearResume = useCallback(() => {
+        if (resumeTimer.current)
+            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 publishGeometry = useCallback(() => {
+        if (geometryScheduled.current)
+            return;
+        geometryScheduled.current = true;
+        queueMicrotask(() => {
+            geometryScheduled.current = false;
+            if (!mounted.current)
+                return;
+            const nextMetrics = pendingMetrics.current;
+            const nextOffset = offsetRef.current;
+            setGeometry((previous) => previous.offset === nextOffset &&
+                Object.keys(nextMetrics).every((key) => previous.metrics[key] ===
+                    nextMetrics[key])
+                ? previous : { metrics: nextMetrics, offset: nextOffset });
+        });
+    }, []);
+    const publishOffset = useCallback((next) => {
+        offsetRef.current = next;
+        if (next === 0)
+            pausedLines.current = 0;
+        publishGeometry();
+    }, [publishGeometry]);
+    const isHeld = useCallback(() => latest.current.hold ||
+        !!latest.current.scrollbar?.controller?.isCaptured(), []);
     const armResume = useCallback(() => {
-        clearResumeTimer();
-        if (!shouldArmResume({
-            resumeMs: resumeMsRef.current,
-            offset: offsetRef.current,
-            newLinesWhilePaused: newLinesRef.current,
-            hold: holdRef.current,
-        })) {
+        clearResume();
+        const current = latest.current;
+        if (!current.active || !shouldArmResume({ resumeMs: current.resumeMs,
+            offset: offsetRef.current, newLinesWhilePaused: pausedLines.current, hold: isHeld() }))
             return;
-        }
-        const timer = setTimeout(() => {
+        resumeTimer.current = 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.
+            if (latest.current.active && !isHeld())
+                publishOffset(0);
+        }, current.resumeMs);
+        resumeTimer.current.unref?.();
+    }, [clearResume, isHeld, publishOffset]);
     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,
+        if (!scrollbar)
+            return;
+        const controller = createScrollbarController({
+            getGeometry: () => scrollbar.geometry,
+            isEnabled: () => latest.current.active && scrollbar.frameReady && scrollbar.isEnabled(),
+            setOffset: (next) => { publishOffset(next); armResume(); },
+            page: (kind) => {
+                publishOffset(applyScrollTimes({ offset: offsetRef.current }, kind, latest.current.metrics, 1).offset);
+            },
+            onStart: () => { clearResume(); scrollbar.onStart?.(); },
+            onHold: (held) => { setDragging(held); armResume(); },
         });
-        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 });
+        scrollbar.controller = controller;
+        return () => {
+            controller.dispose();
+            scrollbar.controller = null;
+            scrollbar.geometry = null;
+            scrollbar.invalidate();
+        };
+    }, [scrollbar, publishOffset, armResume, clearResume]);
+    useEffect(() => clearResume, [clearResume]);
+    useLayoutEffect(() => {
+        mounted.current = true;
+        return () => { mounted.current = false; };
+    }, []);
+    useEffect(() => { armResume(); }, [hold, resumeMs, armResume]);
+    useLayoutEffect(() => {
+        const reset = lastReset.current !== props.resetKey;
+        lastReset.current = props.resetKey;
+        const pin = lastPin.current !== props.pinToBottomNonce;
+        lastPin.current = props.pinToBottomNonce;
+        const intent = lastIntent.current !== props.intent?.nonce ? props.intent : undefined;
+        lastIntent.current = props.intent?.nonce;
+        if (reset) {
+            baseline.current = null;
+            pausedLines.current = 0;
+            publishOffset(0);
+            scrollbar?.controller?.cancel();
         }
-        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
-    // `useEffect([nonce])` fires on mount as well as on change, and this
-    // component is unmounted whenever an overlay opens (`App.tsx` swaps it out) —
-    // without the guard, closing an overlay replays whatever wheel gesture was in
-    // flight when it opened, and the transcript jumps a page on its own. That is
-    // R-P1-7, which this codebase has already paid for once through the keyboard
-    // path; the overlay-swallowing rule in `App`'s key handler becomes a SECOND
-    // line of defence rather than the only one.
-    const lastAppliedNonce = useRef(intent?.nonce);
-    const intentNonce = intent?.nonce ?? 0;
-    useEffect(() => {
-        const current = intentRef.current;
-        if (!current)
-            return;
-        if (current.nonce === lastAppliedNonce.current)
+        if (!active) {
+            clearResume();
+            scrollbar?.invalidate();
+            if (scrollbar)
+                scrollbar.geometry = null;
+            previousActive.current = false;
             return;
-        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
-    }, [intentNonce]);
-    useEffect(() => {
-        setScroll({ offset: 0 });
-    }, [pinToBottomNonce]);
-    useEffect(() => {
-        onScrolledLinesChange?.(offset);
-    }, [offset, onScrolledLinesChange]);
-    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).
-    const indicatorVisible = showScrollIndicator && cols >= MIN_INDICATOR_COLS;
-    // PUBLISHED, NOT LIFTED (tui-render-performance L3 / §3.3.2). The three
-    // numbers virtualisation needs are already owned here; a `useMemo`d context
-    // 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 (_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 }))] }) }));
+        }
+        const viewport = clipRef.current ? measureElement(clipRef.current).height : 0;
+        const body = bodyRef.current ? measureElement(bodyRef.current).height : 0;
+        const footer = footerRef.current ? measureElement(footerRef.current).height : 0;
+        const layout = buildDocumentLayout({ rows: viewport + 4, bodyRows: body, footerRows: footer });
+        const padding = props.footer === undefined ? 0 : layout.paddingRows;
+        const content = body + footer + padding;
+        const tail = props.tailRowsRef?.current.rows ?? 0;
+        const old = baseline.current;
+        const reflow = !old || old.cols !== cols || old.viewport !== viewport;
+        const tailDelta = reflow ? 0 : tail - old.tail;
+        const footerDelta = reflow ? 0 : footer - old.footer;
+        const paddingDelta = !old || reflow || props.footer === undefined ? 0 :
+            Math.max(0, viewport - old.body - old.footer - tailDelta - footerDelta) - old.padding;
+        const nextMetrics = { viewport, content, padding, footer };
+        latest.current.metrics = nextMetrics;
+        // Markdown estimates may take more than 50 measurements to converge in a
+        // tall viewport. Publishing during the layout commit recursively mounts
+        // another window before the height store's microtask can finish. Coalesce
+        // geometry with that store outside the commit; keep measuring every frame.
+        // Offset clamps must join the same publication: at the top, each corrected
+        // estimate shrinks the overflow and would otherwise recurse via setOffset.
+        pendingMetrics.current = nextMetrics;
+        publishGeometry();
+        const followed = reduceFollow({ offset: offsetRef.current,
+            overflowLines: Math.max(0, content - viewport), tailDelta,
+            layoutTailDelta: footerDelta + paddingDelta, hold: isHeld(),
+            newLinesWhilePaused: pausedLines.current });
+        pausedLines.current = followed.newLinesWhilePaused;
+        let next = pin || reset ? 0 : followed.offset;
+        if (!pin && intent)
+            next = applyScrollTimes({ offset: next }, intent.kind, nextMetrics, intent.repeat ?? 1).offset;
+        publishOffset(next);
+        baseline.current = { viewport, content, body, footer, padding, cols, tail };
+        if (tailDelta !== 0 || pin || intent || !previousActive.current)
+            armResume();
+        previousActive.current = true;
+        const bounds = `${cols}:${stdout?.columns}:${stdout?.rows}:${viewport}`;
+        if (bounds !== geometryBounds.current) {
+            geometryBounds.current = bounds;
+            geometryRevision.current++;
+            scrollbar?.invalidate();
+        }
+        if (scrollbar) {
+            scrollbar.geometry = { trackTop: 2, trackCol: stdout?.columns ?? cols,
+                trackRows: viewport, contentRows: content, offset: next,
+                thumb: thumbRange(viewport, content, next, true), revision: geometryRevision.current };
+            scrollbar.onGeometry?.();
+        }
+        const visible = composerVisible(props.composerRef?.current ?? null, clipRef.current);
+        if (lastVisible.current !== visible) {
+            lastVisible.current = visible;
+            props.onComposerVisibilityChange?.(visible);
+        }
+    });
+    const shiftUp = Math.max(0, metrics.content - metrics.viewport - offset);
+    useEffect(() => { props.onScrolledLinesChange?.(offset); }, [offset, props.onScrolledLinesChange]);
+    useEffect(() => { if (active)
+        props.onViewportShiftChange?.(shiftUp); }, [active, shiftUp, props.onViewportShiftChange]);
+    const geometry = useMemo(() => ({ viewportRows: metrics.viewport, offset,
+        contentRows: metrics.content, trailingContentRows: metrics.padding + metrics.footer }), [metrics, offset]);
+    return (_jsxs(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: [_jsxs(Box, { display: active ? 'flex' : 'none', flexDirection: "row", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: [_jsx(Box, { ref: clipRef, flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: _jsxs(Box, { flexDirection: "column", flexShrink: 0, marginTop: -shiftUp, children: [_jsx(ViewportGeometryContext.Provider, { value: geometry, children: _jsx(Box, { ref: bodyRef, flexDirection: "column", flexShrink: 0, children: props.children }) }), _jsx(Box, { height: metrics.padding, flexShrink: 0 }), _jsx(Box, { ref: footerRef, flexDirection: "column", flexShrink: 0, children: props.footer })] }) }), props.rail, props.showScrollIndicator && _jsx(ScrollIndicator, { rows: metrics.viewport, thumb: thumbRange(metrics.viewport, metrics.content, offset, true), dragging: dragging, theme: props.theme, caps: props.caps })] }), _jsx(Box, { display: active ? 'none' : 'flex', flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: props.overlay ?? null })] }));
 }