Network helpers, docs hygiene, Outline sync notes

2026-07-14 19:50:42 -05:00 · 2026-07-14 19:50:42 -05:00 · 6e3763f44f
commit 6e3763f44f
parent 7369b1c5e5
14 changed files with 635 additions and 87 deletions
--- a/.gitea/workflows/ci.yml
+++ b/.gitea/workflows/ci.yml
@ -5,6 +5,7 @@ name: CI
 on:
  push:
    branches: [main]
+    tags: ['v*']
  pull_request:
    types: [opened, synchronize, reopened]

@ -56,3 +57,81 @@ jobs:
        run: |
          docker run --rm -v "$PWD:/repo" ghcr.io/gitleaks/gitleaks:latest \
            detect --source /repo --no-banner --redact
+
+  # Release: only runs on `vX.Y.Z` tag push. Gates a Gitea release behind the
+  # same integrity checks as CI (never trust a bare "bump + tag") plus two
+  # consistency checks bare tagging can't give you: tag == package.json
+  # version, and CHANGELOG.md actually documents this version.
+  release:
+    runs-on: [homelab, self-hosted, linux]
+    container:
+      image: node:20-bookworm
+    if: startsWith(github.ref, 'refs/tags/v')
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install
+        run: npm ci
+      - name: Typecheck
+        run: npm run typecheck
+      - name: Unit tests
+        run: npm test
+      - name: Build
+        run: npm run build
+      - name: Verify tag matches package.json version
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          PKG_VERSION="$(node -p "require('./package.json').version")"
+          if [ "$TAG" != "$PKG_VERSION" ]; then
+            echo "::error::tag v$TAG does not match package.json version $PKG_VERSION"
+            exit 1
+          fi
+          echo "RELEASE_VERSION=$TAG" >> "$GITEA_ENV"
+      - name: Extract CHANGELOG section for this version
+        run: |
+          node -e '
+            const fs = require("fs");
+            const version = process.env.RELEASE_VERSION;
+            const text = fs.readFileSync("CHANGELOG.md", "utf8");
+            const re = new RegExp(`^## ${version.replace(/\./g, "\\.")}.*$`, "m");
+            const start = text.search(re);
+            if (start === -1) {
+              console.error(`::error::CHANGELOG.md has no "## ${version}" section — update it before tagging`);
+              process.exit(1);
+            }
+            const rest = text.slice(start);
+            const next = rest.slice(1).search(/^## /m);
+            const section = next === -1 ? rest : rest.slice(0, next + 1);
+            fs.writeFileSync("/tmp/release-notes.md", section.trim() + "\n");
+          '
+      - name: Pack npm tarball
+        run: npm pack --pack-destination /tmp
+      - name: Create Gitea release
+        run: |
+          BODY_JSON=$(node -e '
+            const fs = require("fs");
+            const body = fs.readFileSync("/tmp/release-notes.md", "utf8");
+            process.stdout.write(JSON.stringify({
+              tag_name: process.env.GITHUB_REF_NAME,
+              name: process.env.GITHUB_REF_NAME,
+              body,
+              draft: false,
+              prerelease: false,
+            }));
+          ')
+          RESPONSE=$(curl -sS -X POST \
+            -H "Authorization: token ${{ secrets.GITEA_TOKEN }}" \
+            -H "Content-Type: application/json" \
+            -d "$BODY_JSON" \
+            "https://git.levkin.ca/api/v1/repos/ilia/playkit/releases")
+          RELEASE_ID=$(node -e "console.log(JSON.parse(process.argv[1]).id)" "$RESPONSE")
+          if [ -z "$RELEASE_ID" ] || [ "$RELEASE_ID" = "undefined" ]; then
+            echo "::error::release creation failed: $RESPONSE"
+            exit 1
+          fi
+          TARBALL=$(ls /tmp/levkin-playkit-*.tgz)
+          curl -sS -X POST \
+            -H "Authorization: token ${{ secrets.GITEA_TOKEN }}" \
+            -F "attachment=@${TARBALL}" \
+            "https://git.levkin.ca/api/v1/repos/ilia/playkit/releases/${RELEASE_ID}/assets"
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -1,5 +1,14 @@
 # Changelog

+## 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
+- Ops: Pushgateway + `live-playkit` Grafana board now provisioned via ansible `deploy/observability/` (pending `make deploy-observability`); removed the standalone `dashboards/playkit-overview.json` (superseded) and the `dashboards` entry from `package.json` `files`
+
 ## 0.3.0 — 2026-07-14

 - **Zod schema asserts** — `assertSchema()` + optional `schema` on `ApiClient` requests
--- a/README.md
+++ b/README.md
@ -8,7 +8,7 @@ Use it as a library from any consumer repo (punimtag, MirrorMatch, …). App-spe

 ```bash
 # git tag dependency (until a private npm registry is wired)
-npm install git+https://git.levkin.ca/ilia/playkit.git#v0.1.0
+npm install git+https://git.levkin.ca/ilia/playkit.git#v0.3.0

 # peer
 npm install -D @playwright/test
@ -72,27 +72,57 @@ test('sign-out stays on public host', async ({ page, playkitConfig, timings }) =
 | `createLogger` / `redactSecrets` | Structured JSON logs |
 | `TimingCollector` / `pushPrometheusMetrics` | Action timings → Prometheus Pushgateway → Grafana |
 | `createPlaykitRuntime` | One-shot config + logger + API + timings |
-| `MailtrapClient` / `waitForEmail` | Assert password-reset / verify emails in Mailtrap sandbox |
+| `createMailInbox` / `MailpitClient` / `MailtrapClient` | Assert password-reset / verify emails (Mailpit homelab trap or Mailtrap SaaS) |
+| `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 |

-## Mailtrap (email testing)
+See also `docs/NETWORK.md`, `docs/IDEAS.md` (OSS-borrowed backlog), `docs/OUTLINE.md` (live docs sync).
+
+## Network (page traffic)

 ```ts
-import { MailtrapClient, firstLinkMatching, assertPublicHost } from '@levkin/playkit';
+import { interceptNetworkCall, startNetworkErrorMonitor } from '@levkin/playkit';

-const mail = MailtrapClient.fromEnv();
-if (!mail) throw new Error('set MAILTRAP_API_TOKEN + MAILTRAP_INBOX_ID');
+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)
+
+`createMailInbox()` picks the provider from `PLAYKIT_MAIL_PROVIDER` (default
+`mailpit`) so specs don't need to know which backend is behind it. Prefer
+**Mailpit** — it's our homelab SMTP trap (`10.0.10.45`, no external
+dependency); use Mailtrap only if you specifically want the SaaS sandbox.
+
+```ts
+import { createMailInbox, readMailHtml, firstLinkMatching, assertPublicHost } from '@levkin/playkit';
+
+const mail = createMailInbox(); // reads PLAYKIT_MAIL_PROVIDER / MAILPIT_* / MAILTRAP_*
+if (!mail) throw new Error('set MAILPIT_BASE_URL (or MAILTRAP_API_TOKEN + MAILTRAP_INBOX_ID)');

 const after = new Date();
 // … trigger forgot-password in the app …
 const msg = await mail.waitForEmail({ to: 'e2e@example.com', subject: /reset/i, after });
-const html = await mail.getHtml(msg.id, msg.html_path);
+const html = await readMailHtml(mail, msg); // normalizes Mailpit vs Mailtrap message shape
 const link = firstLinkMatching(html, /reset-password/);
 assertPublicHost(link!);
 ```

-**Important:** Mailtrap only sees mail if the app’s SMTP points at the sandbox
-(`sandbox.smtp.mailtrap.io` + inbox credentials). Sending via Gmail to a real
-address will not appear in the sandbox. See ansible `docs/hardening/SECRETS.md`.
+**Important:** the mail client only sees mail if the app's SMTP actually
+points at that trap (Mailpit `10.0.10.45:1025` in DEV, or Mailtrap's
+`sandbox.smtp.mailtrap.io` + inbox credentials for SaaS). Sending via Gmail to
+a real address will not appear in either. See ansible `docs/hardening/SECRETS.md`
+(`## Playkit / punimtag e2e secrets`).

 ## Develop this repo

@ -106,8 +136,14 @@ npm run build
 ## Release

 1. Bump `version` in `package.json`
-2. Update `CHANGELOG.md`
-3. Tag `vX.Y.Z` and push — consumers pin the tag
+2. Update `CHANGELOG.md` with a `## X.Y.Z` section (the release job extracts this verbatim as release notes)
+3. Tag `vX.Y.Z` and push
+
+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

--- a/ROADMAP.md
+++ b/ROADMAP.md
@ -25,6 +25,15 @@ Living plan for making `@levkin/playkit` more useful across Levkin repos.
 - [ ] **Consumer template** — `npx @levkin/playkit init` scaffolding `e2e/` + CI snippet
 - [ ] **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** — 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

@ -33,8 +42,19 @@ 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
 - [ ] **Network assert helpers** — fail if request hits `10.x` / wrong host after navigation
+
+## Ideas pulled from similar OSS tools (2026-07 research)
+
+See `docs/IDEAS.md` for expanded notes. Summary:
+
+- [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+
--- a/dashboards/playkit-overview.json
+++ b/dashboards/playkit-overview.json
@ -1,71 +0,0 @@
-{
-  "annotations": {
-    "list": [
-      {
-        "builtIn": 1,
-        "datasource": { "type": "prometheus", "uid": "prometheus" },
-        "enable": true,
-        "expr": "playkit_action_ok{project=~\"$project\"}",
-        "name": "Playkit action failed",
-        "type": "classic_conditions"
-      }
-    ]
-  },
-  "editable": true,
-  "fiscalYearStartMonth": 0,
-  "graphTooltip": 1,
-  "id": null,
-  "links": [],
-  "panels": [
-    {
-      "title": "Action duration (ms)",
-      "type": "timeseries",
-      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 0 },
-      "datasource": { "type": "prometheus", "uid": "prometheus" },
-      "targets": [
-        {
-          "expr": "playkit_action_duration_ms{project=~\"$project\", env=~\"$env\"}",
-          "legendFormat": "{{action}}"
-        }
-      ]
-    },
-    {
-      "title": "Action success (1=ok)",
-      "type": "timeseries",
-      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 0 },
-      "datasource": { "type": "prometheus", "uid": "prometheus" },
-      "targets": [
-        {
-          "expr": "playkit_action_ok{project=~\"$project\", env=~\"$env\"}",
-          "legendFormat": "{{action}}"
-        }
-      ]
-    }
-  ],
-  "schemaVersion": 39,
-  "tags": ["playkit", "e2e"],
-  "templating": {
-    "list": [
-      {
-        "name": "project",
-        "type": "query",
-        "datasource": { "type": "prometheus", "uid": "prometheus" },
-        "query": "label_values(playkit_action_duration_ms, project)",
-        "includeAll": true,
-        "current": { "text": "All", "value": "$__all" }
-      },
-      {
-        "name": "env",
-        "type": "query",
-        "datasource": { "type": "prometheus", "uid": "prometheus" },
-        "query": "label_values(playkit_action_duration_ms, env)",
-        "includeAll": true,
-        "current": { "text": "All", "value": "$__all" }
-      }
-    ]
-  },
-  "time": { "from": "now-6h", "to": "now" },
-  "title": "Playkit E2E overview",
-  "uid": "playkit-overview",
-  "version": 1
-}
--- a/docs/CONSUMER.md
+++ b/docs/CONSUMER.md
@ -3,7 +3,7 @@
 ## 1. Depend on a release

 ```bash
-npm install git+https://git.levkin.ca/ilia/playkit.git#v0.1.0
+npm install git+https://git.levkin.ca/ilia/playkit.git#v0.3.0
 npm install -D @playwright/test
 npx playwright install chromium
 ```
@ -25,7 +25,8 @@ Store in Infisical `LevkinOps` / `Development` (path e.g. `/playkit/punimtag`):

 - `PLAYKIT_BASE_URL=https://punimtagdev.levkin.ca`
 - `E2E_ADMIN_EMAIL` / `E2E_ADMIN_PASSWORD` (dedicated test user — not a human’s password)
- optional `PLAYKIT_PUSHGATEWAY_URL`
+- optional `PLAYKIT_PUSHGATEWAY_URL=http://10.0.10.24:9091` (Pushgateway on the observability LXC — config lives in ansible `deploy/observability/`; scrape job + `live-playkit` Grafana board are wired, but confirm `make deploy-observability` has actually been run before turning `PLAYKIT_METRICS_ENABLED=true` on in CI)
+- for mail specs: `PLAYKIT_MAIL_PROVIDER=mailpit` (default) + `MAILPIT_BASE_URL` / `MAILPIT_USER` / `MAILPIT_PASSWORD`, or `MAILTRAP_*` for SaaS

 Sync into Gitea Actions secrets for the consumer repo.

@ -54,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`.
--- a/docs/IDEAS.md
+++ b/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.
--- a/docs/NETWORK.md
+++ b/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.
--- a/docs/OUTLINE.md
+++ b/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
+```
--- a/package.json
+++ b/package.json
@ -31,7 +31,6 @@
  },
  "files": [
    "dist",
-    "dashboards",
    "README.md",
    "ROADMAP.md",
    "LICENSE"
--- a/src/browser/index.ts
+++ b/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';
--- a/src/browser/network.test.ts
+++ b/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);
+  });
+});
--- a/src/browser/network.ts
+++ b/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);
+}
--- a/src/index.ts
+++ b/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 {