@reticlehq/server 3.4.0 → 3.6.0

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

@@ -12,11 +12,11 @@
 import { takeJsCoverage } from './js-coverage.js';
 import { stampedDriveUrl } from './drive-url-stamp.js';
 import { launchChromium } from '../../launch-chromium.js';
-import { chromiumLaunchHint, gotoOptions } from '../pool/playwright-launcher.js';
+import { HIDE_RETICLE_CHROME_CSS, chromiumLaunchHint, 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 { ActionType, clampHoldMs, DriveErrorCode, DRIVE_PLAYWRIGHT_MISSING_MSG, explicitCodeFromArgs, InputMode, InputModeReason, pressKeyFromArgs, pressKeysFromArgs, pressModifiersFromArgs, } from '@reticlehq/core';
 import { installNetworkMocks } from './network-mock.js';
 import { attachNetworkDetail } from './network-detail.js';
 import { injectedConnectArgs } from '../pool/zero-install.js';
@@ -34,8 +34,8 @@ 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.
+ * Which actions are driven by a native pointer. `press` is excluded on purpose — a key has no
+ * pointer, and widening this would change what every existing caller of it means.
  */
 export function isPointerAction(action) {
     return (action === ActionType.HOVER ||
@@ -43,37 +43,217 @@ export function isPointerAction(action) {
         action === ActionType.DBLCLICK ||
         action === ActionType.DRAG);
 }
+/**
+ * The routing question `tryRealInput` asks: does this action have a real-input path at all? Wider
+ * than `isPointerAction` by `press`, which needs no coordinates.
+ */
+export function isRealInputAction(action) {
+    return isPointerAction(action) || action === ActionType.PRESS;
+}
+/**
+ * A gesture that was NOT driven. No center for a key press — a zero would read as a real point.
+ *
+ * `inputMode` is SYNTHETIC: no real gesture ran, so this is the path the caller is about to take.
+ */
+function undriven(action, box) {
+    const base = { performed: false, inputMode: InputMode.SYNTHETIC };
+    return action === ActionType.PRESS ? base : { ...base, center: boxCenter(box) };
+}
 /** 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;
+/**
+ * Drive a `press` with a real keyboard — coordinate-free; the key goes to whatever holds focus.
+ * Key and modifiers come from the same core helpers the synthetic dispatcher uses, so the two paths
+ * cannot read the same args differently.
+ *
+ * A `holdMs` splits the chord into down / wait / up, the same shape the page uses for a held key.
+ * `keyboard.press` would send it instantly instead, reporting a hold-to-confirm that never held.
+ * The one thing this cannot reproduce is the auto-repeat a held key emits: the driver sends a single
+ * keydown, where the in-page path sends the repeats a browser would. Named rather than papered over
+ * — an app that counts repeats needs the synthetic path, and a caller that sees a held key do
+ * nothing now has a reason to try it.
+ */
+async function pressViaKeyboard(page, args, sleep, now) {
+    const key = pressKeyFromArgs(args);
+    const modifiers = pressModifiersFromArgs(args);
+    const chord = 0 < modifiers.length ? `${modifiers.join('+')}+${key}` : key;
+    const holdMs = clampHoldMs(args.holdMs);
+    if (0 === holdMs) {
+        // `press` DOES take a chord string ("Control+k"), so the tap path needs no splitting.
+        await page.keyboard.press(chord);
+        return 0;
+    }
+    /*
+     * `down`/`up` take ONE key each, unlike `press`: `down('Control+k')` throws
+     * `Unknown key: "Control+k"` — measured on a real Chromium, not assumed. The chord string the
+     * tap path uses therefore cannot express a hold, so the chord is split here: modifiers down in
+     * chord order, the key last, and released in reverse (key first, modifiers reversed), which is
+     * what a hand does and what an app's keyup bookkeeping expects.
+     *
+     * Without the split a held shortcut threw before a single key moved, the caller fell back to
+     * the synthetic path, and a real hold was impossible for any press with modifiers — the exact
+     * gesture `holdMs` exists for.
+     *
+     * ## Why every key that went down is tracked, and every exit path cleans up
+     *
+     * The down calls are the ones that MOVE the keyboard, and they can fail partway: `Control` goes
+     * down, the key after it rejects, and the driver's copy of `Control` is still held. That path
+     * used to fall straight to the caller's synthetic replay — which presses the same chord again on
+     * a keyboard that is already holding a modifier. Tracking what actually went down is what makes
+     * the cleanup below able to release the right keys, and only those: releasing a key that never
+     * went down is its own lie, and it would turn a clean failure into an unnecessary refusal.
+     */
+    const pressed = [];
+    const pressDown = async (k) => {
+        await page.keyboard.down(k);
+        pressed.push(k);
+    };
+    try {
+        for (const modifier of modifiers)
+            await pressDown(modifier);
+        await pressDown(key);
+    }
+    catch (error) {
+        // The chord is PARTIALLY down. Release what is held before reporting the failure; if that
+        // cannot be proved, `releaseKeys` throws RELEASE_FAILED and the caller refuses the replay —
+        // the same rule as a failed release on the ordinary path, for the same reason. Only when the
+        // cleanup DOES succeed is the original error safe to hand back.
+        await releaseKeys(page, pressed);
+        throw error;
+    }
+    const startedAt = now();
+    try {
+        await sleep(holdMs);
+    }
+    catch (error) {
+        // The wait failed, and the caller is about to run the synthetic path — which presses this SAME
+        // key a second time. If the driver's copy stays down, a held modifier then colours every later
+        // action for the rest of the run. Best-effort on purpose: whatever went wrong with the wait is
+        // the error worth reporting. A cleanup that cannot be proved is the exception — that one is a
+        // stuck key, and it must reach the caller as a refusal rather than be swallowed.
+        try {
+            await releaseKeys(page, pressed);
+        }
+        catch {
+            throw new DriveError(DriveErrorCode.RELEASE_FAILED, 'the wait failed and the keys it pressed could not be released, so they may still be held');
+        }
+        throw error;
+    }
+    // NOT best-effort: on the ordinary path a failed release is a real failure the caller must hear
+    // about, and swallowing it would report a press whose key is still down.
+    await releaseKeys(page, pressed);
+    return now() - startedAt;
+}
+/**
+ * Release the given keys, in reverse press order, and report a failure as one that leaves the
+ * keyboard UNKNOWN rather than as an ordinary provider error.
+ *
+ * Every release is attempted even after one fails: a stuck `Control` is worse than a stuck letter,
+ * so a failure on one key must not skip the rest. The first failure is what is thrown, since it is
+ * the one that happened first, and it is wrapped in `DriveError` so the caller can tell "this
+ * gesture failed" from "this gesture may have left a key down" — the difference between a safe
+ * synthetic replay and an unsafe one.
+ */
+async function releaseKeys(page, pressed) {
+    let failure;
+    for (const k of [...pressed].reverse()) {
+        try {
+            await page.keyboard.up(k);
+        }
+        catch (error) {
+            failure ??= error;
+        }
+    }
+    if (failure !== undefined) {
+        throw new DriveError(DriveErrorCode.RELEASE_FAILED, `the key was pressed but could not be released, so it may still be held: ${describeFailure(failure)}`);
+    }
+}
+/**
+ * A thrown value as a line a reader can act on.
+ *
+ * Not `String(error)`: a non-Error thrown value (a rejected plain object, an SDK that throws a
+ * record) stringifies to `[object Object]`, which names nothing and hides the one fact the message
+ * exists to carry. Anything that is neither an Error nor a string says so rather than pretending.
+ */
+function describeFailure(error) {
+    if (error instanceof Error)
+        return error.message;
+    return 'string' === typeof error ? error : 'an unknown error';
+}
+/**
+ * The `press`es this module will NOT drive: a chord that only the in-page dispatcher can express.
+ *
+ * `args.keys` asks for several keys held down TOGETHER, pressed in order and released in reverse.
+ * That is not a `page.keyboard.press` chord — a non-modifier key cannot appear before the last `+`
+ * — and a real keyboard cannot aim a key at a named element. `args.code` is the third: the driver
+ * presses by KEY name and offers no way to send a physical `code` that disagrees with it, so
+ * `{ text: 'z', code: 'KeyY' }` would strike a different key than the one asked for. All three are
+ * routed to the synthetic path by the caller, which reports the reason rather than pretending a
+ * different gesture happened.
+ *
+ * Ordered by how specifically the caller asked: `keys` then `code` name the KEY, `ref` names only
+ * the target. Two can apply at once, and the earlier one is the more unusual request — the reason
+ * should name that, not the generic "you passed a ref".
+ */
+export function unspellablePressReason(ref, args) {
+    if (0 < pressKeysFromArgs(args).length) {
+        return InputModeReason.SYNTHETIC_MULTI_KEY_PRESS_PREFERRED;
+    }
+    if (explicitCodeFromArgs(args) !== undefined) {
+        return InputModeReason.SYNTHETIC_KEY_CODE_PRESS_PREFERRED;
+    }
+    if (0 < ref.length)
+        return InputModeReason.SYNTHETIC_ELEMENT_PRESS_PREFERRED;
+    return undefined;
+}
 /**
  * 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) {
+export async function performGesture(page, action, box, args, sleep, 
+/** Injected so a test can assert the achieved hold deterministically; defaults to the real clock. */
+now = Date.now) {
+    // Ahead of the box, not after it: a press addresses focus rather than a point, and the
+    // placeholder box its caller passes would otherwise be turned into a (0,0) that reads like a real
+    // location. The result reports NO `center` for the same reason.
+    if (action === ActionType.PRESS) {
+        const heldMs = await pressViaKeyboard(page, args, sleep, now);
+        return {
+            performed: true,
+            inputMode: InputMode.REAL,
+            // Omitted rather than 0 when there was no hold — see `RealInputResult.heldMs`.
+            ...(heldMs > 0 ? { heldMs } : {}),
+        };
+    }
     const center = boxCenter(box);
     const { cx, cy } = center;
+    const real = (performed) => ({
+        performed,
+        center,
+        inputMode: InputMode.REAL,
+    });
     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 };
+        return real(true);
     }
     if (action === ActionType.CLICK) {
         await page.mouse.move(cx, cy);
         await page.mouse.click(cx, cy);
-        return { performed: true, center };
+        return real(true);
     }
     if (action === ActionType.DBLCLICK) {
         await page.mouse.move(cx, cy);
         await page.mouse.dblclick(cx, cy);
-        return { performed: true, center };
+        return real(true);
     }
     if (action === ActionType.DRAG) {
         if (args.toBox === undefined)
-            return { performed: false, center };
+            return real(false);
         const dst = boxCenter(args.toBox);
         const steps = args.steps ?? DEFAULT_DRAG_STEPS;
         await page.mouse.move(cx, cy);
@@ -84,14 +264,14 @@ export async function performGesture(page, action, box, args, sleep) {
             await page.mouse.move(px, py, { steps: 1 });
         }
         await page.mouse.up();
-        return { performed: true, center };
+        return real(true);
     }
     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 real(true);
     }
-    return { performed: false, center };
+    return real(false);
 }
 /**
  * Reticle paints its own dev overlay (presenter HUD + border glow) into the page. That chrome is
@@ -100,18 +280,19 @@ export async function performGesture(page, action, box, args, sleep) {
  * (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 });
+    const buf = await page.screenshot(opts.jpegQuality !== undefined
+        ? { type: 'jpeg', quality: opts.jpegQuality }
+        : 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) => {
@@ -138,6 +319,7 @@ const cdpConnect = async (url) => {
 export class CdpRealInputProvider {
     #cdpUrl;
     #sleep;
+    #now;
     #connect;
     #onNetworkDetail;
     /** Pages already listening. #pageFor resolves on EVERY call, so without this each action would add
@@ -149,6 +331,7 @@ export class CdpRealInputProvider {
     constructor(options) {
         this.#cdpUrl = options.cdpUrl;
         this.#sleep = options.sleep ?? nodeSleep;
+        this.#now = options.now ?? Date.now;
         this.#connect = options.connect ?? cdpConnect;
         this.#onNetworkDetail = options.onNetworkDetail;
     }
@@ -205,8 +388,8 @@ export class CdpRealInputProvider {
     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);
+            return undriven(action, box);
+        return performGesture(page, action, box, args, this.#sleep, this.#now);
     }
     /** PNG of the correlated page, or undefined if none matches. */
     async screenshot(sessionUrl, opts) {
@@ -309,6 +492,7 @@ export class LaunchedRealInputProvider {
     #driveUrl;
     #headless;
     #sleep;
+    #now;
     #launch;
     #injectConnect;
     #storageState;
@@ -321,6 +505,7 @@ export class LaunchedRealInputProvider {
         this.#driveUrl = options.driveUrl;
         this.#headless = options.headless;
         this.#sleep = options.sleep ?? nodeSleep;
+        this.#now = options.now ?? Date.now;
         this.#launch = options.launch ?? launchedChromium;
         this.#injectConnect = options.injectConnect;
         this.#storageState = options.storageState;
@@ -438,8 +623,8 @@ export class LaunchedRealInputProvider {
     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);
+            return Promise.resolve(undriven(action, box));
+        return performGesture(page, action, box, args, this.#sleep, this.#now);
     }
     /** PNG of the owned page, or undefined before navigate / after dispose. */
     screenshot(_sessionUrl, opts) {

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

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { CDP_NO_PROVIDER_REASON, CDP_NO_PROVIDER_RECOMMENDATION } from '@reticlehq/core';
+import { CDP_NO_PROVIDER_REASON, VIEWPORT_NO_PROVIDER_RECOMMENDATION } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { sessionIdShape } from '../../surface/tools/tool-kit.js';
 import { MAX_VIEWPORT_PX, MIN_VIEWPORT_PX, viewportPxSchema, } from '../../surface/tools/args/numeric-bounds.js';
@@ -16,7 +16,7 @@ function viewportProvider(deps) {
 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 ' +
+        description: 'Pin the DRIVEN or LEASED page (needs `reticle drive`, or `reticle_lease` acquire when there is no CDP provider) 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.',
@@ -34,8 +34,8 @@ export const VIEWPORT_TOOLS = [
             recommendation: z.string().optional(),
         },
         handler: async (deps, args) => {
-            const width = clampDim(args['width']);
-            const height = clampDim(args['height']);
+            const width = clampDim('width', args['width']);
+            const height = clampDim('height', args['height']);
             const session = deps.sessions.resolve(asString(args['sessionId']));
             const provider = viewportProvider(deps);
             if (provider !== undefined) {
@@ -60,13 +60,23 @@ export const VIEWPORT_TOOLS = [
                 height: 0,
                 ok: false,
                 reason: CDP_NO_PROVIDER_REASON,
-                recommendation: CDP_NO_PROVIDER_RECOMMENDATION,
+                recommendation: VIEWPORT_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));
+/**
+ * Clamp a requested dimension into [MIN_DIM, MAX_DIM]; a missing value falls back to MIN_DIM.
+ *
+ * A value that is PRESENT but not a finite number is refused, not read as missing: a client that
+ * sent `"1440"` meant 1440, and answering with a 64px page it never asked for made every later
+ * snapshot, click and screenshot on that page read as broken (#1118).
+ */
+function clampDim(key, value) {
+    if (value === undefined)
+        return MIN_DIM;
+    if ('number' !== typeof value || !Number.isFinite(value)) {
+        throw new Error(`${ReticleTool.VIEWPORT}: \`${key}\` must be a number of CSS px, got ${JSON.stringify(value)} — NOT applied`);
+    }
+    return Math.max(MIN_DIM, Math.min(Math.round(value), MAX_DIM));
 }

package/dist/portal/pool/browser-pool.d.ts

@@ -10,7 +10,7 @@
  * the thin Playwright adapter that satisfies these interfaces lives separately.
  */
 import { type SeedStorage } from '@reticlehq/core';
-import type { Launcher, PooledMockRule } from './pool-contract.js';
+import type { Launcher, PooledMockRule, ScreenshotOptions } from './pool-contract.js';
 export type { InitScriptHandle, Launcher, PooledBrowser, PooledContext, PooledCookie, PooledDialog, PooledMockRule, PooledPage, } from './pool-contract.js';
 /** A leased context+page for one flow. `release` frees the slot and closes the context. */
 export interface Lease {
@@ -42,9 +42,17 @@ interface BrowserPoolOptions {
      * the ~450KB build is only read if some page ever needs it; undefined when there is none to give.
      */
     zeroInstallScript?: () => string | undefined;
+    /**
+     * Launches a browser with a window, for a lease somebody wants to watch. Launched only when the
+     * first headed lease is asked for. Absent: a headed lease is refused.
+     */
+    launchHeaded?: Launcher;
 }
+/** What a headed lease is refused with where no window can be opened. */
+export declare const NO_HEADED_BROWSER = "no headed browser can be opened here";
 /**
- * Owns a single browser and leases isolated contexts out of it, capped at `maxContexts`.
+ * Owns a headless browser (and, when asked, a headed one) and leases isolated contexts out of them,
+ * capped at `maxContexts` across both.
  * Not exported as a singleton — the daemon owns one instance.
  */
 export declare class BrowserPool {
@@ -60,15 +68,17 @@ export declare class BrowserPool {
     /** The sessionIds of every currently leased context — used to report/group leased sessions. */
     leasedSessionIds(): string[];
     /**
-     * The public session id of an active lease on this origin, if we already hold one.
+     * The public session id of an active lease on this origin that `owner` took, if there is one.
      *
      * The lease TOOL reuses that id instead of minting a second context: a second acquire on the same
-     * origin used to leave both tabs connected and poison default session resolution (#600). The pool's
-     * own `acquire` still mints — the parallel suite needs isolation on purpose.
+     * origin used to leave both tabs connected and poison default session resolution (#600). Only the
+     * caller that took the lease gets it back: handing it to whoever asked put two agents in one tab,
+     * each one's verdicts resting on the other's actions (#1226). A caller with no owner cannot be told
+     * apart from another, so it always gets its own. The pool's own `acquire` still mints.
      *
      * Prefers the alias the agent was given, when the app registered under its own name.
      */
-    leaseIdOnOrigin(origin: string): string | undefined;
+    leaseIdOnOrigin(origin: string, owner: string | undefined): string | undefined;
     /**
      * Release a lease by its sessionId (closes the context, frees the slot). No-op if unknown.
      *
@@ -106,9 +116,7 @@ export declare class BrowserPool {
      * Touches the lease like any other tool call, so capturing keeps it alive rather than letting the
      * reaper take it out from under a diff.
      */
-    screenshotLease(sessionId: string, opts?: {
-        fullPage?: boolean;
-    }): Promise<Uint8Array | undefined>;
+    screenshotLease(sessionId: string, opts?: ScreenshotOptions): Promise<Uint8Array | undefined>;
     /**
      * Move the real pointer on a leased page, or false when this session is not a lease or cannot
      * hover. Same optional-capability contract as screenshotLease: absence must read as "could not
@@ -167,6 +175,9 @@ export declare class BrowserPool {
         signal?: AbortSignal;
         sessionId?: string;
         seedStorage?: SeedStorage;
+        owner?: string;
+        /** In a browser with a window the person can watch. */
+        headed?: boolean;
     }): Promise<Lease>;
     /**
      * The websocket address this lease's page reported it could not reach, if it reported one.
@@ -181,4 +192,6 @@ export declare class BrowserPool {
     lastDialogMessage(sessionId: string): string | undefined;
     /** Close every context and the browser. Pending waiters are rejected (the pool is terminal now). */
     shutdown(): Promise<void>;
+    /** Whether this lease lives in the headed browser. */
+    isHeaded(sessionId: string): boolean;
 }