browxai 0.7.0

package/dist/page/actions-probe.d.ts

@@ -0,0 +1,32 @@
+import type { Locator, Page } from "playwright-core";
+import type { ElementProbe, HitPoint } from "./actionresult.js";
+import type { ActionTarget } from "./locator.js";
+export interface PreProbeData {
+    ownerLabel?: string;
+    ownerText?: string;
+    container?: {
+        kind: string;
+        rowKey?: string;
+        rowText?: string;
+    };
+}
+/**
+ * Capture the pre-action state of the owning control and the enclosing repeated
+ * container, so the post-action probe can emit `changed` flags without the
+ * caller re-snapshotting. Exported for unit tests; runs at the DOM level.
+ */
+export declare function preProbe(loc: Locator): Promise<PreProbeData>;
+/**
+ * Always read post-action DOM state so callers can confirm a write landed
+ * without a follow-up `snapshot`/`screenshot` round-trip. We deliberately do not
+ * echo back `valueRequested` as `value` — the probe reports what the DOM actually
+ * holds, not what the caller asked for. Exported for unit tests.
+ */
+export declare function probe(loc: Locator, target: ActionTarget, valueRequested?: string, pre?: PreProbeData): Promise<ElementProbe>;
+/** Coordinate-action evidence helper: read `document.elementFromPoint` at (x,y)
+ *  with role/text/ancestor context. Returns null when nothing's there. */
+export declare function captureHit(page: Page, x: number, y: number): Promise<HitPoint | null>;
+/** Best-effort identity for the active element so we can report whether focus
+ *  shifted during a coord action. Returns a stable-ish key (tag + id + role +
+ *  testid + first text). */
+export declare function captureFocusedRef(page: Page): Promise<string | null>;

package/dist/page/actions-probe.js

@@ -0,0 +1,294 @@
+// Post-action element probing — `preProbe` / `probe` capture the DOM state of
+// the targeted element (and its owning control / repeated container) before and
+// after an action, plus the coord-action evidence helpers `captureHit` /
+// `captureFocusedRef`. Split out of actions.ts so that file stays under the size
+// budget; behavior-identical to the prior inline form.
+//
+// These functions are stringified and executed in the browser, where TS's DOM
+// lib is intentionally NOT in scope (tsconfig `lib: ["ES2022"]`). Rather than
+// fall back to `any`, the precise structural shape each in-page script touches is
+// described and `unknown` runtime values are narrowed into it via real
+// `typeof`/`in` guards. Behaviour is unchanged — these types are erased.
+// Post-action probe runs MULTIPLE `loc.evaluate()` calls — each defaults to
+// Playwright's 30s timeout. On busy SPAs where re-renders re-attach the element
+// handle constantly, a probe evaluate can hang far longer than makes sense for a
+// read-only check. Bound each evaluate to PROBE_EVAL_MS so a stuck probe returns
+// partial data instead of consuming the whole action deadline.
+const PROBE_EVAL_MS = 1500;
+/** In-page: post-action checkbox/radio checked state (or "mixed"). */
+const checkedScript = (el) => {
+    const tag = el.tagName?.toLowerCase();
+    const type = el.type?.toLowerCase();
+    if (tag !== "input" || (type !== "checkbox" && type !== "radio"))
+        return undefined;
+    if (el.indeterminate)
+        return "mixed";
+    return el.checked === true;
+};
+/** In-page: visible-wrapper text for controls that render state outside
+ *  `input.value` (chip selects, combobox displays, badge pickers). Walks up to 4
+ *  ancestors for a labelled node (role attr or `data-testid|test|cy|qa`); falls
+ *  back to the immediate parent's innerText. Capped at 200 chars. */
+const displayTextScript = (el) => {
+    const DOC_BODY_TAG = "BODY";
+    const isElement = (n) => !!n && typeof n === "object";
+    const isLabelled = (e) => {
+        const role = e.getAttribute?.("role") || null;
+        const ds = e.dataset || {};
+        return !!(role || ds.testid || ds.test || ds.cy || ds.qa);
+    };
+    const cappedText = (e) => {
+        const t = (e.innerText || "").trim();
+        return t ? t.slice(0, 200) : null;
+    };
+    let cur = isElement(el) ? el : null;
+    for (let i = 0; i < 4 && cur; i++) {
+        const next = cur.parentElement;
+        if (!isElement(next) || next.tagName === DOC_BODY_TAG)
+            break;
+        cur = next;
+        if (isLabelled(cur))
+            return cappedText(cur);
+    }
+    if (isElement(el) && isElement(el.parentElement))
+        return cappedText(el.parentElement);
+    return null;
+};
+/**
+ * Capture the pre-action state of the owning control and the enclosing repeated
+ * container, so the post-action probe can emit `changed` flags without the
+ * caller re-snapshotting. Exported for unit tests; runs at the DOM level.
+ */
+export async function preProbe(loc) {
+    // Same 1.5s bound as `probe` — see PROBE_EVAL_MS rationale.
+    try {
+        const count = await loc.count();
+        if (count === 0)
+            return {};
+        return await loc.evaluate(probeAncestorsScript, undefined, { timeout: 1500 }).catch(() => ({}));
+    }
+    catch {
+        return {};
+    }
+}
+/** Read the post-action value (input.value / contenteditable text / null). */
+async function readProbeValue(loc) {
+    const inputValue = await loc.inputValue({ timeout: PROBE_EVAL_MS }).catch(() => undefined);
+    if (inputValue !== undefined)
+        return inputValue;
+    return loc
+        .evaluate((el) => el.isContentEditable ? (el.textContent ?? "") : null, undefined, { timeout: PROBE_EVAL_MS })
+        .catch(() => null);
+}
+/** Fold the post-action owner/container ancestor state into the probe, composing
+ *  `changed` deltas against the pre-action snapshot when one was supplied. */
+function applyAncestorState(out, pre, post) {
+    if (pre && (pre.ownerText !== undefined || post.ownerText !== undefined)) {
+        const before = pre.ownerText;
+        const after = post.ownerText;
+        const oc = { changed: before !== after };
+        if (post.ownerLabel ?? pre.ownerLabel)
+            oc.label = post.ownerLabel ?? pre.ownerLabel;
+        if (before !== undefined)
+            oc.displayTextBefore = before;
+        if (after !== undefined)
+            oc.displayTextAfter = after;
+        out.ownerControl = oc;
+    }
+    if (post.container) {
+        const cont = {
+            kind: post.container.kind,
+            ...(post.container.rowKey ? { rowKey: post.container.rowKey } : {}),
+            ...(post.container.rowText !== undefined ? { rowText: post.container.rowText } : {}),
+        };
+        if (pre?.container)
+            cont.changed = pre.container.rowText !== post.container.rowText;
+        out.container = cont;
+    }
+}
+/**
+ * Always read post-action DOM state so callers can confirm a write landed
+ * without a follow-up `snapshot`/`screenshot` round-trip. We deliberately do not
+ * echo back `valueRequested` as `value` — the probe reports what the DOM actually
+ * holds, not what the caller asked for. Exported for unit tests.
+ */
+export async function probe(loc, target, valueRequested, pre) {
+    const ref = target.ref;
+    try {
+        const count = await loc.count();
+        if (count === 0)
+            return { ref, stillAttached: false };
+        const focused = await loc
+            .evaluate((el) => el === el.ownerDocument?.activeElement, undefined, { timeout: PROBE_EVAL_MS })
+            .catch(() => false);
+        const value = await readProbeValue(loc);
+        const checked = await loc
+            .evaluate(checkedScript, undefined, { timeout: PROBE_EVAL_MS })
+            .catch(() => undefined);
+        const displayText = await loc
+            .evaluate(displayTextScript, undefined, { timeout: PROBE_EVAL_MS })
+            .catch(() => null);
+        const out = { ref, stillAttached: true, focused, value: value ?? null };
+        if (checked !== undefined)
+            out.checked = checked;
+        if (valueRequested !== undefined)
+            out.valueRequested = valueRequested;
+        if (displayText !== null)
+            out.displayText = displayText;
+        // post-action owner/container state. Always read; compose deltas against
+        // `pre` when supplied. Same in-page script as preProbe, so directly comparable.
+        const post = await loc
+            .evaluate(probeAncestorsScript, undefined, { timeout: PROBE_EVAL_MS })
+            .catch(() => ({}));
+        applyAncestorState(out, pre, post);
+        return out;
+    }
+    catch {
+        return { ref, stillAttached: false };
+    }
+}
+const OWNER_ROLES = new Set(["combobox", "listbox", "radiogroup", "group", "menu", "tablist"]);
+const ROW_ROLES = new Set(["row", "listitem", "article"]);
+const ROW_TAGS = new Set(["tr", "li"]);
+/**
+ * In-page script used by `preProbe` and the post-action half of `probe`. Walks up
+ * the target's ancestor chain for the nearest owning form control (combobox /
+ * listbox / radiogroup / labelled `data-test*` wrapper) and the nearest repeated
+ * container (`role=row`/`listitem`/`article`, or `<tr>`/`<li>`). Capped at 6
+ * ancestor steps and 200 chars per text field. Returns {} when nothing matches.
+ *
+ * Defined as a plain function (not an arrow) so Playwright can stringify it
+ * across the CDP boundary cleanly. `el` is typed `unknown` and narrowed to the
+ * precise structural `AncestorEl` shape — the leading runtime check makes the
+ * narrowing sound. The per-concern matchers are nested so the whole thing stays
+ * one self-contained serializable literal.
+ */
+const probeAncestorsScript = function probeAncestors(el) {
+    if (!el || typeof el !== "object")
+        return {};
+    function attr(cur, name) {
+        return cur.getAttribute ? cur.getAttribute(name) : null;
+    }
+    function isFieldOwner(cur, role, ariaLabel) {
+        const ds = cur.dataset || {};
+        const hasTestAttr = !!(ds.testid || ds.test || ds.cy || ds.qa);
+        if (role && OWNER_ROLES.has(role))
+            return true;
+        return hasTestAttr && !!(role || ariaLabel);
+    }
+    function matchOwner(cur) {
+        const role = attr(cur, "role");
+        const ariaLabel = attr(cur, "aria-label");
+        if (!isFieldOwner(cur, role, ariaLabel))
+            return null;
+        const txt = (cur.innerText || "").trim();
+        const res = {};
+        if (txt)
+            res.ownerText = txt.length > 200 ? txt.slice(0, 199) + "…" : txt;
+        if (ariaLabel)
+            res.ownerLabel = ariaLabel;
+        return res;
+    }
+    function matchContainer(cur) {
+        const role = cur.getAttribute ? cur.getAttribute("role") : null;
+        const tag = cur.tagName ? cur.tagName.toLowerCase() : "";
+        if (!((role && ROW_ROLES.has(role)) || ROW_TAGS.has(tag)))
+            return null;
+        const kind = role && ROW_ROLES.has(role) ? role : tag;
+        const rowText = (cur.innerText || "").trim().replace(/\s+/g, " ");
+        const capped = rowText.length > 200 ? rowText.slice(0, 199) + "…" : rowText;
+        const firstText = (cur.innerText || "")
+            .trim()
+            .split("\n")
+            .find((s) => s.trim().length > 0);
+        const out = { kind };
+        if (firstText) {
+            const t = firstText.trim();
+            out.rowKey = t.length > 80 ? t.slice(0, 79) + "…" : t;
+        }
+        if (capped)
+            out.rowText = capped;
+        return out;
+    }
+    const out = {};
+    let cur = el.parentElement;
+    for (let i = 0; i < 6 && cur && cur.tagName !== "BODY" && cur.tagName !== "HTML"; i++) {
+        if (!out.ownerText) {
+            const owner = matchOwner(cur);
+            if (owner) {
+                if (owner.ownerText)
+                    out.ownerText = owner.ownerText;
+                if (owner.ownerLabel)
+                    out.ownerLabel = owner.ownerLabel;
+            }
+        }
+        if (!out.container) {
+            const container = matchContainer(cur);
+            if (container)
+                out.container = container;
+        }
+        if (out.ownerText && out.container)
+            break;
+        cur = cur.parentElement;
+    }
+    return out;
+};
+/** Coordinate-action evidence helper: read `document.elementFromPoint` at (x,y)
+ *  with role/text/ancestor context. Returns null when nothing's there. */
+export async function captureHit(page, x, y) {
+    return page
+        .evaluate(({ x, y }) => {
+        const g = globalThis;
+        const doc = g.document;
+        if (!doc)
+            return null;
+        const el = doc.elementFromPoint(x, y);
+        if (!el)
+            return null;
+        const tag = (el.tagName || "").toLowerCase();
+        const role = el.getAttribute
+            ? el.getAttribute("role") || undefined
+            : undefined;
+        const text = (el.textContent || "").trim().replace(/\s+/g, " ").slice(0, 120);
+        const parent = el.parentElement;
+        const ancestorText = parent
+            ? (parent.innerText || "").trim().replace(/\s+/g, " ").slice(0, 200)
+            : undefined;
+        const out = { tag };
+        if (role)
+            out.role = role;
+        if (text)
+            out.text = text;
+        if (ancestorText)
+            out.ancestorText = ancestorText;
+        return out;
+    }, { x, y })
+        .catch(() => null);
+}
+/** Best-effort identity for the active element so we can report whether focus
+ *  shifted during a coord action. Returns a stable-ish key (tag + id + role +
+ *  testid + first text). */
+export async function captureFocusedRef(page) {
+    return page
+        .evaluate(() => {
+        const g = globalThis;
+        const doc = g.document;
+        if (!doc)
+            return null;
+        const a = doc.activeElement;
+        if (!a)
+            return null;
+        const id = a.id || "";
+        const role = a.getAttribute ? a.getAttribute("role") || "" : "";
+        const testid = a.getAttribute
+            ? a.getAttribute("data-testid") ||
+                a.getAttribute("data-test") ||
+                a.getAttribute("data-cy") ||
+                ""
+            : "";
+        const tag = (a.tagName || "").toLowerCase();
+        const txt = (a.textContent || "").trim().slice(0, 60);
+        return `${tag}#${id}@${role}[${testid}]:${txt}`;
+    })
+        .catch(() => null);
+}

package/dist/page/actions-scroll.d.ts

@@ -0,0 +1,40 @@
+import type { Locator, Page } from "playwright-core";
+import type { ElementProbe } from "./actionresult.js";
+/** Minimal structural view of an element exposing scroll geometry/mutators. */
+export interface ScrollContainerEl {
+    scrollTop: number;
+    scrollLeft: number;
+    readonly scrollHeight: number;
+    readonly scrollWidth: number;
+    readonly clientHeight: number;
+    readonly clientWidth: number;
+    scrollBy: (x: number, y: number) => void;
+}
+/** Minimal structural view of the scrolling element read by the geometry probes. */
+export interface ScrollingEl {
+    readonly scrollTop: number;
+    readonly scrollLeft: number;
+    readonly scrollHeight: number;
+    readonly scrollWidth: number;
+    readonly clientHeight: number;
+    readonly clientWidth: number;
+}
+/** Minimal structural view of `document` as used by the scroll geometry scripts. */
+interface DocumentLike {
+    readonly documentElement?: ScrollingEl;
+    readonly scrollingElement?: ScrollingEl | null;
+}
+/** Minimal structural view of `window`/`globalThis` as used by the scroll script. */
+export interface WindowLike {
+    readonly document?: DocumentLike;
+    readonly scrollX: number;
+    readonly scrollY: number;
+    scrollTo: (x: number, y: number) => void;
+    scrollBy: (x: number, y: number) => void;
+}
+export type ScrollGeometry = NonNullable<ElementProbe["scroll"]>;
+/** Post-scroll geometry of the document/window scroller. */
+export declare function windowScrollGeometry(page: Page): Promise<ScrollGeometry | undefined>;
+/** Post-scroll geometry of a scroll-container element. */
+export declare function elementScrollGeometry(loc: Locator): Promise<ScrollGeometry | undefined>;
+export {};

package/dist/page/actions-scroll.js

@@ -0,0 +1,53 @@
+// Scroll geometry helpers for the `scroll` action — post-scroll geometry of the
+// window/document scroller and of a scroll-container element. Split out of
+// actions.ts so that file stays under the size budget; behavior-identical.
+//
+// These scripts run in the browser where TS's DOM lib is intentionally NOT in
+// scope, so the structural shape each one touches is described precisely and
+// `unknown` runtime values are narrowed via real guards.
+/** Post-scroll geometry of the document/window scroller. */
+export async function windowScrollGeometry(page) {
+    return page
+        .evaluate(() => {
+        const g = globalThis;
+        const w = g;
+        const d = w.document;
+        const s = d?.scrollingElement || d?.documentElement;
+        if (!s)
+            return undefined;
+        const x = w.scrollX ?? s.scrollLeft ?? 0;
+        const y = w.scrollY ?? s.scrollTop ?? 0;
+        return {
+            x,
+            y,
+            scrollWidth: s.scrollWidth,
+            scrollHeight: s.scrollHeight,
+            clientWidth: s.clientWidth,
+            clientHeight: s.clientHeight,
+            atTop: y <= 1,
+            atBottom: y + s.clientHeight >= s.scrollHeight - 1,
+        };
+    })
+        .catch(() => undefined);
+}
+/** Post-scroll geometry of a scroll-container element. */
+export async function elementScrollGeometry(loc) {
+    return loc
+        .evaluate((el) => {
+        const e = el;
+        if (!e)
+            return undefined;
+        const y = e.scrollTop ?? 0;
+        return {
+            x: e.scrollLeft ?? 0,
+            y,
+            scrollWidth: e.scrollWidth,
+            scrollHeight: e.scrollHeight,
+            clientWidth: e.clientWidth,
+            clientHeight: e.clientHeight,
+            atTop: y <= 1,
+            atBottom: y + e.clientHeight >= e.scrollHeight - 1,
+        };
+    })
+        .catch(() => undefined);
+}

package/dist/page/actions.d.ts

@@ -0,0 +1,132 @@
+import { type ActionContext, type ActionResult, type ActionWindowOptions, type ElementProbe } from "./actionresult.js";
+import { type ActionTarget } from "./locator.js";
+export interface ClickArgs extends ActionWindowOptions {
+    target: ActionTarget;
+    button?: "left" | "right" | "middle";
+    force?: boolean;
+}
+export declare function click(ctx: ActionContext, args: ClickArgs): Promise<ActionResult>;
+export interface FillArgs extends ActionWindowOptions {
+    target: ActionTarget;
+    value: string;
+}
+export declare function fill(ctx: ActionContext, args: FillArgs): Promise<ActionResult>;
+export interface NavigateArgs extends ActionWindowOptions {
+    url: string;
+}
+export declare function navigate(ctx: ActionContext, args: NavigateArgs): Promise<ActionResult>;
+export interface PressArgs extends ActionWindowOptions {
+    target?: ActionTarget;
+    key: string;
+}
+export declare function press(ctx: ActionContext, args: PressArgs): Promise<ActionResult>;
+export interface HoverArgs extends ActionWindowOptions {
+    target: ActionTarget;
+}
+export declare function hover(ctx: ActionContext, args: HoverArgs): Promise<ActionResult>;
+export interface SelectArgs extends ActionWindowOptions {
+    target: ActionTarget;
+    values: string[];
+}
+export declare function select(ctx: ActionContext, args: SelectArgs): Promise<ActionResult>;
+export interface WaitForArgs extends ActionWindowOptions {
+    /** Element-visibility wait (mutually exclusive with `text`). */
+    target?: ActionTarget;
+    /** SPA-readiness wait — poll until this visible text appears anywhere
+     *  in the page. The non-target gating mode real apps need after a reload /
+     *  nav. NO arbitrary-JS predicate mode by design — that stays `eval_js`'s
+     *  domain (the single `eval`-gated loophole). */
+    text?: string;
+    timeoutMs?: number;
+}
+export declare function waitFor(ctx: ActionContext, args: WaitForArgs): Promise<ActionResult>;
+export type ScrollEdge = "top" | "bottom" | "left" | "right";
+export interface ScrollArgs extends ActionWindowOptions {
+    /** What to scroll. Omitted → the page/window. A ref/selector/named element
+     *  is either scrolled *into view* (default) or scrolled *within* (when it's
+     *  a scroll container and `to`/`by` is given). A coords target does a wheel
+     *  scroll at that point (canvas / map panning). */
+    target?: ActionTarget;
+    /** Scroll to an edge of the page (or the targeted container). */
+    to?: ScrollEdge;
+    /** Wheel-style delta in CSS px. Positive y = down, positive x = right. */
+    by?: {
+        x?: number;
+        y?: number;
+    };
+    /** When `target` is an element: scroll it into view. Defaults to true when a
+     *  target is given and neither `to` nor `by` is set. */
+    intoView?: boolean;
+}
+export type ScrollMode = {
+    kind: "into-view";
+} | {
+    kind: "container";
+} | {
+    kind: "wheel-at";
+} | {
+    kind: "window";
+};
+/**
+ * Resolve which of the four scroll behaviours a `ScrollArgs` selects, or throw
+ * a clear error for a no-op call. Pure — exported for unit tests.
+ *
+ *   - target + (no to/by) | intoView:true  → scroll the element into view
+ *   - target + (to|by) + intoView:false    → scroll *within* the container
+ *   - coords target                        → wheel scroll at the point
+ *   - no target + (to|by)                  → window scroll
+ */
+export declare function scrollMode(args: ScrollArgs): ScrollMode;
+export declare function scroll(ctx: ActionContext, args: ScrollArgs): Promise<ActionResult>;
+export interface SetViewportArgs extends ActionWindowOptions {
+    width: number;
+    height: number;
+}
+/** mid-session viewport resize. `page.setViewportSize` re-lays-out and
+ *  often triggers responsive re-render / lazy-load — wrapped in the action
+ *  window so `structure` / `network` / `snapshotDelta` show what changed.
+ *  Device emulation (isMobile/touch/UA/DPR) is creation-time only; this only
+ *  changes the size. */
+export declare function setViewport(ctx: ActionContext, args: SetViewportArgs): Promise<ActionResult>;
+export interface ChooseOptionArgs extends ActionWindowOptions {
+    target: ActionTarget;
+    option: string;
+    exact?: boolean;
+}
+/**
+ * `choose_option` primitive. Generic combobox/listbox/menu selection
+ * for custom controls that aren't native `<select>` (so the existing `select`
+ * tool can't drive them). The pattern: open the target control, wait for a
+ * visible listbox/menu/portal, find the option element by exact text, click
+ * it, return the probe on the *trigger* so `ownerControl.displayText`
+ * shows the committed selection.
+ *
+ * Falls back across `role=option` → `role=menuitem` → `getByText` so works
+ * on any reasonable combobox shape. Does **not** simulate keyboard navigation
+ * (type-and-press-Enter) — that's a different primitive and prone to picking
+ * the wrong option in dense lists.
+ */
+export declare function chooseOption(ctx: ActionContext, args: ChooseOptionArgs): Promise<ActionResult>;
+export type GoBackArgs = ActionWindowOptions;
+export declare function goBack(ctx: ActionContext, args?: GoBackArgs): Promise<ActionResult>;
+export type GoForwardArgs = ActionWindowOptions;
+export declare function goForward(ctx: ActionContext, args?: GoForwardArgs): Promise<ActionResult>;
+/** Dispatch-side secret materialisation. Wraps `SecretRegistry.materialize`
+ *  with a no-registry fallback so non-secrets callers don't need to feature-
+ *  detect. Exported for composing primitives (e.g. multi-field fill). */
+export declare function materialiseValue(ctx: ActionContext, raw: string): {
+    ok: true;
+    value: string;
+    alias?: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** Post-probe defence-in-depth: mask any registered real-value that leaked
+ *  into the probe's `value` / `displayText` / `ownerControl` / `container`
+ *  string fields. The fill / press path is the canonical source of these
+ *  leaks — the field's DOM value reflects what we just typed.
+ *  Exported for composing primitives (e.g. multi-field fill). */
+export declare function maskProbe(probed: ElementProbe | void, ctx: ActionContext): ElementProbe | void;
+export type { PreProbeData } from "./actions-probe.js";
+export { preProbe, probe, captureHit, captureFocusedRef } from "./actions-probe.js";