@reticlehq/server 3.5.0 → 3.7.0

package/dist/portal/bridge/bridge.d.ts

@@ -1,6 +1,7 @@
 import * as http from 'node:http';
 import { Session } from '../session/session.js';
 import { SessionManager } from '../session/session-manager.js';
+import { type HarnessRequest } from './harness-request.js';
 import { pairingTokenSource } from './pairing-token.js';
 /** A human clicked ▶ on a saved flow in the panel — replay it with no agent. Wired by the daemon. */
 type ReplayRequestHandler = (sessionId: string, flowName: string) => void;
@@ -107,10 +108,15 @@ export declare class Bridge {
      */
     attachSyncRequest(handler: () => void): void;
     /**
-     * Register a handler for the panel's harness switch. Optional for the same reason as the above: a
-     * bridge built without one ignores the request rather than refusing it.
+     * Register a handler for the panel's Harness controls (switch, Run, Stop). Optional for the same
+     * reason as the above: a bridge built without one ignores the request rather than refusing it.
      */
-    attachHarnessRequest(handler: (enabled: boolean) => void): void;
+    attachHarnessRequest(handler: (request: HarnessRequest, session: Session) => void): void;
+    /**
+     * Register a handler for the panel's Sign in, told which tab asked (its project is linked once the
+     * sign-in lands). Optional, like the above: without one it is ignored.
+     */
+    attachSigninRequest(handler: (from: Session) => void): void;
     /** Register a handler to run when a session connects. Additive — every handler runs. */
     attachSessionCreate(handler: (session: Session) => void): void;
     close(): Promise<void>;

package/dist/portal/bridge/bridge.js

@@ -8,11 +8,13 @@ import { EventType, HumanControlKind, RETICLE_WS_PATH, ReticleMessageSchema, LOO
 import { Session } from '../session/session.js';
 import { SessionManager } from '../session/session-manager.js';
 import { tokensMatch } from './token-auth.js';
+import { noteWrongPathUpgrades, wrongPathReason } from './wrong-path.js';
+import { harnessRequest } from './harness-request.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 { describeSkew, sdkFix, SkewPair } from '../../command/version/version-skew.js';
+import { SESSION_PARKED_REASON, sessionReplacedReason, } from '../session/facts/session-replaced.js';
+import { describeSdkBehind, describeSkew, sdkFix, SDK_BEHIND_NARRATION, SkewPair, } from '../../command/version/version-skew.js';
 import { noteVersionSkew } from '../../command/version/version-nudge.js';
 import { protocolSkewReason } from './protocol-skew.js';
 import { SERVER_VERSION } from '../../command/version/identity/server-version.js';
@@ -129,23 +131,9 @@ function replayRequest(event) {
     const name = event.data['text'];
     return 'string' === typeof name && name.length > 0 ? name : undefined;
 }
-/**
- * The desired harness state if this event is the panel's switch, else undefined.
- *
- * Carries `on`/`off` rather than meaning "toggle": a double-click on a flaky connection sends two,
- * and two toggles land back where they started while two `on`s are the same as one.
- */
-function harnessRequest(event) {
-    if (event.type !== EventType.HUMAN_CONTROL)
-        return undefined;
-    if (event.data['kind'] !== HumanControlKind.HARNESS)
-        return undefined;
-    const want = event.data['text'];
-    if ('on' === want)
-        return true;
-    if ('off' === want)
-        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) {
@@ -273,6 +261,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) {
@@ -396,6 +385,15 @@ export class Bridge {
         this.#wss.on('error', (err) => {
             log('bridge_ws_error', { error: err.message });
         });
+        // A dial on any other path got a bare 400 from `ws` and left no trace for a diagnosis (#1242).
+        // Only a dial the origin check would have let in is the app's: a socket with no Origin is any
+        // local process, and recording it would tell the agent the app is running when it may not be.
+        noteWrongPathUpgrades(this.#wss, (path, origin) => {
+            log('bridge_wrong_path', { path, origin: origin ?? 'missing' });
+            if (origin !== undefined && this.#originAllowed(origin)) {
+                this.sessions.noteClosure(wrongPathReason(path, origin), this.#clock());
+            }
+        });
         this.#wss.on('connection', (socket) => {
             this.#onConnection(socket);
         });
@@ -478,6 +476,22 @@ export class Bridge {
                         log('hello_invalid', { ...refused });
                         this.sessions.noteClosure(WS_CLOSE_REASON.INVALID_HELLO, this.#clock(), refused);
                     }
+                    // On a LIVE session a frame that fails the schema is dropped, not answered with a close.
+                    // The SDK reads every 1008 as permanent and stops reconnecting, so one event kind from a
+                    // newer SDK ended the session for good, mid-drive, until a manual reload (#1413). What was
+                    // thrown away is evidence, so it is recorded as a transport gap in this window: a verdict
+                    // over it is downgraded rather than graded over an event nobody read. Only before hello is
+                    // a bad frame still a terminal refusal.
+                    if (undefined !== session) {
+                        log('invalid_frame_dropped', { sessionId: session.id, ...peekFrameKind(text) });
+                        session.pushEvent({
+                            t: session.elapsed(),
+                            type: EventType.TRANSPORT_OVERFLOW,
+                            sessionId: session.id,
+                            data: { dropped: 1 },
+                        });
+                        return;
+                    }
                     socket.close(...WS_CLOSE.INVALID_MESSAGE);
                     return;
                 }
@@ -543,6 +557,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);
@@ -654,6 +673,16 @@ export class Bridge {
                         session.versionSkew = skew;
                         noteVersionSkew(SkewPair.SDK, skew);
                     }
+                    else {
+                        // Wire-compatible but a minor or more behind: the agent hears it on its next tool call
+                        // and the person on the overlay. Not `versionSkew`, which marks the pair as broken.
+                        const behind = describeSdkBehind(parsed.sdkVersion, SERVER_VERSION, fixForThisProject);
+                        if (behind !== undefined && parsed.sdkVersion !== undefined) {
+                            log('sdk_behind', { sessionId: session.id, sdk: parsed.sdkVersion });
+                            noteVersionSkew(SkewPair.SDK_BEHIND, behind);
+                            session.pushNarration(SDK_BEHIND_NARRATION(parsed.sdkVersion, SERVER_VERSION), false);
+                        }
+                    }
                     log('session_connected', { sessionId: session.id, url: session.url });
                     // The one fact that separates a broken install from an unused one. Best-effort and wrapped:
                     // a metric must never affect whether an app can connect. See SessionSummary.appConnects.
@@ -695,7 +724,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?.(session);
                     // 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'));
@@ -832,12 +864,19 @@ export class Bridge {
         this.#onSyncRequest = handler;
     }
     /**
-     * Register a handler for the panel's harness switch. Optional for the same reason as the above: a
-     * bridge built without one ignores the request rather than refusing it.
+     * Register a handler for the panel's Harness controls (switch, Run, Stop). Optional for the same
+     * reason as the above: a bridge built without one ignores the request rather than refusing it.
      */
     attachHarnessRequest(handler) {
         this.#onHarnessRequest = handler;
     }
+    /**
+     * Register a handler for the panel's Sign in, told which tab asked (its project is linked once the
+     * sign-in lands). 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);
@@ -852,3 +891,24 @@ export class Bridge {
         });
     }
 }
+/**
+ * The `kind` and event `type` of a frame that failed the schema, for the log: never its payload,
+ * which can carry anything the page sent. Each is a bounded string or absent.
+ */
+function peekFrameKind(text) {
+    const short = (v) => 'string' === typeof v ? v.slice(0, MAX_LOGGED_FRAME_FIELD) : undefined;
+    try {
+        const json = JSON.parse(text);
+        const kind = short(json?.kind);
+        const eventType = short(json?.event?.type);
+        return {
+            ...(kind === undefined ? {} : { kind }),
+            ...(eventType === undefined ? {} : { eventType }),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/** How much of a frame's `kind` or event `type` the drop log keeps. */
+const MAX_LOGGED_FRAME_FIELD = 64;

package/dist/portal/bridge/harness-request.d.ts

@@ -0,0 +1,23 @@
+/**
+ * What the panel's Harness controls asked for, narrowed at the boundary: the autonomous switch,
+ * Run Harness (with an optional persona), or Stop. Keyed by the control's own wire kind.
+ *
+ * The switch carries `on`/`off` rather than meaning "toggle": a double-click on a flaky connection
+ * sends two, and two toggles land back where they started while two `on`s are the same as one.
+ */
+import { HumanControlKind } from '@reticlehq/core';
+export type HarnessRequest = {
+    kind: typeof HumanControlKind.HARNESS;
+    enabled: boolean;
+} | {
+    kind: typeof HumanControlKind.HARNESS_RUN;
+    persona?: string;
+} | {
+    kind: typeof HumanControlKind.HARNESS_STOP;
+} | {
+    kind: typeof HumanControlKind.HARNESS_LINK;
+};
+export declare function harnessRequest(event: {
+    type: string;
+    data: Record<string, unknown>;
+}): HarnessRequest | undefined;

package/dist/portal/bridge/harness-request.js

@@ -0,0 +1,27 @@
+/**
+ * What the panel's Harness controls asked for, narrowed at the boundary: the autonomous switch,
+ * Run Harness (with an optional persona), or Stop. Keyed by the control's own wire kind.
+ *
+ * The switch carries `on`/`off` rather than meaning "toggle": a double-click on a flaky connection
+ * sends two, and two toggles land back where they started while two `on`s are the same as one.
+ */
+import { EventType, HumanControlKind } from '@reticlehq/core';
+export function harnessRequest(event) {
+    if (event.type !== EventType.HUMAN_CONTROL)
+        return undefined;
+    const kind = event.data['kind'];
+    const text = event.data['text'];
+    if (HumanControlKind.HARNESS_STOP === kind || HumanControlKind.HARNESS_LINK === kind)
+        return { kind };
+    if (HumanControlKind.HARNESS_RUN === kind) {
+        const persona = 'string' === typeof text ? text.trim() : '';
+        return 0 < persona.length ? { kind, persona } : { kind };
+    }
+    if (HumanControlKind.HARNESS !== kind)
+        return undefined;
+    if ('on' === text)
+        return { kind, enabled: true };
+    if ('off' === text)
+        return { kind, enabled: false };
+    return undefined;
+}

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/bridge/wrong-path.d.ts

@@ -0,0 +1,17 @@
+import type { WebSocketServer } from 'ws';
+/** The path an upgrade asked for: the pathname only, because a query can carry a pairing token. */
+export declare function requestedPath(url: string | undefined): string;
+/**
+ * What the no-session diagnosis says about it. The path is in it because the path is the fix. It
+ * says only what the record shows: a wrong-path upgrade is answered before any origin check, so
+ * the client could be anything, and a sentence promising the app is running would send the agent
+ * away from a dev server that really is stopped. The bridge records one only from an Origin its
+ * handshake would have accepted.
+ */
+export declare function wrongPathReason(path: string, origin: string): string;
+/**
+ * Report each upgrade `ws` turns away for its path. Wraps `shouldHandle`, which `ws` documents as
+ * the method to override and calls for every upgrade before it answers 400, so the decision itself
+ * is left to `ws` and only observed here.
+ */
+export declare function noteWrongPathUpgrades(wss: WebSocketServer, note: (path: string, origin: string | undefined) => void): void;

package/dist/portal/bridge/wrong-path.js

@@ -0,0 +1,35 @@
+import { RETICLE_WS_PATH } from '@reticlehq/core';
+/** Long enough for any real path, short enough that a junk request cannot fill the log line. */
+const MAX_PATH_SHOWN = 80;
+/** The path an upgrade asked for: the pathname only, because a query can carry a pairing token. */
+export function requestedPath(url) {
+    const path = (url ?? '').split('?', 1)[0] ?? '';
+    const shown = 0 === path.length ? '/' : path;
+    return shown.length > MAX_PATH_SHOWN ? `${shown.slice(0, MAX_PATH_SHOWN)}…` : shown;
+}
+/**
+ * What the no-session diagnosis says about it. The path is in it because the path is the fix. It
+ * says only what the record shows: a wrong-path upgrade is answered before any origin check, so
+ * the client could be anything, and a sentence promising the app is running would send the agent
+ * away from a dev server that really is stopped. The bridge records one only from an Origin its
+ * handshake would have accepted.
+ */
+export function wrongPathReason(path, origin) {
+    return (`a WebSocket upgrade from ${origin} asked for ${path} and got a 400: the bridge listens on ` +
+        `${RETICLE_WS_PATH} only. If that was your app, point the URL given to connect({ url }) at ` +
+        `the bridge path, for example ws://localhost:<port>${RETICLE_WS_PATH}.`);
+}
+/**
+ * Report each upgrade `ws` turns away for its path. Wraps `shouldHandle`, which `ws` documents as
+ * the method to override and calls for every upgrade before it answers 400, so the decision itself
+ * is left to `ws` and only observed here.
+ */
+export function noteWrongPathUpgrades(wss, note) {
+    const handles = wss.shouldHandle.bind(wss);
+    wss.shouldHandle = (req) => {
+        const handled = handles(req);
+        if (false === handled)
+            note(requestedPath(req.url), req.headers.origin);
+        return handled;
+    };
+}

package/dist/portal/input/network-mock-tools.js

@@ -70,6 +70,15 @@ export function toRules(value) {
         return rule;
     });
 }
+/**
+ * The applied result, after telling the recorder. Steps driven while a mock is active are marked
+ * on the ambient tape, so a journey proved against mocked responses is not auto-saved as a flow
+ * that would replay against the real backend (#1459).
+ */
+function mocksApplied(deps, sessionId, count) {
+    deps.recordings.markMocked(sessionId, 0 < count);
+    return { applied: true, count };
+}
 export const NETWORK_MOCK_TOOLS = [
     {
         name: ReticleTool.NETWORK_MOCK,
@@ -104,14 +113,14 @@ export const NETWORK_MOCK_TOOLS = [
             if (provider !== undefined) {
                 const applied = await provider.setMocks(session.url, rules);
                 if (applied)
-                    return { applied: true, count: rules.length };
+                    return mocksApplied(deps, session.id, rules.length);
             }
             // A lease is a Playwright-owned page — CDP intercept was always there, this tool just had no
             // route to it. Tried after the driven provider: when both exist, drive is the page the caller
             // means, and a lease is the fallback rather than a competitor.
             const leased = await deps.pool?.setMocksLease(session.id, rules);
             if (true === leased)
-                return { applied: true, count: rules.length };
+                return mocksApplied(deps, session.id, rules.length);
             return {
                 applied: false,
                 count: 0,

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,74 @@ 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;
+    /** One image pixel per CSS pixel, so a high-density display does not double a step screenshot. */
+    cssScale?: boolean;
 }
 /** The capability surface reticle_act depends on. A FAKE implementing this is injected in tests. */
 export interface RealInputProvider {
@@ -117,17 +163,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 +206,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 +264,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). */