wrc-ts 0.1.0

package/dist/internal/convert.js

@@ -0,0 +1,250 @@
+// Internal proto ↔ TS helpers used by client.ts. Anything in here is
+// implementation detail and is NOT exported from the package entrypoints.
+import { create } from "@bufbuild/protobuf";
+import { HeaderModificationSchema, CookiePartitionKeySchema, CookieParamSchema, HeaderSchema, StorageItemSchema, StorageOriginEntrySchema, } from "../gen/wrc_pb.js";
+import { pickFrame } from "../locator.js";
+export function elementFields(target, optsInFrame) {
+    const out = {};
+    if (target.selector)
+        out.selector = target.selector;
+    if (target.jsExpression)
+        out.jsExpression = target.jsExpression;
+    if (target.backendNodeId)
+        out.backendNodeId = target.backendNodeId;
+    const fid = pickFrame(optsInFrame, target);
+    if (fid)
+        out.frameId = fid;
+    if (target.x !== undefined)
+        out.x = target.x;
+    if (target.y !== undefined)
+        out.y = target.y;
+    return out;
+}
+// ──────────────────────────────────────────────────────────────────────
+// Rect
+// ──────────────────────────────────────────────────────────────────────
+export function rectFromProto(r) {
+    if (!r)
+        return { x: 0, y: 0, width: 0, height: 0 };
+    return { x: r.x, y: r.y, width: r.width, height: r.height };
+}
+// ──────────────────────────────────────────────────────────────────────
+// Element / Drag / Wait results
+// ──────────────────────────────────────────────────────────────────────
+export function elementResultFromProto(r) {
+    return {
+        success: r.success,
+        frameId: r.frameId,
+        backendNodeId: r.backendNodeId,
+        isVisible: r.isVisible,
+        bounds: rectFromProto(r.bounds),
+        rootX: r.rootX,
+        rootY: r.rootY,
+    };
+}
+export function dragResultFromProto(r) {
+    return {
+        success: r.success,
+        frameId: r.frameId,
+        backendNodeId: r.backendNodeId,
+        startX: r.startX,
+        startY: r.startY,
+        endX: r.endX,
+        endY: r.endY,
+    };
+}
+export function waitResultFromProto(r) {
+    return {
+        index: r.index,
+        frameId: r.frameId,
+        backendNodeId: r.backendNodeId,
+        isVisible: r.isVisible,
+        bounds: rectFromProto(r.bounds),
+    };
+}
+// ──────────────────────────────────────────────────────────────────────
+// FrameInfo / PageInfo
+// ──────────────────────────────────────────────────────────────────────
+export function frameInfoFromProto(f) {
+    return {
+        frameId: f.frameId,
+        url: f.url,
+        isOOPIF: f.isOopif,
+        hasJSContext: f.hasJsContext,
+        isLoading: f.isLoading,
+        isVisible: f.isVisible,
+        absoluteRect: rectFromProto(f.absoluteRect),
+        relativeRect: rectFromProto(f.relativeRect),
+        children: f.children.map(frameInfoFromProto),
+    };
+}
+export function pageInfoFromProto(p) {
+    return {
+        pageId: p.pageId,
+        browserContextId: p.browserContextId,
+        url: p.url,
+        title: p.title,
+        viewport: rectFromProto(p.viewport),
+        frameTree: p.frameTree
+            ? frameInfoFromProto(p.frameTree)
+            : {},
+    };
+}
+// ──────────────────────────────────────────────────────────────────────
+// Headers
+// ──────────────────────────────────────────────────────────────────────
+export function headerFromProto(h) {
+    return { name: h.name, value: h.value };
+}
+export function headersToProto(headers) {
+    if (!headers)
+        return [];
+    return headers.map(h => {
+        const msg = create(HeaderSchema);
+        msg.name = h.name;
+        msg.value = h.value;
+        return msg;
+    });
+}
+// ──────────────────────────────────────────────────────────────────────
+// Intercepted request / response
+// ──────────────────────────────────────────────────────────────────────
+export function interceptedRequestFromProto(r) {
+    if (!r)
+        return null;
+    return {
+        method: r.method,
+        url: r.url,
+        headers: r.headers.map(headerFromProto),
+        body: r.body,
+        resourceType: r.resourceType,
+    };
+}
+export function interceptedResponseFromProto(r) {
+    if (!r)
+        return null;
+    return {
+        url: r.url,
+        statusCode: r.statusCode,
+        headers: r.headers.map(headerFromProto),
+        body: r.body,
+    };
+}
+// ──────────────────────────────────────────────────────────────────────
+// Cookies
+// ──────────────────────────────────────────────────────────────────────
+export function cookieParamFromProto(c) {
+    return {
+        name: c.name,
+        value: c.value,
+        url: c.url,
+        domain: c.domain,
+        path: c.path,
+        secure: c.secure,
+        httpOnly: c.httpOnly,
+        sameSite: c.sameSite,
+        expires: c.expires,
+        priority: c.priority,
+        sourceScheme: c.sourceScheme,
+        sourcePort: c.sourcePort,
+        partitionKey: c.partitionKey
+            ? {
+                topLevelSite: c.partitionKey.topLevelSite,
+                hasCrossSiteAncestor: c.partitionKey.hasCrossSiteAncestor,
+            }
+            : undefined,
+    };
+}
+export function cookieParamsToProto(cookies) {
+    return cookies.map(c => {
+        const msg = create(CookieParamSchema);
+        msg.name = c.name;
+        msg.value = c.value;
+        if (c.url !== undefined)
+            msg.url = c.url;
+        msg.domain = c.domain;
+        msg.path = c.path;
+        if (c.secure !== undefined)
+            msg.secure = c.secure;
+        if (c.httpOnly !== undefined)
+            msg.httpOnly = c.httpOnly;
+        if (c.sameSite !== undefined)
+            msg.sameSite = c.sameSite;
+        if (c.expires !== undefined)
+            msg.expires = c.expires;
+        if (c.priority !== undefined)
+            msg.priority = c.priority;
+        if (c.sourceScheme !== undefined)
+            msg.sourceScheme = c.sourceScheme;
+        if (c.sourcePort !== undefined)
+            msg.sourcePort = c.sourcePort;
+        if (c.partitionKey !== undefined) {
+            msg.partitionKey = create(CookiePartitionKeySchema);
+            msg.partitionKey.topLevelSite = c.partitionKey.topLevelSite;
+            msg.partitionKey.hasCrossSiteAncestor = c.partitionKey.hasCrossSiteAncestor;
+        }
+        return msg;
+    });
+}
+// ──────────────────────────────────────────────────────────────────────
+// Storage (localStorage)
+// ──────────────────────────────────────────────────────────────────────
+export function storageEntryFromProto(e) {
+    return {
+        origin: e.origin,
+        items: e.items.map(it => ({ key: it.key, value: it.value })),
+    };
+}
+export function storageEntriesToProto(storage) {
+    return storage.map(e => {
+        const msg = create(StorageOriginEntrySchema);
+        msg.origin = e.origin;
+        msg.items = e.items.map(it => {
+            const item = create(StorageItemSchema);
+            item.key = it.key;
+            item.value = it.value;
+            return item;
+        });
+        return msg;
+    });
+}
+// ──────────────────────────────────────────────────────────────────────
+// Network — patterns + header modifications
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * splitRequestPatterns turns a RequestPattern[] into the proto's parallel
+ * URL + abort-flag slices. When no pattern has abort set, the aborts
+ * slice is returned as an empty array so it stays off the wire.
+ */
+export function splitRequestPatterns(patterns) {
+    const urls = new Array(patterns.length);
+    let any = false;
+    for (let i = 0; i < patterns.length; i++) {
+        urls[i] = patterns[i].url;
+        if (patterns[i].abort)
+            any = true;
+    }
+    if (!any)
+        return { urls, aborts: [] };
+    const aborts = new Array(patterns.length);
+    for (let i = 0; i < patterns.length; i++) {
+        aborts[i] = patterns[i].abort ? 1 : 0;
+    }
+    return { urls, aborts };
+}
+export function headerModsToProto(mods) {
+    if (!mods)
+        return [];
+    return mods.map(m => {
+        const msg = create(HeaderModificationSchema);
+        msg.name = m.name;
+        if (m.value !== undefined)
+            msg.value = m.value;
+        msg.action = m.action;
+        if (m.before)
+            msg.before = m.before;
+        if (m.after)
+            msg.after = m.after;
+        return msg;
+    });
+}

package/dist/locator.d.ts

@@ -0,0 +1,191 @@
+/**
+ * AllFrames is the WRC.pdl sentinel for "match in every frame on the page".
+ * Use it for any field documented as accepting a frameId — both
+ * Locator.inFrame and *Opts.inFrame.
+ */
+export declare const AllFrames = "ALL_FRAMES";
+/**
+ * Locator is the universal "what element / what condition" type. It is used
+ * both as a wait condition (passed to wait()/waitAny()) and as a target for
+ * element actions (passed to click(), fill(), …).
+ *
+ * Not every field is meaningful in every context:
+ *   - selector / jsExpression  → both wait and actions
+ *   - backendNodeId            → actions only (wait rejects it)
+ *   - visible / steadyMs       → wait only (silently ignored by actions)
+ *   - x / y                    → actions only (wait rejects it)
+ *   - frameId                  → both, may be overridden by call-level
+ *                                opts.inFrame
+ *
+ * Use the css() / js() / node() / at() constructors instead of building
+ * this class by hand.
+ *
+ * Modifiers (visible, steady, inFrame, inAllFrames) are immutable — they
+ * return a new Locator and leave the original untouched, so it's safe to
+ * share a base locator across calls.
+ */
+export declare class Locator {
+    readonly selector: string;
+    readonly jsExpression: string;
+    readonly backendNodeId: number;
+    readonly frameId: string;
+    readonly visibleFlag?: boolean;
+    readonly steadyMs?: number;
+    readonly x?: number;
+    readonly y?: number;
+    private constructor();
+    /** Internal — clone the locator with one or more fields overridden. */
+    private with;
+    /**
+     * Enforces or disables the visibility check for this Locator's wait
+     * condition.
+     *
+     * Pass `false` to opt out of the default `DefaultVisible` (true). Has
+     * no effect when used as an action target — actions never check
+     * visibility before dispatching.
+     *
+     * @param v - true to require visibility, false to skip the check
+     *
+     * @returns a new Locator with the override applied
+     *
+     * @example
+     * await browser.wait(css("#hidden").visible(false));
+     */
+    visible(v: boolean): Locator;
+    /**
+     * Requires the element to keep a stable position and size for at least
+     * `ms` milliseconds before the wait matches.
+     *
+     * Pass 0 to disable the default `DefaultSteadyMs` (500). Has no effect
+     * for js() expressions that return a non-Element value, nor when used
+     * as an action target.
+     *
+     * @param ms - steady-state duration in milliseconds; 0 disables
+     *
+     * @returns a new Locator with the override applied
+     *
+     * @example
+     * await browser.wait(css(".banner").steady(0));
+     */
+    steady(ms: number): Locator;
+    /**
+     * Scopes this Locator to a specific frameId.
+     *
+     * Use the frameId from a previous result or {@link CloudBrowser.getPages}
+     * to target elements inside a known iframe.
+     *
+     * @param frameId - id of the frame to scope to
+     *
+     * @returns a new Locator scoped to that frame
+     *
+     * @example
+     * const pages = await browser.getPages();
+     * const iframeId = pages[0].frameTree.children[0].frameId;
+     * await browser.click(css("button").inFrame(iframeId));
+     */
+    inFrame(frameId: string): Locator;
+    /**
+     * Scopes this Locator to every frame.
+     *
+     * Equivalent to `.inFrame(AllFrames)`. Use this when an element might
+     * appear inside any of several frames and you do not want to enumerate
+     * them.
+     *
+     * @returns a new Locator scoped to all frames
+     *
+     * @example
+     * await browser.wait(css("button.consent").inAllFrames());
+     */
+    inAllFrames(): Locator;
+    /** @internal — used by action methods to validate at send time. */
+    validateTarget(cmd: string, allowCoords: boolean): void;
+    /** @internal */
+    static _css(selector: string): Locator;
+    /** @internal */
+    static _js(expression: string): Locator;
+    /** @internal */
+    static _node(backendNodeId: number): Locator;
+    /** @internal */
+    static _at(x: number, y: number): Locator;
+}
+/**
+ * css waits for / targets an element matching the given CSS selector.
+ *
+ * When used in {@link CloudBrowser.wait}/{@link CloudBrowser.waitAny}, the
+ * returned Locator carries the SDK defaults `DefaultVisible` (true) and
+ * `DefaultSteadyMs` (500). Override per call with `.visible(false)` /
+ * `.steady(ms)` (use `.steady(0)` to disable the steady check).
+ *
+ * When used as an action target (click, fill, …) the visible/steady
+ * fields are ignored — there are no corresponding fields on the action
+ * requests.
+ *
+ * @param selector - CSS selector matching the element
+ *
+ * @returns Locator usable as a wait condition or as an action target
+ *
+ * @example
+ * // As a wait condition.
+ * await browser.wait(css("button.submit"));
+ * // As an action target.
+ * await browser.click(css("button.submit"));
+ */
+export declare function css(selector: string): Locator;
+/**
+ * js waits for / targets the result of a JavaScript expression.
+ *
+ * Same wait defaults as {@link css} (`DefaultVisible`=true,
+ * `DefaultSteadyMs`=500); these only apply when the expression returns a
+ * DOM Element. For non-Element truthy values (boolean, string, number,
+ * plain object) both fields are no-ops and the condition matches as soon
+ * as the value is truthy. Use `.visible(false)` / `.steady(0)` to opt out.
+ *
+ * @param expression - JavaScript expression evaluated in the target frame
+ *
+ * @returns Locator usable as a wait condition or as an action target
+ *
+ * @example
+ * await browser.wait(js("window.__ready === true"));
+ */
+export declare function js(expression: string): Locator;
+/**
+ * node targets an element by its DevTools backendNodeId.
+ *
+ * Use this when you already have a backendNodeId from a previous result
+ * (e.g. a wait or evaluate result) and want to act on the exact same
+ * element without re-resolving by selector. Action-only — using it in
+ * wait() throws at send time.
+ *
+ * @param backendNodeId - DevTools backendNodeId of the target element
+ *
+ * @returns Locator usable only as an action target
+ *
+ * @example
+ * const r = await browser.click(css("button.open"));
+ * await browser.click(node(r.backendNodeId));
+ */
+export declare function node(backendNodeId: number): Locator;
+/**
+ * at targets viewport coordinates instead of an element.
+ *
+ * Useful for clicking inside a canvas, hovering decorative regions, or
+ * dispatching events at synthetic positions. Action-only — using it in
+ * wait() throws at send time. Note that only click and moveTo accept at;
+ * scrollTo, drag, fill and select all require a real element.
+ *
+ * @param x - viewport-relative x in CSS pixels
+ * @param y - viewport-relative y in CSS pixels
+ *
+ * @returns Locator usable only as an action target
+ *
+ * @example
+ * // Click at canvas-relative coordinates.
+ * await browser.click(at(120, 240));
+ */
+export declare function at(x: number, y: number): Locator;
+/**
+ * @internal — returns the frame to send on the wire: opts.inFrame wins
+ * over the locator's own frameId. Empty everywhere → undefined (server
+ * uses main frame).
+ */
+export declare function pickFrame(optsFrame: string | undefined, locator: Locator): string | undefined;

package/dist/locator.js

@@ -0,0 +1,255 @@
+import { DefaultSteadyMs, DefaultVisible } from "./defaults.js";
+import { WRCError } from "./errors.js";
+/**
+ * AllFrames is the WRC.pdl sentinel for "match in every frame on the page".
+ * Use it for any field documented as accepting a frameId — both
+ * Locator.inFrame and *Opts.inFrame.
+ */
+export const AllFrames = "ALL_FRAMES";
+/**
+ * Locator is the universal "what element / what condition" type. It is used
+ * both as a wait condition (passed to wait()/waitAny()) and as a target for
+ * element actions (passed to click(), fill(), …).
+ *
+ * Not every field is meaningful in every context:
+ *   - selector / jsExpression  → both wait and actions
+ *   - backendNodeId            → actions only (wait rejects it)
+ *   - visible / steadyMs       → wait only (silently ignored by actions)
+ *   - x / y                    → actions only (wait rejects it)
+ *   - frameId                  → both, may be overridden by call-level
+ *                                opts.inFrame
+ *
+ * Use the css() / js() / node() / at() constructors instead of building
+ * this class by hand.
+ *
+ * Modifiers (visible, steady, inFrame, inAllFrames) are immutable — they
+ * return a new Locator and leave the original untouched, so it's safe to
+ * share a base locator across calls.
+ */
+export class Locator {
+    constructor(init) {
+        this.selector = "";
+        this.jsExpression = "";
+        this.backendNodeId = 0;
+        this.frameId = "";
+        Object.assign(this, init);
+    }
+    /** Internal — clone the locator with one or more fields overridden. */
+    with(patch) {
+        return new Locator({
+            selector: this.selector,
+            jsExpression: this.jsExpression,
+            backendNodeId: this.backendNodeId,
+            frameId: this.frameId,
+            visibleFlag: this.visibleFlag,
+            steadyMs: this.steadyMs,
+            x: this.x,
+            y: this.y,
+            ...patch,
+        });
+    }
+    // ── Modifiers (return new Locator) ──────────────────────────────────
+    /**
+     * Enforces or disables the visibility check for this Locator's wait
+     * condition.
+     *
+     * Pass `false` to opt out of the default `DefaultVisible` (true). Has
+     * no effect when used as an action target — actions never check
+     * visibility before dispatching.
+     *
+     * @param v - true to require visibility, false to skip the check
+     *
+     * @returns a new Locator with the override applied
+     *
+     * @example
+     * await browser.wait(css("#hidden").visible(false));
+     */
+    visible(v) {
+        return this.with({ visibleFlag: v });
+    }
+    /**
+     * Requires the element to keep a stable position and size for at least
+     * `ms` milliseconds before the wait matches.
+     *
+     * Pass 0 to disable the default `DefaultSteadyMs` (500). Has no effect
+     * for js() expressions that return a non-Element value, nor when used
+     * as an action target.
+     *
+     * @param ms - steady-state duration in milliseconds; 0 disables
+     *
+     * @returns a new Locator with the override applied
+     *
+     * @example
+     * await browser.wait(css(".banner").steady(0));
+     */
+    steady(ms) {
+        return this.with({ steadyMs: ms });
+    }
+    /**
+     * Scopes this Locator to a specific frameId.
+     *
+     * Use the frameId from a previous result or {@link CloudBrowser.getPages}
+     * to target elements inside a known iframe.
+     *
+     * @param frameId - id of the frame to scope to
+     *
+     * @returns a new Locator scoped to that frame
+     *
+     * @example
+     * const pages = await browser.getPages();
+     * const iframeId = pages[0].frameTree.children[0].frameId;
+     * await browser.click(css("button").inFrame(iframeId));
+     */
+    inFrame(frameId) {
+        return this.with({ frameId });
+    }
+    /**
+     * Scopes this Locator to every frame.
+     *
+     * Equivalent to `.inFrame(AllFrames)`. Use this when an element might
+     * appear inside any of several frames and you do not want to enumerate
+     * them.
+     *
+     * @returns a new Locator scoped to all frames
+     *
+     * @example
+     * await browser.wait(css("button.consent").inAllFrames());
+     */
+    inAllFrames() {
+        return this.with({ frameId: AllFrames });
+    }
+    /** @internal — used by action methods to validate at send time. */
+    validateTarget(cmd, allowCoords) {
+        const hasCoords = this.x !== undefined && this.y !== undefined;
+        const hasElement = this.selector !== "" || this.jsExpression !== "" || this.backendNodeId !== 0;
+        if (!hasElement && !hasCoords) {
+            throw new WRCError(`wrc.${cmd}: target must have selector, JS expression, backendNodeId, or at(x,y)`);
+        }
+        if (hasCoords && !allowCoords) {
+            throw new WRCError(`wrc.${cmd}: at(x,y) is not supported here — use an element locator`);
+        }
+    }
+    // ── Constructors (top-level functions re-export these) ──────────────
+    /** @internal */
+    static _css(selector) {
+        return new Locator({
+            selector,
+            visibleFlag: DefaultVisible,
+            steadyMs: DefaultSteadyMs,
+        });
+    }
+    /** @internal */
+    static _js(expression) {
+        return new Locator({
+            jsExpression: expression,
+            visibleFlag: DefaultVisible,
+            steadyMs: DefaultSteadyMs,
+        });
+    }
+    /** @internal */
+    static _node(backendNodeId) {
+        return new Locator({ backendNodeId });
+    }
+    /** @internal */
+    static _at(x, y) {
+        return new Locator({ x, y });
+    }
+}
+// ──────────────────────────────────────────────────────────────────────
+// Top-level constructors (preferred over Locator.* statics)
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * css waits for / targets an element matching the given CSS selector.
+ *
+ * When used in {@link CloudBrowser.wait}/{@link CloudBrowser.waitAny}, the
+ * returned Locator carries the SDK defaults `DefaultVisible` (true) and
+ * `DefaultSteadyMs` (500). Override per call with `.visible(false)` /
+ * `.steady(ms)` (use `.steady(0)` to disable the steady check).
+ *
+ * When used as an action target (click, fill, …) the visible/steady
+ * fields are ignored — there are no corresponding fields on the action
+ * requests.
+ *
+ * @param selector - CSS selector matching the element
+ *
+ * @returns Locator usable as a wait condition or as an action target
+ *
+ * @example
+ * // As a wait condition.
+ * await browser.wait(css("button.submit"));
+ * // As an action target.
+ * await browser.click(css("button.submit"));
+ */
+export function css(selector) {
+    return Locator._css(selector);
+}
+/**
+ * js waits for / targets the result of a JavaScript expression.
+ *
+ * Same wait defaults as {@link css} (`DefaultVisible`=true,
+ * `DefaultSteadyMs`=500); these only apply when the expression returns a
+ * DOM Element. For non-Element truthy values (boolean, string, number,
+ * plain object) both fields are no-ops and the condition matches as soon
+ * as the value is truthy. Use `.visible(false)` / `.steady(0)` to opt out.
+ *
+ * @param expression - JavaScript expression evaluated in the target frame
+ *
+ * @returns Locator usable as a wait condition or as an action target
+ *
+ * @example
+ * await browser.wait(js("window.__ready === true"));
+ */
+export function js(expression) {
+    return Locator._js(expression);
+}
+/**
+ * node targets an element by its DevTools backendNodeId.
+ *
+ * Use this when you already have a backendNodeId from a previous result
+ * (e.g. a wait or evaluate result) and want to act on the exact same
+ * element without re-resolving by selector. Action-only — using it in
+ * wait() throws at send time.
+ *
+ * @param backendNodeId - DevTools backendNodeId of the target element
+ *
+ * @returns Locator usable only as an action target
+ *
+ * @example
+ * const r = await browser.click(css("button.open"));
+ * await browser.click(node(r.backendNodeId));
+ */
+export function node(backendNodeId) {
+    return Locator._node(backendNodeId);
+}
+/**
+ * at targets viewport coordinates instead of an element.
+ *
+ * Useful for clicking inside a canvas, hovering decorative regions, or
+ * dispatching events at synthetic positions. Action-only — using it in
+ * wait() throws at send time. Note that only click and moveTo accept at;
+ * scrollTo, drag, fill and select all require a real element.
+ *
+ * @param x - viewport-relative x in CSS pixels
+ * @param y - viewport-relative y in CSS pixels
+ *
+ * @returns Locator usable only as an action target
+ *
+ * @example
+ * // Click at canvas-relative coordinates.
+ * await browser.click(at(120, 240));
+ */
+export function at(x, y) {
+    return Locator._at(x, y);
+}
+/**
+ * @internal — returns the frame to send on the wire: opts.inFrame wins
+ * over the locator's own frameId. Empty everywhere → undefined (server
+ * uses main frame).
+ */
+export function pickFrame(optsFrame, locator) {
+    if (optsFrame)
+        return optsFrame;
+    if (locator.frameId)
+        return locator.frameId;
+    return undefined;
+}