@reticlehq/server 2.14.0 → 3.2.0

package/dist/input/real-input.js

@@ -1,405 +0,0 @@
-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);
-    }
-    /** 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.
-            await page.goto(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));
-    }
-    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/input/scroll-find.js

@@ -1,111 +0,0 @@
-import { ReticleCommand, SCROLL_FIND_DEFAULTS } from '@reticlehq/core';
-import { asRecord } from '../tools/tools-helpers.js';
-/** 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/input/scroll-tools.d.ts

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

package/dist/input/scroll-tools.js

@@ -1,76 +0,0 @@
-import { z } from 'zod';
-import { QueryBy } from '@reticlehq/core';
-import { ReticleTool } from '../tools/tool-names.js';
-import { asNumber, asString } from '../tools/tools-helpers.js';
-import { listIndexSchema, scrollCountSchema } from '../tools/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 } : {});
-        },
-    },
-];

package/dist/input/viewport-tools.d.ts

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

package/dist/input/viewport-tools.js

@@ -1,72 +0,0 @@
-import { z } from 'zod';
-import { CDP_NO_PROVIDER_REASON, CDP_NO_PROVIDER_RECOMMENDATION } from '@reticlehq/core';
-import { ReticleTool } from '../tools/tool-names.js';
-import { sessionIdShape } from '../tools/tool-kit.js';
-import { MAX_VIEWPORT_PX, MIN_VIEWPORT_PX, viewportPxSchema } from '../tools/numeric-bounds.js';
-import { asString } from '../tools/tools-helpers.js';
-/** Bounds so a viewport request stays sane (and a typo can't ask for a 1px or 100k-px window). */
-const MIN_DIM = MIN_VIEWPORT_PX;
-const MAX_DIM = MAX_VIEWPORT_PX;
-function viewportProvider(deps) {
-    const p = deps.realInput;
-    return p !== undefined && 'function' === typeof p.setViewport
-        ? p
-        : undefined;
-}
-export const VIEWPORT_TOOLS = [
-    {
-        name: ReticleTool.VIEWPORT,
-        description: 'Pin the DRIVEN page (needs `reticle drive`) to a fixed viewport size so a screenshot baseline is ' +
-            'reproducible across machines — the missing piece of CI-stable visual regression, alongside ' +
-            'reticle_visual_diff `masks` and a frozen clock (reticle_clock). Set it once before reticle_screenshot / ' +
-            'reticle_visual_diff. Returns { applied, width, height } or the no-provider recommendation.',
-        inputSchema: {
-            width: viewportPxSchema.describe('Viewport width in CSS px (e.g. 1280).'),
-            height: viewportPxSchema.describe('Viewport height in CSS px (e.g. 800).'),
-            ...sessionIdShape,
-        },
-        outputSchema: {
-            applied: z.boolean(),
-            width: z.number(),
-            height: z.number(),
-            ok: z.boolean().optional(),
-            reason: z.string().optional(),
-            recommendation: z.string().optional(),
-        },
-        handler: async (deps, args) => {
-            const width = clampDim(args['width']);
-            const height = clampDim(args['height']);
-            const session = deps.sessions.resolve(asString(args['sessionId']));
-            const provider = viewportProvider(deps);
-            if (provider !== undefined) {
-                const applied = await provider.setViewport(session.url, { width, height });
-                if (applied)
-                    return { applied: true, width, height };
-            }
-            // A lease is a Playwright-owned page, so the resize was always possible — this tool just had
-            // no route to it. Tried after the driven provider, on the same rule reticle_network_mock
-            // follows: when both exist, drive is the page the caller means and a lease is the fallback.
-            //
-            // Without this, `reticle_viewport` refused on every SDK-only install, which is the DEFAULT
-            // install. Reported from the field: mobile-only UI — a `lg:hidden` hamburger, a drawer that
-            // only mounts under a breakpoint — could not be driven at a desktop viewport at all, and the
-            // recommendation printed alongside the refusal asked the reader to install a second browser.
-            const leased = await deps.pool?.setViewportLease(session.id, { width, height });
-            if (true === leased)
-                return { applied: true, width, height };
-            return {
-                applied: false,
-                width: 0,
-                height: 0,
-                ok: false,
-                reason: CDP_NO_PROVIDER_REASON,
-                recommendation: CDP_NO_PROVIDER_RECOMMENDATION,
-            };
-        },
-    },
-];
-/** Clamp a requested dimension into [MIN_DIM, MAX_DIM]; a missing/NaN value falls back to MIN_DIM. */
-function clampDim(value) {
-    const n = 'number' === typeof value && Number.isFinite(value) ? Math.round(value) : MIN_DIM;
-    return Math.max(MIN_DIM, Math.min(n, MAX_DIM));
-}