browxai 0.7.0

package/dist/page/verify.js

@@ -0,0 +1,451 @@
+// `verify_*` assertive read primitives.
+//
+// `wait_for` is *permissive* — it returns when satisfied OR when its deadline
+// expires with `ok:false`. That leaves agents writing loops that can't
+// terminate deterministically. The verify family is the assertive sibling:
+// "this element MUST be visible / this text MUST appear / this value MUST
+// equal X right now — else fail loudly." A failed verify always emits a
+// structured `{source:"app", expected, actual}` failure, never a warning the
+// LLM has to eyeball.
+//
+// Each helper is pure plumbing — it resolves the target, reads the relevant
+// piece of state, and returns one of:
+//   { ok: true }
+//   { ok: false, failure: { source, kind, expected, actual, evidence? } }
+//
+// All five element-level helpers share the same ref-no-longer-found shape:
+// when the ref doesn't resolve in the current snapshot, they fail with
+// `source:"browxai"` so the agent can tell "the app's wrong" apart from
+// "the snapshot rolled and the ref evaporated."
+//
+// `verify_predicate` (the composed-data helper) delegates to the shared
+// predicate vocabulary in `src/util/predicates.ts` — same vocabulary that
+// underwrites `batch.expect`. It deliberately accepts NO arbitrary-JS
+// expression: the predicate `kind` is a fixed enum and the accessor `key` is
+// constrained to an allow-list of namespaced paths into a small data bag the
+// caller supplies. `eval_js` (gated behind the `eval` capability) is the only
+// arbitrary-JS escape hatch in browxai — the verify family does not add a
+// second one.
+import { composeSnapshot } from "./compose.js";
+import { findByRef } from "./snapshot.js";
+import { searchTreeForText } from "./text_search.js";
+import { walk } from "./a11y.js";
+import { visibleRect } from "./bbox.js";
+import { locatorFor } from "./locator.js";
+import { evaluatePredicate, validatePredicate, } from "../util/predicates.js";
+/** Resolve an `ActionTarget` to a Playwright Locator + the rich ref evidence,
+ *  failing-emitting (`source:"browxai"`) when a ref isn't in the registry. */
+function resolveOrFail(page, refs, target, kind, expected) {
+    if (target.coords) {
+        return {
+            ok: false,
+            failure: {
+                source: "browxai",
+                kind,
+                expected,
+                actual: "coords target",
+                evidence: { hint: "verify_* helpers don't accept coords targets — use ref/selector/named" },
+            },
+        };
+    }
+    if (target.ref) {
+        if (!refs.has(target.ref)) {
+            return {
+                ok: false,
+                failure: {
+                    source: "browxai",
+                    kind,
+                    expected,
+                    actual: "ref no longer in the snapshot",
+                    evidence: {
+                        ref: target.ref,
+                        hint: "call snapshot() or find() again — the page may have re-rendered",
+                    },
+                },
+            };
+        }
+    }
+    let loc;
+    try {
+        loc = locatorFor(page, refs, target);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            failure: {
+                source: "browxai",
+                kind,
+                expected,
+                actual: e instanceof Error ? e.message : String(e),
+            },
+        };
+    }
+    return { ok: true, loc, ...(target.ref ? { ref: target.ref } : {}) };
+}
+/** Verify that the targeted element is visible (non-zero box, not
+ *  display:none/visibility:hidden, opacity > 0). `source:"app"` on miss. */
+export async function verifyVisible(page, refs, target) {
+    const expected = "visible (non-zero box, displayed, opacity > 0)";
+    const resolved = resolveOrFail(page, refs, target, "visible", expected);
+    if (!resolved.ok)
+        return resolved;
+    const { loc } = resolved;
+    try {
+        const count = await loc.count();
+        if (count === 0) {
+            return {
+                ok: false,
+                failure: {
+                    source: "app",
+                    kind: "visible",
+                    expected,
+                    actual: "missing (locator matched 0 nodes)",
+                },
+            };
+        }
+        const isVisible = await loc.first().isVisible();
+        if (isVisible)
+            return { ok: true };
+        // Distinguish off-screen vs hidden where we can.
+        const reason = await probeNotVisibleReason(loc.first());
+        return {
+            ok: false,
+            failure: {
+                source: "app",
+                kind: "visible",
+                expected,
+                actual: reason,
+            },
+        };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            failure: {
+                source: "browxai",
+                kind: "visible",
+                expected,
+                actual: e instanceof Error ? e.message : String(e),
+            },
+        };
+    }
+}
+async function probeNotVisibleReason(loc) {
+    try {
+        return await loc
+            .evaluate((el) => {
+            const cs = window.getComputedStyle(el);
+            if (cs.display === "none")
+                return "hidden (display:none)";
+            if (cs.visibility === "hidden")
+                return "hidden (visibility:hidden)";
+            if (Number(cs.opacity || "1") === 0)
+                return "hidden (opacity:0)";
+            const r = el.getBoundingClientRect();
+            if (r.width === 0 || r.height === 0)
+                return "hidden (zero-sized box)";
+            return "off-screen or covered";
+        })
+            .catch(() => "hidden");
+    }
+    catch {
+        return "hidden";
+    }
+}
+/** Verify that the targeted element's visible text matches. `exact:true` →
+ *  case-sensitive equality on the trimmed innerText. Default → case-insensitive
+ *  substring. `source:"app"` on miss. */
+export async function verifyText(page, refs, target, text, exact) {
+    const expected = exact
+        ? `text === ${JSON.stringify(text)}`
+        : `text includes ${JSON.stringify(text)}`;
+    const resolved = resolveOrFail(page, refs, target, "text", expected);
+    if (!resolved.ok)
+        return resolved;
+    const { loc } = resolved;
+    try {
+        if ((await loc.count()) === 0) {
+            return {
+                ok: false,
+                failure: {
+                    source: "app",
+                    kind: "text",
+                    expected,
+                    actual: "missing (locator matched 0 nodes)",
+                },
+            };
+        }
+        const actualText = (await loc
+            .first()
+            .innerText()
+            .catch(() => null)) ?? "";
+        const trimmed = actualText.trim();
+        const hit = exact ? trimmed === text : trimmed.toLowerCase().includes(text.toLowerCase());
+        if (hit)
+            return { ok: true };
+        return {
+            ok: false,
+            failure: {
+                source: "app",
+                kind: "text",
+                expected,
+                actual: trimmed.slice(0, 200),
+                evidence: { exact, length: trimmed.length },
+            },
+        };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            failure: {
+                source: "browxai",
+                kind: "text",
+                expected,
+                actual: e instanceof Error ? e.message : String(e),
+            },
+        };
+    }
+}
+/** Verify that the targeted input/textarea/contenteditable carries the given
+ *  value (strict equality after a defensive `String()`). `source:"app"` on
+ *  miss. */
+export async function verifyValue(page, refs, target, value) {
+    const expected = `value === ${JSON.stringify(value)}`;
+    const resolved = resolveOrFail(page, refs, target, "value", expected);
+    if (!resolved.ok)
+        return resolved;
+    const { loc } = resolved;
+    try {
+        if ((await loc.count()) === 0) {
+            return {
+                ok: false,
+                failure: {
+                    source: "app",
+                    kind: "value",
+                    expected,
+                    actual: "missing (locator matched 0 nodes)",
+                },
+            };
+        }
+        const actual = await loc
+            .first()
+            .evaluate((el) => {
+            // Any element carrying a string `value` (input/textarea/select, but
+            // also output/button/etc.) reports it directly; a contenteditable host
+            // falls back to its rendered text. Structural checks mirror the DOM
+            // surface without assuming a single concrete element type.
+            const valued = el;
+            if (typeof valued.value === "string")
+                return valued.value;
+            if (el instanceof HTMLElement && el.isContentEditable)
+                return el.innerText ?? "";
+            return null;
+        })
+            .catch(() => null);
+        if (actual === null) {
+            return {
+                ok: false,
+                failure: {
+                    source: "app",
+                    kind: "value",
+                    expected,
+                    actual: "element has no `value` (not an input/textarea/select/contenteditable)",
+                },
+            };
+        }
+        if (String(actual) === value)
+            return { ok: true };
+        return {
+            ok: false,
+            failure: {
+                source: "app",
+                kind: "value",
+                expected,
+                actual: String(actual).slice(0, 200),
+            },
+        };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            failure: {
+                source: "browxai",
+                kind: "value",
+                expected,
+                actual: e instanceof Error ? e.message : String(e),
+            },
+        };
+    }
+}
+/** Verify that exactly `n` elements match the given selector (or visible-text
+ *  search). One of `selector` or `text` is required. `source:"app"` on miss. */
+export async function verifyCount(page, cdp, refs, opts) {
+    if (opts.selector && opts.text) {
+        return {
+            ok: false,
+            failure: {
+                source: "browxai",
+                kind: "count",
+                expected: `exactly one of selector / text`,
+                actual: "both selector and text supplied",
+            },
+        };
+    }
+    if (!opts.selector && !opts.text) {
+        return {
+            ok: false,
+            failure: {
+                source: "browxai",
+                kind: "count",
+                expected: `one of selector / text`,
+                actual: "neither selector nor text supplied",
+            },
+        };
+    }
+    const target = opts.selector ?? `text:${opts.text}`;
+    const expected = `count === ${opts.n} matching ${target}`;
+    try {
+        let actualCount;
+        if (opts.selector) {
+            actualCount = await page.locator(opts.selector).count();
+        }
+        else {
+            // Visible-text path: walk the composed a11y tree, count nodes whose
+            // trimmed name matches `text` case-insensitively (text_search-style).
+            const { tree } = await composeSnapshot(cdp, refs, opts.testAttributes);
+            if (!tree)
+                actualCount = 0;
+            else
+                actualCount = searchTreeForText(tree, opts.text, false, 1000).length;
+        }
+        if (actualCount === opts.n)
+            return { ok: true };
+        return {
+            ok: false,
+            failure: {
+                source: "app",
+                kind: "count",
+                expected,
+                actual: actualCount,
+                evidence: { matching: target },
+            },
+        };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            failure: {
+                source: "browxai",
+                kind: "count",
+                expected,
+                actual: e instanceof Error ? e.message : String(e),
+            },
+        };
+    }
+}
+/** Verify that the targeted element's `attr` attribute equals `value`. When
+ *  `value` is undefined, this asserts the attribute is present (any value).
+ *  `source:"app"` on miss. */
+export async function verifyAttribute(page, refs, target, attr, value) {
+    const expected = value === undefined
+        ? `attribute "${attr}" is present`
+        : `attribute "${attr}" === ${JSON.stringify(value)}`;
+    const resolved = resolveOrFail(page, refs, target, "attribute", expected);
+    if (!resolved.ok)
+        return resolved;
+    const { loc } = resolved;
+    try {
+        if ((await loc.count()) === 0) {
+            return {
+                ok: false,
+                failure: {
+                    source: "app",
+                    kind: "attribute",
+                    expected,
+                    actual: "missing (locator matched 0 nodes)",
+                },
+            };
+        }
+        const actual = await loc
+            .first()
+            .getAttribute(attr)
+            .catch(() => null);
+        if (value === undefined) {
+            if (actual !== null)
+                return { ok: true };
+            return {
+                ok: false,
+                failure: {
+                    source: "app",
+                    kind: "attribute",
+                    expected,
+                    actual: null,
+                    evidence: { attr },
+                },
+            };
+        }
+        if (actual === value)
+            return { ok: true };
+        return {
+            ok: false,
+            failure: {
+                source: "app",
+                kind: "attribute",
+                expected,
+                actual,
+                evidence: { attr },
+            },
+        };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            failure: {
+                source: "browxai",
+                kind: "attribute",
+                expected,
+                actual: e instanceof Error ? e.message : String(e),
+            },
+        };
+    }
+}
+/**
+ * Evaluate a fixed-vocabulary `Predicate` against caller-supplied data
+ * (typically an `ActionResult` + optional companion `snapshot` / `evidence`).
+ *
+ * NOT arbitrary JS: the engine accepts only `kind` values from the
+ * `Predicate` enum and `key` accessor strings starting with an allow-listed
+ * root segment. Adopters supply *data* (which key, which expected value);
+ * the *vocabulary* is owned server-side. See `src/util/predicates.ts`.
+ */
+export function verifyPredicate(predicate, data) {
+    const shapeError = validatePredicate(predicate);
+    if (shapeError) {
+        return {
+            ok: false,
+            failure: {
+                source: "browxai",
+                kind: "predicate-shape",
+                expected: "well-formed Predicate",
+                actual: shapeError,
+            },
+        };
+    }
+    const res = evaluatePredicate(predicate, data);
+    if (res.ok)
+        return { ok: true };
+    return {
+        ok: false,
+        failure: {
+            source: "app",
+            kind: res.kind,
+            expected: res.expected,
+            actual: res.actual,
+            ...(res.key !== undefined ? { evidence: { key: res.key } } : {}),
+        },
+    };
+}
+// Re-export the page/snapshot-walking helpers other call sites may want when
+// composing custom `verify_predicate` data bags. Keeps `verify.ts` the single
+// import surface for verify-family work.
+export { findByRef, walk, visibleRect };

package/dist/page/video.d.ts

@@ -0,0 +1,115 @@
+import type { Page } from "playwright-core";
+/** Maximum size (in bytes) at which a finalized video is returned inline as
+ *  base64 (`format:"bytes"`) rather than only by path. Conservative cap —
+ *  video bytes balloon fast; agents that hit it should rely on the path. */
+export declare const VIDEO_INLINE_CAP_BYTES: number;
+/** Per-session video recorder state. One per `SessionEntry`. */
+export interface VideoRecorderState {
+    /** True between session creation (with `recordVideo`) and `close_session`. */
+    active: boolean;
+    /** Workspace-absolute path the .webm will be written to on close. Reserved
+     *  at session creation; the user-facing deterministic name. */
+    targetPath?: string;
+    /** Staging directory passed to Playwright's `recordVideo.dir`. Playwright
+     *  auto-names a file inside this dir; we move/copy it to `targetPath` on
+     *  session close via `page.video().saveAs(targetPath)`. */
+    stagingDir?: string;
+    /** Recorded video size. */
+    size?: {
+        width: number;
+        height: number;
+    };
+    /** epoch ms the recorder was wired (context creation time). */
+    startedAt?: number;
+    /** True once the .webm has been saved to `targetPath` on disk (i.e.
+     *  `finalizeOnClose` has run). `get_video` checks this before reading. */
+    finalized: boolean;
+    /** True once `stop_video` has been called. The actual flush still happens
+     *  on `close_session` (Playwright constraint); this just records the
+     *  agent's intent so the result envelope can carry it. */
+    pendingFinalize: boolean;
+}
+export declare function newVideoRecorderState(): VideoRecorderState;
+/** Configuration accepted by `open_session({recordVideo})`. */
+export interface VideoStartConfig {
+    /** Workspace-rooted path. Optional — defaults to
+     *  `<workspace>/videos/<session-id>-<ISO>.webm` when omitted. Path traversal
+     *  outside the workspace is rejected. */
+    path?: string;
+    /** Recorded video size. Maps to Playwright's `recordVideo.size`. */
+    size?: {
+        width: number;
+        height: number;
+    };
+}
+/** Structured refusal — matches the shape `assertPdfSupported` returns so the
+ *  tool layer can wrap it uniformly. */
+export interface VideoRefusal {
+    error: string;
+    hint: string;
+}
+/** Refuse video on session modes Playwright's `recordVideo` doesn't support
+ *  cleanly. BYOB (`attached`) is the only refusal: we don't wire
+ *  context-creation primitives on the consumer's Chrome, mirroring the
+ *  `pdf_save` / `recordHar` posture. Managed `persistent` and `incognito`
+ *  sessions are both supported (headed and headless). */
+export declare function assertVideoSupported(ctx: {
+    mode: "persistent" | "incognito" | "attached";
+}): VideoRefusal | null;
+/** Default video filename for an auto-named recording. ISO timestamp with
+ *  `:` / `.` mapped to `-` so the name is filesystem-safe on every platform. */
+export declare function defaultVideoFilename(sessionId: string, now?: Date): string;
+/** Resolve an explicit user-supplied path (workspace-escape rejected) OR
+ *  build the default `<workspace>/videos/<auto>.webm` path. Creates the
+ *  parent dir on demand — still under the workspace root by construction. */
+export declare function resolveVideoTargetPath(workspaceRoot: string, sessionId: string, userPath: string | undefined, tool: string): string;
+/** Resolve + create the staging directory Playwright writes its auto-named
+ *  .webm into. One staging dir per session, under
+ *  `<workspace>/videos/.staging/<sessionId>-<ISO>/`. Workspace-rooted by
+ *  construction (resolveWorkspacePath rejects escape). */
+export declare function resolveVideoStagingDir(workspaceRoot: string, sessionId: string, now?: Date): string;
+/** Build the Playwright `recordVideo` option for `open_session({recordVideo})`.
+ *  The caller passes this into `browser.newContext({recordVideo})` /
+ *  `chromium.launchPersistentContext({recordVideo})`. Returns both the
+ *  Playwright-shaped option AND the resolved target path + staging dir so the
+ *  registry can persist them on `VideoRecorderState`. */
+export declare function buildRecordVideoOption(workspaceRoot: string, sessionId: string, cfg: VideoStartConfig): {
+    targetPath: string;
+    stagingDir: string;
+    size?: {
+        width: number;
+        height: number;
+    };
+    recordVideo: {
+        dir: string;
+        size?: {
+            width: number;
+            height: number;
+        };
+    };
+};
+/** Mark the recorder as `pendingFinalize` — the agent has signalled they
+ *  want the recording stopped. The actual flush happens on `close_session`
+ *  (Playwright finalizes the .webm only when the context closes). Mirrors
+ *  the `stop_har` shape for the `nativeRecord:true` posture. */
+export declare function stopVideo(state: VideoRecorderState): {
+    wasActive: boolean;
+    targetPath?: string;
+    pendingFinalize: boolean;
+    finalized: boolean;
+};
+/** Finalize the recording on session teardown. Calls `page.video().saveAs()`
+ *  with the deterministic target path — Playwright waits for the page to
+ *  close and the video to be fully written before resolving. Best-effort:
+ *  errors here MUST NOT block session teardown (mirrors the `perf` /
+ *  `artifacts` cleanup posture in the registry teardown). */
+export declare function finalizeVideoOnClose(page: Page, state: VideoRecorderState): Promise<void>;
+/** Read a finalized video file. `format: "bytes"` inlines as base64 when
+ *  under the cap; `format: "path"` (or over-cap) returns only the path. */
+export declare function readVideoIfReady(path: string, format?: "path" | "bytes", capBytes?: number): {
+    exists: boolean;
+    path: string;
+    bytes?: number;
+    inlineBase64?: string;
+    tooLargeToInline?: boolean;
+};