@aragon-agent/cli 0.6.7 → 0.6.9

package/dist/ui/layout/ScrollViewport.js

@@ -1,204 +1,214 @@
 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';
+/**
+ * Whether `element` lies fully inside `clip`. A missing element (not mounted) or
+ * clip reports `true`, so a caller that consumes the answer must first know the
+ * element is actually mounted. Rows are one line tall, so "partially visible"
+ * cannot occur for the run status row.
+ */
+function elementVisible(element, clip) {
+    if (!element || !clip)
+        return true;
+    let top = 0;
+    let current = element;
+    while (current && current !== clip) {
+        top += current.yogaNode?.getComputedTop() ?? 0;
+        current = current.parentNode;
+    }
+    return current === clip && top >= 0 &&
+        top + measureElement(element).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 lastActivityVisible = 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)
+        if (!active) {
+            clearResume();
+            scrollbar?.invalidate();
+            if (scrollbar)
+                scrollbar.geometry = null;
+            previousActive.current = false;
             return;
-        if (current.nonce === lastAppliedNonce.current)
-            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 = elementVisible(props.composerRef?.current ?? null, clipRef.current);
+        if (lastVisible.current !== visible) {
+            lastVisible.current = visible;
+            props.onComposerVisibilityChange?.(visible);
+        }
+        const activityVisible = elementVisible(props.activityRef?.current ?? null, clipRef.current);
+        if (lastActivityVisible.current !== activityVisible) {
+            lastActivityVisible.current = activityVisible;
+            props.onActivityVisibilityChange?.(activityVisible);
+        }
+    });
+    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 })] }));
 }

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

@@ -1,29 +1,4 @@
-/**
- * Layout budget (spec §4.2a) — the ONE function that says how many rows the
- * viewport gets.
- *
- * Before v0.4.0 this number was computed nowhere and assumed in three places,
- * which is how the viewport ended up NON-MONOTONIC in `rows`: growing the
- * terminal from 27 to 28 rows promoted the header to the 8-row wordmark tier and
- * the visible content SHRANK from 18 rows to 13. Making the brand region a
- * constant 1 row (§4.2) is what fixes that, and this module is where the fix is
- * expressed as arithmetic so `budget.test.ts` can pin it.
- *
- * Deliberately NOT part of `frame.ts`: that file is the read-only foundation
- * (invariant I-1) and this is content-layer policy.
- *
- * Scope: the STATIC chrome only. 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).
- */
+/** Fullscreen reserves three fixed rows; composer height is a footer layout input. */
 /** Below this many rows the composer's hint line is dropped to buy back a row. */
 export declare const HINT_MIN_ROWS = 20;
 export interface ChromeBudget {
@@ -50,28 +25,5 @@ export interface ChromeBudget {
  */
 export declare function clampDraftRows(rows: number, draftRows: number): number;
 export declare function chromeBudget(rows: number, draftRows?: number): ChromeBudget;
-/**
- * Rows available to the viewport at a given terminal height.
- *
- * Note what is NOT a parameter: whether the transcript is empty. The absence of
- * that argument is the guarantee that the first submitted message cannot make
- * the layout jump (A-4). Do not add it back.
- *
- * `draftRows` IS NOT THAT ARGUMENT, and the distinction is the whole of D-12.
- * A-4 forbids making the budget depend on TRANSCRIPT content, so that the first
- * submitted message cannot move the layout. `draftRows` depends only on what the
- * user is typing right now, and its whole purpose is that the jump is ALREADY
- * HAPPENING -- Yoga takes the rows out of the transcript whether or not this
- * function was told. `App` adds the hysteresis (grow now, shrink one tick later)
- * that keeps it from becoming per-keystroke jitter.
- *
- * It DEFAULTS TO 1, i.e. to the constant this function used to assume, so every
- * pre-existing caller and every pre-existing assertion is byte-identical -- and
- * `viewportRows.length` stays 1, because a parameter with a default does not
- * count toward it.
- *
- * Non-decreasing in `rows` at a fixed `draftRows = 1`: the one step where chrome
- * grows (the hint row at `HINT_MIN_ROWS`) coincides with `rows` growing by one,
- * so the net change is 0 rather than -1.
- */
-export declare function viewportRows(rows: number, draftRows?: number): number;
+/** Shared document height; the legacy draft argument remains source-compatible. */
+export declare function viewportRows(rows: number, _draftRows?: number): number;

package/dist/ui/layout/budget.js

@@ -1,29 +1,4 @@
-/**
- * Layout budget (spec §4.2a) — the ONE function that says how many rows the
- * viewport gets.
- *
- * Before v0.4.0 this number was computed nowhere and assumed in three places,
- * which is how the viewport ended up NON-MONOTONIC in `rows`: growing the
- * terminal from 27 to 28 rows promoted the header to the 8-row wordmark tier and
- * the visible content SHRANK from 18 rows to 13. Making the brand region a
- * constant 1 row (§4.2) is what fixes that, and this module is where the fix is
- * expressed as arithmetic so `budget.test.ts` can pin it.
- *
- * Deliberately NOT part of `frame.ts`: that file is the read-only foundation
- * (invariant I-1) and this is content-layer policy.
- *
- * Scope: the STATIC chrome only. 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).
- */
+/** Fullscreen reserves three fixed rows; composer height is a footer layout input. */
 import { draftMaxRows } from '../composer-limits.js';
 import { frameHeight, MIN_FULLSCREEN_ROWS } from './frame.js';
 /** Below this many rows the composer's hint line is dropped to buy back a row. */
@@ -47,33 +22,9 @@ export function chromeBudget(rows, draftRows = 1) {
         status: 1,
     };
 }
-/**
- * Rows available to the viewport at a given terminal height.
- *
- * Note what is NOT a parameter: whether the transcript is empty. The absence of
- * that argument is the guarantee that the first submitted message cannot make
- * the layout jump (A-4). Do not add it back.
- *
- * `draftRows` IS NOT THAT ARGUMENT, and the distinction is the whole of D-12.
- * A-4 forbids making the budget depend on TRANSCRIPT content, so that the first
- * submitted message cannot move the layout. `draftRows` depends only on what the
- * user is typing right now, and its whole purpose is that the jump is ALREADY
- * HAPPENING -- Yoga takes the rows out of the transcript whether or not this
- * function was told. `App` adds the hysteresis (grow now, shrink one tick later)
- * that keeps it from becoming per-keystroke jitter.
- *
- * It DEFAULTS TO 1, i.e. to the constant this function used to assume, so every
- * pre-existing caller and every pre-existing assertion is byte-identical -- and
- * `viewportRows.length` stays 1, because a parameter with a default does not
- * count toward it.
- *
- * Non-decreasing in `rows` at a fixed `draftRows = 1`: the one step where chrome
- * grows (the hint row at `HINT_MIN_ROWS`) coincides with `rows` growing by one,
- * so the net change is 0 rather than -1.
- */
-export function viewportRows(rows, draftRows = 1) {
+/** Shared document height; the legacy draft argument remains source-compatible. */
+export function viewportRows(rows, _draftRows = 1) {
     if (!Number.isFinite(rows) || rows < MIN_FULLSCREEN_ROWS)
         return 0;
-    const c = chromeBudget(rows, draftRows);
-    return Math.max(0, frameHeight(rows) - c.header - c.toast - c.composer - c.status);
+    return Math.max(0, frameHeight(rows) - 3);
 }

package/dist/ui/layout/document-layout.d.ts

@@ -0,0 +1,13 @@
+export interface DocumentLayoutInput {
+    rows: number;
+    bodyRows: number;
+    footerRows: number;
+}
+export interface DocumentLayout {
+    viewportRows: number;
+    paddingRows: number;
+    contentRows: number;
+    trailingContentRows: number;
+}
+/** Allocate the shared document, filling short sessions before the editor. */
+export declare function buildDocumentLayout(input: DocumentLayoutInput): DocumentLayout;

package/dist/ui/layout/document-layout.js

@@ -0,0 +1,11 @@
+import { frameHeight } from './frame.js';
+/** Allocate the shared document, filling short sessions before the editor. */
+export function buildDocumentLayout(input) {
+    const count = (n) => Number.isFinite(n) ? Math.max(0, Math.floor(n)) : 0;
+    const viewportRows = count(input.rows) > 0 ? Math.max(0, frameHeight(count(input.rows)) - 3) : 0;
+    const body = count(input.bodyRows);
+    const footer = count(input.footerRows);
+    const paddingRows = Math.max(0, viewportRows - body - footer);
+    return { viewportRows, paddingRows, contentRows: body + paddingRows + footer,
+        trailingContentRows: paddingRows + footer };
+}

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

@@ -58,6 +58,7 @@ export interface FollowInput {
     overflowLines: number;
     /** Signed: rows appended at (or removed from) the tail since the last frame. */
     tailDelta: number;
+    layoutTailDelta?: number;
     /** True while a selection drag holds the viewport (§4.4). */
     hold: boolean;
     newLinesWhilePaused: number;

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

@@ -74,9 +74,7 @@ export function reduceFollow(input) {
     // 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);
+    const next = clampScroll(offset + tailDelta + (input.layoutTailDelta ?? 0), overflowLines);
     return {
         offset: next,
         // Only real arrivals arm the resume timer, and reaching the bottom by ANY

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

@@ -4,7 +4,6 @@
  * Two pure functions with zero React dependency so the load-bearing invariant
  * I-1 (`frameHeight(r) < r`) can be pinned by a unit test rather than by hope.
  */
-export type RenderMode = 'fullscreen' | 'inline';
 /** Below this many rows a full-screen frame has no usable viewport left. */
 export declare const MIN_FULLSCREEN_ROWS = 12;
 /** Below this many columns the chrome (composer + status bar) cannot line-wrap sanely. */
@@ -35,24 +34,3 @@ export declare const FALLBACK_COLS = 80;
  * terminal is strictly better than a per-frame full-screen repaint.
  */
 export declare function frameHeight(rows: number | undefined): number;
-interface StdoutLike {
-    isTTY?: boolean;
-    rows?: number;
-    columns?: number;
-}
-/**
- * Decide the render mode once, at startup (never re-decided at run time —
- * entering/leaving the alt-screen mid-session is a state machine we do not want).
- *
- * Order is semantics, not style:
- *  1. an explicit opt-out always wins (users can always get v0.2.0 back);
- *  2. `isTTY` is the one gate `--fullscreen` cannot override — writing ANSI into
- *     a pipe or a redirected file is a contract violation, whereas a heuristic
- *     misfire only costs polish;
- *  3. the explicit force comes next so it can beat the heuristics below;
- *  4. heuristics (TERM/CI/size), all overridable by `--fullscreen`.
- */
-export declare function decideRenderMode(flags: {
-    fullscreen?: boolean;
-}, env: Record<string, string | undefined>, stdout: StdoutLike | undefined): RenderMode;
-export {};