Add network intercept/error monitor; document soak and Outline sync

- interceptNetworkCall + startNetworkErrorMonitor for page traffic
  (spy/mock + fail on silent 4xx/5xx), with unit tests
- docs/NETWORK.md, docs/IDEAS.md (OSS backlog), docs/OUTLINE.md
  (update Outline QA & Dev Playkit page on each release)
- Adoption pause: no other consumer repos until punimtag soak

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- **Network interception / error monitor** — `interceptNetworkCall()`, `startNetworkErrorMonitor()` (see `docs/NETWORK.md`)
+- Docs: `docs/OUTLINE.md` checklist (update Outline QA & Dev Playkit page on each release); `docs/IDEAS.md` for OSS-borrowed backlog; adoption pause (no new consumer repos until soak)
 - CI: add tag-triggered `release` job (`.gitea/workflows/ci.yml`) — re-runs build/test, verifies tag matches `package.json` version and `CHANGELOG.md` documents it, creates a Gitea release with an `npm pack` tarball attached. Requires a one-time `GITEA_TOKEN` Actions secret.
 - Docs: bump install pin examples from `v0.1.0` to `v0.3.0` (README, CONSUMER.md)
 - Docs: lead with Mailpit (homelab default) instead of Mailtrap in README email section; use `createMailInbox()` + `readMailHtml()` in the example instead of a provider-specific client

README.md

@@ -76,6 +76,26 @@ test('sign-out stays on public host', async ({ page, playkitConfig, timings }) =
 | `assertSchema` | Zod schema asserts (standalone or via `ApiClient` `schema` option) |
 | `saveStorageState` / `storageStateUse` | Auth once, reuse across specs |
 | `playkitFailureArtifacts` | Trace/video/screenshot only on failure |
+| `interceptNetworkCall` | Spy or mock the next matching page network call |
+| `startNetworkErrorMonitor` | Fail tests that silently collect HTTP 4xx/5xx |
+
+See also `docs/NETWORK.md`, `docs/IDEAS.md` (OSS-borrowed backlog), `docs/OUTLINE.md` (live docs sync).
+
+## Network (page traffic)
+
+```ts
+import { interceptNetworkCall, startNetworkErrorMonitor } from '@levkin/playkit';
+
+const users = interceptNetworkCall({ page, url: '**/api/users' });
+const net = startNetworkErrorMonitor(page, { excludePatterns: ['sentry.io'] });
+try {
+  await page.goto('/users');
+  const { status } = await users;
+  expect(status).toBe(200);
+} finally {
+  net.assertNoErrors();
+}
+```
 
 ## Email testing (Mailpit default, Mailtrap optional)
 
@@ -121,6 +141,8 @@ npm run build
 
 Pushing the tag triggers `.gitea/workflows/ci.yml`'s `release` job: it re-runs typecheck/test/build, verifies the tag matches `package.json`'s `version` and that `CHANGELOG.md` documents it, then creates a Gitea release (with the `npm pack` tarball attached) via the API using a repo-scoped `GITEA_TOKEN` Actions secret. If any check fails, no release is created — fix and re-tag. Consumers still pin the git tag (`#vX.Y.Z`); the Gitea release is for visibility/changelog, not an npm registry publish (see ROADMAP "private Gitea npm registry").
 
+4. **Update Outline** — after the release is green, sync the Playkit page under Outline **QA & Dev** (`notes.levkin.ca`). Checklist: `docs/OUTLINE.md`.
+
 **One-time setup:** add a `GITEA_TOKEN` secret (repo `Settings → Actions → Secrets` on `ilia/playkit`) scoped to create releases on this repo — separate from the `PLAYKIT_GIT_TOKEN` consumers use to clone it.
 
 ## License

ROADMAP.md

@@ -26,10 +26,15 @@ Living plan for making `@levkin/playkit` more useful across Levkin repos.
 - [ ] **Deploy-smoke CLI** — `playkit smoke --project punimtag` post-deploy gate
 - [ ] **Retry policy presets** — flaky-network vs strict-CI profiles
 - [ ] **Self-test against a real fake site** — today's unit tests only mock HTTP/mail; `examples/` specs are explicitly *not run* in kit CI. Stand up a tiny demo app (or point at an existing DEV LXC) and run the browser/API/mail helpers against it in CI, so a regression in `BasePage`/`ApiClient`/`assertPublicHost` is caught before a consumer pins a broken tag.
+- [x] **Network interception / network error monitor** — `interceptNetworkCall()`, `startNetworkErrorMonitor()` / `assertNoErrors()` (see `docs/NETWORK.md`)
 - [x] **Tag-triggered release workflow** — `.gitea/workflows/ci.yml` `release` job now runs on `vX.Y.Z` tag push: re-verifies build/test, checks tag == `package.json` version, checks `CHANGELOG.md` has that version's section, then creates a Gitea release (npm-pack tarball attached) via the API. Needs a one-time `GITEA_TOKEN` Actions secret on this repo (see README "Release"). Still open: `build-and-test`/`secret-scan` also re-run on the tag push (same `on.push` trigger) — harmless redundancy, not wired to skip.
-- [ ] **Live docs** — see `docs/CONSUMER.md` decision note; likely an Outline page under the existing "QA & Dev" collection (`notes.levkin.ca`, already deployed with API automation) rather than a new static site.
+- [ ] **Live docs** — Outline page under **QA & Dev** (`notes.levkin.ca`). Sync checklist in `docs/OUTLINE.md` — update Outline whenever playkit is released.
 - [x] **Pushgateway + dashboard wired in ansible** — `pushgateway` service, Prometheus scrape job, and a generated `live-playkit` Grafana board now live in ansible `deploy/observability/` (superseding the old standalone `dashboards/playkit-overview.json`, which is removed). Ops still needs to run `make deploy-observability` against the LXC before `PLAYKIT_METRICS_ENABLED=true` does anything in CI — check with the ansible repo owner before flipping that on.
 
+## Adoption pause
+
+**No new consumer repos until we soak.** Keep playing through punimtag e2e + kit CI for a few days (release job, Pushgateway/dashboard apply, network helpers) before migrating `screening` / `slack-sieve` / `portfolio`. See `docs/IDEAS.md`.
+
 ## Later (v0.5+) — professional polish
 
 - [ ] **Web Vitals** (LCP/CLS/INP) collection via Playwright CDP + metrics labels
@@ -37,7 +42,7 @@ Living plan for making `@levkin/playkit` more useful across Levkin repos.
 - [ ] **Visual regression** — screenshot baselines with per-project bucket (MinIO)
 - [ ] **Contract testing** — OpenAPI-driven API suite generator
 - [ ] **Multi-browser matrix helper** — chromium/firefox/webkit project factory
-- [ ] **Flake quarantine** — annotate + quarantine flaky tests with Grafana panel
+- [ ] **Flake quarantine** — annotate + quarantine flaky tests with Grafana panel (depends on burn-in — see below)
 - [ ] **Hermes / Mattermost reporter** — post failed suite summary to `#eng`
 - [ ] **Infisical SDK helper** — `loadSecretsFromInfisical()` for local runs (machine identity)
 - [ ] **JUnit + HTML report merge** — single artifact for Gitea PR checks
@@ -45,11 +50,11 @@ Living plan for making `@levkin/playkit` more useful across Levkin repos.
 
 ## Ideas pulled from similar OSS tools (2026-07 research)
 
-Comparing playkit against `seontechnologies/playwright-utils` (102★, functional-core/fixture-shell design), `kitium-ai/playwright-helpers` (enterprise-grade, contract/a11y/chaos), `maravexa/playwright-exporter` (scheduled synthetic monitoring), and `vitalics/playwright-prometheus-remote-write-reporter` (remote-write instead of Pushgateway). What's worth taking:
+See `docs/IDEAS.md` for expanded notes. Summary:
 
-- [ ] **Functional-core-for-everything audit** — playkit already does this for the runtime object (`createPlaykitRuntime` wraps plain functions), but individual utilities like `ApiClient` are class-only. `playwright-utils` ships every utility as *both* a standalone function (explicit deps, easy to unit test) and a fixture wrapper. Worth an audit pass on `ApiClient`/`MailpitClient` to see which could get a functional export alongside the class.
-- [ ] **Network interception / network error monitor** — `playwright-utils` has dedicated helpers for asserting on intercepted requests and flagging console/network errors during a test, distinct from `ApiClient` (which is for *making* requests, not observing the page's own traffic). Genuinely missing capability, not just a naming difference.
-- [ ] **Test burn-in (flake detection)** — `playwright-utils`' "burn-in" utility reruns a spec N times before merge to catch flaky tests early. This *is* the mechanism for the existing "Flake quarantine" item above — implement burn-in first, quarantine consumes its output.
-- [ ] **Scheduled synthetic monitoring** — `playwright-exporter` runs suites on a cron and exposes pass/fail + duration as Prometheus metrics independent of any Pushgateway. This overlaps heavily with the "Deploy-smoke CLI" item (`playkit smoke --project punimtag`) — evaluate reusing/wrapping `playwright-exporter` on a schedule instead of building a bespoke CLI from scratch.
-- [ ] **Remote-write as a Pushgateway alternative** — `playwright-prometheus-remote-write-reporter` pushes via Prometheus remote-write instead of a Pushgateway (no separate service to run/scrape). Now moot for us since Pushgateway is wired into `deploy/observability` (2026-07-14), but worth remembering if that stack ever needs simplifying.
-- Confirmed sane (no action): OpenAPI contract testing, axe-core a11y, and visual regression are already on this roadmap and match what `kitium-ai/playwright-helpers` treats as "enterprise" table stakes — no new items needed, just execute what's already listed.
+- [x] **Network interception / network error monitor** — shipped (above)
+- [ ] **Test burn-in (flake detection)** — rerun a spec N times; mechanism for flake quarantine
+- [ ] **Scheduled synthetic monitoring** — evaluate `playwright-exporter` before bespoke smoke CLI
+- [ ] **Functional-core-for-everything audit** — optional function wrappers alongside class APIs
+- ~~Remote-write vs Pushgateway~~ — moot while Pushgateway is the path
+- Confirmed sane (no action): OpenAPI / axe / visual reg already under v0.5+

docs/CONSUMER.md

@@ -55,3 +55,6 @@ e2e:
 
 PR → CI green (unit + e2e when secrets present) → merge → documented deploy script.  
 Do not claim “fixed” from a bare `pct exec` hotfix without a follow-up PR.
+
+**Adoption pause:** do not add playkit to other app repos until punimtag + kit CI
+have soaked for a few days. See `docs/IDEAS.md`.

docs/IDEAS.md

@@ -0,0 +1,53 @@
+# Ideas backlog (from similar OSS tools)
+
+Notes from comparing `@levkin/playkit` to public kits (2026-07). Tracking items
+also live in `ROADMAP.md` — this page expands *why* / *how*, not just the checkbox.
+
+## Already shipping (borrowed shape)
+
+- **Network interception + error monitor** — see `docs/NETWORK.md`. Sourced from
+  [`playwright-utils`](https://github.com/seontechnologies/playwright-utils)
+  (spy/stub + background 4xx/5xx “Sentry for tests”), trimmed to Levkin needs.
+
+## Documented next (not implemented yet)
+
+### Test burn-in (flake detection)
+
+`playwright-utils` “burn-in” re-runs a spec N times (local or CI) before merge.
+That is the *mechanism* behind playkit’s “flake quarantine” roadmap item —
+implement burn-in first (CLI flag or `PLAYKIT_BURN_IN=N`), then quarantine can
+consume “failed once in N” signals into Grafana / Annotations.
+
+### Scheduled synthetic monitoring
+
+[`playwright-exporter`](https://github.com/maravexa/playwright-exporter) runs
+Playwright suites on a cron and exposes pass/fail + duration as Prometheus
+metrics. Overlaps with “deploy-smoke CLI”. Prefer evaluating that tool (or a
+thin wrapper) on a schedule against punimtag DEV **before** writing a bespoke
+`playkit smoke` binary.
+
+### Functional-core / fixture-shell audit
+
+`playwright-utils` ships each utility as a plain function *and* a fixture.
+Playkit already does this for `createPlaykitRuntime`; `ApiClient` /
+`MailpitClient` are class-first. Audit later: keep classes, add thin function
+wrappers only where consumers repeatedly wrap them themselves.
+
+### Remote-write vs Pushgateway
+
+[`playwright-prometheus-remote-write-reporter`](https://github.com/vitalics/playwright-prometheus-remote-write-reporter)
+avoids a Pushgateway by writing straight into Prometheus. **Moot for now** —
+homelab Pushgateway is wired in ansible `deploy/observability` (pending apply).
+Keep as a simplification option if Pushgateway ops cost ever hurts.
+
+### Enterprise polish already on the roadmap
+
+Contract testing (OpenAPI), axe-core a11y, and visual regression match what
+`kitium-ai/playwright-helpers` treats as table stakes — already listed under
+v0.5+ in `ROADMAP.md`; no extra checklist needed.
+
+## Adoption pause
+
+**Do not wire other app repos onto playkit yet.** Shake out punimtag + kit CI
+for a few days (metrics path, release job, network helpers) before migrating
+`screening` / `slack-sieve` / `portfolio`. Revisit after that soak.

docs/NETWORK.md

@@ -0,0 +1,63 @@
+# Network helpers (page traffic)
+
+`ApiClient` *makes* HTTP calls from the test process. These helpers watch what the
+**browser page** itself does during UI flows — spy/mock specific calls, and fail
+tests that silently collect 4xx/5xx in the background.
+
+## Spy / mock — `interceptNetworkCall`
+
+Set up **before** the action that triggers the request:
+
+```ts
+import { interceptNetworkCall } from '@levkin/playkit';
+
+const users = interceptNetworkCall({
+  page,
+  method: 'GET',
+  url: '**/api/users',
+});
+
+await page.goto('/users');
+const { status, responseJson } = await users;
+expect(status).toBe(200);
+```
+
+Stub a response:
+
+```ts
+const users = interceptNetworkCall({
+  page,
+  url: '**/api/users',
+  fulfillResponse: {
+    status: 200,
+    body: [{ id: 1, name: 'e2e' }],
+  },
+});
+
+await page.goto('/users');
+await users;
+await expect(page.getByText('e2e')).toBeVisible();
+```
+
+## Background errors — `startNetworkErrorMonitor`
+
+Catches silent backend failures while the UI still looks fine:
+
+```ts
+import { startNetworkErrorMonitor } from '@levkin/playkit';
+
+test('dashboard stays clean', async ({ page }) => {
+  const net = startNetworkErrorMonitor(page, {
+    excludePatterns: [/analytics\.google\.com/, 'sentry.io'],
+  });
+  try {
+    await page.goto('/dashboard');
+    await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+  } finally {
+    net.assertNoErrors(); // throws with method/status/url list if any 4xx/5xx
+  }
+});
+```
+
+Opt out of known 4xx paths via `excludePatterns` (substring or `RegExp`).
+Call `assertNoErrors()` (or `stop()`) so the listener is removed.

docs/OUTLINE.md

@@ -0,0 +1,34 @@
+# Outline live docs checklist
+
+Canonical prose stays in git (`README.md`, `docs/*`, `ROADMAP.md`).
+Browsable front door: **Outline** → collection **QA & Dev** → doc **Playkit**
+(`https://notes.levkin.ca`).
+
+## When to update Outline
+
+Update the Outline Playkit page **whenever playkit ships a release** (after the
+tag / Gitea release is green), or whenever you merge a docs-only change that
+changes consumer behavior:
+
+1. Tag / release finished (or main docs PR merged)
+2. Open Outline → QA & Dev → Playkit
+3. Sync at least: current version pin, “what’s in the box”, install snippet,
+   link to CHANGELOG / ROADMAP / NETWORK.md
+4. Optional: `make outline-setup` from ansible only if you maintain seed notes there —
+   prefer editing the living page by hand so it stays readable
+
+Paste template (adjust version):
+
+```markdown
+# @levkin/playkit
+
+Shared Playwright + API e2e kit. **Source of truth is the git repo.**
+
+- Repo: https://git.levkin.ca/ilia/playkit
+- Current: vX.Y.Z
+- Consumers: punimtag (e2e/) — *pause further adoption until soak completes*
+
+## Quick links
+- README · CONSUMER.md · NETWORK.md · IDEAS.md · ROADMAP · CHANGELOG
+- Metrics: dash.levkin.ca → Live — Playkit e2e
+```

src/browser/index.ts

@@ -13,3 +13,15 @@ export {
 } from './actions.js';
 export { saveStorageState, storageStateUse } from './storageState.js';
 export { playkitFailureArtifacts } from './playwrightPreset.js';
+export {
+  interceptNetworkCall,
+  startNetworkErrorMonitor,
+  NetworkErrorMonitor,
+  matchesExcludePattern,
+  dedupeNetworkErrors,
+  type FulfillResponse,
+  type InterceptNetworkCallOptions,
+  type InterceptedNetworkCall,
+  type NetworkError,
+  type NetworkErrorMonitorOptions,
+} from './network.js';

src/browser/network.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import {
+  dedupeNetworkErrors,
+  matchesExcludePattern,
+  type NetworkError,
+} from './network.js';
+
+describe('matchesExcludePattern', () => {
+  it('matches substring and regex', () => {
+    expect(matchesExcludePattern('https://cdn.example.com/x.js', ['cdn.example.com'])).toBe(
+      true,
+    );
+    expect(matchesExcludePattern('https://api.example.com/users', [/\/users$/])).toBe(true);
+    expect(matchesExcludePattern('https://api.example.com/ok', ['cdn', /\/missing/])).toBe(
+      false,
+    );
+  });
+});
+
+describe('dedupeNetworkErrors', () => {
+  it('keeps first of identical method/status/url', () => {
+    const raw: NetworkError[] = [
+      {
+        url: 'https://api/x',
+        status: 500,
+        method: 'GET',
+        timestamp: '2026-01-01T00:00:00.000Z',
+      },
+      {
+        url: 'https://api/x',
+        status: 500,
+        method: 'GET',
+        timestamp: '2026-01-01T00:00:01.000Z',
+      },
+      {
+        url: 'https://api/x',
+        status: 404,
+        method: 'GET',
+        timestamp: '2026-01-01T00:00:02.000Z',
+      },
+    ];
+    const out = dedupeNetworkErrors(raw);
+    expect(out).toHaveLength(2);
+    expect(out[0]?.status).toBe(500);
+    expect(out[1]?.status).toBe(404);
+  });
+});

src/browser/network.ts

@@ -0,0 +1,253 @@
+/**
+ * Observe / mock page network traffic, and fail tests that silently hit 4xx/5xx.
+ *
+ * Distinct from ApiClient (which *makes* requests): these helpers watch what
+ * the browser itself does during UI flows.
+ *
+ * Inspired by seontechnologies/playwright-utils network utilities — leaner
+ * surface for Levkin consumers.
+ */
+import type { Page, Request, Response, Route } from '@playwright/test';
+import { createLogger, type Logger } from '../logging/logger.js';
+
+export interface FulfillResponse {
+  status?: number;
+  headers?: Record<string, string>;
+  body?: unknown;
+}
+
+export interface InterceptNetworkCallOptions {
+  page: Page;
+  // Playwright URL glob (e.g. "**" + "/api/users") or RegExp.
+  url: string | RegExp;
+  method?: string;
+  /** When set, fulfill the route with this mock instead of hitting the network. */
+  fulfillResponse?: FulfillResponse;
+  /** Custom route handler (overrides fulfillResponse when both provided). */
+  handler?: (route: Route, request: Request) => Promise<void>;
+  timeout?: number;
+}
+
+export interface InterceptedNetworkCall {
+  request: Request;
+  response: Response | null;
+  status: number;
+  responseJson: unknown;
+  requestJson: unknown;
+}
+
+function methodMatches(request: Request, method?: string): boolean {
+  if (!method) return true;
+  return request.method().toUpperCase() === method.toUpperCase();
+}
+
+async function parseJsonSafe(raw: string | null): Promise<unknown> {
+  if (!raw) return undefined;
+  try {
+    return JSON.parse(raw) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+function responsePredicate(
+  response: Response,
+  url: string | RegExp,
+  method?: string,
+): boolean {
+  if (!methodMatches(response.request(), method)) return false;
+  if (url instanceof RegExp) return url.test(response.url());
+  // Prefer Playwright's built-in glob matching when possible via URL string compare.
+  try {
+    return response.url().match(new RegExp(
+      url
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*\*/g, '.*')
+        .replace(/\*/g, '[^/?]*'),
+    )) !== null;
+  } catch {
+    return response.url().includes(String(url));
+  }
+}
+
+/**
+ * Spy on (or stub) the next matching page network call.
+ *
+ * Set this up *before* the action that triggers the request, then await the
+ * returned promise after that action:
+ *
+ *   const call = interceptNetworkCall({ page, url: '**' + '/api/users' });
+ *   await page.goto('/users');
+ *   const { status, responseJson } = await call;
+ */
+export function interceptNetworkCall(
+  options: InterceptNetworkCallOptions,
+): Promise<InterceptedNetworkCall> {
+  const { page, url, method, fulfillResponse, handler, timeout = 30_000 } = options;
+  const log = createLogger({ name: 'interceptNetworkCall' });
+  const needsRoute = Boolean(handler || fulfillResponse);
+
+  // Register the response waiter first so we never miss a fast request.
+  const responsePromise = page.waitForResponse(
+    (res) => responsePredicate(res, url, method),
+    { timeout },
+  );
+
+  const setup = needsRoute
+    ? page.route(url, async (route, request) => {
+        if (!methodMatches(request, method)) {
+          await route.continue();
+          return;
+        }
+        if (handler) {
+          await handler(route, request);
+          return;
+        }
+        const body =
+          typeof fulfillResponse!.body === 'string' || Buffer.isBuffer(fulfillResponse!.body)
+            ? fulfillResponse!.body
+            : fulfillResponse!.body === undefined
+              ? undefined
+              : JSON.stringify(fulfillResponse!.body);
+        await route.fulfill({
+          status: fulfillResponse!.status ?? 200,
+          headers: {
+            'content-type': 'application/json',
+            ...fulfillResponse!.headers,
+          },
+          body: body as string | Buffer | undefined,
+        });
+      })
+    : Promise.resolve();
+
+  return setup
+    .then(() => responsePromise)
+    .then(async (response) => {
+      const request = response.request();
+      const requestJson = await parseJsonSafe(request.postData());
+      let responseJson: unknown;
+      try {
+        responseJson = await response.json();
+      } catch {
+        responseJson = undefined;
+      }
+      log.info(needsRoute ? 'intercept fulfilled/handled' : 'intercept observed', {
+        method: request.method(),
+        url: request.url(),
+        status: response.status(),
+      });
+      return {
+        request,
+        response,
+        status: response.status(),
+        responseJson,
+        requestJson,
+      };
+    })
+    .finally(async () => {
+      if (needsRoute) {
+        await page.unroute(url).catch(() => undefined);
+      }
+    });
+}
+
+export interface NetworkError {
+  url: string;
+  status: number;
+  method: string;
+  timestamp: string;
+}
+
+export interface NetworkErrorMonitorOptions {
+  /** Skip matching URLs (string substring or RegExp). */
+  excludePatterns?: Array<string | RegExp>;
+  /** Minimum status to treat as an error (default 400). */
+  minStatus?: number;
+  logger?: Logger;
+}
+
+/** Pure helper — exported for unit tests. */
+export function matchesExcludePattern(
+  url: string,
+  patterns: Array<string | RegExp> = [],
+): boolean {
+  return patterns.some((p) => (typeof p === 'string' ? url.includes(p) : p.test(url)));
+}
+
+/** Deduplicate by method + status + url. */
+export function dedupeNetworkErrors(errors: NetworkError[]): NetworkError[] {
+  const seen = new Set<string>();
+  const out: NetworkError[] = [];
+  for (const e of errors) {
+    const key = `${e.method}:${e.status}:${e.url}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(e);
+  }
+  return out;
+}
+
+export class NetworkErrorMonitor {
+  private readonly errors: NetworkError[] = [];
+  private readonly onResponse: (response: Response) => void;
+  private stopped = false;
+
+  constructor(
+    private readonly page: Page,
+    private readonly options: NetworkErrorMonitorOptions = {},
+  ) {
+    const log = options.logger ?? createLogger({ name: 'NetworkErrorMonitor' });
+    const minStatus = options.minStatus ?? 400;
+    const exclude = options.excludePatterns ?? [];
+
+    this.onResponse = (response: Response) => {
+      if (this.stopped) return;
+      const status = response.status();
+      if (status < minStatus) return;
+      const requestUrl = response.url();
+      if (matchesExcludePattern(requestUrl, exclude)) return;
+      const entry: NetworkError = {
+        url: requestUrl,
+        status,
+        method: response.request().method(),
+        timestamp: new Date().toISOString(),
+      };
+      this.errors.push(entry);
+      log.warn('network error observed', { ...entry });
+    };
+
+    this.page.on('response', this.onResponse);
+  }
+
+  getErrors(): NetworkError[] {
+    return dedupeNetworkErrors(this.errors);
+  }
+
+  stop(): void {
+    if (this.stopped) return;
+    this.stopped = true;
+    this.page.off('response', this.onResponse);
+  }
+
+  /**
+   * Throw if any 4xx/5xx (after exclusions / dedupe) were observed.
+   * Call in afterEach or at the end of a test that should remain "clean".
+   */
+  assertNoErrors(): void {
+    const errs = this.getErrors();
+    this.stop();
+    if (errs.length === 0) return;
+    const lines = errs.map((e) => `  ${e.method} ${e.status} ${e.url}`).join('\n');
+    throw new Error(
+      `Network errors detected: ${errs.length} request(s) failed.\nFailed requests:\n${lines}`,
+    );
+  }
+}
+
+/** Start listening for HTTP error responses on a page. */
+export function startNetworkErrorMonitor(
+  page: Page,
+  options?: NetworkErrorMonitorOptions,
+): NetworkErrorMonitor {
+  return new NetworkErrorMonitor(page, options);
+}

src/index.ts

@@ -22,9 +22,19 @@ export {
   saveStorageState,
   storageStateUse,
   playkitFailureArtifacts,
+  interceptNetworkCall,
+  startNetworkErrorMonitor,
+  NetworkErrorMonitor,
+  matchesExcludePattern,
+  dedupeNetworkErrors,
   type ClickOptions,
   type FillOptions,
   type GotoOptions,
+  type FulfillResponse,
+  type InterceptNetworkCallOptions,
+  type InterceptedNetworkCall,
+  type NetworkError,
+  type NetworkErrorMonitorOptions,
 } from './browser/index.js';
 
 export {