@reticlehq/server 2.0.0

package/dist/input/real-input.js

@@ -0,0 +1,289 @@
+import { ActionType, DriveErrorCode, DRIVE_PLAYWRIGHT_MISSING_MSG } from '@reticlehq/core';
+import { installNetworkMocks } from './network-mock.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 }
+        : opts.fullPage === true
+            ? { ...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');
+    return chromium.connectOverCDP(url);
+};
+/** CDP-backed real-input provider. Lazily connects on first availability check / perform. */
+export class CdpRealInputProvider {
+    #cdpUrl;
+    #sleep;
+    #connect;
+    #browser;
+    constructor(options) {
+        this.#cdpUrl = options.cdpUrl;
+        this.#sleep = options.sleep ?? nodeSleep;
+        this.#connect = options.connect ?? cdpConnect;
+    }
+    async #ensureBrowser() {
+        if (this.#browser !== undefined)
+            return this.#browser;
+        try {
+            this.#browser = await this.#connect(this.#cdpUrl);
+            return this.#browser;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async #pageFor(sessionUrl) {
+        const browser = await this.#ensureBrowser();
+        if (browser === undefined)
+            return undefined;
+        const pages = browser.contexts().flatMap((c) => c.pages());
+        const exact = pages.find((p) => p.url() === sessionUrl);
+        if (exact !== undefined)
+            return exact;
+        const target = stripVolatile(sessionUrl);
+        return pages.find((p) => stripVolatile(p.url()) === target);
+    }
+    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. */
+const launchedChromium = async (headless) => {
+    let mod;
+    try {
+        mod = await import('playwright');
+    }
+    catch {
+        throw new DriveError(DriveErrorCode.PLAYWRIGHT_MISSING, DRIVE_PLAYWRIGHT_MISSING_MSG);
+    }
+    try {
+        return await mod.chromium.launch({ headless });
+    }
+    catch (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;
+    #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;
+    }
+    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;
+        try {
+            await page.goto(this.#driveUrl);
+        }
+        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.
+        }
+    }
+    isAvailableFor(sessionUrl) {
+        const page = this.#page;
+        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.#page;
+        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.#page;
+        if (page === undefined)
+            return Promise.resolve(undefined);
+        return capturePage(page, opts);
+    }
+    /** 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. */
+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;
+}
+//# sourceMappingURL=real-input.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"real-input.js","sourceRoot":"","sources":["../../src/input/real-input.ts"],"names":[],"mappings":"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"}

package/dist/input/scroll-find.d.ts

@@ -0,0 +1,41 @@
+import { type CommandResult } from '@reticlehq/core';
+/** The slice of Session scroll-to-find needs — so tests inject a fake without a live browser. */
+export interface ScrollFindSession {
+    command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
+}
+export interface ScrollFindQuery {
+    by: string;
+    value: string;
+    name?: string;
+    /** Ref of the scrollable list container; omit to scroll the document. */
+    container?: string;
+    /**
+     * Known index of the target row in the list. When combined with totalCount, enables bisection:
+     * one jump to the estimated scroll offset rather than 20 sequential viewport scrolls.
+     */
+    targetIndex?: number;
+    /** Total item count in the list (required for bisection). */
+    totalCount?: number;
+}
+export interface ScrollFindResult {
+    found: boolean;
+    /** The first matching element descriptor (when found). */
+    element?: Record<string, unknown>;
+    /** How many viewport scrolls were performed. */
+    scrolls: number;
+    /**
+     * true ⇒ stopped because the list reached its end / could not scroll (raising maxScrolls won't
+     * help). false ⇒ stopped at the maxScrolls budget (more rows may exist further down).
+     */
+    exhausted: boolean;
+}
+/**
+ * Reveal an element that a windowed/virtualized list has not mounted yet. Queries
+ * once (it may already be visible), then scrolls the container ~one viewport at a time, re-querying
+ * after each, until the element appears, the list ends, or the maxScrolls budget is spent. Pure
+ * orchestration over the session command seam — fully unit-testable with a fake.
+ */
+export declare function scrollToFind(session: ScrollFindSession, q: ScrollFindQuery, opts?: {
+    maxScrolls?: number;
+}): Promise<ScrollFindResult>;
+//# sourceMappingURL=scroll-find.d.ts.map

package/dist/input/scroll-find.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-find.d.ts","sourceRoot":"","sources":["../../src/input/scroll-find.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwC,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAG3F,iGAAiG;AACjG,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CAC/E;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAiBD;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,iBAAiB,EAC1B,CAAC,EAAE,eAAe,EAClB,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACjC,OAAO,CAAC,gBAAgB,CAAC,CA0C3B"}

package/dist/input/scroll-find.js

@@ -0,0 +1,59 @@
+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;
+}
+/**
+ * Reveal an element that a windowed/virtualized list has not mounted yet. Queries
+ * once (it may already be visible), then scrolls the container ~one viewport at a time, re-querying
+ * after each, until the element appears, the list ends, or the maxScrolls budget is spent. 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 };
+    // 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. Then refine linearly.
+    let scrolls = 0;
+    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, {
+            ...(q.container !== undefined ? { ref: q.container } : {}),
+            fraction,
+        });
+        scrolls += 1;
+        const hit = await queryFirst(session, q);
+        if (hit !== undefined)
+            return { found: true, element: hit, scrolls, exhausted: false };
+        // Fall through to linear refinement from current position (already near the target).
+        const data = asRecord(sr.result);
+        if (data['atEnd'] === true || data['scrolled'] === false) {
+            return { found: false, scrolls, exhausted: true };
+        }
+    }
+    for (let i = 0; i < max; i += 1) {
+        const sr = await session.command(ReticleCommand.SCROLL, q.container !== undefined ? { ref: q.container } : {});
+        scrolls += 1;
+        const data = asRecord(sr.result);
+        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 — no more rows to reveal.
+        if (data['atEnd'] === true || data['scrolled'] === false) {
+            return { found: false, scrolls, exhausted: true };
+        }
+    }
+    return { found: false, scrolls, exhausted: false }; // spent the budget; more may lie further down
+}
+//# sourceMappingURL=scroll-find.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-find.js","sourceRoot":"","sources":["../../src/input/scroll-find.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,8 @@
+import type { ToolDef } from '../tools/tools.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.
+ */
+export declare const SCROLL_TOOLS: ToolDef[];
+//# sourceMappingURL=scroll-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-tools.d.ts","sourceRoot":"","sources":["../../src/input/scroll-tools.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAY,MAAM,mBAAmB,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,OAAO,EAkEjC,CAAC"}

package/dist/input/scroll-tools.js

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import { ReticleTool } from '../tools/tool-names.js';
+import { asNumber, asString } from '../tools/tools-helpers.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.
+ */
+export const SCROLL_TOOLS = [
+    {
+        name: ReticleTool.SCROLL_TO,
+        description: 'Find an element in a VIRTUALIZED list that has not rendered yet. Pass `by` (role|text|testid|label|placeholder|alt) 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: z
+                .string()
+                .describe('Query strategy for finding the target: role | text | testid | label | placeholder | alt'),
+            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: z
+                .number()
+                .optional()
+                .describe('Maximum number of scroll steps before giving up. Default: 20.'),
+            targetIndex: z
+                .number()
+                .optional()
+                .describe('Known row index of the target in the list. Combine with totalCount for bisection — jumps directly to the estimated offset.'),
+            totalCount: z
+                .number()
+                .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(),
+        },
+        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 } : {});
+        },
+    },
+];
+//# sourceMappingURL=scroll-tools.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-tools.js","sourceRoot":"","sources":["../../src/input/scroll-tools.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,3 @@
+import type { ToolDef } from '../tools/tools.js';
+export declare const VIEWPORT_TOOLS: ToolDef[];
+//# sourceMappingURL=viewport-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"viewport-tools.d.ts","sourceRoot":"","sources":["../../src/input/viewport-tools.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAY,MAAM,mBAAmB,CAAC;AA2B3D,eAAO,MAAM,cAAc,EAAE,OAAO,EAwCnC,CAAC"}

package/dist/input/viewport-tools.js

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import { VISUAL_NO_PROVIDER_RECOMMENDATION, VisualReason } from '@reticlehq/core';
+import { ReticleTool } from '../tools/tool-names.js';
+import { asString } from '../tools/tools-helpers.js';
+const sessionIdShape = {
+    sessionId: z
+        .string()
+        .optional()
+        .describe('Active session ID from reticle_sessions. Omit when only one browser session is open.'),
+};
+/** Bounds so a viewport request stays sane (and a typo can't ask for a 1px or 100k-px window). */
+const MIN_DIM = 64;
+const MAX_DIM = 10000;
+function viewportProvider(deps) {
+    const p = deps.realInput;
+    return p !== undefined && typeof p.setViewport === 'function'
+        ? 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: z.number().int().describe('Viewport width in CSS px (e.g. 1280).'),
+            height: z.number().int().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 provider = viewportProvider(deps);
+            if (provider === undefined) {
+                return {
+                    applied: false,
+                    width: 0,
+                    height: 0,
+                    ok: false,
+                    reason: VisualReason.NO_PROVIDER,
+                    recommendation: VISUAL_NO_PROVIDER_RECOMMENDATION,
+                };
+            }
+            const width = clampDim(args['width']);
+            const height = clampDim(args['height']);
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            const applied = await provider.setViewport(session.url, { width, height });
+            return { applied, width, height };
+        },
+    },
+];
+/** Clamp a requested dimension into [MIN_DIM, MAX_DIM]; a missing/NaN value falls back to MIN_DIM. */
+function clampDim(value) {
+    const n = typeof value === 'number' && Number.isFinite(value) ? Math.round(value) : MIN_DIM;
+    return Math.max(MIN_DIM, Math.min(n, MAX_DIM));
+}
+//# sourceMappingURL=viewport-tools.js.map

package/dist/input/viewport-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewport-tools.js","sourceRoot":"","sources":["../../src/input/viewport-tools.ts"],"names":[],"mappings":"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"}