@melra/browser-runtime 0.3.0-alpha.10

package/dist/index.d.ts

@@ -0,0 +1,169 @@
+import type { BrowserOperation } from "@melra/protocol";
+import { type NetworkPolicy } from "./network-policy.js";
+export interface BrowserRuntimeOptions extends NetworkPolicy {
+    artifactDirectory: string;
+    workspaceRoot: string;
+    executablePath?: string;
+    headless?: boolean;
+    cdpEndpoint?: string;
+    cdpContextIndex?: number;
+    recordHarPath?: string;
+    /**
+     * HTTP archive every request is answered from, instead of the network.
+     *
+     * A request the archive does not hold is aborted rather than fetched: a
+     * replay that quietly reaches the live web is not a replay, and the whole
+     * point is that the same task run twice sees the same bytes. Nothing leaves
+     * the machine while this is set, so the destination checks below never come
+     * up — a recording made against an allowed host stays replayable after the
+     * host is removed from the allowlist, because the host is no longer involved.
+     */
+    replayHarPath?: string;
+    /**
+     * Directory holding cookies, storage, and profile state between runs.
+     *
+     * Absent means a fresh throwaway profile per run, which is the safe default
+     * and also why a logged-in site had to be logged into again on every task.
+     */
+    userDataDir?: string;
+    /**
+     * What to do with a window the page opens itself.
+     *
+     * `"block"` closes it and reports it, which is the honest default for an
+     * unattended agent: a popup that steals focus is a page deciding what the
+     * caller looks at next. `"allow"` keeps it as an addressable tab.
+     */
+    popups?: "allow" | "block";
+}
+/**
+ * Name any human-verification widget embedded in the page.
+ *
+ * Returns nothing when the page is clear, so a normal snapshot is unchanged.
+ */
+export declare function captchaReport(frameUrls: string[]): Record<string, unknown>;
+export declare class BrowserRuntime {
+    private readonly options;
+    private browser;
+    private context;
+    private activePage;
+    private connection;
+    private proxy;
+    private routeHandler;
+    /**
+     * Dialogs raised by the action currently running, cleared by `execute`.
+     *
+     * One buffer on the runtime rather than one per page because the handler is
+     * registered on the context, and because operations execute one at a time —
+     * a task owns its runtime for the length of one action.
+     */
+    private dialogs;
+    /**
+     * Windows the page opened during the action currently running, same lifetime
+     * as `dialogs` and reported the same way.
+     */
+    private popups;
+    /** Pending closes of blocked popups, awaited before the action reports. */
+    private closing;
+    /** True only while `tab_new` is opening the tab the caller asked for. */
+    private openingTab;
+    constructor(options: BrowserRuntimeOptions);
+    private uploadPaths;
+    private ensureContext;
+    /**
+     * Opens a page MELRA asked for, not one the site opened by itself.
+     *
+     * The popup handler cannot tell the two apart — both arrive as a `page`
+     * event — so this flag is the difference, and it is held across exactly the
+     * await that emits the event.
+     */
+    private openPage;
+    private page;
+    /**
+     * The tab list, with the index each entry can be addressed by.
+     *
+     * Returned by every tab action rather than only by `tabs`, because opening,
+     * switching, and closing all renumber the list — a caller that had to issue a
+     * separate `tabs` call after each one would be acting on a stale index.
+     */
+    private describeTabs;
+    /**
+     * The frames a target may live in, main frame first.
+     *
+     * Consent banners, cookie walls, payment fields, and captcha widgets are
+     * almost always in an iframe, and `page.locator` only ever searched the main
+     * document — so the element an agent could plainly see in a screenshot was
+     * unaddressable, and the run died on an action timeout. Searching every frame
+     * with the main one first keeps precise callers unaffected and makes the
+     * embedded case work without a new field to pass.
+     *
+     * Ad and analytics pages can attach dozens of frames, so the list is bounded.
+     */
+    private frames;
+    /**
+     * Every way the caller gave us to find the element, in the order we trust
+     * them. Split out from `locator` because waiting and acting need the same
+     * list but disagree about what to do when nothing matches yet.
+     */
+    private candidates;
+    /**
+     * Resolve a target to a locator that actually matches something.
+     *
+     * Text matching used to be `exact: true` only, which fails on the whitespace,
+     * casing, and nested-markup differences that real pages are full of — a button
+     * rendered as `<button> Sign in </button>` never matched `"Sign in"`. Exact is
+     * still tried first so a precise caller keeps precise behaviour; the substring
+     * form is only consulted when exact found nothing.
+     *
+     * A target that matches nothing is reported as such instead of being handed to
+     * Playwright to fail as an opaque action timeout thirty seconds later.
+     */
+    private locator;
+    /**
+     * Wait for a target to reach a state, re-resolving it on every poll.
+     *
+     * Playwright's own `waitFor` is bound to one frame decided up front, which is
+     * exactly wrong here: the consent iframe or captcha widget being waited for
+     * usually does not exist yet when the wait starts. Re-reading `page.frames()`
+     * each round costs a poll interval of latency and covers the frame that
+     * appears halfway through.
+     *
+     * `visible` and `attached` are satisfied by any one candidate; `hidden` and
+     * `detached` must hold for all of them. Fanning out across frames makes that
+     * distinction load-bearing — most frames never contain the target, so "some
+     * candidate is absent" is true from the first poll and would report a banner
+     * as dismissed while it is still on screen.
+     */
+    private waitForTarget;
+    /**
+     * Type by pressing keys rather than by assigning the value.
+     *
+     * `.fill()` sets the field and fires a single `input` event. Anything that
+     * listens for keystrokes never sees the text: React inputs with key handlers,
+     * autocomplete dropdowns, comboboxes that filter as you type, and fields that
+     * enable a submit button only after a `keyup`. The old server used
+     * `page.type`, and losing that is most of why typing "stopped working".
+     * `.fill("")` is still how the field gets cleared, because it empties one
+     * reliably no matter what is in it.
+     */
+    private typeInto;
+    private snapshot;
+    /**
+     * Read one element rather than the whole page.
+     *
+     * The old server had `extract_text` and `extract_html`; both were dropped, so
+     * a caller wanting one table out of a large document had to take the entire
+     * page text and cut it up itself. `inspect` already accepts a target, so
+     * scoping it needs no new action.
+     */
+    private extract;
+    private settledSnapshot;
+    execute(operation: BrowserOperation): Promise<Record<string, unknown>>;
+    private run;
+    close(): Promise<void>;
+}
+export * from "./network-policy.js";
+export * from "./pinning-proxy.js";
+export * from "./selector.js";
+export * from "./stable-dom.js";
+export * from "./browser-connection.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,gBAAgB,EAAiB,MAAM,iBAAiB,CAAC;AAKvE,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,qBAAqB,CAAC;AAK7B,MAAM,WAAW,qBAAsB,SAAQ,aAAa;IAC1D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;CAC5B;AA6CD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiB1E;AAgGD,qBAAa,cAAc;IAyBb,OAAO,CAAC,QAAQ,CAAC,OAAO;IAxBpC,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,UAAU,CAAmB;IACrC,OAAO,CAAC,UAAU,CAAgC;IAClD,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,YAAY,CAAgD;IACpE;;;;;;OAMG;IACH,OAAO,CAAC,OAAO,CAAiC;IAChD;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAiC;IAC/C,2EAA2E;IAC3E,OAAO,CAAC,OAAO,CAA0B;IACzC,yEAAyE;IACzE,OAAO,CAAC,UAAU,CAAS;gBAEE,OAAO,EAAE,qBAAqB;YAE7C,WAAW;YA8BX,aAAa;IA0J3B;;;;;;OAMG;YACW,QAAQ;YASR,IAAI;IASlB;;;;;;OAMG;YACW,YAAY;IAa1B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,MAAM;IAId;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAwBlB;;;;;;;;;;;OAWG;YACW,OAAO;IAarB;;;;;;;;;;;;;;OAcG;YACW,aAAa;IAsC3B;;;;;;;;;;OAUG;YACW,QAAQ;YAeR,QAAQ;IAwCtB;;;;;;;OAOG;YACW,OAAO;YAqBP,eAAe;IAcvB,OAAO,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAuB9D,GAAG;IAsTX,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CA0B7B;AAED,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC"}