@reticlehq/server 3.5.0 → 3.6.0

package/dist/portal/bridge/bridge.js

@@ -11,7 +11,7 @@ import { tokensMatch } from './token-auth.js';
 import { pairingTokenSource } from './pairing-token.js';
 import { log } from '../../log.js';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
-import { sessionReplacedReason } from '../session/facts/session-replaced.js';
+import { SESSION_PARKED_REASON, sessionReplacedReason, } from '../session/facts/session-replaced.js';
 import { describeSkew, sdkFix, SkewPair } from '../../command/version/version-skew.js';
 import { noteVersionSkew } from '../../command/version/version-nudge.js';
 import { protocolSkewReason } from './protocol-skew.js';
@@ -147,6 +147,10 @@ function harnessRequest(event) {
         return false;
     return undefined;
 }
+/** True when this event is the panel's Sign in. Pure boundary narrowing, like the above. */
+function isSigninRequest(event) {
+    return event.type === EventType.HUMAN_CONTROL && event.data['kind'] === HumanControlKind.SIGNIN;
+}
 /** True when this event is the panel's "sync now" button. Pure boundary narrowing, like the above. */
 function isSyncRequest(event) {
     return event.type === EventType.HUMAN_CONTROL && event.data['kind'] === HumanControlKind.SYNC;
@@ -273,6 +277,7 @@ export class Bridge {
     /** Wired by the daemon: push to the dashboard now, because somebody asked in the panel. */
     #onSyncRequest;
     #onHarnessRequest;
+    #onSigninRequest;
     constructor(options) {
         const host = options.host ?? LOOPBACK_HOST;
         if ((options.token?.length ?? 0) > TRANSPORT_LIMITS.MAX_TOKEN_LENGTH) {
@@ -543,6 +548,11 @@ export class Bridge {
                         socket.close(WS_CLOSE.AUTH_FAILED[0], reason);
                         return;
                     }
+                    // A window the agent detached stays detached across its own reloads. See SessionManager.park.
+                    if (this.sessions.isParked(parsed.sessionId)) {
+                        socket.close(1008, SESSION_PARKED_REASON);
+                        return;
+                    }
                     const existing = this.sessions.get(parsed.sessionId);
                     if (existing === undefined && this.sessions.count() >= this.#maxSessions) {
                         socket.close(...WS_CLOSE.SESSION_LIMIT);
@@ -695,7 +705,10 @@ export class Bridge {
                     // The switch is written through to the platform by the daemon, for the same reason: the
                     // Session has no cloud credential and should not grow one.
                     else if (harness !== undefined)
-                        this.#onHarnessRequest?.(harness);
+                        this.#onHarnessRequest?.(harness, session);
+                    // Signing in writes `~/.reticle`, which only the daemon may do; the panel only asks.
+                    else if (isSigninRequest(parsed.event))
+                        this.#onSigninRequest?.();
                     // Pass the raw frame's byte length so the buffer doesn't re-serialize every event for accounting.
                     else
                         session.pushEvent(parsed.event, Buffer.byteLength(text, 'utf8'));
@@ -838,6 +851,10 @@ export class Bridge {
     attachHarnessRequest(handler) {
         this.#onHarnessRequest = handler;
     }
+    /** Register a handler for the panel's Sign in. Optional, like the above: without one it is ignored. */
+    attachSigninRequest(handler) {
+        this.#onSigninRequest = handler;
+    }
     /** Register a handler to run when a session connects. Additive — every handler runs. */
     attachSessionCreate(handler) {
         this.#onSessionCreate.push(handler);

package/dist/portal/bridge/pairing-token.d.ts

@@ -33,6 +33,15 @@ export declare function pairingTokenSource(input: {
     explicit: boolean;
     env: NodeJS.ProcessEnv;
 }): 'explicit' | 'env:RETICLE_TOKEN' | 'env:RETICLE_PAIRING_TOKEN_DIR' | 'default';
+/**
+ * The pairing token this machine was told to use, or undefined when it was told nothing.
+ *
+ * `RETICLE_TOKEN` first, then the token file in `RETICLE_PAIRING_TOKEN_DIR`, the precedence
+ * `pairingTokenSource` names. A command that mints its own one-shot token for a hosted preview asks
+ * this first: in a container the app's plugin bakes the directory token in, and a fresh token made
+ * the daemon refuse the only app it was started to verify (#1251).
+ */
+export declare function configuredPairingToken(env: NodeJS.ProcessEnv, deps: PairingTokenDeps): Promise<string | undefined>;
 export declare function pairingTokenPath(dir: string): string;
 /** Production IO adapter: 0600 file + 0700 dir so only the owner can read the secret. */
 export declare function nodePairingTokenDeps(): PairingTokenDeps;

package/dist/portal/bridge/pairing-token.js

@@ -41,6 +41,23 @@ export function pairingTokenSource(input) {
         return `env:${PAIRING_TOKEN_DIR_ENV}`;
     return 'default';
 }
+/**
+ * The pairing token this machine was told to use, or undefined when it was told nothing.
+ *
+ * `RETICLE_TOKEN` first, then the token file in `RETICLE_PAIRING_TOKEN_DIR`, the precedence
+ * `pairingTokenSource` names. A command that mints its own one-shot token for a hosted preview asks
+ * this first: in a container the app's plugin bakes the directory token in, and a fresh token made
+ * the daemon refuse the only app it was started to verify (#1251).
+ */
+export async function configuredPairingToken(env, deps) {
+    const token = env[ReticleEnv.TOKEN]?.trim();
+    if (token !== undefined && 0 < token.length)
+        return token;
+    const dir = env[PAIRING_TOKEN_DIR_ENV];
+    if (dir === undefined || 0 === dir.length)
+        return undefined;
+    return readOrCreatePairingToken(dir, deps);
+}
 export function pairingTokenPath(dir) {
     return join(dir, ReticleDir.PAIRING_TOKEN_FILE);
 }

package/dist/portal/input/real-input.d.ts

@@ -11,7 +11,7 @@
  */
 import { type ScriptCoverage } from './js-coverage.js';
 import type { Browser, Page } from 'playwright';
-import { ActionType, DriveErrorCode } from '@reticlehq/core';
+import { ActionType, DriveErrorCode, InputMode, InputModeReason } from '@reticlehq/core';
 import { type MockRule } from './network-mock.js';
 import { type NetworkDetail } from './network-detail.js';
 /** Viewport CSS-px box as returned by the INSPECT command (getBoundingClientRect). */
@@ -21,28 +21,72 @@ export interface ElementBox {
     width: number;
     height: number;
 }
-/** Args forwarded from reticle_act (fill value, type text, drag drop-target box). */
-export interface RealInputArgs {
+/**
+ * Args forwarded from reticle_act (fill value, type text, press key, drag drop-target box).
+ *
+ * A `type`, not an `interface`: only the alias form gets an implicit index signature, so the core
+ * arg readers take it as a plain record without a cast at every call site.
+ */
+export type RealInputArgs = {
     value?: string;
     text?: string;
+    /** For press: the key name, e.g. Escape or Tab. `text` also carries it; `key` is the fallback. */
+    key?: string;
+    /** For press: modifier names (Meta/Control/Shift/Alt; aliases like `cmd` accepted). */
+    modifiers?: string[];
+    /**
+     * For press: several keys held down TOGETHER, pressed in order and released in reverse. Read but
+     * never forwarded — a chord with a non-modifier key has no `page.keyboard.press` spelling, so the
+     * caller routes such a press to the synthetic dispatcher before it reaches here.
+     */
+    keys?: string[];
+    /**
+     * For press: how long to keep the key down between keydown and keyup. The same argument the
+     * synthetic path has always honoured, so a hold-to-confirm key driven through the driver holds
+     * for exactly as long as one driven in the page.
+     */
+    holdMs?: number;
     /** For drag: the resolved box of the drop-target ref (toRef). */
     toBox?: ElementBox;
     steps?: number;
-}
-interface RealInputResult {
+};
+/** What a provider reports for one driven gesture. Exported so a fake can build it by name. */
+export interface RealInputResult {
     /** True if a native gesture was actually driven. */
     performed: boolean;
-    /** Center used, for diagnostics/tests. */
-    center: {
+    /** Center used, for diagnostics/tests. ABSENT for a key press: see `undriven`. */
+    center?: {
         cx: number;
         cy: number;
     };
+    /**
+     * Which path this result came from. `real` whenever a gesture was actually driven, so a caller
+     * reading it on a `performed: true` result learns nothing it did not already know — it is here
+     * for the `performed: false` case, where the caller is about to take the synthetic path and
+     * saying `real` would describe a gesture that never ran.
+     */
+    inputMode: InputMode;
+    /**
+     * How long the key was ACTUALLY held, for a real press that was asked to hold. Absent for every
+     * other gesture, and for a press with no `holdMs` — the same rule the synthetic path uses, where
+     * an absent `heldMs` means "this action does not hold" rather than "it held for no time".
+     *
+     * Measured rather than echoed back: `holdMs: 1200` against a 1200ms animation is a race by
+     * construction, and a throttled tab stretches the wait. A caller needs to tell "held 1200" from
+     * "held 1204", and can only do that with the achieved number.
+     */
+    heldMs?: number;
 }
 /** Options for a page screenshot — full-page scroll capture and/or a clip box. */
 export interface ScreenshotOpts {
     fullPage?: boolean;
     /** Restrict the capture to one element/region (viewport CSS px). */
     clip?: ElementBox;
+    /**
+     * A live picture, as a JPEG at this quality: what a person is watching, taken as it is. The
+     * baseline tweaks (hiding the HUD, stopping animations) would make their window flicker each second.
+     */
+    jpegQuality?: number;
 }
 /** The capability surface reticle_act depends on. A FAKE implementing this is injected in tests. */
 export interface RealInputProvider {
@@ -117,17 +161,40 @@ export declare function boxCenter(box: ElementBox): {
     cy: number;
 };
 /**
- * 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 declare function isPointerAction(action: ActionType): boolean;
+/**
+ * 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 declare function isRealInputAction(action: ActionType): boolean;
 type SleepFn = (ms: number) => Promise<void>;
 type ConnectFn = (url: string) => Promise<Browser>;
+/**
+ * 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 declare function unspellablePressReason(ref: string, args: Record<string, unknown>): InputModeReason | 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 declare function performGesture(page: Page, action: ActionType, box: ElementBox, args: RealInputArgs, sleep: SleepFn): Promise<RealInputResult>;
+export declare function performGesture(page: Page, action: ActionType, box: ElementBox, args: RealInputArgs, sleep: SleepFn, 
+/** Injected so a test can assert the achieved hold deterministically; defaults to the real clock. */
+now?: () => number): Promise<RealInputResult>;
 /**
  * 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.
@@ -137,6 +204,8 @@ interface CdpProviderOptions {
     cdpUrl: string;
     /** Injected so the settle delay is deterministic in tests; defaults to a real Node timer. */
     sleep?: SleepFn;
+    /** Injected so a measured hold is deterministic in tests; defaults to the real clock. */
+    now?: () => number;
     /** Injected connector so unit tests can stub Playwright without import. */
     connect?: ConnectFn;
     /**
@@ -193,6 +262,8 @@ export interface LaunchedProviderOptions {
     headless: boolean;
     /** Injected so the settle delay is deterministic in tests; defaults to a real Node timer. */
     sleep?: SleepFn;
+    /** Injected so a measured hold is deterministic in tests; defaults to the real clock. */
+    now?: () => number;
     /** Injected launcher so unit tests can stub Playwright; defaults to dynamic import('playwright'). */
     launch?: LaunchFn;
     /** When set, re-invoke the page's reticle.connect with these after load (drive-a-hosted-preview). */

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.',
@@ -60,7 +60,7 @@ export const VIEWPORT_TOOLS = [
                 height: 0,
                 ok: false,
                 reason: CDP_NO_PROVIDER_REASON,
-                recommendation: CDP_NO_PROVIDER_RECOMMENDATION,
+                recommendation: VIEWPORT_NO_PROVIDER_RECOMMENDATION,
             };
         },
     },