@aragon-agent/cli 0.5.1 → 0.5.2

package/dist/input/stdin-mouse-filter.js

@@ -0,0 +1,153 @@
+/**
+ * Stdin mouse filter (mouse-wheel-region-routing §4.2 / §5.2).
+ *
+ * WHY A WRAPPER AND NOT A SECOND LISTENER. Ink 5.2.1 owns stdin in a way that
+ * forbids a second reader: `components/App.js` calls `setEncoding('utf8')`,
+ * `ref()`, `setRawMode(true)`, subscribes to `'readable'` and drains with
+ * `read()`. Attaching our own `'data'` listener to the same `process.stdin`
+ * would switch the stream into flowing mode and RACE Ink's `read()` for chunks
+ * — some keystrokes would reach Ink, some would not, non-deterministically
+ * (D-3). So the filter REPLACES the stream Ink is given: it reads the real
+ * stdin, strips every mouse report, and writes the remainder into a
+ * `PassThrough` that carries the surface Ink requires.
+ *
+ * ORDERING IS AN INVARIANT, NOT A CONVENTION (I-8). The caller must build this
+ * filter BEFORE anything writes `\x1b[?1000h`. Reporting enabled while Ink
+ * still holds the raw stream does not degrade the feature — it types
+ * `[<0;12;5M` into the user's message on every click, which is strictly worse
+ * than the bug this feature fixes. `cli.tsx::runInteractive` is the only caller
+ * and passes `filter !== null` to `enterAltScreen`.
+ */
+import { PassThrough } from 'node:stream';
+import { splitMouseEvents } from './mouse-events.js';
+/**
+ * How long a possible-prefix tail is held before being flushed as text.
+ *
+ * This is what stops a lone `\x1b` — the Esc key, which aborts a run — from
+ * being held hostage waiting for a `[` that will never arrive. Worst-case Esc
+ * latency becomes 12 ms, and only for the keystroke that is literally a bare
+ * ESC; every other key resolves `isMousePrefix` to false immediately.
+ */
+const PENDING_FLUSH_MS = 12;
+/** Assign a method onto the PassThrough without widening its public type. */
+function define(target, name, value) {
+    Object.defineProperty(target, name, { value, writable: true, configurable: true });
+}
+export function createMouseFilter(real) {
+    const wrapper = new PassThrough();
+    const listeners = new Set();
+    let pending = '';
+    let flushTimer = null;
+    let disposed = false;
+    // --- The surface Ink reads off the stream it is handed. ------------------
+    // `isRawModeSupported()` reads `props.stdin.isTTY` (App.js:34), so this has
+    // to be a DELEGATING GETTER rather than a snapshot: a stdin that is not a TTY
+    // must still report so through the wrapper, or Ink throws instead of falling
+    // back.
+    Object.defineProperty(wrapper, 'isTTY', {
+        get: () => real.isTTY,
+        configurable: true,
+    });
+    define(wrapper, 'setRawMode', (mode) => {
+        real.setRawMode?.(mode);
+        return wrapper;
+    });
+    define(wrapper, 'ref', () => {
+        real.ref?.();
+        return wrapper;
+    });
+    define(wrapper, 'unref', () => {
+        real.unref?.();
+        return wrapper;
+    });
+    const emit = (event) => {
+        for (const listener of [...listeners])
+            listener(event);
+    };
+    const clearFlushTimer = () => {
+        if (!flushTimer)
+            return;
+        clearTimeout(flushTimer);
+        flushTimer = null;
+    };
+    const flushPending = () => {
+        clearFlushTimer();
+        if (pending.length === 0 || disposed)
+            return;
+        const text = pending;
+        pending = '';
+        wrapper.write(text);
+    };
+    const onData = (chunk) => {
+        if (disposed)
+            return;
+        clearFlushTimer();
+        const decoded = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+        const split = splitMouseEvents(pending + decoded);
+        pending = split.pending;
+        if (split.text.length > 0)
+            wrapper.write(split.text);
+        for (const event of split.events)
+            emit(event);
+        if (pending.length > 0) {
+            // `.unref()` so a held tail can never keep the process alive on its own.
+            flushTimer = setTimeout(flushPending, PENDING_FLUSH_MS);
+            flushTimer.unref?.();
+        }
+    };
+    // P2-7: a closed stdin must still terminate Ink's reader, or it waits forever
+    // on a stream that will never produce another byte.
+    const onEnd = () => {
+        flushPending();
+        if (!wrapper.writableEnded)
+            wrapper.end();
+    };
+    // `setEncoding('utf8')` on the REAL stream so Node's StringDecoder handles
+    // multi-byte boundaries for us — the parser works on characters, and a UTF-8
+    // sequence split across two chunks would otherwise become two mojibake
+    // characters before it ever reached `splitMouseEvents`.
+    real.setEncoding?.('utf8');
+    real.on('data', onData);
+    real.once('end', onEnd);
+    real.once('close', onEnd);
+    return {
+        stdin: wrapper,
+        source: {
+            subscribe(listener) {
+                listeners.add(listener);
+                return () => listeners.delete(listener);
+            },
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            clearFlushTimer();
+            real.removeListener('data', onData);
+            real.removeListener('end', onEnd);
+            real.removeListener('close', onEnd);
+            listeners.clear();
+            // I-7: a live `'data'` listener on stdin keeps the event loop alive, and
+            // `aragon` would hang on exit instead of returning to the shell.
+            real.pause?.();
+            real.unref?.();
+        },
+    };
+}
+/**
+ * Build a filter, or `null` if construction throws.
+ *
+ * The `null` return is the whole point (P0-1): `enterAltScreen` derives whether
+ * to enable mouse reporting from `filter !== null`, so a construction failure
+ * degrades to "the wheel is inert" — a supported, tested rung of the fail-safe
+ * ladder — rather than leaving reporting on with no filter in front of Ink.
+ */
+export function tryCreateMouseFilter(real, onError) {
+    try {
+        return createMouseFilter(real);
+    }
+    catch (err) {
+        onError?.(err instanceof Error ? err.message : String(err));
+        return null;
+    }
+}

package/dist/ui/App.d.ts

@@ -9,6 +9,8 @@ import type { AgentController } from '../agent/controller.js';
 import type { ConfirmRequest } from '../tools/index.js';
 import { type Overlay } from '../agent/reducer.js';
 import { type RenderMode } from './layout/frame.js';
+import { type FrameGeometry } from './layout/regions.js';
+import type { MouseSource } from '../input/stdin-mouse-filter.js';
 import type { HumanInputBridge } from '../tools/human-input.js';
 export interface ConfirmBridge {
     handler: ((req: ConfirmRequest) => Promise<boolean>) | null;
@@ -23,5 +25,11 @@ export interface AppProps {
     confirmBridge?: ConfirmBridge;
     /** The plan-mode human channel; absent in tests that do not exercise it. */
     humanInputBridge?: HumanInputBridge;
+    /** Wheel events, already stripped out of stdin. Absent whenever mouse support
+     *  is off: inline mode, `--no-mouse`, a non-TTY, or a filter that failed to
+     *  build (mouse-wheel-region-routing §4.2). */
+    mouseSource?: MouseSource;
+    /** Test-only seam (§8.2): frame geometry, bypassing `measureElement`. */
+    geometryOverride?: FrameGeometry;
 }
-export declare function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, }: AppProps): React.ReactElement;
+export declare function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, geometryOverride, }: AppProps): React.ReactElement;

package/dist/ui/App.js

@@ -31,6 +31,8 @@ import { ScrollViewport } from './layout/ScrollViewport.js';
 import { useTerminalSize } from './layout/useTerminalSize.js';
 import { frameHeight, MIN_FULLSCREEN_ROWS } from './layout/frame.js';
 import { HINT_MIN_ROWS, viewportRows as computeViewportRows } from './layout/budget.js';
+import { UNMEASURED_GEOMETRY } from './layout/regions.js';
+import { OVERLAY_PAGE, useWheelRouting } from './use-wheel-routing.js';
 import { installConsoleBridge } from './console-bridge.js';
 import { publishExitSnapshot } from './exit-snapshot.js';
 import { OverlayFrame } from './layout/OverlayFrame.js';
@@ -46,9 +48,7 @@ import { makeSkillsCommand, registerSkillCommands } from '../commands/skills.js'
 import { MODE_LABEL, nextMode } from '../agent/agent-mode.js';
 /** Merge pending delta actions ~33 ms and flush the coalescer buffer. */
 const COALESCE_MS = 33;
-/** Rows a PgUp/PgDn moves inside a controlled overlay. */
-const OVERLAY_PAGE = 8;
-export function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, }) {
+export function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, geometryOverride, }) {
     const { exit } = useApp();
     const { stdout } = useStdout();
     const fullscreen = mode === 'fullscreen';
@@ -61,6 +61,8 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
     const [promptHistory, setPromptHistory] = useState(() => controller.getConfig().promptHistory ?? []);
     // Scroll plumbing: intent goes down, one derived display number comes back.
     const [scrollIntent, setScrollIntent] = useState();
+    /** One prompt-history step per wheel notch over the composer band (§4.7). */
+    const [historyIntent, setHistoryIntent] = useState();
     const [pinToBottomNonce, setPinToBottomNonce] = useState(0);
     const [scrolledLines, setScrolledLines] = useState(0);
     // I-5 (§4.13): Ctrl+L cannot repaint by writing escapes — Ink dedupes
@@ -98,6 +100,8 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
     /** Every outstanding `gate.request()`. Held in a ref, never in state: it is
      *  bookkeeping for promises, and re-rendering on it would be noise. */
     const pendingHuman = useRef(new Set());
+    /** Written by `AppShell`'s layout effect, read at wheel-event time (§4.5). */
+    const geometryRef = useRef(UNMEASURED_GEOMETRY);
     /**
      * THE SINGLE SETTLE PATH for a human request. Idempotent per entry, and it
      * clears the overlay as its last act.
@@ -233,7 +237,12 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
             return undefined;
         return installConsoleBridge((level, text) => dispatch({ type: 'notice', level, text }));
     }, [fullscreen]);
-    useStartupNotices(dispatch);
+    // `enabled` is `mouseSource`, not `cfg.mouse`: a user whose terminal drops
+    // the events must never be shown advice about a mode not in effect (§6.1).
+    useStartupNotices(dispatch, {
+        enabled: !!mouseSource,
+        onSeen: () => persistConfig({ mouseNoticeSeen: true }),
+    });
     // --- Exit snapshot: the only way state reaches cli.tsx (§4.4). ----------
     useEffect(() => {
         publishExitSnapshot({
@@ -400,8 +409,9 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         controller.setSubmitCount(nextCount);
         persistConfig({ promptHistory: next, submitCount: nextCount });
     };
-    const scrollBy = useCallback((kind) => {
-        setScrollIntent((prev) => ({ kind, nonce: (prev?.nonce ?? 0) + 1 }));
+    /** `repeat` folds a coalesced wheel burst; the keyboard always sends one. */
+    const scrollBy = useCallback((kind, repeat = 1) => {
+        setScrollIntent((prev) => ({ kind, nonce: (prev?.nonce ?? 0) + 1, repeat }));
     }, []);
     /**
      * Send a message to the agent, bypassing slash parsing.
@@ -500,11 +510,30 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         }
         resolveHuman({ kind: 'planDecision', decision: verdict.decision, feedback: verdict.feedback });
     };
+    // --- Mouse wheel region routing (§4.6). Table and coalescer live in the
+    // hook (D-13); only the wiring it cannot own stays here. Inline arrows are
+    // fine — the hook re-reads its options through a ref every render. The
+    // `Math.max(0, …)` mirrors the keyboard branch below, and for the same
+    // reason: `OverlayFrame` only ever reports a clamp DOWNWARD.
+    const { clearCoalescer } = useWheelRouting({
+        mouseSource,
+        geometryRef,
+        geometryOverride,
+        getOverlay: () => stateRef.current.overlay,
+        onScroll: scrollBy,
+        onOverlayScroll: (delta) => setOverlayScroll((n) => Math.max(0, n + delta)),
+        onHistoryStep: (dir) => setHistoryIntent((prev) => ({ dir, nonce: (prev?.nonce ?? 0) + 1 })),
+    });
     // A fresh overlay always opens at the top; carrying the previous overlay's
     // offset over would open Help mid-list for no reason the user can see.
+    //
+    // `clearCoalescer()` rides along here rather than adding a second subscriber
+    // to the same transition (§4.7 rule 2): an accumulated-but-unflushed
+    // transcript scroll must not survive an overlay opening.
     useEffect(() => {
         setOverlayScroll(0);
-    }, [state.overlay]);
+        clearCoalescer();
+    }, [state.overlay, clearCoalescer]);
     // --- Initial overlay / prompt (after handlers are defined). ------------
     useEffect(() => {
         if (initialOverlay)
@@ -666,6 +695,12 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
             apiKey: '',
             logLevel: cfg.log.level,
         }, apiKeys: cfg.apiKeys, maxRows: overlayMaxRows, cols: cols, scrollOffset: overlayScroll, onScrollClamp: setOverlayScroll, theme: theme, caps: caps, onSave: handleSettingsSave })) : overlay === 'confirm' && confirmState ? (_jsx(ConfirmDialog, { state: confirmState, maxRows: overlayMaxRows, cols: cols, theme: theme, caps: caps, onClose: closeConfirm })) : overlay === 'question' && humanRequest?.kind === 'questions' ? (_jsx(QuestionOverlay, { questions: humanRequest.questions, maxRows: overlayMaxRows, cols: cols, theme: theme, caps: caps, onSubmit: (answers) => resolveHuman({ kind: 'answers', answers, cancelled: false }) })) : overlay === 'plan' && humanRequest?.kind === 'plan' ? (_jsx(PlanReviewOverlay, { plan: humanRequest.plan, maxRows: overlayMaxRows, cols: cols, scrollOffset: overlayScroll, onScrollClamp: setOverlayScroll, theme: theme, caps: caps, onVerdict: handlePlanVerdict })) : null;
+    // A MEASUREMENT MUST NEVER OUTLIVE THE FRAME IT DESCRIBED (P1-5): neither
+    // path below renders the full-screen `AppShell`, so nothing else would
+    // overwrite a stale `bottom`. See `UNMEASURED_GEOMETRY` for why there is no
+    // arithmetic fallback.
+    if (!fullscreen || rows < MIN_FULLSCREEN_ROWS)
+        geometryRef.current = UNMEASURED_GEOMETRY;
     // A resize can drop below the usable floor. Do NOT leave the alt-screen —
     // entering and leaving it on every drag is worse than a placeholder — and take
     // the height from `frameHeight()` like everything else, because this is the
@@ -683,11 +718,11 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
     // the header the moment the first message lands.
     const opener = empty ? (_jsx(SessionOpener, { variant: fullscreen ? pickOpenerVariant(viewportBudget, cols, caps) : 'none', version: version, cwd: controller.getCwd(), hasKey: hasKey, viewportRows: fullscreen ? viewportBudget : Number.POSITIVE_INFINITY, theme: theme, caps: caps })) : null;
     const density = cfg.density;
-    const viewport = fullscreen ? (overlayNode ? (_jsx(Box, { flexDirection: "column", flexGrow: 1, overflow: "hidden", children: overlayNode })) : (_jsxs(ScrollViewport, { intent: scrollIntent, pinToBottomNonce: pinToBottomNonce, onScrolledLinesChange: setScrolledLines, theme: theme, caps: caps, children: [opener, _jsx(TranscriptList, { entries: state.entries, expandedToolIds: state.expandedToolIds, thinkingVisible: state.thinkingVisible, reducedMotion: reducedMotion, density: density, theme: theme, caps: caps, windowSize: cfg.transcriptWindow ?? DEFAULT_TRANSCRIPT_WINDOW })] }))) : (_jsxs(_Fragment, { children: [opener, _jsx(Transcript, { entries: state.entries, expandedToolIds: state.expandedToolIds, thinkingVisible: state.thinkingVisible, reducedMotion: reducedMotion, density: density, theme: theme, caps: caps }), overlayNode] }));
+    const viewport = fullscreen ? (overlayNode ? (_jsx(Box, { flexDirection: "column", flexGrow: 1, overflow: "hidden", children: overlayNode })) : (_jsxs(ScrollViewport, { intent: scrollIntent, pinToBottomNonce: pinToBottomNonce, onScrolledLinesChange: setScrolledLines, showScrollIndicator: true, theme: theme, caps: caps, children: [opener, _jsx(TranscriptList, { entries: state.entries, expandedToolIds: state.expandedToolIds, thinkingVisible: state.thinkingVisible, reducedMotion: reducedMotion, density: density, theme: theme, caps: caps, windowSize: cfg.transcriptWindow ?? DEFAULT_TRANSCRIPT_WINDOW })] }))) : (_jsxs(_Fragment, { children: [opener, _jsx(Transcript, { entries: state.entries, expandedToolIds: state.expandedToolIds, thinkingVisible: state.thinkingVisible, reducedMotion: reducedMotion, density: density, theme: theme, caps: caps }), overlayNode] }));
     // The completion popup lives inside the bottom chrome and can add up to 9
     // rows; unbounded, it pushes the status bar past the frame height where
     // `overflow: hidden` clips it away (R-14 / M-14). Cap it against the viewport.
     const popupMaxRows = fullscreen ? Math.max(1, viewportBudget - 4) : undefined;
-    const composer = fullscreen ? (_jsx(Composer, { isActive: overlay === null, running: state.status === 'running', history: promptHistory, commands: commandOptions, cwd: controller.getCwd(), showHint: rows >= HINT_MIN_ROWS, submitCount: cfg.submitCount, hintsEnabled: cfg.hints, agentMode: state.agentMode, popupMaxRows: popupMaxRows, theme: theme, caps: caps, onSubmit: (text) => void handleSubmit(text), onHelp: () => dispatch({ type: 'setOverlay', overlay: 'help' }) })) : (_jsx(Box, { marginTop: 1, children: _jsx(PromptInput, { isActive: overlay === null, running: state.status === 'running', history: promptHistory, commands: commandOptions, cwd: controller.getCwd(), agentMode: state.agentMode, theme: theme, caps: caps, onSubmit: (text) => void handleSubmit(text), onHelp: () => dispatch({ type: 'setOverlay', overlay: 'help' }) }) }));
-    return (_jsx(AppShell, { mode: mode, rows: rows, cols: cols, header: header, viewport: viewport, toast: _jsx(ToastStack, { toasts: state.toasts, theme: theme, mode: mode }), composer: composer, status: _jsx(StatusBar, { model: cfg.model, provider: cfg.provider, usageTotal: state.usageTotal, contextTokens: state.contextTokens, contextWindow: modelInfo.contextWindow, contextWindowKnown: modelKnown, status: state.status, elapsedMs: elapsedMs, thinkingLevel: cfg.thinkingLevel, tokPerSec: tokPerSec, theme: theme, caps: caps, scrolledLines: scrolledLines, redrawNonce: redrawNonce, agentMode: state.agentMode, pendingAgentMode: state.pendingAgentMode }) }));
+    const composer = fullscreen ? (_jsx(Composer, { isActive: overlay === null, running: state.status === 'running', history: promptHistory, commands: commandOptions, cwd: controller.getCwd(), showHint: rows >= HINT_MIN_ROWS, submitCount: cfg.submitCount, hintsEnabled: cfg.hints, agentMode: state.agentMode, popupMaxRows: popupMaxRows, historyIntent: historyIntent, theme: theme, caps: caps, onSubmit: (text) => void handleSubmit(text), onHelp: () => dispatch({ type: 'setOverlay', overlay: 'help' }) })) : (_jsx(Box, { marginTop: 1, children: _jsx(PromptInput, { isActive: overlay === null, running: state.status === 'running', history: promptHistory, commands: commandOptions, cwd: controller.getCwd(), agentMode: state.agentMode, theme: theme, caps: caps, onSubmit: (text) => void handleSubmit(text), onHelp: () => dispatch({ type: 'setOverlay', overlay: 'help' }) }) }));
+    return (_jsx(AppShell, { mode: mode, rows: rows, cols: cols, geometryRef: geometryRef, header: header, viewport: viewport, toast: _jsx(ToastStack, { toasts: state.toasts, theme: theme, mode: mode }), composer: composer, status: _jsx(StatusBar, { model: cfg.model, provider: cfg.provider, usageTotal: state.usageTotal, contextTokens: state.contextTokens, contextWindow: modelInfo.contextWindow, contextWindowKnown: modelKnown, status: state.status, elapsedMs: elapsedMs, thinkingLevel: cfg.thinkingLevel, tokPerSec: tokPerSec, theme: theme, caps: caps, scrolledLines: scrolledLines, redrawNonce: redrawNonce, agentMode: state.agentMode, pendingAgentMode: state.pendingAgentMode }) }));
 }

package/dist/ui/Composer.d.ts

@@ -35,9 +35,14 @@ export interface ComposerProps {
     /** Mirror of the controller's effective mode; drives the chip and the border. */
     agentMode: AgentMode;
     popupMaxRows?: number;
+    /** Pure pass-through to `PromptInput` (mouse-wheel-region-routing §5.6). */
+    historyIntent?: {
+        dir: 'up' | 'down';
+        nonce: number;
+    };
     theme: Theme;
     caps: TermCapabilities;
     onSubmit: (text: string) => void;
     onHelp?: () => void;
 }
-export declare function Composer({ isActive, running, history, commands, cwd, showHint, submitCount, hintsEnabled, agentMode, popupMaxRows, theme, caps, onSubmit, onHelp, }: ComposerProps): React.ReactElement;
+export declare function Composer({ isActive, running, history, commands, cwd, showHint, submitCount, hintsEnabled, agentMode, popupMaxRows, historyIntent, theme, caps, onSubmit, onHelp, }: ComposerProps): React.ReactElement;

package/dist/ui/Composer.js

@@ -56,7 +56,7 @@ function hintText(running, submitCount, glyphs, mode) {
         '? help',
     ].join(dot);
 }
-export function Composer({ isActive, running, history, commands, cwd, showHint, submitCount, hintsEnabled, agentMode, popupMaxRows, theme, caps, onSubmit, onHelp, }) {
+export function Composer({ isActive, running, history, commands, cwd, showHint, submitCount, hintsEnabled, agentMode, popupMaxRows, historyIntent, theme, caps, onSubmit, onHelp, }) {
     const [hasDraft, setHasDraft] = useState(false);
     const onDraftChange = useCallback((next) => setHasDraft(next), []);
     // Plan mode inserts ONE branch, above `draft` and below `running`. The
@@ -73,7 +73,7 @@ export function Composer({ isActive, running, history, commands, cwd, showHint,
                     : theme.idleBorder ?? theme.border;
     const glyphs = pickGlyphs(caps);
     const visible = showHint && hintsEnabled;
-    return (_jsxs(Box, { flexDirection: "column", flexShrink: 0, children: [_jsx(PromptInput, { isActive: isActive, running: running, history: history, commands: commands, cwd: cwd, theme: theme, caps: caps, popupMaxRows: popupMaxRows, onSubmit: onSubmit, onHelp: onHelp, agentMode: agentMode, bordered: { color: borderColor }, onDraftChange: onDraftChange }), visible && (
+    return (_jsxs(Box, { flexDirection: "column", flexShrink: 0, children: [_jsx(PromptInput, { isActive: isActive, running: running, history: history, commands: commands, cwd: cwd, theme: theme, caps: caps, popupMaxRows: popupMaxRows, onSubmit: onSubmit, onHelp: onHelp, agentMode: agentMode, bordered: { color: borderColor }, onDraftChange: onDraftChange, historyIntent: historyIntent }), visible && (
             // The chip rides the EXISTING hint row rather than adding one, so it
             // costs zero rows on a 24-row terminal.
             _jsxs(Box, { flexDirection: "row", flexShrink: 0, children: [_jsx(Text, { children: '  ' }), _jsx(ModeChip, { mode: agentMode, theme: theme, caps: caps }), _jsx(Text, { wrap: "truncate", color: theme.hintFg ?? theme.muted, children: hintText(running, submitCount, glyphs, agentMode) })] }))] }));

package/dist/ui/PromptInput.d.ts

@@ -55,6 +55,20 @@ interface PromptInputProps {
     };
     /** Fires only when the draft flips empty ⇄ non-empty, for the border color. */
     onDraftChange?: (hasDraft: boolean) => void;
+    /**
+     * One prompt-history step, pushed by the wheel router when a notch lands on
+     * the composer band (mouse-wheel-region-routing §5.6). `nonce` is monotonic
+     * so two notches in the same direction are two steps.
+     *
+     * Applied through the SAME `verticalOrHistory` / popup-selection branches the
+     * keyboard uses, deliberately: it means the wheel and `↑`/`↓` cannot drift
+     * apart, and the "never clobber an in-progress draft" guard protects the
+     * wheel for free.
+     */
+    historyIntent?: {
+        dir: 'up' | 'down';
+        nonce: number;
+    };
 }
 /** Apply an edit intent as a pure buffer/cursor transform. */
 export declare function applyEdit(buffer: string, cursor: number, intent: EditIntent): {
@@ -84,5 +98,5 @@ export declare function fileTokenAt(buffer: string, cursor: number): {
     end: number;
     query: string;
 } | null;
-export declare function PromptInput({ isActive, running, history, commands, cwd, theme, caps, popupMaxRows, agentMode, onSubmit, onHelp, bordered, onDraftChange, }: PromptInputProps): React.ReactElement;
+export declare function PromptInput({ isActive, running, history, commands, cwd, theme, caps, popupMaxRows, agentMode, onSubmit, onHelp, bordered, onDraftChange, historyIntent, }: PromptInputProps): React.ReactElement;
 export {};

package/dist/ui/PromptInput.js

@@ -127,7 +127,7 @@ function isControlSeq(input) {
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
-export function PromptInput({ isActive, running, history, commands, cwd, theme, caps, popupMaxRows, agentMode, onSubmit, onHelp, bordered, onDraftChange, }) {
+export function PromptInput({ isActive, running, history, commands, cwd, theme, caps, popupMaxRows, agentMode, onSubmit, onHelp, bordered, onDraftChange, historyIntent, }) {
     const [buffer, setBuffer] = useState('');
     const [cursor, setCursor] = useState(0);
     const [historyIndex, setHistoryIndex] = useState(null);
@@ -261,6 +261,43 @@ export function PromptInput({ isActive, running, history, commands, cwd, theme,
                 recallDown();
         }
     };
+    // --- Wheel-driven history step (mouse-wheel-region-routing §5.6). ---------
+    // The applier closes over the buffer, the cursor and the popup state, so it
+    // is re-created on every render and reached through a ref: depending on it
+    // directly would re-fire the effect on every keystroke.
+    const applyHistoryIntent = useRef(() => { });
+    applyHistoryIntent.current = (dir) => {
+        // Mirrors the keyboard branch exactly — with the completion popup open,
+        // Up/Down move the selection rather than recalling history.
+        if (popupItems.length > 0) {
+            setSel(dir === 'up'
+                ? Math.max(0, clampedSel - 1)
+                : Math.min(popupItems.length - 1, clampedSel + 1));
+            return;
+        }
+        verticalOrHistory(dir);
+    };
+    const historyIntentRef = useRef(historyIntent);
+    historyIntentRef.current = historyIntent;
+    // I-9: seeded from the incoming nonce during the FIRST render, so a mount
+    // that inherits a nonce cannot replay it. This component really does remount
+    // — `App` returns the terminal-too-small placeholder before `AppShell` —
+    // so without the guard, shrinking the window mid-wheel and growing it back
+    // recalls a history entry with no gesture behind it.
+    const lastHistoryNonce = useRef(historyIntent?.nonce);
+    const historyNonce = historyIntent?.nonce ?? 0;
+    useEffect(() => {
+        const current = historyIntentRef.current;
+        if (!current || !isActive)
+            return;
+        if (current.nonce === lastHistoryNonce.current)
+            return;
+        lastHistoryNonce.current = current.nonce;
+        applyHistoryIntent.current(current.dir);
+        // Keyed on the nonce alone, same reasoning as `ScrollViewport`'s intent
+        // effect: `historyIntent` is a fresh object on every parent render.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [historyNonce]);
     // --- Input handling. -----------------------------------------------------
     useInput((input, key) => {
         // FIRST STATEMENT, BEFORE THE POPUP BRANCH, AND IT HAS TO STAY THERE.

package/dist/ui/glyphs.d.ts

@@ -72,6 +72,18 @@ export interface Glyphs {
     railVertical: string;
     railBranch: string;
     railEnd: string;
+    /**
+     * Scroll-position indicator on the viewport's right edge (mouse-wheel §4.8).
+     *
+     * These are byte-for-byte identical to `railVertical` / `gaugeFull` in both
+     * tiers, and that is DELIBERATE (P2-2). This file's header mandates "add a
+     * field here instead" of a new exception, and semantic field names are what
+     * make the ASCII tier reviewable at a glance. Reusing `gaugeFull` would
+     * couple the scroll thumb to the context-window gauge, so that restyling one
+     * silently restyles the other — do not "deduplicate" them.
+     */
+    scrollTrack: string;
+    scrollThumb: string;
     /** Redaction dot for `maskSecret` in the settings screen (§4.1 tier B). */
     maskDot: string;
     /**

package/dist/ui/glyphs.js

@@ -55,6 +55,8 @@ const UNICODE_GLYPHS = {
     railVertical: '│',
     railBranch: '├',
     railEnd: '╰',
+    scrollTrack: '│',
+    scrollThumb: '█',
     maskDot: '•',
     boxStyle: 'round',
     tool: {
@@ -107,6 +109,8 @@ const ASCII_GLYPHS = {
     railVertical: '|',
     railBranch: '|',
     railEnd: '\\',
+    scrollTrack: '|',
+    scrollThumb: '#',
     maskDot: '*',
     boxStyle: 'classic',
     tool: {

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

@@ -11,6 +11,7 @@
  */
 import React from 'react';
 import { type RenderMode } from './frame.js';
+import { type FrameGeometry } from './regions.js';
 export interface AppShellProps {
     mode: RenderMode;
     rows: number;
@@ -20,5 +21,13 @@ export interface AppShellProps {
     toast: React.ReactNode;
     composer: React.ReactNode;
     status: React.ReactNode;
+    /**
+     * Where the wheel router reads the composer band boundary from (mouse-wheel
+     * §4.5). Written in a LAYOUT EFFECT to a MUTABLE REF, never to state: the
+     * measurement happens on every commit, and routing it through `setState`
+     * would add a re-render to the streaming path for a value nothing renders
+     * (R-7).
+     */
+    geometryRef?: React.MutableRefObject<FrameGeometry>;
 }
-export declare function AppShell({ mode, rows, cols, header, viewport, toast, composer, status, }: AppShellProps): React.ReactElement;
+export declare function AppShell({ mode, rows, cols, header, viewport, toast, composer, status, geometryRef, }: AppShellProps): React.ReactElement;

package/dist/ui/layout/AppShell.js

@@ -1,9 +1,44 @@
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
-import { Box } from 'ink';
+/**
+ * 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.
+ */
+import { useLayoutEffect, useRef } from 'react';
+import { Box, measureElement } from 'ink';
 import { frameHeight } from './frame.js';
-export function AppShell({ mode, rows, cols, header, viewport, toast, composer, status, }) {
+import { UNMEASURED_GEOMETRY } from './regions.js';
+export function AppShell({ mode, rows, cols, header, viewport, toast, composer, status, geometryRef, }) {
+    const bottomRef = useRef(null);
+    // DECLARED ABOVE THE INLINE EARLY RETURN, and it has to stay there: React
+    // keys hooks by call order, and a hook that only runs in one mode changes
+    // that order between modes.
+    //
+    // Ink computes yoga layout in `onRender`, which React runs BEFORE layout
+    // effects, so this reflects the commit that just happened — the same
+    // mechanism `ScrollViewport` already relies on.
+    useLayoutEffect(() => {
+        if (!geometryRef)
+            return;
+        if (mode === 'inline' || !bottomRef.current) {
+            geometryRef.current = UNMEASURED_GEOMETRY;
+            return;
+        }
+        geometryRef.current = {
+            // 1 in the alternate screen — see the note on `FrameGeometry.top`.
+            top: 1,
+            height: frameHeight(rows),
+            bottom: measureElement(bottomRef.current).height,
+        };
+    });
     if (mode === 'inline') {
         return (_jsxs(Box, { flexDirection: "column", children: [header, viewport, toast, composer, status] }));
     }
-    return (_jsxs(Box, { flexDirection: "column", height: frameHeight(rows), width: cols, overflow: "hidden", children: [_jsx(Box, { flexDirection: "column", flexShrink: 0, children: header }), _jsx(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: viewport }), _jsxs(Box, { flexDirection: "column", flexShrink: 0, children: [toast, composer, status] })] }));
+    return (_jsxs(Box, { flexDirection: "column", height: frameHeight(rows), width: cols, overflow: "hidden", children: [_jsx(Box, { flexDirection: "column", flexShrink: 0, children: header }), _jsx(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: viewport }), _jsxs(Box, { ref: bottomRef, flexDirection: "column", flexShrink: 0, children: [toast, composer, status] })] }));
 }

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

@@ -0,0 +1,31 @@
+/**
+ * ScrollIndicator (mouse-wheel-region-routing §4.8) — the one-column scroll
+ * position rail on the viewport's right edge.
+ *
+ * NAMING (P2-1): this is NOT `layout/Gutter.tsx`. That one is the two-column
+ * left rail every transcript entry sits in, and it carries an invariant of its
+ * own. Two components called a gutter, on opposite edges, for unrelated
+ * purposes, is how a codebase stops being able to say what it means.
+ *
+ * THE COLUMN IS RESERVED UNCONDITIONALLY, track glyph and all. Showing it only
+ * while scrolled would change the content width, re-wrap every line, change the
+ * content height, and feed that back into the measurement that decides whether
+ * to show it — a shimmer at the exact moment the user is reading. Constant
+ * width, no feedback loop (D-9); `width={1}` and `flexShrink={0}` hold the
+ * column even on the first frame, before anything has been measured.
+ */
+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;
+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;
+    theme: Theme;
+    caps: TermCapabilities;
+}
+export declare function ScrollIndicator({ rows, thumb, theme, caps, }: ScrollIndicatorProps): React.ReactElement;

package/dist/ui/layout/ScrollIndicator.js

@@ -0,0 +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, }) {
+    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));
+    }
+    return (_jsx(Box, { flexDirection: "column", flexShrink: 0, width: 1, children: cells }));
+}

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

@@ -17,17 +17,23 @@ import type { Theme } from '../theme.js';
 import type { TermCapabilities } from '../capabilities.js';
 import { type ScrollIntent } from './scroll.js';
 export interface ScrollViewportProps {
-    /** Scroll intent. `nonce` is monotonic so pressing the same key twice re-fires. */
+    /**
+     * 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. */
     onScrolledLinesChange?: (lines: number) => void;
+    /** Reserve the right-edge scroll-position rail (mouse-wheel §4.8). */
+    showScrollIndicator?: boolean;
     theme: Theme;
     caps: TermCapabilities;
     children: React.ReactNode;
 }
-export declare function ScrollViewport({ intent, pinToBottomNonce, onScrolledLinesChange, theme, caps, children, }: ScrollViewportProps): React.ReactElement;
+export declare function ScrollViewport({ intent, pinToBottomNonce, onScrolledLinesChange, showScrollIndicator, theme, caps, children, }: ScrollViewportProps): React.ReactElement;