@reticlehq/server 2.14.0 → 3.2.0

package/dist/portal/input/real-input.js

@@ -0,0 +1,488 @@
+import { stampedDriveUrl } from './drive-url-stamp.js';
+import { chromiumLaunchOptions } from '../../chromium-launch-options.js';
+import { gotoOptions } from '../pool/playwright-launcher.js';
+import { BrowserLaunchKind } from '@reticlehq/core/telemetry';
+import { getSessionMetrics } from '../../telemetry/session-metrics.js';
+import { classifyConnectFailure } from '../../telemetry/connect-failure.js';
+import { ActionType, DriveErrorCode, DRIVE_PLAYWRIGHT_MISSING_MSG } from '@reticlehq/core';
+import { installNetworkMocks } from './network-mock.js';
+import { attachNetworkDetail } from './network-detail.js';
+/** Structured, code-tagged failure so callers branch on cause, not message text. */
+export class DriveError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'DriveError';
+    }
+}
+/** Center of a viewport box in CSS px. Pure — unit-tested directly. */
+export function boxCenter(box) {
+    return { cx: box.x + box.width / 2, cy: box.y + box.height / 2 };
+}
+/**
+ * Which actions are driven by native pointer input. fill/type stay synthetic unless a
+ * provider explicitly runs them.
+ */
+export function isPointerAction(action) {
+    return (action === ActionType.HOVER ||
+        action === ActionType.CLICK ||
+        action === ActionType.DBLCLICK ||
+        action === ActionType.DRAG);
+}
+/** Settle delay after a native gesture so the reaction can begin to flush (named, not free). */
+const REAL_INPUT_SETTLE_MS = 16;
+/** Default number of interpolation steps for a native drag. */
+const DEFAULT_DRAG_STEPS = 8;
+/**
+ * Shared gesture executor: drive a native gesture on an already-resolved Page. Used by both the
+ * CDP-attached and the launched (drive) providers so the pointer logic lives in one place.
+ */
+export async function performGesture(page, action, box, args, sleep) {
+    const center = boxCenter(box);
+    const { cx, cy } = center;
+    if (action === ActionType.HOVER) {
+        await page.mouse.move(cx, cy);
+        await page.mouse.move(cx + 1, cy);
+        await page.mouse.move(cx, cy);
+        await sleep(REAL_INPUT_SETTLE_MS);
+        return { performed: true, center };
+    }
+    if (action === ActionType.CLICK) {
+        await page.mouse.move(cx, cy);
+        await page.mouse.click(cx, cy);
+        return { performed: true, center };
+    }
+    if (action === ActionType.DBLCLICK) {
+        await page.mouse.move(cx, cy);
+        await page.mouse.dblclick(cx, cy);
+        return { performed: true, center };
+    }
+    if (action === ActionType.DRAG) {
+        if (args.toBox === undefined)
+            return { performed: false, center };
+        const dst = boxCenter(args.toBox);
+        const steps = args.steps ?? DEFAULT_DRAG_STEPS;
+        await page.mouse.move(cx, cy);
+        await page.mouse.down();
+        for (let i = 1; i <= steps; i += 1) {
+            const px = cx + ((dst.cx - cx) * i) / steps;
+            const py = cy + ((dst.cy - cy) * i) / steps;
+            await page.mouse.move(px, py, { steps: 1 });
+        }
+        await page.mouse.up();
+        return { performed: true, center };
+    }
+    if (action === ActionType.FILL || action === ActionType.TYPE) {
+        await page.mouse.click(cx, cy);
+        await page.keyboard.type(args.value ?? args.text ?? '');
+        return { performed: true, center };
+    }
+    return { performed: false, center };
+}
+/**
+ * Reticle paints its own dev overlay (presenter HUD + border glow) into the page. That chrome is
+ * time-varying — the activity log and border state change with every command — so capturing it
+ * makes a fresh screenshot of an unchanged page differ from its baseline. Hide it during capture
+ * (Playwright applies this stylesheet only for the shot, then reverts) so visual baselines reflect
+ * the app, not Reticle. Disabling animations settles any remaining transitions for determinism.
+ */
+const HIDE_RETICLE_CHROME_CSS = '[data-reticle-overlay]{display:none !important}';
+const SCREENSHOT_DETERMINISM = { style: HIDE_RETICLE_CHROME_CSS, animations: 'disabled' };
+/**
+ * Capture a PNG from a Playwright page. Shared by the CDP + launched providers so the
+ * screenshot path lives in one place (mirrors performGesture). Returns the raw PNG bytes.
+ */
+export async function capturePage(page, opts) {
+    const buf = await page.screenshot(opts.clip !== undefined
+        ? { ...SCREENSHOT_DETERMINISM, clip: opts.clip }
+        : true === opts.fullPage
+            ? { ...SCREENSHOT_DETERMINISM, fullPage: true }
+            : { ...SCREENSHOT_DETERMINISM });
+    return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+}
+const nodeSleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+const cdpConnect = async (url) => {
+    const { chromium } = await import('playwright');
+    // Attaching to someone's already-running browser is the fragile path — a stale CDP url, a browser
+    // that was closed — so its FAILURE rate is the number worth watching. Settled with the outcome
+    // rather than counted up front, which is what the first version got wrong: it incremented before
+    // the await, so it silently reported attempts while the other paths reported successes.
+    const settle = getSessionMetrics().recordConnectAttempt(BrowserLaunchKind.ATTACHED);
+    try {
+        const browser = await chromium.connectOverCDP(url);
+        settle();
+        return browser;
+    }
+    catch (error) {
+        settle(classifyConnectFailure(error));
+        throw error;
+    }
+};
+/** CDP-backed real-input provider. Lazily connects on first availability check / perform. */
+export class CdpRealInputProvider {
+    #cdpUrl;
+    #sleep;
+    #connect;
+    #onNetworkDetail;
+    /** Pages already listening. #pageFor resolves on EVERY call, so without this each action would add
+     *  another listener and every response would be emitted once per action taken so far. */
+    #listening = new WeakSet();
+    #browser;
+    constructor(options) {
+        this.#cdpUrl = options.cdpUrl;
+        this.#sleep = options.sleep ?? nodeSleep;
+        this.#connect = options.connect ?? cdpConnect;
+        this.#onNetworkDetail = options.onNetworkDetail;
+    }
+    /** Attach the response listener the first time we see a page; a no-op afterwards. */
+    #listen(page) {
+        const sink = this.#onNetworkDetail;
+        if (sink === undefined || this.#listening.has(page))
+            return;
+        this.#listening.add(page);
+        attachNetworkDetail(page, sink);
+    }
+    async #ensureBrowser() {
+        if (this.#browser !== undefined) {
+            // A cached browser can be DEAD: CDP dropped (the page was closed, the debugged Chrome exited,
+            // the network blipped). The old code cached it forever, so every later call handed back a
+            // corpse and the whole drive path went silently unavailable until the daemon restarted.
+            // Playwright's Browser exposes isConnected(); a test fake may not, so only an EXPLICIT false
+            // drops the cache — a fake without the method is assumed live.
+            const alive = this.#browser.isConnected?.() ?? true;
+            if (alive)
+                return this.#browser;
+            this.#browser = undefined; // fall through and reconnect
+        }
+        try {
+            this.#browser = await this.#connect(this.#cdpUrl);
+            return this.#browser;
+        }
+        catch {
+            this.#browser = undefined; // a failed reconnect must not leave a stale handle behind
+            return undefined;
+        }
+    }
+    async #pageFor(sessionUrl) {
+        const browser = await this.#ensureBrowser();
+        if (browser === undefined)
+            return undefined;
+        const page = selectPage(browser.contexts().flatMap((c) => c.pages()), sessionUrl);
+        if (page !== undefined)
+            this.#listen(page);
+        return page;
+    }
+    async isAvailableFor(sessionUrl) {
+        try {
+            return (await this.#pageFor(sessionUrl)) !== undefined;
+        }
+        catch {
+            return false;
+        }
+    }
+    async perform(sessionUrl, action, box, args) {
+        const page = await this.#pageFor(sessionUrl);
+        if (page === undefined)
+            return { performed: false, center: boxCenter(box) };
+        return performGesture(page, action, box, args, this.#sleep);
+    }
+    /** PNG of the correlated page, or undefined if none matches. */
+    async screenshot(sessionUrl, opts) {
+        const page = await this.#pageFor(sessionUrl);
+        if (page === undefined)
+            return undefined;
+        return capturePage(page, opts);
+    }
+    /** The context's cookies and per-origin storage; undefined when no driven page matches. */
+    async storageState(sessionUrl) {
+        const page = await this.#pageFor(sessionUrl);
+        if (page === undefined)
+            return undefined;
+        return page.context().storageState();
+    }
+    /**
+     * Put a captured context state back: cookies through the context, per-origin storage through the
+     * page, because only the context owns a cookie jar and only a document owns its localStorage.
+     *
+     * False when no driven page matches. The caller throws on that — see `fixturePortFor`.
+     */
+    async applyStorageState(sessionUrl, state) {
+        const page = await this.#pageFor(sessionUrl);
+        if (page === undefined)
+            return false;
+        const saved = state;
+        if (saved.cookies !== undefined)
+            await page.context().addCookies(saved.cookies);
+        for (const origin of saved.origins ?? []) {
+            // Only the document for an origin can write that origin's localStorage, so this is applied in
+            // the page rather than through the context. A page sitting on a different origin cannot be
+            // given another origin's storage, and silently succeeding there would be the quiet half-restore
+            // this whole path exists to avoid.
+            if (!page.url().startsWith(origin.origin))
+                continue;
+            await page.evaluate((entries) => {
+                // Reached through `globalThis` rather than `window`: this body is serialised and runs in the
+                // PAGE, but it is typechecked here, and this package never pulls in the DOM lib — a server
+                // that can name `window` is one step from a server that uses it.
+                const store = globalThis.localStorage;
+                if (store === undefined)
+                    return;
+                for (const entry of entries)
+                    store.setItem(entry.name, entry.value);
+            }, origin.localStorage ?? []);
+        }
+        return true;
+    }
+    /** Apply network-mock rules to the correlated page; false when no driven page matches. */
+    async setMocks(sessionUrl, rules) {
+        const page = await this.#pageFor(sessionUrl);
+        if (page === undefined)
+            return false;
+        await installNetworkMocks(page, rules);
+        return true;
+    }
+    /** Pin the correlated page's viewport to fixed dimensions; false when no driven page matches. */
+    async setViewport(sessionUrl, size) {
+        const page = await this.#pageFor(sessionUrl);
+        if (page === undefined)
+            return false;
+        await page.setViewportSize({ width: size.width, height: size.height });
+        return true;
+    }
+    /** Best-effort cleanup; idempotent. */
+    async dispose() {
+        const browser = this.#browser;
+        this.#browser = undefined;
+        if (browser !== undefined)
+            await browser.close();
+    }
+}
+const INJECT_CONNECT_WAIT_MS = 8_000;
+/** The only place the dynamic value import of Playwright lives for the launched (drive) path. */
+export const launchedChromium = async (headless) => {
+    let mod;
+    try {
+        mod = await import('playwright');
+    }
+    catch {
+        throw new DriveError(DriveErrorCode.PLAYWRIGHT_MISSING, DRIVE_PLAYWRIGHT_MISSING_MSG);
+    }
+    const settle = getSessionMetrics().recordConnectAttempt(BrowserLaunchKind.LAUNCHED);
+    try {
+        const browser = await mod.chromium.launch(chromiumLaunchOptions(headless));
+        settle();
+        return browser;
+    }
+    catch (e) {
+        settle(classifyConnectFailure(e));
+        throw new DriveError(DriveErrorCode.LAUNCH_FAILED, e instanceof Error ? e.message : String(e));
+    }
+};
+/**
+ * Launches and OWNS a Playwright Chromium, navigates it to `driveUrl`, then drives native
+ * input on that page. Headless-capable so @reticlehq/test / CI can run hover/drag unattended.
+ */
+export class LaunchedRealInputProvider {
+    #driveUrl;
+    #headless;
+    #sleep;
+    #launch;
+    #injectConnect;
+    #storageState;
+    #onNetworkDetail;
+    #browser;
+    #page;
+    constructor(options) {
+        this.#driveUrl = options.driveUrl;
+        this.#headless = options.headless;
+        this.#sleep = options.sleep ?? nodeSleep;
+        this.#launch = options.launch ?? launchedChromium;
+        this.#injectConnect = options.injectConnect;
+        this.#storageState = options.storageState;
+        this.#onNetworkDetail = options.onNetworkDetail;
+    }
+    async navigate() {
+        this.#browser = await this.#launch(this.#headless);
+        const page = await this.#browser.newPage(this.#storageState !== undefined ? { storageState: this.#storageState } : undefined);
+        this.#page = page;
+        // Capture CDP-authoritative response detail into the driven session's journal (best-effort).
+        if (this.#onNetworkDetail !== undefined)
+            attachNetworkDetail(page, this.#onNetworkDetail);
+        try {
+            // Same navigation rule as the pool, and for the same measured reason: Playwright's default
+            // waits for `load`, which an app with one never-finishing subresource never fires — 30s of
+            // nothing and then a failure that blames the app. The SDK connect is a module script, so it
+            // has already run by DOMContentLoaded. See gotoOptions.
+            // Stamped, so the page can tell Reticle opened it — see drive-url-stamp.ts. Without it the
+            // first-run tour mounts over a driven page and its scrim swallows every native gesture.
+            await page.goto(stampedDriveUrl(this.#driveUrl), gotoOptions(undefined));
+        }
+        catch (e) {
+            throw new DriveError(DriveErrorCode.NAVIGATE_FAILED, e instanceof Error ? e.message : String(e));
+        }
+        await this.#tryInjectConnect(page);
+    }
+    /**
+     * Wait for the page's Reticle singleton to exist, then re-invoke connect with our token + loopback
+     * URL so a hosted (non-localhost) preview pairs to our bridge without the app being reconfigured.
+     * Best-effort: a page with no SDK simply never exposes the global, and we move on.
+     */
+    async #tryInjectConnect(page) {
+        const opts = this.#injectConnect;
+        if (opts === undefined)
+            return;
+        try {
+            await page.waitForFunction('!!globalThis.__reticleInstance', {
+                timeout: INJECT_CONNECT_WAIT_MS,
+            });
+            const arg = JSON.stringify({ allowNonLocalhost: true, token: opts.token, url: opts.url });
+            await page.evaluate(`globalThis.__reticleInstance.connect(${arg})`);
+        }
+        catch {
+            // No SDK on the page (or it connected already) — the no-session guard in verify reports it.
+        }
+    }
+    /**
+     * The page we own, or undefined once it is gone.
+     *
+     * The handle is cached for the life of the provider and Playwright keeps answering `url()` after
+     * the page has closed, so a closed window read as AVAILABLE and every method below threw
+     * "Target page, context or browser has been closed" — the raw Playwright message, surfaced to the
+     * agent as a tool error, on every call for the rest of the run. A dead page is the same fact as no
+     * page, and every caller already handles that. Only an EXPLICIT `true` drops it, matching
+     * `CdpRealInputProvider`'s `isConnected` check: a test fake without the method is assumed live.
+     */
+    #livePage() {
+        const page = this.#page;
+        if (page === undefined)
+            return undefined;
+        if (true === page.isClosed?.()) {
+            this.#page = undefined; // never ask a corpse twice
+            return undefined;
+        }
+        return page;
+    }
+    isAvailableFor(sessionUrl) {
+        const page = this.#livePage();
+        if (page === undefined)
+            return Promise.resolve(false);
+        if (page.url() === sessionUrl)
+            return Promise.resolve(true);
+        return Promise.resolve(stripVolatile(page.url()) === stripVolatile(sessionUrl));
+    }
+    /**
+     * The context's cookies and per-origin storage, or undefined when no page is live.
+     *
+     * Present here and not only on the CDP provider because THIS is the provider `reticle drive`
+     * builds, and `fixturePortFor` refuses outright when either half is missing — so without these a
+     * driven session had no fixture port at all, and every suite seeded nothing while reading as if it
+     * seeded everything. Same two methods, same contract, one page instead of a page lookup.
+     */
+    async storageState(_sessionUrl) {
+        const page = this.#livePage();
+        if (page === undefined)
+            return undefined;
+        return page.context().storageState();
+    }
+    /**
+     * Put a captured state back: cookies through the context, per-origin storage through the page.
+     * Only the context owns a cookie jar and only a document owns its localStorage.
+     */
+    async applyStorageState(_sessionUrl, state) {
+        const page = this.#livePage();
+        if (page === undefined)
+            return false;
+        const saved = state;
+        if (saved.cookies !== undefined)
+            await page.context().addCookies(saved.cookies);
+        for (const origin of saved.origins ?? []) {
+            // A page sitting on a different origin cannot be given another origin's storage, and silently
+            // succeeding there is the quiet half-restore this whole path exists to avoid.
+            if (!page.url().startsWith(origin.origin))
+                continue;
+            await page.evaluate((entries) => {
+                const store = globalThis.localStorage;
+                if (store === undefined)
+                    return;
+                for (const entry of entries)
+                    store.setItem(entry.name, entry.value);
+            }, origin.localStorage ?? []);
+        }
+        return true;
+    }
+    perform(_sessionUrl, action, box, args) {
+        const page = this.#livePage();
+        if (page === undefined)
+            return Promise.resolve({ performed: false, center: boxCenter(box) });
+        return performGesture(page, action, box, args, this.#sleep);
+    }
+    /** PNG of the owned page, or undefined before navigate / after dispose. */
+    screenshot(_sessionUrl, opts) {
+        const page = this.#livePage();
+        if (page === undefined)
+            return Promise.resolve(undefined);
+        return capturePage(page, opts);
+    }
+    /**
+     * Pin the owned page's viewport; false before navigate / after dispose.
+     *
+     * `CdpRealInputProvider` has had this since it shipped and THIS provider did not, so
+     * `reticle_viewport` refused with `no-cdp-provider` under `reticle drive` — while recommending
+     * `reticle drive` as the fix. Same for `setMocks` below. A driven browser was attached and taking
+     * screenshots the whole time; only these two methods were missing.
+     */
+    async setViewport(_sessionUrl, size) {
+        const page = this.#livePage();
+        if (page === undefined)
+            return false;
+        await page.setViewportSize({ width: size.width, height: size.height });
+        return true;
+    }
+    /** Apply network-mock rules to the owned page; false before navigate / after dispose. */
+    async setMocks(_sessionUrl, rules) {
+        const page = this.#livePage();
+        if (page === undefined)
+            return false;
+        await installNetworkMocks(page, rules);
+        return true;
+    }
+    /** Close the owned browser once. Idempotent and safe before navigate. */
+    async dispose() {
+        const browser = this.#browser;
+        this.#browser = undefined;
+        this.#page = undefined;
+        if (browser !== undefined)
+            await browser.close();
+    }
+}
+/** Drop hash/query so a page whose URL drifted by fragment still correlates to the session. */
+/**
+ * Correlate a session URL to one driven page, or refuse.
+ *
+ * Exact match first, query string included — that is the only fully reliable signal. The stripped
+ * fallback exists for a real case (an app pushState's to /overview, so the page's URL no longer
+ * equals the session's) but it is only sound when UNAMBIGUOUS.
+ *
+ * Returning the first loose match was a false-green generator: the benchmark fixture selects a bug
+ * purely by query string, so two pages differing only there stripped to the same key, and a visual
+ * diff happily compared the wrong page to itself and reported "0.00% changed, matched" for pixels
+ * that demonstrably differed. Ambiguity now yields undefined, which callers already surface as
+ * "no driven page" rather than as a passing comparison.
+ */
+export function selectPage(pages, sessionUrl) {
+    const exact = pages.find((p) => p.url() === sessionUrl);
+    if (exact !== undefined)
+        return exact;
+    const target = stripVolatile(sessionUrl);
+    const loose = pages.filter((p) => stripVolatile(p.url()) === target);
+    return 1 === loose.length ? loose[0] : undefined;
+}
+function stripVolatile(url) {
+    const hash = url.indexOf('#');
+    const base = hash >= 0 ? url.slice(0, hash) : url;
+    const query = base.indexOf('?');
+    return query >= 0 ? base.slice(0, query) : base;
+}

package/dist/portal/input/scroll-find.js

@@ -0,0 +1,111 @@
+import { ReticleCommand, SCROLL_FIND_DEFAULTS } from '@reticlehq/core';
+import { asRecord } from '@reticlehq/core';
+/** One query for the target; returns the first matching element descriptor or undefined. */
+async function queryFirst(session, q) {
+    const res = await session.command(ReticleCommand.QUERY, {
+        by: q.by,
+        value: q.value,
+        ...(q.name !== undefined ? { name: q.name } : {}),
+    });
+    const elements = asRecord(res.result)['elements'];
+    if (Array.isArray(elements) && elements.length > 0)
+        return asRecord(elements[0]);
+    return undefined;
+}
+/**
+ * A note attached to `{ found: false, exhausted: true }` only when the failure is actually
+ * informative: nothing in the container ever moved (so the "list" being searched was never
+ * scrollable and the target is likely inside one with its own scroll container). Reaching the
+ * genuine ends of a container that DID scroll stays quiet — that is exhaustion, not confusion.
+ */
+function exhaustNote(q, data, nothingEverScrolled) {
+    if (q.container !== undefined)
+        return {};
+    if (true === data['scrolled'] || !nothingEverScrolled)
+        return {};
+    return {
+        note: "The document did not scroll — the target may be inside a list with its own scroll container. Pass that container's ref as `container`.",
+    };
+}
+/** One viewport-height step upward when the last result carried no clientHeight to size it by. */
+const UP_STEP_FALLBACK_PX = 400;
+/**
+ * Size the upward step off the container the SCROLL result just described, falling back to a
+ * plain viewport height when the result did not carry one.
+ */
+function upStepPx(last) {
+    const h = last['clientHeight'];
+    return 'number' === typeof h && h > 0 ? h : UP_STEP_FALLBACK_PX;
+}
+/**
+ * Reveal an element that a windowed/virtualized list has not mounted yet. Queries once (it may
+ * already be visible), optionally jumps straight to a bisection estimate, then walks the container
+ * a viewport at a time re-querying after each step. Downward first; when the bottom is reached the
+ * walk TURNS AROUND and continues upward, because a list that is already scrolled to its end keeps
+ * its earlier rows mounted above the viewport and a downward-only search answered "exhausted" on
+ * its first step (#505). `exhausted` therefore means BOTH directions are spent, not "the bottom is
+ * here". Pure orchestration over the session command seam — fully unit-testable with a fake.
+ */
+export async function scrollToFind(session, q, opts = {}) {
+    const max = opts.maxScrolls ?? SCROLL_FIND_DEFAULTS.MAX_SCROLLS;
+    const first = await queryFirst(session, q);
+    if (first !== undefined)
+        return { found: true, element: first, scrolls: 0, exhausted: false };
+    const baseArgs = () => q.container !== undefined ? { ref: q.container } : {};
+    let scrolls = 0;
+    let last = {};
+    // Bisection: if the caller knows the target index and list size, jump to the estimated offset in
+    // one scroll command rather than stepping a viewport at a time. The estimate can land on either
+    // side of the target, so refinement below still searches both directions from wherever this put us.
+    if (q.targetIndex !== undefined && q.totalCount !== undefined && q.totalCount > 1) {
+        const fraction = Math.min(1, Math.max(0, q.targetIndex / q.totalCount));
+        const sr = await session.command(ReticleCommand.SCROLL, { ...baseArgs(), fraction });
+        scrolls += 1;
+        last = asRecord(sr.result);
+        const hit = await queryFirst(session, q);
+        if (hit !== undefined)
+            return { found: true, element: hit, scrolls, exhausted: false };
+    }
+    let downwardSpent = false;
+    let everScrolled = false;
+    // The downward pass. Spending its whole budget without reaching the end means rows may remain
+    // further down, so that answer is `exhausted:false` and the upward pass never runs.
+    for (let i = 0; i < max && !downwardSpent; i += 1) {
+        const sr = await session.command(ReticleCommand.SCROLL, baseArgs());
+        scrolls += 1;
+        const data = asRecord(sr.result);
+        last = data;
+        if (true === data['scrolled'])
+            everScrolled = true;
+        const hit = await queryFirst(session, q);
+        if (hit !== undefined)
+            return { found: true, element: hit, scrolls, exhausted: false };
+        // Reached the bottom, or the container would not move downward — turn around before giving up.
+        if (true === data['atEnd'] || true !== data['scrolled'])
+            downwardSpent = true;
+    }
+    // If the downward pass spent its budget it never saw the end, so there is nothing to turn around
+    // for; report honestly rather than doubling a call whose caller asked for `max` steps.
+    if (!downwardSpent) {
+        return { found: false, scrolls, exhausted: false };
+    }
+    // The upward pass gets the caller's budget again, not what is left of it: a list at the bottom of
+    // 14k px needs ~90 scrolls to reach its end and ~90 more to get back, so sharing one budget would
+    // strand the search halfway and answer `exhausted:false` about a list both of whose ends are known.
+    for (let i = 0; i < max; i += 1) {
+        const sr = await session.command(ReticleCommand.SCROLL, { ...baseArgs(), dy: -upStepPx(last) });
+        scrolls += 1;
+        const data = asRecord(sr.result);
+        last = data;
+        if (true === data['scrolled'])
+            everScrolled = true;
+        const hit = await queryFirst(session, q);
+        if (hit !== undefined)
+            return { found: true, element: hit, scrolls, exhausted: false };
+        // The top refusing to move means both directions are spent.
+        if (true !== data['scrolled']) {
+            return { found: false, scrolls, exhausted: true, ...exhaustNote(q, data, !everScrolled) };
+        }
+    }
+    return { found: false, scrolls, exhausted: false }; // spent the upward budget; more may lie above
+}

package/dist/portal/input/scroll-tools.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDef } from '../../surface/tools/tool-kit.js';
+export declare const SCROLL_TOOLS: ToolDef[];

package/dist/portal/input/scroll-tools.js

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+import { QueryBy } from '@reticlehq/core';
+import { ReticleTool } from '@reticlehq/core';
+import { asNumber, asString } from '@reticlehq/core';
+import { listIndexSchema, scrollCountSchema } from '../../surface/tools/args/numeric-bounds.js';
+import { scrollToFind } from './scroll-find.js';
+/**
+ * reticle_scroll_to — the windowed/virtualized-list escape hatch. A plain reticle_query
+ * only sees rendered nodes, so an off-screen row in a react-window/react-virtualized list returns
+ * nothing. This scrolls the container until the row mounts, then returns its ref.
+ */
+/**
+ * The query strategies, derived from QueryBy — the same vocabulary reticle_query uses, and for the
+ * same reason. A free string here produced the identical false negative: `by:'css'` scrolled the
+ * whole list and reported `{ found: false, exhausted: true }`, which reads as "the row is not in
+ * this list" rather than "that strategy does not exist".
+ */
+const QUERY_BY_LIST = Object.values(QueryBy).join(' | ');
+const queryByEnum = z.enum(Object.values(QueryBy));
+export const SCROLL_TOOLS = [
+    {
+        name: ReticleTool.SCROLL_TO,
+        description: 'Find an element in a VIRTUALIZED list that has not rendered yet. Pass `by` (see the parameter for the exact strategies) and `value` (query string) to identify the target row. Scrolls the container until the row mounts, the list ends, or maxScrolls (default 20) is spent. Pass targetIndex + totalCount for bisection — jumps directly to the estimated offset in one scroll (e.g. targetIndex:800 totalCount:1000 jumps to 80% of scrollHeight). Returns { found, element?, scrolls, exhausted }.',
+        inputSchema: {
+            by: queryByEnum.describe(`Query strategy for finding the target: ${QUERY_BY_LIST}`),
+            value: z
+                .string()
+                .describe('Query value for the selected strategy (the element to scroll into view).'),
+            name: z.string().optional().describe('Optional accessible name filter when using by=role.'),
+            container: z
+                .string()
+                .optional()
+                .describe('Element ref for the scrollable container. Omit to scroll the document.'),
+            maxScrolls: scrollCountSchema
+                .optional()
+                .describe('Maximum number of scroll steps before giving up. Default: 20.'),
+            targetIndex: listIndexSchema
+                .optional()
+                .describe('Known row index of the target in the list. Combine with totalCount for bisection — jumps directly to the estimated offset.'),
+            totalCount: listIndexSchema
+                .optional()
+                .describe('Total item count in the virtualized list. Required for bisection with targetIndex.'),
+            sessionId: z
+                .string()
+                .optional()
+                .describe('Active session ID from reticle_sessions. Omit when only one browser session is open.'),
+        },
+        outputSchema: {
+            found: z.boolean(),
+            element: z.object({ ref: z.string(), role: z.string(), name: z.string() }).optional(),
+            scrolls: z.number(),
+            exhausted: z.boolean(),
+            note: z
+                .string()
+                .optional()
+                .describe('Present only when informative: the document itself did not scroll, so the target may be inside a list with its own scroll container — pass its ref as `container`.'),
+        },
+        handler: (deps, args) => {
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            const name = asString(args['name']);
+            const container = asString(args['container']);
+            const targetIndex = asNumber(args['targetIndex']);
+            const totalCount = asNumber(args['totalCount']);
+            const q = {
+                by: asString(args['by']) ?? '',
+                value: asString(args['value']) ?? '',
+                ...(name !== undefined ? { name } : {}),
+                ...(container !== undefined ? { container } : {}),
+                ...(targetIndex !== undefined ? { targetIndex } : {}),
+                ...(totalCount !== undefined ? { totalCount } : {}),
+            };
+            const maxScrolls = asNumber(args['maxScrolls']);
+            return scrollToFind(session, q, maxScrolls !== undefined ? { maxScrolls } : {});
+        },
+    },
+];