browxai 0.7.0

package/dist/page/video.js

@@ -0,0 +1,169 @@
+// Session video recording — Playwright's native `recordVideo` context option.
+//
+// Strategy. Playwright's video recorder is wired at context creation and
+// finalized when the context closes — same constraint shape as the native
+// `recordHar` path (see src/page/har.ts). There is NO public mid-session
+// flush; the .webm on disk is written only when the page / context closes.
+// We honour that:
+//
+//   - `open_session({recordVideo: {path?, size?}})` resolves the user-facing
+//     target path (workspace-rooted; default
+//     `<workspace>/videos/<sessionId>-<ISO>.webm`), then wires Playwright's
+//     `recordVideo` against a staging directory under `videos/.staging/...`.
+//     Playwright auto-names the file in the dir (an opaque GUID) — on
+//     `close_session` we resolve that to the deterministic target path via
+//     `page.video().saveAs(target)`.
+//   - `stop_video({session?})` mirrors `stop_har` in the `nativeRecord:true`
+//     posture: Playwright doesn't expose a mid-context stop, so the tool
+//     surfaces the constraint instead of silently lying. The recorder state
+//     is marked `pendingFinalize:true` and the video will land at the target
+//     path when `close_session` runs.
+//   - `get_video({session?, format?})` reads the finalized file off disk:
+//     `format: "path"` (default) returns the absolute path; `format: "bytes"`
+//     inlines as base64 when under the inline cap, else returns the path
+//     with a `tooLargeToInline:true` hint. A get-before-stop call surfaces a
+//     structured error pointing at `close_session` (the file isn't on disk
+//     yet — Playwright constraint).
+//
+// Workspace-rooted by construction. Every path runs through
+// `resolveWorkspacePath` (same helper as HAR / storage-state / pdf_save).
+// Path traversal outside `$BROWX_WORKSPACE` is rejected.
+//
+// BYOB / attached. Mirror of HAR + pdf_save: the consumer's Chrome is
+// not-owned and we don't wire context-creation primitives on it. The tool
+// layer refuses cleanly with a structured error (see `assertVideoSupported`).
+import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+import { resolveWorkspacePath } from "../session/storage.js";
+/** 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 const VIDEO_INLINE_CAP_BYTES = 1024 * 1024; // 1 MiB
+export function newVideoRecorderState() {
+    return { active: false, finalized: false, pendingFinalize: false };
+}
+/** 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 function assertVideoSupported(ctx) {
+    if (ctx.mode === "attached") {
+        return {
+            error: "video recording: not supported on attached / BYOB sessions — " +
+                "Playwright's `recordVideo` is a context-creation primitive and " +
+                "we don't mutate the consumer's Chrome (not-owned).",
+            hint: 'open a managed session (open_session({mode:"persistent"}) or ' +
+                '{mode:"incognito"}) with {recordVideo:{...}} and drive that.',
+        };
+    }
+    return null;
+}
+/** Default video filename for an auto-named recording. ISO timestamp with
+ *  `:` / `.` mapped to `-` so the name is filesystem-safe on every platform. */
+export function defaultVideoFilename(sessionId, now = new Date()) {
+    const iso = now.toISOString().replace(/[:.]/g, "-");
+    const safeId = sessionId.replace(/[^A-Za-z0-9._-]/g, "_");
+    return `${safeId}-${iso}.webm`;
+}
+/** 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 function resolveVideoTargetPath(workspaceRoot, sessionId, userPath, tool) {
+    const resolved = userPath
+        ? resolveWorkspacePath(workspaceRoot, userPath, tool)
+        : resolveWorkspacePath(workspaceRoot, `videos/${defaultVideoFilename(sessionId)}`, tool);
+    // `resolved` is workspace-rooted by construction (resolveWorkspacePath
+    // rejects any escape from `workspaceRoot`); `dirname(resolved)` is
+    // workspace-rooted too — the mkdirSync below never touches cwd.
+    // BROWX_WORKSPACE-derived.
+    const parent = dirname(resolved);
+    if (parent && parent !== resolved && !existsSync(parent)) {
+        mkdirSync(parent, { recursive: true });
+    }
+    return resolved;
+}
+/** 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 function resolveVideoStagingDir(workspaceRoot, sessionId, now = new Date()) {
+    const iso = now.toISOString().replace(/[:.]/g, "-");
+    const safeId = sessionId.replace(/[^A-Za-z0-9._-]/g, "_");
+    const stagingRel = `videos/.staging/${safeId}-${iso}`;
+    // resolveWorkspacePath rejects any escape from `workspaceRoot` — the
+    // resolved staging dir is BROWX_WORKSPACE-rooted by construction; the
+    // mkdirSync below never touches cwd.
+    const resolved = resolveWorkspacePath(workspaceRoot, stagingRel, "open_session");
+    if (!existsSync(resolved))
+        mkdirSync(resolved, { recursive: true });
+    return resolved;
+}
+/** 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 function buildRecordVideoOption(workspaceRoot, sessionId, cfg) {
+    const targetPath = resolveVideoTargetPath(workspaceRoot, sessionId, cfg.path, "open_session");
+    const stagingDir = resolveVideoStagingDir(workspaceRoot, sessionId);
+    const recordVideo = {
+        dir: stagingDir,
+    };
+    if (cfg.size)
+        recordVideo.size = cfg.size;
+    return { targetPath, stagingDir, size: cfg.size, recordVideo };
+}
+/** 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 function stopVideo(state) {
+    if (!state.active) {
+        return { wasActive: false, pendingFinalize: false, finalized: state.finalized };
+    }
+    state.pendingFinalize = true;
+    return {
+        wasActive: true,
+        targetPath: state.targetPath,
+        pendingFinalize: true,
+        finalized: state.finalized,
+    };
+}
+/** 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 async function finalizeVideoOnClose(page, state) {
+    if (!state.active || !state.targetPath)
+        return;
+    const video = page.video();
+    if (!video) {
+        // recordVideo was wired but the page reports no video — best-effort.
+        return;
+    }
+    try {
+        await video.saveAs(state.targetPath);
+        state.finalized = true;
+    }
+    catch {
+        /* best-effort — teardown never blocks on this */
+    }
+}
+/** Read a finalized video file. `format: "bytes"` inlines as base64 when
+ *  under the cap; `format: "path"` (or over-cap) returns only the path. */
+export function readVideoIfReady(path, format = "path", capBytes = VIDEO_INLINE_CAP_BYTES) {
+    if (!existsSync(path)) {
+        return { exists: false, path };
+    }
+    const st = statSync(path);
+    if (format === "path") {
+        return { exists: true, path, bytes: st.size };
+    }
+    if (st.size > capBytes) {
+        return { exists: true, path, bytes: st.size, tooLargeToInline: true };
+    }
+    const buf = readFileSync(path);
+    return { exists: true, path, bytes: st.size, inlineBase64: buf.toString("base64") };
+}

package/dist/page/visibility.d.ts

@@ -0,0 +1,22 @@
+import type { BrowserContext, Page } from "playwright-core";
+export type VisibilityState = "background" | "foreground";
+export interface VisibilityResult {
+    ok: boolean;
+    state: VisibilityState;
+    /** true when a real scratch-page background swap was applied (the driven
+     *  page is genuinely not the front tab), false when only the synthetic
+     *  visibility flip was possible. */
+    realBackgrounding: boolean;
+    /** present on a `background` call with `holdMs`: how long the page was held
+     *  hidden before auto-foregrounding. */
+    heldMs?: number;
+    note?: string;
+}
+/**
+ * Drive the tab's visibility. `background` with `holdMs` is the headline
+ * primitive: background the page, hold it hidden for `holdMs` (real throttling
+ * in effect where the browser honours it), then auto-foreground — so the
+ * background→return transition that triggers the bug is reproducible in one
+ * call. `holdMs` is ignored for `foreground`.
+ */
+export declare function setTabVisibility(page: Page, context: BrowserContext, state: VisibilityState, holdMs?: number): Promise<VisibilityResult>;

package/dist/page/visibility.js

@@ -0,0 +1,94 @@
+// Tab background / foreground control.
+//
+// A whole class of real bugs only reproduces when the tab is *backgrounded*
+// during a transition: the browser throttles `setTimeout`, pauses
+// `requestAnimationFrame` (framework enter/animation hooks never fire), and on
+// return a `visibilitychange`/focus handler replays stale state. browxai
+// otherwise keeps the driven tab foreground, so agentic QA scores these flows
+// PASS while they are broken.
+//
+// Two levers, applied together:
+//   1. Synthetic: server-injected *fixed* script (not agent JS — same posture
+//      as the sampler / overlay-hide) overrides `document.visibilityState` /
+//      `document.hidden` and dispatches `visibilitychange`. This deterministic
+//      across managed/incognito/attached/headless, and covers the large
+//      on-focus-refetch / visibilitychange-handler / realtime-replay subset.
+//   2. Real best-effort: bring a blank scratch page in the same context to the
+//      front so Chromium actually treats the driven page as hidden (real
+//      timer/rAF throttling). Headless Chromium may not throttle even when
+//      backgrounded — so this is best-effort and reported as such, never
+//      silently assumed (cf. the documented headless gaps).
+const SCRATCH_URL = "about:blank";
+// Fixed in-page scripts. `configurable: true` so the two states can be
+// re-applied across calls. No agent-supplied code path.
+const HIDE = `(() => {
+  Object.defineProperty(document, 'visibilityState', { configurable: true, get: () => 'hidden' });
+  Object.defineProperty(document, 'hidden', { configurable: true, get: () => true });
+  document.dispatchEvent(new Event('visibilitychange'));
+  window.dispatchEvent(new Event('blur'));
+})()`;
+const SHOW = `(() => {
+  Object.defineProperty(document, 'visibilityState', { configurable: true, get: () => 'visible' });
+  Object.defineProperty(document, 'hidden', { configurable: true, get: () => false });
+  document.dispatchEvent(new Event('visibilitychange'));
+  window.dispatchEvent(new Event('focus'));
+})()`;
+/** Reuse-or-create a blank scratch page for this context (used to actually
+ *  background the driven page by taking front focus away from it). */
+async function scratchPage(context, driven) {
+    try {
+        const existing = context.pages().find((p) => p !== driven && p.url() === SCRATCH_URL);
+        if (existing)
+            return existing;
+        const p = await context.newPage();
+        await p.goto(SCRATCH_URL).catch(() => undefined);
+        return p;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Drive the tab's visibility. `background` with `holdMs` is the headline
+ * primitive: background the page, hold it hidden for `holdMs` (real throttling
+ * in effect where the browser honours it), then auto-foreground — so the
+ * background→return transition that triggers the bug is reproducible in one
+ * call. `holdMs` is ignored for `foreground`.
+ */
+export async function setTabVisibility(page, context, state, holdMs) {
+    if (state === "foreground") {
+        await page.evaluate(SHOW).catch(() => undefined);
+        await page.bringToFront().catch(() => undefined);
+        return { ok: true, state, realBackgrounding: false };
+    }
+    // background
+    const scratch = await scratchPage(context, page);
+    let realBackgrounding = false;
+    if (scratch) {
+        await scratch.bringToFront().catch(() => undefined);
+        realBackgrounding = true;
+    }
+    await page.evaluate(HIDE).catch(() => undefined);
+    if (holdMs !== undefined && holdMs > 0) {
+        await new Promise((r) => setTimeout(r, holdMs));
+        await page.evaluate(SHOW).catch(() => undefined);
+        await page.bringToFront().catch(() => undefined);
+        return {
+            ok: true,
+            state: "foreground",
+            realBackgrounding,
+            heldMs: holdMs,
+            note: realBackgrounding
+                ? "backgrounded for the hold window (real front-tab swap + synthetic visibilitychange), then auto-foregrounded; timer/rAF throttling is best-effort and may not occur under headless"
+                : "synthetic visibilitychange only (no second page could be created to take front focus); on-focus/visibilitychange handlers fire but real timer throttling is not simulated",
+        };
+    }
+    return {
+        ok: true,
+        state,
+        realBackgrounding,
+        note: realBackgrounding
+            ? "page backgrounded (front-tab swap + synthetic visibilitychange); call tab_visibility({state:'foreground'}) to return. Real timer/rAF throttling is best-effort under headless."
+            : "synthetic visibilitychange only; real timer throttling not simulated",
+    };
+}

package/dist/page/watch.d.ts

@@ -0,0 +1,29 @@
+import { type NetworkEntry, type NetworkSummary, type WsFrame } from "./network.js";
+import type { ActionContext } from "./actionresult.js";
+export interface WatchedRegion {
+    role: string;
+    name?: string;
+    ref: string;
+    appearedAtMs: number;
+    /** ms offset when it vanished, or null if still present at window end. */
+    disappearedAtMs: number | null;
+}
+export interface WatchResult {
+    durationMs: number;
+    samples: number;
+    regions: WatchedRegion[];
+    console: {
+        errors: string[];
+        warnings: number;
+        pageErrors: string[];
+    };
+    network: {
+        summary: NetworkSummary;
+        requests: NetworkEntry[];
+    };
+    wsFrames: WsFrame[];
+}
+export declare function watchWindow(ctx: ActionContext, opts: {
+    durationMs: number;
+    sampleMs?: number;
+}): Promise<WatchResult>;

package/dist/page/watch.js

@@ -0,0 +1,99 @@
+// timed observation window with no driving action.
+//
+// `ActionResult`'s structure diff is endpoint-only (pre vs post) — a *transient*
+// element that appears AND disappears inside the window is invisible to it.
+// `watch` samples the top-level regions across the window, so double-fire /
+// missing-broadcast / flash-of-content classes are caught: each region gets
+// `appearedAtMs` and `disappearedAtMs` (null = still present at the end).
+//
+// Console / network / WS are time-stamped buffers already — sliced over the
+// same window.
+import { walk } from "./a11y.js";
+/** Roles that signal a page-level transient/notification surface. */
+const WATCHED_ROLES = new Set([
+    "dialog",
+    "alertdialog",
+    "alert",
+    "status",
+    "banner",
+    "tooltip",
+    "log",
+    "marquee",
+    "timer",
+]);
+const MAX_DURATION_MS = 60_000;
+const DEFAULT_SAMPLE_MS = 250;
+export async function watchWindow(ctx, opts) {
+    const durationMs = Math.min(Math.max(opts.durationMs, 1), MAX_DURATION_MS);
+    const sampleMs = Math.max(opts.sampleMs ?? DEFAULT_SAMPLE_MS, 50);
+    const tStart = Date.now();
+    // Thread the session's secrets registry (when capability `secrets` is
+    // active and the registry exists on the action context) so the network
+    // tap's literal-value sanitisation runs over URLs / mutation
+    // responseShape keys during the watch window — same chokepoint the
+    // action-window tap uses.
+    // The per-action network tap comes from the engine's substrate:
+    // chromium → the CDP NetworkTap; firefox/webkit → the Playwright context-event
+    // tap. Same close shape on every engine, so the watch result is engine-blind.
+    const net = ctx.network ? ctx.network.openActionTap() : null;
+    if (net)
+        await net.open();
+    // ref → tracking record across samples.
+    const seen = new Map();
+    let samples = 0;
+    const sampleOnce = async () => {
+        const tree = await ctx.snapshot.a11yTree(ctx.refs, ctx.testAttributes).catch(() => null);
+        if (!tree)
+            return;
+        const nowMs = Date.now() - tStart;
+        samples++;
+        for (const { node } of walk(tree)) {
+            if (!WATCHED_ROLES.has(node.role))
+                continue;
+            const rec = seen.get(node.ref);
+            if (rec) {
+                rec.lastMs = nowMs;
+            }
+            else {
+                seen.set(node.ref, { role: node.role, name: node.name, firstMs: nowMs, lastMs: nowMs });
+            }
+        }
+    };
+    await sampleOnce();
+    while (Date.now() - tStart < durationMs) {
+        await new Promise((r) => setTimeout(r, sampleMs));
+        await sampleOnce();
+    }
+    const endMs = Date.now() - tStart;
+    const network = net
+        ? await net.close()
+        : { summary: { total: 0, byType: {}, failed: 0 }, requests: [] };
+    const errors = ctx.console.errorsSince(tStart);
+    const pageErrors = ctx.console.pageErrorsSince(tStart);
+    const warnings = ctx.console.warningCountSince(tStart);
+    const wsFrames = ctx.ws ? ctx.ws.since(tStart, 100) : [];
+    // A region "disappeared" if its last sighting was more than ~1.5 sample
+    // intervals before the final sample (i.e. it wasn't in the last sample).
+    const staleCut = endMs - sampleMs * 1.5;
+    const regions = [...seen.values()].map((r) => ({
+        role: r.role,
+        name: r.name,
+        ref: "",
+        appearedAtMs: r.firstMs,
+        disappearedAtMs: r.lastMs < staleCut ? r.lastMs : null,
+    }));
+    // attach refs back (Map key is the ref)
+    let i = 0;
+    for (const ref of seen.keys()) {
+        regions[i].ref = ref;
+        i++;
+    }
+    return {
+        durationMs,
+        samples,
+        regions,
+        console: { errors, warnings, pageErrors },
+        network: { summary: network.summary, requests: network.requests },
+        wsFrames,
+    };
+}

package/dist/page/workers.d.ts

@@ -0,0 +1,126 @@
+import type { CDPSession, Page } from "playwright-core";
+export type WorkerType = "web" | "service";
+export type WorkerFilter = WorkerType | "all";
+export interface WorkerListing {
+    workerId: string;
+    type: WorkerType;
+    url: string;
+    /** Best-effort state. Web workers: always `"running"` (browser doesn't
+     *  expose lifecycle once they're constructed). Service workers: the CDP
+     *  `running_status` (`stopped` / `starting` / `running` / `stopping`). */
+    state?: string;
+}
+export interface WorkerMessage {
+    workerId: string;
+    /** Always serialised to a string for the ring; structured-clone payloads
+     *  are `JSON.stringify`d on the page side (and silently truncated to the
+     *  payload cap). Binary `MessagePort`s are not transferred. */
+    data: string;
+    /** epoch ms — fixed on receipt. */
+    at: number;
+}
+export interface SwFetchInterceptSpec {
+    /** Glob matched against the intercepted request URL. Same shape as
+     *  `route` / `ws_intercept`. `*` = single path segment, `**` = any. */
+    pattern: string;
+    /** Canned response. `body` defaults to `""`. `contentType` defaults
+     *  to `application/json`. `status` defaults to `200`. */
+    response: {
+        status?: number;
+        body?: string;
+        contentType?: string;
+        headers?: Record<string, string>;
+    };
+}
+export declare const WORKERS_PAGE_SCRIPT = "(() => {\n  if (window.__browxWorkers) return;\n  var NativeWorker = window.Worker;\n  if (!NativeWorker) return;\n  var nativePost = NativeWorker.prototype.postMessage;\n  var workers = new Map(); // wwId -> Worker\n  var messages = []; // {workerId, data, at} ring (capped at 500)\n  var MAX = 500;\n  var nextId = 1;\n\n  function recordMessage(id, payload) {\n    var data;\n    try {\n      data = typeof payload === \"string\" ? payload : JSON.stringify(payload);\n    } catch (_) {\n      data = \"[unserialisable]\";\n    }\n    if (data && data.length > 4000) data = data.slice(0, 4000) + \"\u2026\";\n    messages.push({ workerId: id, data: data, at: Date.now() });\n    if (messages.length > MAX) messages.splice(0, messages.length - MAX);\n  }\n\n  function Wrapped(scriptURL, opts) {\n    var w = arguments.length > 1 ? new NativeWorker(scriptURL, opts) : new NativeWorker(scriptURL);\n    var id = \"ww-\" + (nextId++);\n    workers.set(id, w);\n    try { w.__browxId = id; } catch (_) {}\n    // Mirror every message-from-worker into the ring. We use addEventListener\n    // (not onmessage) so we don't fight with app-side onmessage handlers.\n    try {\n      w.addEventListener(\"message\", function (ev) { recordMessage(id, ev.data); });\n    } catch (_) {}\n    return w;\n  }\n  Wrapped.prototype = NativeWorker.prototype;\n  try { Object.defineProperty(Wrapped, \"name\", { value: \"Worker\" }); } catch (_) {}\n  window.Worker = Wrapped;\n\n  window.__browxWorkers = {\n    list: function () {\n      var out = [];\n      workers.forEach(function (w, id) {\n        // We can't get the scriptURL back from a Worker after construction\n        // in all browsers \u2014 fall back to the recorded url if we tracked it,\n        // else the empty string. (Chromium DOES expose it via internal slot\n        // but not via any public API; we track it at construction via the\n        // initial scriptURL argument \u2014 see __browxWorkers._urls.\n        var url = (window.__browxWorkers._urls && window.__browxWorkers._urls.get(id)) || \"\";\n        out.push({ workerId: id, url: url });\n      });\n      return out;\n    },\n    _urls: new Map(),\n    post: function (id, msg) {\n      var w = workers.get(id);\n      if (!w) return { ok: false, error: \"no worker with id \" + id };\n      try {\n        nativePost.call(w, msg);\n        return { ok: true };\n      } catch (e) {\n        return { ok: false, error: e && e.message ? e.message : String(e) };\n      }\n    },\n    drain: function (id) {\n      var out;\n      if (id) {\n        out = [];\n        var kept = [];\n        for (var i = 0; i < messages.length; i++) {\n          if (messages[i].workerId === id) out.push(messages[i]);\n          else kept.push(messages[i]);\n        }\n        messages = kept;\n      } else {\n        out = messages.slice();\n        messages.length = 0;\n      }\n      return out;\n    },\n  };\n\n  // Track scriptURL at construction. We can't get it post-hoc on most engines.\n  var origWrapped = Wrapped;\n  window.Worker = function (scriptURL, opts) {\n    var w = arguments.length > 1 ? origWrapped(scriptURL, opts) : origWrapped(scriptURL);\n    try {\n      var id = w.__browxId;\n      if (id) {\n        var url = \"\";\n        try { url = String(scriptURL && scriptURL.href ? scriptURL.href : scriptURL || \"\"); } catch (_) {}\n        window.__browxWorkers._urls.set(id, url);\n      }\n    } catch (_) {}\n    return w;\n  };\n  window.Worker.prototype = NativeWorker.prototype;\n  try { Object.defineProperty(window.Worker, \"name\", { value: \"Worker\" }); } catch (_) {}\n})();";
+interface BrowxWorkersApi {
+    list(): Array<{
+        workerId: string;
+        url: string;
+    }>;
+    post(id: string, msg: string): {
+        ok: boolean;
+        error?: string;
+    };
+    drain(id?: string): Array<{
+        workerId: string;
+        data: string;
+        at: number;
+    }>;
+}
+declare global {
+    var __browxWorkers: BrowxWorkersApi | undefined;
+}
+export declare class WorkersRegistry {
+    /** SW attachments keyed by CDP sessionId. */
+    private swAttached;
+    /** Stable monotonic id for the SW listing — `sw-1`, `sw-2`, …. Keyed by
+     *  CDP sessionId so the id survives status transitions on the same SW. */
+    private swIdBySession;
+    private nextSwId;
+    /** Active fetch interceptors. Re-add of the same pattern replaces. */
+    private fetchInterceptors;
+    /** Server-side ring of FROM-SW messages (we relay these via a CDP
+     *  `Runtime.bindingCalled` shuttle on each SW session). */
+    private swMessages;
+    /** True once the page-side wrapper has been installed. */
+    private pageInstalled;
+    /** True once we've called `ServiceWorker.enable` + wired the auto-attach
+     *  on the top-level CDP session. */
+    private swEnabled;
+    /** Detach functions for cleanup. */
+    private detachers;
+    /** Install the page-side `Worker` wrapper. Idempotent. Called eagerly at
+     *  session creation (under capability `read`) so workers opened by the
+     *  initial document are seen — same posture as `WsInteractiveRegistry`. */
+    installPageWrapper(page: Page): Promise<void>;
+    /** Enable the CDP ServiceWorker domain on the session's top-level CDP and
+     *  wire `Target.setAutoAttach` so newly-registered SWs auto-attach as child
+     *  sessions. Idempotent. */
+    /** Register a CDP event handler + push its detacher onto `this.detachers`.
+     *  The event name is dynamic here, so the strongly-typed per-event `on`/`off`
+     *  overloads are bridged through a single untyped seam. */
+    private onCdp;
+    /** `ServiceWorker.workerVersionUpdated` — refresh url/status on the matching
+     *  attachment(s). */
+    private registerVersionUpdated;
+    /** `Target.attachedToTarget` / `detachedFromTarget` — track the SW attachment
+     *  map, arming any already-armed fetch interceptors on a new SW. */
+    private registerAttachDetach;
+    /** `Fetch.requestPaused` (TOP session; flatten routes child events up by
+     *  `sessionId`) — fulfill against a matching interceptor, else continue. */
+    private registerRequestPaused;
+    private handleRequestPaused;
+    installSwListener(cdp: CDPSession): Promise<void>;
+    private applyFetchEnable;
+    list(page: Page, cdp: CDPSession, filter?: WorkerFilter): Promise<WorkerListing[]>;
+    sendMessage(page: Page, cdp: CDPSession, args: {
+        workerId: string;
+        message: string;
+    }): Promise<{
+        ok: boolean;
+        workerId: string;
+        error?: string;
+    }>;
+    readMessages(page: Page, args: {
+        workerId?: string;
+    }): Promise<WorkerMessage[]>;
+    addFetchIntercept(cdp: CDPSession, spec: SwFetchInterceptSpec): Promise<{
+        key: string;
+        active: string[];
+    }>;
+    removeFetchIntercept(cdp: CDPSession, sel: {
+        pattern?: string;
+    }): Promise<{
+        removed: string[];
+        active: string[];
+    }>;
+    listFetchIntercepts(): string[];
+    /** Append a FROM-SW message to the server-side ring. Currently unused by
+     *  the production path (the SW side message-relay is left as a future
+     *  follow-up — see report); kept for symmetry + future use. */
+    recordSwMessage(workerId: string, data: string): void;
+    /** Release all CDP listeners. Called from the session teardown. */
+    dispose(): void;
+}
+export {};