@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,261 @@
+/**
+ * Optional CDP/Playwright real-input mode.
+ *
+ * Synthetic `dispatchEvent` cannot drive native hover/pointer state (an onMouseEnter never
+ * fires, hit-testing never runs). When a CDP endpoint is configured, this module connects a
+ * Playwright `Browser` over CDP and drives REAL pointer/keyboard input against the element box
+ * the SDK resolves (viewport CSS px from getBoundingClientRect).
+ *
+ * Node-only. Playwright is loaded via DYNAMIC `import('playwright')` so non-CDP users never
+ * pay for it; the type-only import is elided by `tsc`, so the build stays green without it.
+ */
+import type { Browser, Page } from 'playwright';
+import { ActionType, DriveErrorCode } 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). */
+export interface ElementBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Args forwarded from reticle_act (fill value, type text, drag drop-target box). */
+export interface RealInputArgs {
+    value?: string;
+    text?: string;
+    /** For drag: the resolved box of the drop-target ref (toRef). */
+    toBox?: ElementBox;
+    steps?: number;
+}
+interface RealInputResult {
+    /** True if a native gesture was actually driven. */
+    performed: boolean;
+    /** Center used, for diagnostics/tests. */
+    center: {
+        cx: number;
+        cy: 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;
+}
+/** The capability surface reticle_act depends on. A FAKE implementing this is injected in tests. */
+export interface RealInputProvider {
+    /** Whether a Playwright Page currently matches this SDK session URL. */
+    isAvailableFor(sessionUrl: string): Promise<boolean>;
+    /** Drive a native gesture for `action` at the element `box`. */
+    perform(sessionUrl: string, action: ActionType, box: ElementBox, args: RealInputArgs): Promise<RealInputResult>;
+    /**
+     * Capture a PNG of the correlated page, or undefined if no page matches. Optional
+     * so the visual layer stays opt-in — a provider that cannot screenshot simply omits it.
+     */
+    screenshot?(sessionUrl: string, opts: ScreenshotOpts): Promise<Uint8Array | undefined>;
+    /**
+     * Read and restore the browser CONTEXT's state — cookies and per-origin storage — so a suite can
+     * start from a known place instead of logging in fifty times.
+     *
+     * Optional, and on the web this is where the capability actually lives. A page cannot write an
+     * httpOnly cookie from inside itself, so the SDK can never do this however much is added to it;
+     * only something holding the context can. A provider with no owned browser omits both, and every
+     * flow then runs from cold, which is correct and merely slower.
+     *
+     * The state is opaque to everything but the browser that produced it. `applyStorageState` returns
+     * false when no driven page matched, which the caller must treat as a failure rather than a
+     * no-op — a suite that believes it is signed in and is not fails fifty times for a reason none of
+     * them names.
+     */
+    storageState?(sessionUrl: string): Promise<unknown>;
+    applyStorageState?(sessionUrl: string, state: unknown): Promise<boolean>;
+    /**
+     * Install (or replace, or with [] clear) network-mock rules on the correlated page — stub a 500,
+     * force offline, delay a response — for deterministic error/edge-state testing. Returns true when
+     * a page matched and the rules were applied, false when no driven page matches this session.
+     * Optional: a provider with no owned browser simply omits it.
+     */
+    setMocks?(sessionUrl: string, rules: MockRule[]): Promise<boolean>;
+    /**
+     * Pin the correlated page's viewport to fixed pixel dimensions so a screenshot baseline is
+     * reproducible across machines (the missing piece of CI-stable visual regression, alongside masks
+     * and the frozen clock). Returns true when a page matched, false otherwise. Optional.
+     */
+    setViewport?(sessionUrl: string, size: {
+        width: number;
+        height: number;
+    }): Promise<boolean>;
+}
+/**
+ * Optional lifecycle a provider that OWNS a browser implements (`reticle drive`). The
+ * reticle_act routing still depends only on `RealInputProvider`; the server uses these to boot/tear-down.
+ */
+export interface OwnedRealInputProvider extends RealInputProvider {
+    /** Launch + navigate the owned browser. Must reject (never hang) on failure. */
+    navigate(): Promise<void>;
+    /** Close the owned browser. Idempotent. */
+    dispose(): Promise<void>;
+}
+/** Structured, code-tagged failure so callers branch on cause, not message text. */
+export declare class DriveError extends Error {
+    readonly code: DriveErrorCode;
+    constructor(code: DriveErrorCode, message: string);
+}
+/** Center of a viewport box in CSS px. Pure — unit-tested directly. */
+export declare function boxCenter(box: ElementBox): {
+    cx: number;
+    cy: number;
+};
+/**
+ * Which actions are driven by native pointer input. fill/type stay synthetic unless a
+ * provider explicitly runs them.
+ */
+export declare function isPointerAction(action: ActionType): boolean;
+type SleepFn = (ms: number) => Promise<void>;
+type ConnectFn = (url: string) => Promise<Browser>;
+/**
+ * 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>;
+/**
+ * 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 declare function capturePage(page: Page, opts: ScreenshotOpts): Promise<Uint8Array>;
+interface CdpProviderOptions {
+    cdpUrl: string;
+    /** Injected so the settle delay is deterministic in tests; defaults to a real Node timer. */
+    sleep?: SleepFn;
+    /** Injected connector so unit tests can stub Playwright without import. */
+    connect?: ConnectFn;
+    /**
+     * Sink for CDP-authoritative network detail. Optional, so the capture stays opt-in.
+     *
+     * This used to exist only on the LAUNCHED provider, which gated wire-level network visibility on
+     * whether Reticle happened to open the browser. That is the wrong axis: owning the browser says
+     * nothing about being able to see its network, and both providers speak CDP. The authoritative
+     * request body is the one thing an in-page fetch wrapper structurally cannot get.
+     */
+    onNetworkDetail?: (detail: NetworkDetail) => void;
+}
+/** CDP-backed real-input provider. Lazily connects on first availability check / perform. */
+export declare class CdpRealInputProvider implements RealInputProvider {
+    #private;
+    constructor(options: CdpProviderOptions);
+    isAvailableFor(sessionUrl: string): Promise<boolean>;
+    perform(sessionUrl: string, action: ActionType, box: ElementBox, args: RealInputArgs): Promise<RealInputResult>;
+    /** PNG of the correlated page, or undefined if none matches. */
+    screenshot(sessionUrl: string, opts: ScreenshotOpts): Promise<Uint8Array | undefined>;
+    /** The context's cookies and per-origin storage; undefined when no driven page matches. */
+    storageState(sessionUrl: string): Promise<unknown>;
+    /**
+     * Put a captured context state back: cookies through the context, per-origin storage through the
+     * page, because only the context owns a cookie jar and only a document owns its localStorage.
+     *
+     * False when no driven page matches. The caller throws on that — see `fixturePortFor`.
+     */
+    applyStorageState(sessionUrl: string, state: unknown): Promise<boolean>;
+    /** Apply network-mock rules to the correlated page; false when no driven page matches. */
+    setMocks(sessionUrl: string, rules: MockRule[]): Promise<boolean>;
+    /** Pin the correlated page's viewport to fixed dimensions; false when no driven page matches. */
+    setViewport(sessionUrl: string, size: {
+        width: number;
+        height: number;
+    }): Promise<boolean>;
+    /** Best-effort cleanup; idempotent. */
+    dispose(): Promise<void>;
+}
+/** Injected launcher so unit tests stub Playwright without import. */
+export type LaunchFn = (headless: boolean) => Promise<Browser>;
+/**
+ * Force a driven page's already-loaded SDK to connect to our loopback bridge with a pairing token,
+ * overriding the app's own (often localhost-only) reticle.connect — so a hosted preview verifies with
+ * no app redeploy. connect is a no-op once connected, so re-invoking it is safe.
+ */
+export interface InjectConnectOptions {
+    token: string;
+    url: string;
+}
+export interface LaunchedProviderOptions {
+    driveUrl: string;
+    headless: boolean;
+    /** Injected so the settle delay is deterministic in tests; defaults to a real Node timer. */
+    sleep?: SleepFn;
+    /** 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). */
+    injectConnect?: InjectConnectOptions;
+    /** Path to a Playwright storageState JSON (cookies/localStorage) — starts the page authenticated. */
+    storageState?: string;
+    /**
+     * Sink for CDP-authoritative network detail. When set, every driven-page response is captured
+     * as a NET_DETAIL and handed here — the daemon routes it onto the driven session's journal so the
+     * inside-app view never loses fidelity to the outside-in view. Omitted → no network detail captured.
+     */
+    onNetworkDetail?: (detail: NetworkDetail) => void;
+}
+/** The only place the dynamic value import of Playwright lives for the launched (drive) path. */
+export declare const launchedChromium: LaunchFn;
+/**
+ * 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 declare class LaunchedRealInputProvider implements OwnedRealInputProvider {
+    #private;
+    constructor(options: LaunchedProviderOptions);
+    navigate(): Promise<void>;
+    isAvailableFor(sessionUrl: string): Promise<boolean>;
+    /**
+     * The context's cookies and per-origin storage, or undefined when no page is live.
+     *
+     * Present here and not only on the CDP provider because THIS is the provider `reticle drive`
+     * builds, and `fixturePortFor` refuses outright when either half is missing — so without these a
+     * driven session had no fixture port at all, and every suite seeded nothing while reading as if it
+     * seeded everything. Same two methods, same contract, one page instead of a page lookup.
+     */
+    storageState(_sessionUrl: string): Promise<unknown>;
+    /**
+     * Put a captured state back: cookies through the context, per-origin storage through the page.
+     * Only the context owns a cookie jar and only a document owns its localStorage.
+     */
+    applyStorageState(_sessionUrl: string, state: unknown): Promise<boolean>;
+    perform(_sessionUrl: string, action: ActionType, box: ElementBox, args: RealInputArgs): Promise<RealInputResult>;
+    /** PNG of the owned page, or undefined before navigate / after dispose. */
+    screenshot(_sessionUrl: string, opts: ScreenshotOpts): Promise<Uint8Array | undefined>;
+    /**
+     * Pin the owned page's viewport; false before navigate / after dispose.
+     *
+     * `CdpRealInputProvider` has had this since it shipped and THIS provider did not, so
+     * `reticle_viewport` refused with `no-cdp-provider` under `reticle drive` — while recommending
+     * `reticle drive` as the fix. Same for `setMocks` below. A driven browser was attached and taking
+     * screenshots the whole time; only these two methods were missing.
+     */
+    setViewport(_sessionUrl: string, size: {
+        width: number;
+        height: number;
+    }): Promise<boolean>;
+    /** Apply network-mock rules to the owned page; false before navigate / after dispose. */
+    setMocks(_sessionUrl: string, rules: MockRule[]): Promise<boolean>;
+    /** Close the owned browser once. Idempotent and safe before navigate. */
+    dispose(): Promise<void>;
+}
+/** Drop hash/query so a page whose URL drifted by fragment still correlates to the session. */
+/**
+ * Correlate a session URL to one driven page, or refuse.
+ *
+ * Exact match first, query string included — that is the only fully reliable signal. The stripped
+ * fallback exists for a real case (an app pushState's to /overview, so the page's URL no longer
+ * equals the session's) but it is only sound when UNAMBIGUOUS.
+ *
+ * Returning the first loose match was a false-green generator: the benchmark fixture selects a bug
+ * purely by query string, so two pages differing only there stripped to the same key, and a visual
+ * diff happily compared the wrong page to itself and reported "0.00% changed, matched" for pixels
+ * that demonstrably differed. Ambiguity now yields undefined, which callers already surface as
+ * "no driven page" rather than as a passing comparison.
+ */
+export declare function selectPage<T extends {
+    url(): string;
+}>(pages: readonly T[], sessionUrl: string): T | undefined;
+export {};