@aragon-agent/cli 0.5.1 → 0.5.2

package/dist/ui/layout/ScrollViewport.js

@@ -16,10 +16,12 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { Box, Text, measureElement, useStdout } from 'ink';
 import { pickGlyphs } from '../glyphs.js';
-import { applyScroll, clampScroll, } from './scroll.js';
+import { applyScrollTimes, clampScroll, } from './scroll.js';
+import { thumbRange } from './scroll-indicator.js';
+import { MIN_INDICATOR_COLS, ScrollIndicator } from './ScrollIndicator.js';
 /** Below this the full hint sentence wraps and eats a second viewport row. */
 const TERSE_HINT_COLS = 42;
-export function ScrollViewport({ intent, pinToBottomNonce = 0, onScrolledLinesChange, theme, caps, children, }) {
+export function ScrollViewport({ intent, pinToBottomNonce = 0, onScrolledLinesChange, showScrollIndicator = false, theme, caps, children, }) {
     const { stdout } = useStdout();
     const cols = stdout?.columns ?? 80;
     const glyphs = pickGlyphs(caps);
@@ -38,12 +40,26 @@ export function ScrollViewport({ intent, pinToBottomNonce = 0, onScrolledLinesCh
         const content = innerRef.current ? measureElement(innerRef.current).height : 0;
         setMetrics((prev) => (prev.viewport === viewport && prev.content === content ? prev : { viewport, content }));
     });
+    // 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;
-        setScroll((prev) => applyScroll(prev, current.kind, metricsRef.current));
+        if (current.nonce === lastAppliedNonce.current)
+            return;
+        lastAppliedNonce.current = current.nonce;
+        const repeat = current.repeat ?? 1;
+        setScroll((prev) => applyScrollTimes(prev, current.kind, metricsRef.current, repeat));
         // 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
@@ -61,7 +77,11 @@ export function ScrollViewport({ intent, pinToBottomNonce = 0, onScrolledLinesCh
     // what "N new lines you have not scrolled down to" means.
     const hiddenBelow = offset;
     const showHint = hiddenBelow > 0;
-    return (_jsxs(Box, { flexDirection: "column", 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: children }) }), showHint && (
+    // 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;
+    return (_jsxs(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: [_jsxs(Box, { flexDirection: "row", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: [_jsx(Box, { ref: clipRef, flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: _jsx(Box, { ref: innerRef, flexDirection: "column", flexShrink: 0, marginTop: -shiftUp, children: children }) }), indicatorVisible && (_jsx(ScrollIndicator, { rows: metrics.viewport, thumb: thumbRange(metrics.viewport, metrics.content, offset), theme: theme, caps: caps }))] }), showHint && (
             // Not an overlay — Ink has no absolute positioning or z-index. This takes
             // the viewport's last row, trading one line of content for a hint that
             // cannot drift. Cheaper than stacking with negative margins.

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

@@ -0,0 +1,55 @@
+/**
+ * Wheel band hit-testing (mouse-wheel-region-routing §4.5) — pure, React-free.
+ *
+ * The requirement is stated in terms of REGIONS ("scrolling over the agent area
+ * scrolls the transcript; scrolling over the input box steps prompt history"),
+ * so the router needs to turn a reported terminal row into one of two bands.
+ *
+ * The boundary is MEASURED, never computed from `budget.ts`. That arithmetic
+ * describes the PLANNED chrome, but the real bottom chrome grows and shrinks at
+ * run time: the toast row comes and goes, the hint row is dropped below
+ * `HINT_MIN_ROWS`, and the autocomplete popup adds up to nine rows. Routing off
+ * the plan would put the boundary in the wrong place exactly when the popup is
+ * open — the moment precision matters most (D-5 / D-16).
+ */
+export type WheelBand = 'content' | 'composer';
+export interface FrameGeometry {
+    /**
+     * 1-based row of the frame's first row. 1 in the alternate screen.
+     *
+     * This is DERIVED, not assumed, and it has a named dependency: it holds
+     * because the full-screen transcript renders no `<Static>`
+     * (`Transcript.tsx`), so Ink's `log-update` writes `frameHeight(rows) = rows-1`
+     * lines plus a newline into a `rows`-row buffer — nothing scrolls, and the
+     * frame sits at rows `1 … rows-1` with the cursor parked on the undrawn last
+     * row. Reintroducing `<Static>` into the full-screen path pushes the frame
+     * down the screen and silently biases every hit test; whoever does that has
+     * to change `top` here at the same time.
+     */
+    top: number;
+    /** Rows the frame occupies — `frameHeight(rows)`. */
+    height: number;
+    /** Measured rows of the bottom chrome (toast + composer + status). */
+    bottom: number;
+}
+/**
+ * The "I do not know where the frame is" value.
+ *
+ * `App` writes it into the geometry ref on every render path that does NOT
+ * render the full-screen `AppShell` — the terminal-too-small placeholder and
+ * inline mode — so a stale measurement can never outlive the frame it
+ * described. There is deliberately no arithmetic fallback: an unmeasured frame
+ * routes to `'content'`, which is the band that cannot destroy anything, and
+ * one invisible frame after a resize is a better failure than a wrong band
+ * (§4.5, P1-5 / D-16).
+ */
+export declare const UNMEASURED_GEOMETRY: FrameGeometry;
+/**
+ * Which band does terminal row `y` belong to?
+ *
+ * Fails toward `'content'`: the whole point of this feature is that a wheel
+ * notch must never edit the user's draft (I-3), so every degenerate input —
+ * nothing measured yet, a row outside the frame, a chrome measurement that
+ * swallowed the screen — resolves to the harmless direction.
+ */
+export declare function hitTestWheel(y: number, geometry: FrameGeometry): WheelBand;

package/dist/ui/layout/regions.js

@@ -0,0 +1,52 @@
+/**
+ * Wheel band hit-testing (mouse-wheel-region-routing §4.5) — pure, React-free.
+ *
+ * The requirement is stated in terms of REGIONS ("scrolling over the agent area
+ * scrolls the transcript; scrolling over the input box steps prompt history"),
+ * so the router needs to turn a reported terminal row into one of two bands.
+ *
+ * The boundary is MEASURED, never computed from `budget.ts`. That arithmetic
+ * describes the PLANNED chrome, but the real bottom chrome grows and shrinks at
+ * run time: the toast row comes and goes, the hint row is dropped below
+ * `HINT_MIN_ROWS`, and the autocomplete popup adds up to nine rows. Routing off
+ * the plan would put the boundary in the wrong place exactly when the popup is
+ * open — the moment precision matters most (D-5 / D-16).
+ */
+/**
+ * The "I do not know where the frame is" value.
+ *
+ * `App` writes it into the geometry ref on every render path that does NOT
+ * render the full-screen `AppShell` — the terminal-too-small placeholder and
+ * inline mode — so a stale measurement can never outlive the frame it
+ * described. There is deliberately no arithmetic fallback: an unmeasured frame
+ * routes to `'content'`, which is the band that cannot destroy anything, and
+ * one invisible frame after a resize is a better failure than a wrong band
+ * (§4.5, P1-5 / D-16).
+ */
+export const UNMEASURED_GEOMETRY = { top: 1, height: 0, bottom: 0 };
+/**
+ * Which band does terminal row `y` belong to?
+ *
+ * Fails toward `'content'`: the whole point of this feature is that a wheel
+ * notch must never edit the user's draft (I-3), so every degenerate input —
+ * nothing measured yet, a row outside the frame, a chrome measurement that
+ * swallowed the screen — resolves to the harmless direction.
+ */
+export function hitTestWheel(y, geometry) {
+    const { top, height } = geometry;
+    if (!Number.isFinite(height) || height <= 0)
+        return 'content';
+    if (!Number.isFinite(y))
+        return 'content';
+    // Clamp into the frame so the one undrawn bottom row — and any off-by-one
+    // from a terminal that reports 0-based rows — lands on a real band instead of
+    // being dropped.
+    const row = Math.min(Math.max(Math.floor(y), top), top + height - 1);
+    // I-6: at least one content row always survives. This clamp is a backstop
+    // that should never fire, and that is checkable rather than hopeful: the
+    // completion popup is capped at `viewportRows(rows) - 4`, so the measured
+    // chrome tops out at `rows - 6` against a frame of `rows - 1` — five content
+    // rows survive the worst case the layout can produce.
+    const bottom = Math.min(Math.max(Math.floor(geometry.bottom) || 0, 0), height - 1);
+    return row >= top + height - bottom ? 'composer' : 'content';
+}

package/dist/ui/layout/scroll-indicator.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Scroll-thumb geometry (mouse-wheel-region-routing §4.8) — pure, React-free.
+ *
+ * Wheel scrolling without a position indicator is a half-finished affordance:
+ * the user learns THAT they moved but not HOW FAR or how much is left. The
+ * status bar's `↑N` answers neither.
+ *
+ * OFFSET COUNTS FROM THE BOTTOM, exactly as `scroll.ts` documents — `0` is
+ * pinned to the newest output and `overflow` is parked at the very top. The
+ * rows hidden ABOVE are therefore `overflow - offset`, and that inversion is
+ * precisely what gets done by accident, so it is computed here once and named.
+ */
+export interface ThumbRange {
+    /** 0-based row of the thumb's first row, within the viewport. */
+    start: number;
+    /** Thumb height in rows; always >= 1 when a range is returned. */
+    size: number;
+}
+/**
+ * Where the thumb sits, or `null` when the content fits and there is nothing to
+ * indicate.
+ *
+ * `size` never rounds to zero: a 10-row window over a 5000-row transcript still
+ * gets a one-row thumb, because an indicator that vanishes at exactly the
+ * moment the transcript is longest is worse than no indicator at all.
+ */
+export declare function thumbRange(viewportRows: number, contentRows: number, offsetFromBottom: number): ThumbRange | null;

package/dist/ui/layout/scroll-indicator.js

@@ -0,0 +1,35 @@
+/**
+ * Scroll-thumb geometry (mouse-wheel-region-routing §4.8) — pure, React-free.
+ *
+ * Wheel scrolling without a position indicator is a half-finished affordance:
+ * the user learns THAT they moved but not HOW FAR or how much is left. The
+ * status bar's `↑N` answers neither.
+ *
+ * OFFSET COUNTS FROM THE BOTTOM, exactly as `scroll.ts` documents — `0` is
+ * pinned to the newest output and `overflow` is parked at the very top. The
+ * rows hidden ABOVE are therefore `overflow - offset`, and that inversion is
+ * precisely what gets done by accident, so it is computed here once and named.
+ */
+/**
+ * Where the thumb sits, or `null` when the content fits and there is nothing to
+ * indicate.
+ *
+ * `size` never rounds to zero: a 10-row window over a 5000-row transcript still
+ * gets a one-row thumb, because an indicator that vanishes at exactly the
+ * moment the transcript is longest is worse than no indicator at all.
+ */
+export function thumbRange(viewportRows, contentRows, offsetFromBottom) {
+    const viewport = Math.floor(viewportRows);
+    const content = Math.floor(contentRows);
+    if (!Number.isFinite(viewport) || !Number.isFinite(content))
+        return null;
+    if (viewport <= 0 || content <= viewport)
+        return null;
+    const overflow = content - viewport;
+    const offset = Math.min(Math.max(Math.floor(offsetFromBottom) || 0, 0), overflow);
+    const size = Math.min(viewport, Math.max(1, Math.round((viewport * viewport) / content)));
+    const travel = viewport - size;
+    const hiddenAbove = overflow - offset;
+    const start = travel <= 0 ? 0 : Math.round((hiddenAbove / overflow) * travel);
+    return { start: Math.min(Math.max(start, 0), travel), size };
+}

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

@@ -26,3 +26,12 @@ export declare function clampScroll(offset: number, overflowLines: number): numb
 export declare function pageSize(viewportHeight: number): number;
 export declare function isPinnedToBottom(state: ScrollState): boolean;
 export declare function applyScroll(state: ScrollState, intent: ScrollIntent, metrics: ViewportMetrics): ScrollState;
+/**
+ * Fold `applyScroll` `times` times — one `setState`, one render, however fast
+ * the wheel spins (mouse-wheel-region-routing §5.5).
+ *
+ * Folding rather than multiplying is deliberate: `applyScroll` owns the
+ * downward bottom-snap and the clamp, and reimplementing either here would give
+ * the wheel a different notion of "pinned to the bottom" than the keyboard has.
+ */
+export declare function applyScrollTimes(state: ScrollState, intent: ScrollIntent, metrics: ViewportMetrics, times: number): ScrollState;

package/dist/ui/layout/scroll.js

@@ -74,3 +74,26 @@ export function applyScroll(state, intent, metrics) {
     }
     return { offset: clamped };
 }
+/**
+ * Upper bound on one folded burst. `repeat` arrives from the wheel router's
+ * coalescing window, and an unbounded fold is a free CPU-burn primitive for a
+ * high-resolution / free-spinning wheel (R-10).
+ */
+const MAX_SCROLL_REPEAT = 100;
+/**
+ * Fold `applyScroll` `times` times — one `setState`, one render, however fast
+ * the wheel spins (mouse-wheel-region-routing §5.5).
+ *
+ * Folding rather than multiplying is deliberate: `applyScroll` owns the
+ * downward bottom-snap and the clamp, and reimplementing either here would give
+ * the wheel a different notion of "pinned to the bottom" than the keyboard has.
+ */
+export function applyScrollTimes(state, intent, metrics, times) {
+    const n = Number.isFinite(times)
+        ? Math.min(MAX_SCROLL_REPEAT, Math.max(1, Math.floor(times)))
+        : 1;
+    let next = state;
+    for (let i = 0; i < n; i += 1)
+        next = applyScroll(next, intent, metrics);
+    return next;
+}

package/dist/ui/overlays/HelpOverlay.js

@@ -13,6 +13,8 @@ function keyRows(times) {
         ['Ctrl+T', 'Toggle thinking blocks'],
         ['PgUp / PgDn', 'Scroll a page (transcript, or this overlay)'],
         ['Shift+Up / Shift+Down', 'Scroll the transcript a line (full-screen mode)'],
+        ['Wheel', 'Scroll the transcript (over the input box: prompt history)'],
+        ['Shift+Wheel', 'Scroll the transcript a page'],
         ['Up / Down', 'Prompt history (empty input)'],
     ];
 }

package/dist/ui/screen.d.ts

@@ -15,11 +15,24 @@ export interface ScreenHandle {
     /** Leave the alternate screen. Idempotent — safe from every exit path. */
     restore(): void;
 }
+export interface AltScreenOptions {
+    /**
+     * TRUE MEANS "A MOUSE FILTER IS ALREADY INSTALLED", NOT "THE USER WANTS MOUSE
+     * SUPPORT" (invariant I-8).
+     *
+     * This module must never derive the value from config, env or platform.
+     * Enabling reporting without a filter in front of Ink does not degrade the
+     * feature — it types `[<0;12;5M` into the user's message on every click and
+     * every notch, which is strictly worse than the bug the feature fixes. The
+     * only caller is `cli.tsx::runInteractive`, and it passes `filter !== null`.
+     */
+    readonly mouse: boolean;
+}
 /**
  * Enter the alternate screen. A non-TTY stdout is a hard no-op (tests, pipes,
  * CI) — writing screen-control sequences into a redirected file corrupts it.
  */
-export declare function enterAltScreen(stdout: NodeJS.WriteStream | undefined): ScreenHandle;
+export declare function enterAltScreen(stdout: NodeJS.WriteStream | undefined, options?: AltScreenOptions): ScreenHandle;
 /**
  * Replay the session summary into the normal buffer after `restore()`, so the
  * conversation does not evaporate along with the alternate screen.

package/dist/ui/screen.js

@@ -17,6 +17,32 @@ const CURSOR_HOME = '\x1b[H';
 const CLEAR_VISIBLE = '\x1b[2J';
 /** Ink's log-update hides the cursor; a signal kill never gives it back. */
 const SHOW_CURSOR = '\x1b[?25h';
+/**
+ * `?1000` is NORMAL TRACKING (press / release), the minimum mode that reports
+ * wheel buttons; `?1006` selects SGR encoding so coordinates arrive as decimal
+ * text rather than raw bytes above 0x7F that `setEncoding('utf8')` would
+ * mangle. Motion tracking (`?1002` / `?1003`) is deliberately NOT enabled: it
+ * floods stdin on every pointer move and buys nothing this feature uses.
+ */
+const ENABLE_MOUSE = '\x1b[?1000h\x1b[?1006h';
+const DISABLE_MOUSE = '\x1b[?1006l\x1b[?1000l';
+/**
+ * Alternate scroll (DEC private mode 1007) is what turns a wheel notch into a
+ * burst of arrow keys, which `PromptInput` reads as prompt-history recall. With
+ * mouse reporting ON we do not touch it at all: 1007 is defined to translate
+ * the wheel only while no application is tracking the mouse, so `?1000h`
+ * already suppresses it and a second mutation of shared state buys nothing.
+ *
+ * With mouse reporting OFF we turn it off so the wheel is INERT rather than
+ * destructive — the fallback rung of the fail-safe ladder. But 1007 is GLOBAL
+ * TERMINAL STATE THIS APP DOES NOT OWN, so it is SAVED and RESTORED (XTSAVE /
+ * XTRESTORE) rather than force-set on the way out: a user who deliberately
+ * disabled alternate scroll in their terminal config must not have it switched
+ * back on by running `aragon --no-mouse` once. A terminal implementing neither
+ * sequence ignores both, so the fallback is no worse than writing nothing.
+ */
+const SAVE_ALT_SCROLL_OFF = '\x1b[?1007s\x1b[?1007l';
+const RESTORE_ALT_SCROLL = '\x1b[?1007r';
 const NOOP_HANDLE = { restore() { } };
 function safeWrite(stdout, data) {
     try {
@@ -30,17 +56,25 @@ function safeWrite(stdout, data) {
  * Enter the alternate screen. A non-TTY stdout is a hard no-op (tests, pipes,
  * CI) — writing screen-control sequences into a redirected file corrupts it.
  */
-export function enterAltScreen(stdout) {
+export function enterAltScreen(stdout, options = { mouse: false }) {
     if (!stdout || !stdout.isTTY || typeof stdout.write !== 'function')
         return NOOP_HANDLE;
-    safeWrite(stdout, ENTER_ALT + CLEAR_VISIBLE + CURSOR_HOME);
+    const mouse = options.mouse === true;
+    safeWrite(stdout, ENTER_ALT + CLEAR_VISIBLE + CURSOR_HOME + (mouse ? ENABLE_MOUSE : SAVE_ALT_SCROLL_OFF));
     let restored = false;
     return {
         restore() {
             if (restored)
                 return;
             restored = true;
-            safeWrite(stdout, SHOW_CURSOR + LEAVE_ALT);
+            // Mouse reporting is disabled BEFORE leaving the alternate screen (I-2).
+            // This handle is what all four exit paths converge on — `process.on
+            // ('exit')`, the crash handler's `setScreenRestore`, the signal
+            // terminator, and `waitUntilExit()` — which is why the sequences live
+            // here and not in `App.tsx`, a component that is on none of them.
+            // Leaving reporting on prints `[<0;12;5M` in the user's shell on every
+            // click, forever, until they run `reset`.
+            safeWrite(stdout, (mouse ? DISABLE_MOUSE : RESTORE_ALT_SCROLL) + SHOW_CURSOR + LEAVE_ALT);
         },
     };
 }

package/dist/ui/use-startup-notices.d.ts

@@ -12,4 +12,14 @@
  * not otherwise see — rather than belonging to the view.
  */
 import type { ViewAction } from '../agent/reducer.js';
-export declare function useStartupNotices(dispatch: (action: ViewAction) => void): void;
+export interface MouseNoticeOptions {
+    /**
+     * Whether reporting is ACTUALLY in effect — i.e. a filter was installed, not
+     * merely that the config asked for one. A user on a terminal where R-1 fires
+     * must never be given advice about a mode that is not running.
+     */
+    enabled: boolean;
+    /** Persist `mouseNoticeSeen`. Called once, after the notice is dispatched. */
+    onSeen: () => void;
+}
+export declare function useStartupNotices(dispatch: (action: ViewAction) => void, mouseNotice?: MouseNoticeOptions): void;

package/dist/ui/use-startup-notices.js

@@ -11,10 +11,20 @@
  * because these two effects share one job — surfacing a condition the user could
  * not otherwise see — rather than belonging to the view.
  */
-import { useEffect } from 'react';
+import { useEffect, useRef } from 'react';
 import { readConfigFile } from '../config/store.js';
 import { getLogger } from '../logging/logger.js';
-export function useStartupNotices(dispatch) {
+/**
+ * The §6.1 notice (mouse-wheel-region-routing). Shown at most once, ever.
+ *
+ * R-3 is the only part of wheel region routing that reaches users who never
+ * scroll, and it REMOVES a gesture — drag to select — that is used more often
+ * than the one being added. A README is consulted only after the belief
+ * "aragon broke copy/paste" has already formed.
+ */
+const MOUSE_SELECTION_NOTICE = 'Mouse wheel scrolls the transcript. Hold Shift to select text, ' +
+    'or turn it off with `aragon config set mouse false`.';
+export function useStartupNotices(dispatch, mouseNotice) {
     // The sink gives up after repeated write failures (a read-only log directory,
     // a full disk). Silently logging nothing is exactly the state a user must not
     // discover later, from an empty file, while trying to explain a bug.
@@ -35,4 +45,20 @@ export function useStartupNotices(dispatch) {
             text: `Using default settings: could not parse ${parseError}`,
         });
     }, [dispatch]);
+    // A `notice`, not a toast: it lands in the transcript and scrolls away
+    // instead of stealing a row. §6's argument against toasts is about per-notch
+    // chatter and does not extend to a one-shot.
+    const noticeRef = useRef(mouseNotice);
+    noticeRef.current = mouseNotice;
+    const mouseEnabled = mouseNotice?.enabled ?? false;
+    const mouseNoticeShown = useRef(false);
+    useEffect(() => {
+        if (!mouseEnabled || mouseNoticeShown.current)
+            return;
+        if (readConfigFile().config?.mouseNoticeSeen)
+            return;
+        mouseNoticeShown.current = true;
+        dispatch({ type: 'notice', level: 'info', text: MOUSE_SELECTION_NOTICE });
+        noticeRef.current?.onSeen();
+    }, [mouseEnabled, dispatch]);
 }

package/dist/ui/use-wheel-routing.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Wheel routing (mouse-wheel-region-routing §4.6 / §4.7).
+ *
+ * Subscribes to the mouse source, turns each wheel notch into a band via
+ * `hitTestWheel`, and dispatches it to the transcript, an open overlay, or the
+ * prompt-history stepper. Lives outside `App.tsx` because that file is exactly
+ * at the 1000-line ceiling `CLAUDE.md` sets, and because the routing table is
+ * the most testable part of this feature and does not want to be inside a
+ * 1000-line component (D-13).
+ *
+ * THE TWO BANDS HAVE DIFFERENT PHYSICS, and that is the requirement rather than
+ * a tuning choice (§4.7). A physical notch produces ONE SGR report, whereas
+ * alternate-scroll used to produce three arrow keys:
+ *
+ *  - transcript: 3 rows per notch, matching the terminal's own convention and
+ *    the muscle memory users bring from every other full-screen app;
+ *  - composer: exactly ONE history step per notch. Multiplying here would make
+ *    a single flick jump three prompts back — unusable, and destructive when a
+ *    draft is in play.
+ *
+ * Bursts are handled differently for the same reason: transcript events are
+ * coalesced into one intent carrying `repeat`, composer events never are (they
+ * are rate-limited by the human, and each must produce its own visible step).
+ */
+import { type MutableRefObject } from 'react';
+import type { Overlay } from '../agent/reducer.js';
+import type { MouseSource } from '../input/stdin-mouse-filter.js';
+import { type FrameGeometry } from './layout/regions.js';
+import type { ScrollIntent } from './layout/scroll.js';
+/**
+ * Rows a PgUp/PgDn — and a Shift+wheel notch — moves inside a controlled
+ * overlay. Declared here rather than in `App.tsx` because both the keyboard
+ * branch and the wheel branch need it and `App` imports this module; the other
+ * direction would be a cycle.
+ */
+export declare const OVERLAY_PAGE = 8;
+export interface WheelRoutingOptions {
+    /** Absent when mouse support is off, in inline mode, or on a non-TTY. */
+    mouseSource?: MouseSource;
+    /** Live frame geometry, written by `AppShell`'s layout effect (§4.5). */
+    geometryRef: MutableRefObject<FrameGeometry>;
+    /**
+     * Test-only seam (§8.2): when set, the router reads this instead of the
+     * measured ref, so a routing test never depends on `measureElement` working
+     * under `ink-testing-library` — a dependency no other test in this package
+     * exercises, and one that would make a routing regression present as a
+     * measurement flake.
+     */
+    geometryOverride?: FrameGeometry;
+    /** Read at EVENT time for the routing branch, and again at FLUSH time (P1-3). */
+    getOverlay: () => Overlay | null;
+    onScroll: (kind: ScrollIntent, repeat: number) => void;
+    /** Signed row delta; the caller clamps at 0 the way the keyboard branch does. */
+    onOverlayScroll: (delta: number) => void;
+    onHistoryStep: (dir: 'up' | 'down') => void;
+}
+export interface WheelRouting {
+    /**
+     * Drop any accumulated-but-unflushed transcript scroll.
+     *
+     * Called by `App` from its existing `state.overlay` effect rather than from a
+     * second subscriber to the same transition. This is guard #2 of the pair that
+     * has to ship together (§14 condition 3); guard #1 is the overlay re-check
+     * inside the flush, and guard #3 is `ScrollViewport`'s I-9 mount-skip.
+     */
+    clearCoalescer: () => void;
+}
+export declare function useWheelRouting(options: WheelRoutingOptions): WheelRouting;

package/dist/ui/use-wheel-routing.js

@@ -0,0 +1,139 @@
+/**
+ * Wheel routing (mouse-wheel-region-routing §4.6 / §4.7).
+ *
+ * Subscribes to the mouse source, turns each wheel notch into a band via
+ * `hitTestWheel`, and dispatches it to the transcript, an open overlay, or the
+ * prompt-history stepper. Lives outside `App.tsx` because that file is exactly
+ * at the 1000-line ceiling `CLAUDE.md` sets, and because the routing table is
+ * the most testable part of this feature and does not want to be inside a
+ * 1000-line component (D-13).
+ *
+ * THE TWO BANDS HAVE DIFFERENT PHYSICS, and that is the requirement rather than
+ * a tuning choice (§4.7). A physical notch produces ONE SGR report, whereas
+ * alternate-scroll used to produce three arrow keys:
+ *
+ *  - transcript: 3 rows per notch, matching the terminal's own convention and
+ *    the muscle memory users bring from every other full-screen app;
+ *  - composer: exactly ONE history step per notch. Multiplying here would make
+ *    a single flick jump three prompts back — unusable, and destructive when a
+ *    draft is in play.
+ *
+ * Bursts are handled differently for the same reason: transcript events are
+ * coalesced into one intent carrying `repeat`, composer events never are (they
+ * are rate-limited by the human, and each must produce its own visible step).
+ */
+import { useCallback, useEffect, useRef } from 'react';
+import { hitTestWheel } from './layout/regions.js';
+/**
+ * Rows a PgUp/PgDn — and a Shift+wheel notch — moves inside a controlled
+ * overlay. Declared here rather than in `App.tsx` because both the keyboard
+ * branch and the wheel branch need it and `App` imports this module; the other
+ * direction would be a cycle.
+ */
+export const OVERLAY_PAGE = 8;
+/** Transcript rows per notch. The terminal's own convention. */
+const CONTENT_LINES_PER_NOTCH = 3;
+/** Overlay rows per notch. Overlay content is short; a page needs Shift. */
+const OVERLAY_LINES_PER_NOTCH = 3;
+/**
+ * Coalescing window for transcript scrolling — one `setState`, one render, no
+ * matter how fast the wheel spins (R-10). Deliberately tighter than the 33 ms
+ * streaming coalescer: this one is in the direct path of a hand gesture.
+ */
+const WHEEL_COALESCE_MS = 16;
+export function useWheelRouting(options) {
+    // Every mutable input reaches the subscription through this ref, so the
+    // effect below subscribes exactly once per `mouseSource` instead of tearing
+    // the listener down and rebuilding it on every parent render.
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    const accumulator = useRef(null);
+    const timer = useRef(null);
+    const clearCoalescer = useCallback(() => {
+        if (timer.current) {
+            clearTimeout(timer.current);
+            timer.current = null;
+        }
+        accumulator.current = null;
+    }, []);
+    const flush = useCallback(() => {
+        if (timer.current) {
+            clearTimeout(timer.current);
+            timer.current = null;
+        }
+        const pending = accumulator.current;
+        accumulator.current = null;
+        if (!pending)
+            return;
+        // P1-3: THE DECISION BELONGS AT FLUSH TIME, not at event time, because the
+        // event-time decision is the one that goes stale. `App` swaps
+        // `ScrollViewport` out for an overlay, and 16 ms is more than wide enough
+        // for an agent-raised `confirm` or an `ask_user` to land inside the window
+        // — the intent would then be applied on a component that is not there, and
+        // the transcript would jump by itself when the overlay closed.
+        if (optionsRef.current.getOverlay())
+            return;
+        optionsRef.current.onScroll(pending.kind, pending.repeat);
+    }, []);
+    const accumulate = useCallback((kind, repeat) => {
+        // A fast up-then-down must never cancel itself into a no-op, so a change
+        // of direction (or of granularity) flushes what is already held.
+        if (accumulator.current && accumulator.current.kind !== kind)
+            flush();
+        const held = accumulator.current;
+        accumulator.current = { kind, repeat: (held?.repeat ?? 0) + repeat };
+        if (!timer.current) {
+            timer.current = setTimeout(flush, WHEEL_COALESCE_MS);
+            timer.current.unref?.();
+        }
+    }, [flush]);
+    const route = useCallback((event) => {
+        const current = optionsRef.current;
+        const geometry = current.geometryOverride ?? current.geometryRef.current;
+        const band = hitTestWheel(event.y, geometry);
+        const overlay = current.getOverlay();
+        // THE OVERLAY BRANCH IS EVALUATED FIRST AND RETURNS FOR EVERY BAND IT
+        // RECOGNIZES — the same two ordering rules the keyboard handler follows,
+        // and for the same reason (R-P1-7).
+        if (overlay) {
+            // The composer is inactive behind an overlay; stepping a hidden draft
+            // is worse than doing nothing.
+            if (band !== 'content')
+                return;
+            // Modes A only. `model` / `confirm` / `question` own their own keys and
+            // scrolling them would leave an inconsistent cursor (R-11).
+            const controlled = overlay === 'help' || overlay === 'settings' || overlay === 'plan';
+            if (!controlled)
+                return;
+            const step = event.shift ? OVERLAY_PAGE : OVERLAY_LINES_PER_NOTCH;
+            current.onOverlayScroll(event.dir === 'up' ? -step : step);
+            return;
+        }
+        if (band === 'composer') {
+            // §4.7: the accumulator flushes when the BAND changes, not only when
+            // the direction does. The composer path is never coalesced, so without
+            // this the transcript scroll that preceded the pointer moving down
+            // lands ~16 ms AFTER the history step it happened before — the two
+            // halves of one gesture, applied out of order.
+            flush();
+            current.onHistoryStep(event.dir);
+            return;
+        }
+        if (event.shift) {
+            accumulate(event.dir === 'up' ? 'pageUp' : 'pageDown', 1);
+            return;
+        }
+        accumulate(event.dir === 'up' ? 'lineUp' : 'lineDown', CONTENT_LINES_PER_NOTCH);
+    }, [accumulate, flush]);
+    const { mouseSource } = options;
+    useEffect(() => {
+        if (!mouseSource)
+            return undefined;
+        const unsubscribe = mouseSource.subscribe(route);
+        return () => {
+            unsubscribe();
+            clearCoalescer();
+        };
+    }, [mouseSource, route, clearCoalescer]);
+    return { clearCoalescer };
+}