browxai 0.7.0

package/dist/page/generate-locator.d.ts

@@ -0,0 +1,57 @@
+import type { RefLocatorInputs } from "./refs.js";
+/** A `generate_locator` result, suitable for pasting into a `.spec.ts`. */
+export interface GeneratedLocator {
+    /** A Playwright locator expression — e.g. `page.getByRole('button', { name: 'Save' })`
+     *  or `page.getByTestId('save-btn')` or `page.locator('table > tbody > tr:nth-child(4)')`.
+     *  Always rooted on the bare identifier `page` so the adopter can rename
+     *  ergonomically (`const saveBtn = page.getByRole(...)`). */
+    playwright: string;
+    /** Per-tier stability label, same vocabulary `find()` already emits.
+     *   high   — testid OR role+name (uniquely identifies the element via a stable signal)
+     *   medium — stable text on a stable role OR stable structural path
+     *   low    — positional / role-only (likely to drift on the next render)
+     */
+    stability: "high" | "medium" | "low";
+    /** Structured breakdown of the parts the locator string is built from.
+     *  Adopters who want to compose their own locator (e.g. chain `.filter()`
+     *  or combine two kinds) can read this without re-parsing the string. */
+    components: GeneratedLocatorComponent[];
+}
+export interface GeneratedLocatorComponent {
+    kind: "testid" | "role" | "text" | "css";
+    value: string;
+    /** Present on `role` components when an accessible name disambiguated the role. */
+    name?: string;
+    /** Present on `testid` components when a non-default test-attribute name
+     *  drove the match (e.g. `data-cy`, `data-type`). */
+    attribute?: string;
+}
+/** Structured failure shape — ref-not-found returns this rather than throwing. */
+export interface GenerateLocatorFailure {
+    ok: false;
+    failure: {
+        kind: "ref-not-found";
+        ref: string;
+        hint: string;
+    };
+}
+export interface GenerateLocatorSuccess extends GeneratedLocator {
+    ok: true;
+}
+export type GenerateLocatorResult = GenerateLocatorSuccess | GenerateLocatorFailure;
+/**
+ * Build a Playwright-string locator + structured breakdown for a `RefLocatorInputs`.
+ *
+ * Priority (mirrors `locatorFromInputs` in `locator.ts`):
+ *   1. testId present                                        → getByTestId / [attr="…"]      (high)
+ *   2. DOM-only ref without testId, cssPath present          → locator(cssPath)              (medium / low)
+ *   3. role + accessible name                                → getByRole(role, { name })     (high)
+ *   4. cssPath fallback (e.g. `both` refs that lost the name)→ locator(cssPath)              (medium / low)
+ *   5. role only                                             → getByRole(role)               (low)
+ */
+export declare function generatePlaywrightLocator(inputs: RefLocatorInputs): GeneratedLocator;
+/** Top-level entry: look the ref up in a registry-shaped lookup and produce
+ *  either a structured success or a structured ref-not-found failure. The
+ *  generator is split from the registry lookup so unit tests can drive it
+ *  directly from `RefLocatorInputs`. */
+export declare function generateLocator(ref: string, lookup: (ref: string) => RefLocatorInputs | undefined): GenerateLocatorResult;

package/dist/page/generate-locator.js

@@ -0,0 +1,136 @@
+// generate_locator(ref) — adopter-facing bridge from a browxai-internal `eN` ref
+// to a *Playwright-string* locator expression an adopter can paste into a
+// `.spec.ts`.
+//
+// browxai's internal locator-resolution machinery (locator.ts) takes a
+// `RefLocatorInputs` record and produces a live Playwright `Locator` object on
+// the page. That's the right shape for *acting* in-process; it's the wrong
+// shape for the regression-suite handoff use case, where the adopter needs a
+// *string* they can transcribe verbatim into their own test file.
+//
+// This module mirrors the resolution priority in `locatorFromInputs` exactly
+// — testId → DOM cssPath (for DOM-only refs) → role+name → cssPath → role-only
+// — so the string we hand back lines up with the locator browxai itself would
+// resolve at action time. It also emits a structured `components` breakdown
+// (the parts that built the string) and a `stability` label derived from the
+// same tier system `find()` already uses.
+/**
+ * Build a Playwright-string locator + structured breakdown for a `RefLocatorInputs`.
+ *
+ * Priority (mirrors `locatorFromInputs` in `locator.ts`):
+ *   1. testId present                                        → getByTestId / [attr="…"]      (high)
+ *   2. DOM-only ref without testId, cssPath present          → locator(cssPath)              (medium / low)
+ *   3. role + accessible name                                → getByRole(role, { name })     (high)
+ *   4. cssPath fallback (e.g. `both` refs that lost the name)→ locator(cssPath)              (medium / low)
+ *   5. role only                                             → getByRole(role)               (low)
+ */
+export function generatePlaywrightLocator(inputs) {
+    // Tier 1: testId. Default `data-testid` lowers to `getByTestId` (Playwright's
+    // ergonomic helper); any other configured attribute lowers to the attribute
+    // CSS form so non-standard test attributes (`data-cy`, `data-type`) Just Work.
+    if (inputs.testId) {
+        const attr = inputs.testIdAttr ?? "data-testid";
+        if (attr === "data-testid") {
+            return {
+                playwright: `page.getByTestId(${jsStringLiteral(inputs.testId)})`,
+                stability: "high",
+                components: [{ kind: "testid", value: inputs.testId }],
+            };
+        }
+        const cssAttr = `[${attr}=${jsonAttrValue(inputs.testId)}]`;
+        return {
+            playwright: `page.locator(${jsStringLiteral(cssAttr)})`,
+            stability: "high",
+            components: [{ kind: "testid", value: inputs.testId, attribute: attr }],
+        };
+    }
+    // Tier 2: DOM-only refs (no a11y name available) — the structural path is
+    // the only signal we have. Stability is medium when the path looks stable
+    // (semantic anchors / id / data-attrs) and low when it's purely positional
+    // (`:nth-child` chains all the way down).
+    if (inputs.source === "dom" && inputs.cssPath) {
+        return cssPathLocator(inputs.cssPath);
+    }
+    // Tier 3: role + accessible name — strong when the a11y pass saw it.
+    // Stability "high": role+name is one of Playwright's most resilient signals
+    // (it survives DOM reshuffling as long as the control's accessible name
+    // doesn't change).
+    if (inputs.name) {
+        const role = inputs.role;
+        return {
+            playwright: `page.getByRole(${jsStringLiteral(role)}, { name: ${jsStringLiteral(inputs.name)} })`,
+            stability: "high",
+            components: [
+                { kind: "role", value: role, name: inputs.name },
+                { kind: "text", value: inputs.name },
+            ],
+        };
+    }
+    // Tier 4: cssPath fallback for `both` refs that the a11y pass saw without a
+    // name. Same stability heuristic as tier 2.
+    if (inputs.cssPath) {
+        return cssPathLocator(inputs.cssPath);
+    }
+    // Tier 5: role only. The agent saw `stability: "low"` from `find()` — same
+    // verdict here.
+    return {
+        playwright: `page.getByRole(${jsStringLiteral(inputs.role)})`,
+        stability: "low",
+        components: [{ kind: "role", value: inputs.role }],
+    };
+}
+/** Build a `page.locator(...)` for a structural CSS path, deriving stability
+ *  from whether the path is purely positional. A path that's entirely
+ *  `:nth-child(N)` segments under generic tags is `low`; a path with semantic
+ *  anchors, ids, or stable test attributes is `medium`. */
+function cssPathLocator(cssPath) {
+    return {
+        playwright: `page.locator(${jsStringLiteral(cssPath)})`,
+        stability: cssPathStability(cssPath),
+        components: [{ kind: "css", value: cssPath }],
+    };
+}
+/** A CSS path is "stable-structural" (medium) when it carries at least one
+ *  non-positional anchor — an `#id`, a `[data-*]`/`[aria-*]`/`[role=]` attribute
+ *  selector, or a semantic landmark tag (`main`, `nav`, `header`, `footer`,
+ *  `aside`, `form`, `section`, `article`). Otherwise it's purely positional
+ *  (chains of `:nth-child`/bare tags) and falls back to `low`. */
+function cssPathStability(cssPath) {
+    if (/#[A-Za-z]/.test(cssPath))
+        return "medium";
+    if (/\[(data-|aria-|role=|id=|name=)/.test(cssPath))
+        return "medium";
+    if (/\b(main|nav|header|footer|aside|form|section|article)\b/.test(cssPath))
+        return "medium";
+    return "low";
+}
+/** JS string literal — single-quoted, with backslash + single-quote escapes.
+ *  Matches Playwright's own examples (`page.getByRole('button', { name: 'Save' })`). */
+function jsStringLiteral(s) {
+    return `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+}
+/** CSS attribute-value JSON form — double-quoted, escapes only `\` and `"`.
+ *  Used inside a bigger JS string literal that we'll quote separately. */
+function jsonAttrValue(s) {
+    return JSON.stringify(s);
+}
+/** Top-level entry: look the ref up in a registry-shaped lookup and produce
+ *  either a structured success or a structured ref-not-found failure. The
+ *  generator is split from the registry lookup so unit tests can drive it
+ *  directly from `RefLocatorInputs`. */
+export function generateLocator(ref, lookup) {
+    const inputs = lookup(ref);
+    if (!inputs) {
+        return {
+            ok: false,
+            failure: {
+                kind: "ref-not-found",
+                ref,
+                hint: `ref "${ref}" is not in this session's registry. Call snapshot() or find() first ` +
+                    `to populate refs (refs survive across snapshots by stable element-key, but a fresh ` +
+                    `session starts empty).`,
+            },
+        };
+    }
+    return { ok: true, ...generatePlaywrightLocator(inputs) };
+}

package/dist/page/gestures.d.ts

@@ -0,0 +1,128 @@
+import type { CDPSession, Page } from "playwright-core";
+import type { RefRegistry } from "./refs.js";
+import { type ActionTarget } from "./locator.js";
+import { type PointProbeResult } from "./point_probe.js";
+export interface Point {
+    x: number;
+    y: number;
+}
+/** Resolve an action target to a viewport point — the element's box centre
+ *  for ref/selector, or the literal coords. */
+export declare function targetPoint(page: Page, refs: RefRegistry, t: ActionTarget): Promise<Point>;
+export interface DragResult {
+    ok: boolean;
+    from: Point;
+    to: Point;
+    steps: number;
+}
+export interface DragPreflight {
+    ok: boolean;
+    preflight: {
+        point: Point;
+        hit: PointProbeResult;
+        /** true when something under the press point looks like a resize handle
+         *  (a `*-resize` cursor) — dragging here is likely to resize, not move. */
+        resizeRisk: boolean;
+    };
+}
+/** Press at `from`, move to `to` over `steps` intermediate points, release.
+ *  With `preflight: true`, instead probe the `from` point and report what's
+ *  under it (top hit element + resize-handle risk) WITHOUT dragging — so the
+ *  agent can confirm the press lands on draggable content, not a resize
+ *  handle, before committing. Element targets resolve to the box centre. */
+export declare function drag(page: Page, refs: RefRegistry, args: {
+    from: ActionTarget;
+    to: ActionTarget;
+    steps?: number;
+    preflight?: boolean;
+}): Promise<DragResult | DragPreflight>;
+export interface DoubleClickResult {
+    ok: boolean;
+    point: Point;
+}
+export declare function doubleClick(page: Page, refs: RefRegistry, target: ActionTarget): Promise<DoubleClickResult>;
+/** Coordinate-space wheel event — for canvas / virtualised lists / map tiles
+ *  that listen for `wheel` and ignore Playwright's element-level scroll.
+ *  Dispatched via CDP `Input.dispatchMouseEvent` (`type: "mouseWheel"`) so the
+ *  event fires at `coords` regardless of the current pointer position, with
+ *  the caller's `deltaX`/`deltaY` (CSS px; positive Y scrolls content up,
+ *  matching the DOM `WheelEvent` convention). One of `deltaX`/`deltaY` must be
+ *  non-zero. */
+export declare function mouseWheel(cdp: CDPSession, args: {
+    coords: Point;
+    deltaX?: number;
+    deltaY?: number;
+}): Promise<{
+    ok: boolean;
+    coords: Point;
+    deltaX: number;
+    deltaY: number;
+}>;
+export type MouseAction = "down" | "move" | "up";
+/** Low-level mouse control for gestures the higher-level tools don't cover
+ *  (custom scrub/trim handles). `move` requires coords; `down`/`up` move
+ *  there first when coords are given, else act at the current position. */
+export declare function mouseAction(page: Page, action: MouseAction, coords?: Point): Promise<{
+    ok: boolean;
+    action: MouseAction;
+    coords?: Point;
+}>;
+export type TouchAction = "start" | "move" | "end";
+/** Dispatch a single touch event at `coords` via CDP. `identifier` tracks the
+ *  finger across a multi-touch sequence (default `1`). `touch_end` accepts
+ *  optional `coords`; when omitted CDP gets an empty `touchPoints[]` — the
+ *  spec's "all fingers up" form. */
+export declare function touchAction(cdp: CDPSession, action: TouchAction, args: {
+    coords?: Point;
+    identifier?: number;
+}): Promise<{
+    ok: boolean;
+    action: TouchAction;
+    coords?: Point;
+    identifier: number;
+}>;
+export interface GesturePinchResult {
+    ok: boolean;
+    coords: Point;
+    scale: number;
+    steps: number;
+    startOffset: number;
+    endOffset: number;
+}
+/** Two-finger pinch in/out, centred on `coords`. Two touch points start at
+ *  `coords ± startOffset` (a fixed 40 CSS px each side — wider than any
+ *  realistic finger pair but small enough to land inside a typical canvas) and
+ *  converge or diverge so the final separation = startOffset × scale.
+ *  `scale < 1` is pinch-in (zoom out); `scale > 1` is pinch-out (zoom in).
+ *  Linear interpolation across `steps` intermediate `touchMove` dispatches —
+ *  pinch handlers (Hammer.js, GoogleMaps, Figma) read the delta between
+ *  successive `changedTouches`, so a linear ramp is sufficient and avoids the
+ *  velocity-detection misfires a sinusoidal curve can trigger on fling-detect
+ *  libraries. */
+export declare function gesturePinch(cdp: CDPSession, args: {
+    coords: Point;
+    scale: number;
+    steps?: number;
+    startOffset?: number;
+}): Promise<GesturePinchResult>;
+export interface GestureSwipeResult {
+    ok: boolean;
+    from: Point;
+    to: Point;
+    steps: number;
+    durationMs: number;
+}
+/** Single-finger swipe from `from` to `to`. Distinct from `drag` — drag uses
+ *  the mouse pipeline; swipe uses the touch pipeline. `durationMs` controls
+ *  pacing (default 200 ms — fast flick; 500+ ms reads as a deliberate scroll).
+ *  Smoothed via an ease-out curve (`1 - (1-t)²`) — touch libraries derive
+ *  velocity from per-frame deltas; ease-out matches the natural deceleration
+ *  most fling-detect heuristics are tuned for (Hammer.js, native scroll
+ *  inertia, react-spring-style physics). */
+export declare function gestureSwipe(cdp: CDPSession, args: {
+    from: Point;
+    to: Point;
+    durationMs?: number;
+    steps?: number;
+    identifier?: number;
+}): Promise<GestureSwipeResult>;

package/dist/page/gestures.js

@@ -0,0 +1,198 @@
+// Pointer-gesture primitives — capability `action`.
+//
+// `click`/`hover` cover taps; media editors and drag-reorder UIs also need
+// drag, double-click, and raw mouse down/move/up.
+import { locatorFor } from "./locator.js";
+import { pointProbe } from "./point_probe.js";
+/** Resolve an action target to a viewport point — the element's box centre
+ *  for ref/selector, or the literal coords. */
+export async function targetPoint(page, refs, t) {
+    if (t.coords)
+        return { x: t.coords.x, y: t.coords.y };
+    const box = await locatorFor(page, refs, t).boundingBox();
+    if (!box || box.width <= 0 || box.height <= 0) {
+        throw new Error("drag/gesture target has no rendered box");
+    }
+    return { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+}
+const RESIZE_CURSOR = /resize/i;
+/** Press at `from`, move to `to` over `steps` intermediate points, release.
+ *  With `preflight: true`, instead probe the `from` point and report what's
+ *  under it (top hit element + resize-handle risk) WITHOUT dragging — so the
+ *  agent can confirm the press lands on draggable content, not a resize
+ *  handle, before committing. Element targets resolve to the box centre. */
+export async function drag(page, refs, args) {
+    const from = await targetPoint(page, refs, args.from);
+    if (args.preflight) {
+        const hit = await pointProbe(page, from);
+        const resizeRisk = hit.stack.some((el) => RESIZE_CURSOR.test(el.cursor || ""));
+        return { ok: true, preflight: { point: from, hit, resizeRisk } };
+    }
+    const steps = Math.min(Math.max(args.steps ?? 12, 1), 100);
+    const to = await targetPoint(page, refs, args.to);
+    await page.mouse.move(from.x, from.y);
+    await page.mouse.down();
+    await page.mouse.move(to.x, to.y, { steps });
+    await page.mouse.up();
+    return { ok: true, from, to, steps };
+}
+export async function doubleClick(page, refs, target) {
+    const point = await targetPoint(page, refs, target);
+    await page.mouse.dblclick(point.x, point.y);
+    return { ok: true, point };
+}
+/** Coordinate-space wheel event — for canvas / virtualised lists / map tiles
+ *  that listen for `wheel` and ignore Playwright's element-level scroll.
+ *  Dispatched via CDP `Input.dispatchMouseEvent` (`type: "mouseWheel"`) so the
+ *  event fires at `coords` regardless of the current pointer position, with
+ *  the caller's `deltaX`/`deltaY` (CSS px; positive Y scrolls content up,
+ *  matching the DOM `WheelEvent` convention). One of `deltaX`/`deltaY` must be
+ *  non-zero. */
+export async function mouseWheel(cdp, args) {
+    const deltaX = args.deltaX ?? 0;
+    const deltaY = args.deltaY ?? 0;
+    if (deltaX === 0 && deltaY === 0) {
+        throw new Error("mouse_wheel requires non-zero deltaX or deltaY");
+    }
+    await cdp.send("Input.dispatchMouseEvent", {
+        type: "mouseWheel",
+        x: args.coords.x,
+        y: args.coords.y,
+        deltaX,
+        deltaY,
+        button: "none",
+        pointerType: "mouse",
+    });
+    return { ok: true, coords: args.coords, deltaX, deltaY };
+}
+/** Low-level mouse control for gestures the higher-level tools don't cover
+ *  (custom scrub/trim handles). `move` requires coords; `down`/`up` move
+ *  there first when coords are given, else act at the current position. */
+export async function mouseAction(page, action, coords) {
+    if (action === "move") {
+        if (!coords)
+            throw new Error("mouse_move requires coords");
+        await page.mouse.move(coords.x, coords.y);
+    }
+    else {
+        if (coords)
+            await page.mouse.move(coords.x, coords.y);
+        if (action === "down")
+            await page.mouse.down();
+        else
+            await page.mouse.up();
+    }
+    return { ok: true, action, ...(coords ? { coords } : {}) };
+}
+const TOUCH_CDP_TYPE = {
+    start: "touchStart",
+    move: "touchMove",
+    end: "touchEnd",
+};
+/** Dispatch a single touch event at `coords` via CDP. `identifier` tracks the
+ *  finger across a multi-touch sequence (default `1`). `touch_end` accepts
+ *  optional `coords`; when omitted CDP gets an empty `touchPoints[]` — the
+ *  spec's "all fingers up" form. */
+export async function touchAction(cdp, action, args) {
+    const identifier = args.identifier ?? 1;
+    if (action !== "end" && !args.coords) {
+        throw new Error(`touch_${action} requires coords`);
+    }
+    const touchPoints = args.coords ? [{ x: args.coords.x, y: args.coords.y, id: identifier }] : [];
+    await cdp.send("Input.dispatchTouchEvent", {
+        type: TOUCH_CDP_TYPE[action],
+        touchPoints,
+    });
+    return {
+        ok: true,
+        action,
+        ...(args.coords ? { coords: args.coords } : {}),
+        identifier,
+    };
+}
+/** Two-finger pinch in/out, centred on `coords`. Two touch points start at
+ *  `coords ± startOffset` (a fixed 40 CSS px each side — wider than any
+ *  realistic finger pair but small enough to land inside a typical canvas) and
+ *  converge or diverge so the final separation = startOffset × scale.
+ *  `scale < 1` is pinch-in (zoom out); `scale > 1` is pinch-out (zoom in).
+ *  Linear interpolation across `steps` intermediate `touchMove` dispatches —
+ *  pinch handlers (Hammer.js, GoogleMaps, Figma) read the delta between
+ *  successive `changedTouches`, so a linear ramp is sufficient and avoids the
+ *  velocity-detection misfires a sinusoidal curve can trigger on fling-detect
+ *  libraries. */
+export async function gesturePinch(cdp, args) {
+    const scale = args.scale;
+    if (!Number.isFinite(scale) || scale <= 0) {
+        throw new Error("gesture_pinch requires a positive finite scale");
+    }
+    const steps = Math.min(Math.max(args.steps ?? 12, 1), 100);
+    const startOffset = args.startOffset ?? 40;
+    const endOffset = startOffset * scale;
+    const cx = args.coords.x;
+    const cy = args.coords.y;
+    const id1 = 1;
+    const id2 = 2;
+    // touchStart with both fingers
+    await cdp.send("Input.dispatchTouchEvent", {
+        type: "touchStart",
+        touchPoints: [
+            { x: cx - startOffset, y: cy, id: id1 },
+            { x: cx + startOffset, y: cy, id: id2 },
+        ],
+    });
+    for (let i = 1; i <= steps; i++) {
+        const t = i / steps;
+        const offset = startOffset + (endOffset - startOffset) * t;
+        await cdp.send("Input.dispatchTouchEvent", {
+            type: "touchMove",
+            touchPoints: [
+                { x: cx - offset, y: cy, id: id1 },
+                { x: cx + offset, y: cy, id: id2 },
+            ],
+        });
+    }
+    // touchEnd lifts all fingers (empty touchPoints[])
+    await cdp.send("Input.dispatchTouchEvent", {
+        type: "touchEnd",
+        touchPoints: [],
+    });
+    return { ok: true, coords: args.coords, scale, steps, startOffset, endOffset };
+}
+/** Single-finger swipe from `from` to `to`. Distinct from `drag` — drag uses
+ *  the mouse pipeline; swipe uses the touch pipeline. `durationMs` controls
+ *  pacing (default 200 ms — fast flick; 500+ ms reads as a deliberate scroll).
+ *  Smoothed via an ease-out curve (`1 - (1-t)²`) — touch libraries derive
+ *  velocity from per-frame deltas; ease-out matches the natural deceleration
+ *  most fling-detect heuristics are tuned for (Hammer.js, native scroll
+ *  inertia, react-spring-style physics). */
+export async function gestureSwipe(cdp, args) {
+    const identifier = args.identifier ?? 1;
+    const durationMs = Math.min(Math.max(args.durationMs ?? 200, 0), 60_000);
+    const steps = Math.min(Math.max(args.steps ?? 16, 1), 200);
+    await cdp.send("Input.dispatchTouchEvent", {
+        type: "touchStart",
+        touchPoints: [{ x: args.from.x, y: args.from.y, id: identifier }],
+    });
+    const dx = args.to.x - args.from.x;
+    const dy = args.to.y - args.from.y;
+    const perStepDelay = durationMs / steps;
+    for (let i = 1; i <= steps; i++) {
+        const t = i / steps;
+        // ease-out: 1 - (1 - t)^2 — fast start, gentle settle
+        const eased = 1 - (1 - t) * (1 - t);
+        const x = args.from.x + dx * eased;
+        const y = args.from.y + dy * eased;
+        await cdp.send("Input.dispatchTouchEvent", {
+            type: "touchMove",
+            touchPoints: [{ x, y, id: identifier }],
+        });
+        if (perStepDelay > 0) {
+            await new Promise((resolve) => setTimeout(resolve, perStepDelay));
+        }
+    }
+    await cdp.send("Input.dispatchTouchEvent", {
+        type: "touchEnd",
+        touchPoints: [],
+    });
+    return { ok: true, from: args.from, to: args.to, steps, durationMs };
+}

package/dist/page/har.d.ts

@@ -0,0 +1,91 @@
+import type { BrowserContext } from "playwright-core";
+/** Maximum size (in bytes) at which a finalized HAR is returned inline rather
+ *  than only by path. Mirrors the same cap used by `network_body` / storage
+ *  dumps — agents that hit it should rely on the path field instead. */
+export declare const HAR_INLINE_CAP_BYTES: number;
+/** Per-session HAR recorder state. One per `SessionEntry`. */
+export interface HarRecorderState {
+    /** True between a successful `start_har` (or `open_session({har})`) and the
+     *  next `stop_har` / session close. */
+    active: boolean;
+    /** Workspace-absolute path the HAR is being written to. Reserved at start. */
+    path?: string;
+    /** epoch ms the recorder was started. */
+    startedAt?: number;
+    /** Capture mode (full vs minimal). Same semantics as Playwright. */
+    mode?: "full" | "minimal";
+    /** Content policy — `embed` inlines bodies (default for `.har`), `attach`
+     *  splits into sidecar files (default for `.zip`), `omit` drops bodies. */
+    content?: "embed" | "attach" | "omit";
+    /** When true, the HAR was wired at context creation via Playwright's native
+     *  `recordHar` option (open_session({har:{...}})) — `stop_har` is a no-op
+     *  for this case (you can't undo a context-creation primitive without
+     *  closing the context). */
+    nativeRecord?: boolean;
+}
+export declare function newHarRecorderState(): HarRecorderState;
+/** Configuration accepted by `start_har` AND `open_session({har})`. */
+export interface HarStartConfig {
+    /** Workspace-rooted path. Optional — defaults to
+     *  `<workspace>/har/<session-id>-<ISO>.har` when omitted. Path traversal
+     *  outside the workspace is rejected (mirrors the storage-state contract). */
+    path?: string;
+    mode?: "full" | "minimal";
+    content?: "embed" | "attach" | "omit";
+    /** Optional URL filter (glob or regex) — only matching requests are stored. */
+    urlFilter?: string;
+}
+/** Default HAR filename for an auto-named recording. ISO timestamp with
+ *  `:` / `.` mapped to `-` so the name is filesystem-safe on every platform. */
+export declare function defaultHarFilename(sessionId: string, now?: Date): string;
+/** Resolve an explicit user-supplied path (workspace-escape rejected) OR
+ *  build the default `<workspace>/har/<auto>.har` path. Creates the parent
+ *  dir on demand — still under the workspace root by construction. */
+export declare function resolveHarPath(workspaceRoot: string, sessionId: string, userPath: string | undefined, tool: string): string;
+/** Validate replay HAR file paths supplied to `open_session({hars})`. Each
+ *  must resolve under `$BROWX_WORKSPACE` and the file must exist (a typo
+ *  silently falling back to live network would defeat the point). */
+export declare function resolveHarReplayPaths(workspaceRoot: string, hars: readonly string[], tool: string): string[];
+/** Begin HAR recording on a live context via `routeFromHAR(update:true)`. The
+ *  HAR file on disk is finalized when the context closes — this returns the
+ *  reserved path and the caller is responsible for `close_session` (or the
+ *  natural session teardown) to flush. Re-calling `start_har` on an already-
+ *  active recorder replaces the in-flight target after a transparent stop. */
+export declare function startHar(context: BrowserContext, state: HarRecorderState, workspaceRoot: string, sessionId: string, cfg?: HarStartConfig): Promise<{
+    path: string;
+    mode: "full" | "minimal";
+    content: "embed" | "attach" | "omit";
+    replacedPrior: boolean;
+}>;
+/** Stop HAR recording on a live context. Removes the recording route; the HAR
+ *  file is written to disk when the context closes (Playwright constraint).
+ *  No-op + `{wasActive:false}` when no recorder is active. */
+export declare function stopHar(context: BrowserContext, state: HarRecorderState): Promise<{
+    wasActive: boolean;
+    path?: string;
+    finalized: boolean;
+    nativeRecord: boolean;
+}>;
+/** Best-effort read of a finalized HAR. Used by callers that want the file
+ *  inlined when small. Returns `undefined` when the file doesn't yet exist
+ *  (HAR not finalized) or is over the inline cap. */
+export declare function readHarIfSmall(path: string, capBytes?: number): string | undefined;
+/** Apply replay HAR(s) to a live context. Each file is wired with
+ *  `notFound:"fallback"` so a request that isn't in the archive falls through
+ *  to the live network (the safer default; agents who want a hermetic replay
+ *  can route the rest themselves). */
+export declare function applyHarReplay(context: BrowserContext, files: readonly string[]): Promise<void>;
+/** Build the Playwright `recordHar` option for `open_session({har})`. The
+ *  caller passes this into `browser.newContext({recordHar})` / equivalent
+ *  on `chromium.launchPersistentContext`. */
+export declare function buildRecordHarOption(workspaceRoot: string, sessionId: string, cfg: HarStartConfig): {
+    path: string;
+    mode: "full" | "minimal";
+    content: "embed" | "attach" | "omit";
+    recordHar: {
+        path: string;
+        mode?: "full" | "minimal";
+        content?: "embed" | "attach" | "omit";
+        urlFilter?: string | RegExp;
+    };
+};