@parity/product-lab 0.0.1-placeholder → 0.1.1

package/adapters/browser/playwright/README.md

@@ -0,0 +1,214 @@
+# @product-lab/browser-playwright
+
+`PlaywrightBrowserLauncher.prerequisites()` reports the full Chromium executable from the same Playwright instance used by `launch`, its revision, executable-file access and the matching Playwright CLI path and effective browser cache. It respects `PLAYWRIGHT_BROWSERS_PATH` and starts nothing. A custom browser type or branded channel refuses inspection instead of reporting the default Chromium. The CLI regression runs this through real composition with an empty cache, a directory at the executable path, then an executable fixture, without launching either (`entrypoints/cli/tests/product-hosts.test.ts`).
+
+`pressTarget(target, key, { timeout? })` exports bounded trusted keyboard input over the browser port; the default
+timeout is 5,000 ms. `HeadlessAppSurface.press` uses it. Missing `Locator.press` refuses explicitly. An ordinary
+focusable target receives native locator focus and key input without a pointer click, so an existing enabled app
+control is preferred for document shortcuts. An unfocusable body/document target refuses by default; explicit
+`{ allowDocumentFocusClick: true }` permits a real pointer focus at a visible background point, checked before input.
+The helper excludes semantic/focusable controls, inline pointer handlers and pointer cursors and refuses if no point
+is available. Those checks cannot rule out arbitrary delegated click handlers; the opt-in records that extra gesture.
+No attributes, focusability changes or synthetic keyboard events are added to the app. Real Chromium controls are in
+`tests/keyboard.test.ts`, including cross-iframe focus, absent capability and a body covered by an app action.
+
+Disabled, inert and ordinary unfocusable targets refuse before keys can reach a previously focused document.
+
+The exported `DocumentFocusClickReceipt` is available through the optional `pressTarget` callback
+`onDocumentFocusClick`. After a successful document pointer-focus click, the helper takes its immediate bounded
+focus snapshot and awaits this callback before checking focus or sending keys. The receipt describes the executed
+native `Locator.click` command: wall-clock start/completion, timeout, requested element-relative position and the
+reproved document viewport point, document/frame URL/context, neutral-point checks and observed focus (or an explicit
+unavailable reason). It identifies delegated-handler coverage as unknown. Command evidence does not assert a captured
+browser event or invent an `isTrusted` field. The caller owns preserving the receipt; it remains available if the key
+later fails. Synchronous and asynchronous recording failures refuse clearly before the key. Ordinary focusable
+targets and refused document focus emit no receipt. The callback is optional and adds no port/provider requirement.
+
+Receipt document/frame URLs retain origin and path but remove credentials, the entire query and fragment;
+`urlSanitization` explicitly names this policy. Only receipt copies are sanitized. Exact in-memory context and
+identity/focus checks retain their original inputs; sanitization cannot make an ownership refusal pass.
+
+A failed focus snapshot still delivers the executed click receipt with coverage unavailable. Receipt metadata omits
+raw exception text that could contain private URLs; the caller receives the original thrown observation error.
+
+After awaiting the receipt callback, a document shortcut immediately rechecks raw document time origin, full URL,
+frame kind/name/origin and its internal frame-index path, together with document/body focus, before requesting keys.
+A detected navigation, same-document URL change or lost focus refuses while retaining the executed click receipt.
+The internal frame path is not public receipt metadata. Sanitized URL copies never decide this check. Separate
+locator calls cannot guarantee against an asynchronous navigation scheduled after the final check; a click receipt
+proves the successful click command, and the key string identifies the requested chord.
+
+The Browser port (`@product-lab/ports/browser`, refactor step 2)
+over Playwright's Chromium.
+
+| Class | Implements | Notes |
+| --- | --- | --- |
+| `PlaywrightBrowser` | `Browser` | Constructing it starts nothing: `await new PlaywrightBrowser({ headless }).launch()`, then `close()`. Options: `headless` (default true), `channel`, `args`, `handleSignals` (default false: the lab owns shutdown), `browserType`. Every launch runs Chromium's synthetic camera and microphone (`withSyntheticMedia`, `@product-lab/domain/devices`), first and with no option that turns them off, so no page can prompt for or take the machine's camera or microphone (22 October 2026; `tests/playwright.test.ts`) |
+| `PlaywrightBrowserLauncher` | `BrowserLauncher` | One `PlaywrightBrowser` per `launch({ headless, channel, args })`, started, with the synthetic media as every `PlaywrightBrowser`; constructor defaults for every launch. The composition root hands it to labs as `SessionContext.browsers` (imported on first launch) |
+| `PlaywrightBrowserContext` | `BrowserContext` | `newPage`, `route`, `routeWebSocket`, `addInitScript`, `close` |
+| `PlaywrightPage` | `BrowserTab` (and so `BrowserPage`) | Locators and iframe frames are Playwright's own objects, which satisfy the port structurally. `onWebSocket(listener)` (backlog item 62) reports every WebSocket the page opens, with its frames in both directions and its close, without taking part in it (`page.on("websocket")`; it also sees a socket a context `routeWebSocket` connects to its server). The truAPI CLI host adapter uses it to tell when a product connected to its host. `tests/playwright.test.ts` |
+| `PlaywrightRoute`, `PlaywrightWebSocketRoute` | `Route`, `WebSocketRoute` | Convert `Uint8Array` bodies and frames to the `Buffer` Playwright needs (a plain `Uint8Array` would be sent as `"1,2,3"`) |
+| `PageConditions` | `ConditionControl` (`@product-lab/ports/browser`, backlog 31) | `PlaywrightPage.conditions(exempt)`: one control per page, asked for before its first navigation (the browser routes only the sockets a page opens afterwards; `goto` and `reload` wait until the routes are in). The network is conditioned by routing, not the browser's offline switch, which also cuts loopback: requests and socket messages outside the `exempt` origins (the identity's local link to its host) go through the domain's `trafficDecision`, delayed or aborted, then fall back to the page's and context's other routes. A socket route has no fallback, so a conditioned socket (`ConditionedSocket`, its messages delivered in order through the domain's `ConditionedWire`) is handed to the socket route the adapter's context would have used (`PlaywrightBrowserContext.routeWebSocket` records them, newest first as Playwright does: a network guard or an endpoint bridge still decides where it goes), or connected to its server when none matches; a route given to the raw Playwright context instead is not seen. Sockets are closed when the identity goes offline. A WebSocket route (the page's, or one given to `PlaywrightBrowserContext.routeWebSocket`) makes the page's `WebSocket` Playwright's mock, whose accessors live on its parent prototype; a script that keeps the browser's natives at start, as the truAPI host's bridge does (`Object.getOwnPropertyDescriptor(WebSocket.prototype, "binaryType").set`), then throws and the app never reaches its host. `FAITHFUL_WEB_SOCKET` (`faithful-web-socket.ts`), added after the route, gives the mock's own prototype the same accessors (Playwright 1.63, truAPI host 0.23). A dedicated worker's `fetch` is routed, its WebSockets are not (Playwright 1.63), and page CPU throttling does not slow a worker: a host whose core runs in a worker conditions its chain traffic another way (a conditioned link). CPU through Chromium's `Emulation.setCPUThrottlingRate` for this page only; another browser names it in `unavailable`. `reset` puts it back online at full speed. `tests/page-conditions.test.ts` |
+| `HeadlessAppSurface` | `AppSurface` | The actor's own page as its app surface (CI, Cucumber); uses only the port, so it works over any `BrowserTab`. `read` and `waitFor` scroll the target into view and count it only on screen (`onScreen`, backlog 199: inside the view and every box that clips it), as the lab window's do; otherwise they fail naming it off screen (`tests/on-screen.test.ts`) |
+| `PlaywrightSlideRenderer` | `SlideRenderer` (`@product-lab/ports/recording`, backlog 36) | HTML to a PNG at the asked size (pixel ratio 1), transparent with `{ transparent: true }`: a demo's slide and its caption overlays. Chromium starts on the first render, a new context per render, and every request other than a `data:` URL is aborted, so a slide fetches nothing. `close()` closes the browser. `tests/slide-renderer.test.ts` |
+| `PageConsoleWatch` | `ConsoleWatch` (`@product-lab/ports/recording`, backlog 23) | `watch(document, listener)`: what an actor's app prints, from its own page (`BrowserTab.onConsole` and `onPageError`, script errors as type `pageerror`) or, for an app frame inside a host page, from the top-level page's messages whose source is the frame's origin (the host page's own are left out; an app's failed resource load reported against another origin is not attributed); a document that reports nothing is `unwatched` with the reason. Listens only. `tests/page-console-watch.test.ts` |
+| `PageFrameCapture` | `FrameCapture` (`@product-lab/ports/recording`, Phase 9) | A PNG of an actor's own page (`PlaywrightPage.screenshot`, not part of the Browser port) or of the element of the frame its app runs in (a Playwright `Frame`, as the WASM test host gives); `unavailable` with the reason for an identity with no page or a document that cannot be imaged. Reads pixels only. An environment offers it as `LabEnvironment.frames` Since the capture settle the screenshot is bounded by the recorder's limit (`capture(actor, { timeoutMs })`), else its own `timeoutMs`. A frame the app replaces while it is imaged (a check that reloads the app, backlog 110) is looked up again and imaged once more (`tests/page-frame-capture.test.ts`). |
+| `src/errors.ts` (internal) | | The adapter's edge classifier (listed in `ERROR_CLASSIFIERS`), the one module here that reads error text: `isDetached` (Playwright's words for an element or frame that left the page while it was used). Tests: `tests/errors.test.ts`, with controls (a closed page, a timeout) |
+| `PlaywrightBrowserOptions.device`, `playwrightDevices`, `deviceContextOptions` | `BrowserLaunchOptions.device` (backlog 31c) | A browser launched with a device emulates it in every context and page it opens: viewport, pixel ratio, mobile flag, touch and user agent (Chromium whatever the device is called). `playwrightDevices()` names Playwright's devices and the desktop window "Desktop" as `DeviceProfile`s; the panel keeps its own copy (an entry point does not import an adapter) and `tools/verify/tests/device-catalogues.test.ts` checks the two do not drift. `tests/devices.test.ts`: a Pixel 7 page lays out at 412×839 CSS pixels with ratio 2.625, touch and its user agent (a context's pages too); a launch without one stays 1280 wide. |
+| `pageVideo`, `PlaywrightBrowserOptions.recordVideo` | `BrowserLaunchOptions.recordVideo` (backlog 18b, headless half; 52) | A browser launched with `recordVideo: { dir }` records each page into `dir` (Playwright's own video: one file per page, from its opening to its closing, through navigations); the adapter notes when each page opened (`src/page-video.ts`, the wall clock the recordings' steps use) for pages from `newPage` and from its contexts' `newPage`; `pageVideo(target)` takes a Playwright `Page` or `Frame` or the adapter's `PlaywrightPage` (`recordedVideo()`). `tests/page-video.test.ts` `PageFrameCapture.video(actorId)` names an identity's page video (with `mediaType`). |
+| `PageFrameCapture` masks, `PageFrameCapture.accessibility`, `axeScan` | `FrameCapture.capture(actor, { mask })` and `FrameCapture.accessibility` (backlog 40) | Masks: the app's own elements a lab names by selector (`defineLab({ checks: { visual: { mask } } })`) are painted over in the screenshot (Playwright's `mask`), for a `PlaywrightPage` (`screenshot({ maskSelectors })`) or a raw `Page` or `Frame` (their own locators). Accessibility: a scan of the identity's app document with the scanner `PageFrameCaptureOptions.accessibility` names, else `axeScan`: axe-core's script is imported only when a scan runs and evaluated into the document once (through the automation channel, so the app's content security policy is not involved; the document's markup is unchanged), then `axe.run` over the whole document, violations only (or only the lab's `rules`); each finding names its rule, impact, help text and URL, and its elements as selectors (` >>> ` across frames). A document that evaluates no script is `unavailable`, with why. `tests/step-checks-browser.test.ts`: an unlabelled button found at `#publish` under `default-src 'none'`, a labelled one not, a frame inside a host page, the page unchanged; masked screenshots of a page with a random account line are the same. Settled (isolation-92b): `capture(actor, { settled })` waits until each selector matches a visible element of the app's document (its locator's `first().waitFor`), else is `unavailable` with `unsettledReason`; a captured frame says how long it waited (`settledMs`, in the check's note: "the screen settled after N ms"); the test images a page that clears its field and enables Publish 800 ms after loading: unsettled the image differs from the page at rest, settled it is the same, and `#never` is named with the wait. |
+
+```ts
+import { HeadlessAppSurface, PlaywrightBrowser } from "@product-lab/browser-playwright";
+
+const browser = await new PlaywrightBrowser({ headless: true }).launch();
+const page = await (await browser.newContext()).newPage();
+await page.goto(appUrl);
+// in an action: the visible lab window's iframe if the run supplies one, else the page
+const ui = context.ui ?? new HeadlessAppSurface(page);
+await ui.fill(ui.app.getByLabel("Note"), "Hello");
+await browser.close();
+```
+
+Host adapters (`adapters/host/*`) take a `Browser` and never import this package (adapters do not
+import each other); the caller constructs it. Playwright's own `Browser`, `BrowserContext`, `Page`,
+`Frame`, `Locator`, `Route` and `WebSocketRoute` also satisfy the port without a cast
+(`tests/structural.test.ts`, checked by `typecheck`), which is how the WASM host's verification
+target (`tools/verify/src/truapi-wasm.ts`) and an example's own launchers pass the Chromium they still
+launch themselves. Handed a raw Playwright route, pass a string or a Node `Buffer` body.
+
+`BrowserTab.networkEvidence()` observes HTTP and outgoing WebSocket traffic before the adapter's first
+navigation, across frames, reloads and opener-linked popups.
+
+By frame (C7, 6 October 2026): every finding names the CDP frame it belongs to, and its document as
+`DirectConnection.document`:
+- a page's request, by its `frameId`;
+- a worker's traffic, by the frame that started it (`TargetInfo.parentFrameId`);
+- a page's socket, by the one frame whose document its creating script is, else the one frame that loaded every script
+  on its stack, else the page's document when the page has no other frame;
+- a WebSocket's handshake `Origin`, as `DirectConnection.origin` (set by the browser; a page cannot choose it).
+  Chromium reports the handshake after the socket's creation, as a separate event: a read waits for every socket
+  already created to report it (or close, or 2 seconds), so it never lists a socket without its `Origin` (7 October
+  2026: a read between the two events failed `tests/network-evidence.test.ts` about one run in five).
+
+`observeFramesNetwork(page)` observes a page from before its first navigation, as the lab window does when it opens.
+Its `frame(name)` reads one named frame (an iframe's `name`, as a lab-window tile's) with everything inside it, the
+workers it started included. Traffic Chromium named no frame for is said as a gap, since it may be that frame's
+(`tests/network-evidence.test.ts`: two tiles, each a host page whose worker opens a socket and a fetch and frames an
+app, each tile's own and never the other's; controls: attribution from `parentFrameId` or `frameId` removed).
+`Network.setBlockedURLs` was tried as a way to block a worker's sockets (Chromium 153): it blocks a page's fetch, but
+neither a page's nor a worker's WebSocket, nor a worker's fetch. So sockets are observed and listed, never blocked, by
+this adapter. HTTP resource types identify ordinary app
+assets only for GET/HEAD requests. Chromium's automatic favicon additionally requires an `Other` GET to
+exactly `/favicon.ico` at the observed main document's origin, no query/userinfo, and native `other`
+initiation without a script stack; scripted favicon fetches and other `Other` GETs remain direct.
+A matching-origin `/@vite/client` initiator or an observed
+`vite-hmr` WebSocket handshake on the app's origin identifies development updates. An app port or token alone
+does not prove update traffic. Recognized chain reads/submissions remove a socket's development exemption
+even when its handshake or initiator claimed Vite. Everything else remains listed.
+JSON-RPC methods classify reads and submissions; binary traffic (including light clients), unavailable
+bodies and unknown methods remain opaque with coverage gaps. Payloads are classified and discarded:
+at most 65,536 bytes are inspected per payload, 20,000 findings are retained per browser, and 1,024
+concurrent sockets per target are tracked; exceeding a limit creates a visible gap.
+Retained method metadata is also bounded: at most 64 batch methods, 128 characters per identifier and
+1,024 characters for joined batch identifiers. Native RTC tracks at most 1,024 peers and 20,000 events;
+overflow emits a gap once and discards subsequent events.
+URL credentials are removed before endpoints, document attribution, details or gaps enter retention:
+userinfo is discarded, auth/session/token query values and fragments are redacted, and bare/unknown
+query keys and values are also redacted. Only an explicit set of safe field names (chain, network,
+pagination, locale, format and version/timestamp fields) retains values. The native RTC receiver sanitizes
+document URLs before crossing its binding. Protocol error strings undergo the same URL sanitization.
+URLs that differ only by removed credentials conservatively share an attribution key and may produce an
+ownership ambiguity gap. Request URLs and app behavior are unchanged.
+
+Chromium CDP observes dedicated, shared and service-worker HTTP/WebSockets.
+Browser-level target discovery attaches pages and SharedWorkers; supported per-target recursive
+auto-attachment observes each page's related frames, dedicated workers and service workers.
+A new dedicated worker is held until this observer watches it, when the browser was launched with its
+debugging port (`worker-hold.ts`, lane wasm, 6 October 2026). Playwright's own DevTools session resumes each worker
+it attaches, so a worker's first instant used to run before the observer's Network domain was on: a socket opened on
+a worker's first line was seen 11 times in 15. Only browser-level auto-attach with `waitForDebuggerOnStart` keeps a
+worker paused until every such session lets it go, and it needs flat sessions, which Playwright's CDP session does not
+route; so `WorkerHold` opens a connection of its own to the browser's debugging port and lets each worker go when the
+observer says it is watched (`release`), at once when its page is not observed, and after 3 s at the latest.
+`PlaywrightBrowser`'s `holdWorkers: true` (and `BrowserLaunchOptions.holdWorkers`) launches with
+`--remote-debugging-port=<a free port the system chose>` and `--remote-debugging-address=127.0.0.1`; the port is never
+printed or logged, and closes with the browser. A TCP port on 127.0.0.1 is reachable by every local process of every
+user on the machine, not only the lab's user, so the lab asks for it only when everything at stake is its own
+(`workerHoldPolicy` in `@product-lab/domain`: a local environment, only lab-made identities, no dot.li host, and the
+lab config does not say `workerHold: false`). Without the port, or with `holdWorkers: { off }`, the gap stays and says
+why: "Worker initialization can race another DevTools session's resume; initial traffic may be missing (worker start
+not held: the debugging port is off because <reason>)". A worker the hold did not have paused says so too ("the hold
+did not have it paused"). `tests/network-evidence.test.ts`: six held runs, each listing a socket opened on a worker's
+first line with no race gap, and an off run whose gap names its reason; held 20 of 20 against 12 of 20 without.
+SharedWorkers also need asynchronous
+discovery/attachment and are not held. Their evidence records incomplete initial worker coverage.
+Shared/service workers expose a browser context rather than a unique owning page; sessions sharing a
+context receive the observations with an attribution gap. A WebSocket without a visible page/frame
+initiator is attributed to `unknown`, with a gap. Unsupported CDP reports unsupported coverage.
+WebTransport and direct TCP/UDP endpoints remain opaque. Full Chromium additionally supplies native
+WebRTC peer/candidate events through a lab-owned `chrome://webrtc-internals` target. The observer creates
+that background target in a separate CDP context, outside consumer page/context inventory, and waits for the native
+subscription acknowledgement before creating app contexts. The target is hidden (`Target.createTarget` with
+`hidden: true`): a headed browser, such as the lab window's, shows no tab or window for it (6 October 2026: before,
+`chrome://webrtc-internals` opened as a window beside the lab window). Chromium hides a target only when remote
+debugging is on; a headless browser that refuses gets the plain background target, which nothing shows, and a headed
+one that refuses runs no tracker and says so ("WebRTC peers in the lab window are not tracked").
+Only bounded peer IDs, document URLs and
+classified candidate endpoints are retained by the observer: no SDP, ICE credentials, stats histories or RTC payloads.
+Peer creation and candidate traffic remain opaque with gaps. Chromium exposes document URL rather than
+actor/context identity; duplicate or unmatched URLs produce unknown ownership and a gap. A URL shared
+by a page and its frame also leaves that source unknown with a gap. The native
+WebUI callback changes only the diagnostic document, never app constructors, methods or source.
+
+`PlaywrightBrowser` defaults to the full `chromium` channel, including in headless mode, instead of
+Playwright's headless shell. Startup includes the extra diagnostic target load and native handshake;
+install the full Chromium distribution with Playwright. Explicit channel/browserType choices are
+preserved. Headless shell, unsupported browsers, failed native handshakes and tracker loss retain
+an explicit incomplete WebRTC coverage gap. Chromium's internal WebUI is version-specific, so a future
+incompatible interface must report unsupported coverage. Popup initialization can also race another
+DevTools session resuming it, so opener-linked popup traffic remains listed with an initial-coverage gap.
+No request or frame is intercepted or altered. Newly attached targets briefly wait until `Network.enable`
+and resume immediately. The observer also retains explicit gaps if that instrumentation fails.
+Global discovery or recursive auto-attachment failure keeps page/worker coverage incomplete even when a manually
+attached page still supplies partial network observations.
+Temporary page-discovery sessions are cleaned up independently of the persistent network observer.
+Closing a page or browser during that cleanup is tolerated. A cleanup error while the page and browser
+remain active becomes a sanitized gap for that page's evidence handle; observation continues and other
+pages do not inherit it.
+
+For consumers adopting raw Playwright objects, call `await PlaywrightPage.observe(page)` before first
+navigation, or `await PlaywrightBrowserContext.observe(context)` before creating pages. The wrappers'
+`goto()` waits for observation setup. Adopting an already loaded page reports its missing initial coverage.
+
+Tests (`tests/playwright.test.ts`, `tests/page-frame-capture.test.ts`, `tests/network-evidence.test.ts`) run Playwright's installed headless Chromium, as
+`entrypoints/panel`'s tests do, against a loopback fixture on an ephemeral `127.0.0.1` port (the WebSocket route on the port after it is intercepted, never bound).
+
+| | |
+| --- | --- |
+| Nx project | `browser-playwright` |
+| Tags | `scope:provider`, `type:adapter` |
+| Exports | `src/index.ts`: `PlaywrightBrowser`, `PlaywrightBrowserOptions`, `PlaywrightBrowserLauncher`, `PlaywrightBrowserContext`, `PlaywrightPage`, `PlaywrightRoute`, `PlaywrightWebSocketRoute`, `HeadlessAppSurface`, `PageFrameCapture`, `PageFrameCaptureOptions`, `PageConsoleWatch`, `PageConditions`, `PlaywrightSlideRenderer`, `pageVideo`, `axeScan`, `playwrightDevices`, `deviceContextOptions` |
+| Depends on | `@product-lab/ports`, `@product-lab/domain` (types of `recordings/` and `checks/`), `playwright` 1.63.0, `axe-core` 4.13.0 (see "Licences") |
+| Used by | the composition root (`SessionContext.browsers`); `examples/notes` (`HeadlessAppSurface`) and its E2E tests; `examples/minimal` and `examples/counter-contract`; `tools/verify` (`src/truapi-cli.ts`); the agent eval's reference solution through the umbrella subpath `@parity/product-lab/browser-playwright`; host adapters take the port instead |
+
+Contract kit: `tests/contract.test.ts` runs the [browser contract kit](../../../contracts/browser/README.md) on headless Chromium, declaring every capability (origin on an ephemeral `127.0.0.1` port, bound in `before`), plus four negative controls that must fail it.
+
+Tests: `bunx nx run browser-playwright:test` (each test is bounded at 60 s, `--test-timeout=60000`, so a hang fails with the test named instead of blocking the gate; the slowest test took about 11 s on 28 September 2026); the structural check runs in `bunx nx run browser-playwright:typecheck`.
+
+Private, workspace-only package. Consumers will install the single umbrella package
+`@parity/product-lab` (`@parity/product-lab/browser-playwright`) once it is published.
+
+## Licences
+
+This package is Apache-2.0. `axe-core` (Deque Systems) is MPL-2.0: it is an unmodified dependency, installed
+from npm as published and imported only when an accessibility scan runs (`src/axe-scan.ts`); its files are not
+copied into or changed in this repository. MPL-2.0 is file-level copyleft, so using it unmodified places no
+condition on this package's own files; a distribution of axe-core itself keeps its licence and source notice
+(the npm package carries both). The user approved it for backlog 40, through the coordinator.
+
+## Selected browser permissions and passive errors (1 October 2026)
+
+`newContext({ permissions })` and `newPage({ permissions })` forward explicit permissions to the selected Playwright context. `onPageError(listener)` observes the original error message and returns a disposer; it does not change the app or its error handling. Consumers redact diagnostic strings before persistence. The Chromium controls exercise camera/microphone grants and listener disposal in `tests/playwright.test.ts`. An example's companion launchers receive `SessionContext.browsers` rather than constructing an independent browser.
+
+The native RTC connection fixture also closes its own browser when Node cancels its test. The test runner deadline alone does not interrupt an outstanding browser evaluation; the cancellation cleanup keeps a failed connection attempt from leaving that browser and test process alive. The original connection, privacy and ownership assertions remain in place.

package/adapters/browser/playwright/src/axe-scan.d.ts

@@ -0,0 +1,6 @@
+import type { AccessibilityScan, UnavailableFrame } from "@parity/product-lab/ports/recording";
+/** Scan `document` (the adapter's `PlaywrightPage`, or a Playwright `Page` or `Frame`) with axe-core. */
+export declare function axeScan(document: object, options?: {
+    rules?: readonly string[];
+    signal?: AbortSignal;
+}): Promise<AccessibilityScan | UnavailableFrame>;

package/adapters/browser/playwright/src/axe-scan.js

@@ -0,0 +1,41 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { PlaywrightPage } from "./playwright-page.js";
+const evaluating = (value) => "evaluate" in value && typeof value.evaluate === "function";
+const scanScript = (rules) => `(async () => {
+  const options = { resultTypes: ["violations"]${rules ? `, runOnly: { type: "rule", values: ${JSON.stringify(rules)} }` : ""} };
+  const result = await window.axe.run(document, options);
+  const selector = (target) => (Array.isArray(target) ? target.map(selector).join(" >>> ") : String(target));
+  return {
+    version: window.axe.version,
+    violations: result.violations.map((item) => ({ id: item.id, impact: item.impact ?? null, help: item.help, helpUrl: item.helpUrl, targets: item.nodes.map((node) => selector(node.target)) })),
+  };
+})()`;
+const IMPACTS = ["minor", "moderate", "serious", "critical"];
+export async function axeScan(document, options = {}) {
+    options.signal?.throwIfAborted();
+    const script = (source) => (document instanceof PlaywrightPage ? document.evaluateScript(source) : document.evaluate(source));
+    if (!(document instanceof PlaywrightPage) && !evaluating(document))
+        return { status: "unavailable", reason: "The app document cannot run a scan (it evaluates no script)" };
+    try {
+        if (!(await script(`typeof window.axe === "object"`))) {
+            const axe = (await import("axe-core")).default;
+            await script(axe.source);
+        }
+        options.signal?.throwIfAborted();
+        const { version, violations } = (await script(scanScript(options.rules)));
+        const findings = violations.map((item) => ({
+            rule: item.id,
+            ...(item.impact && IMPACTS.includes(item.impact) ? { impact: item.impact } : {}),
+            description: item.help,
+            targets: item.targets,
+            help: item.helpUrl,
+        }));
+        return { status: "scanned", scanner: `axe-core ${version}`, findings };
+    }
+    catch (error) {
+        if (options.signal?.aborted)
+            throw error;
+        return { status: "unavailable", reason: `The accessibility scan failed: ${error.message}` };
+    }
+}

package/adapters/browser/playwright/src/bytes.d.ts

@@ -0,0 +1 @@
+export declare function toBuffer(bytes: Uint8Array): Buffer;

package/adapters/browser/playwright/src/bytes.js

@@ -0,0 +1,5 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export function toBuffer(bytes) {
+    return Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}

package/adapters/browser/playwright/src/conditioned-socket.d.ts

@@ -0,0 +1,28 @@
+import type { WebSocketRoute as PlaywrightSocket } from "playwright";
+import type { WebSocketRoute } from "@parity/product-lab/ports/browser";
+/** Hands one message on, now, later or never, as the identity's network condition decides. */
+export type Deliver = (direction: "up" | "down", message: string | Uint8Array, send: () => void) => void;
+/**
+ * A page's socket with the identity's network condition on every message, both ways (backlog 31). Whoever handles it
+ * (the context's own socket route, or nobody) sees the port's `WebSocketRoute`: what the page sends reaches its
+ * `onMessage` handler through the condition, what it sends to the page reaches the page the same way. Connecting
+ * to the server relays both directions explicitly, so none of them bypasses the condition.
+ */
+export declare class ConditionedSocket implements WebSocketRoute {
+    private readonly raw;
+    private readonly deliver;
+    private readonly page;
+    /** Playwright keeps one close handler per socket; the page's close reaches every one given here. */
+    private readonly closes;
+    constructor(raw: PlaywrightSocket, deliver: Deliver);
+    url(): string;
+    onMessage(handler: (message: string | Uint8Array) => unknown): void;
+    onClose(handler: (code: number | undefined, reason: string | undefined) => unknown): void;
+    send(message: string | Uint8Array): void;
+    close(options?: {
+        code?: number;
+        reason?: string;
+    }): Promise<void>;
+    /** The page connected to the socket's own URL, every message relayed through the condition. */
+    connectToServer(): WebSocketRoute;
+}

package/adapters/browser/playwright/src/conditioned-socket.js

@@ -0,0 +1,40 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { PlaywrightWebSocketRoute } from "./playwright-web-socket-route.js";
+export class ConditionedSocket {
+    raw;
+    deliver;
+    page;
+    closes = [];
+    constructor(raw, deliver) {
+        this.raw = raw;
+        this.deliver = deliver;
+        this.page = new PlaywrightWebSocketRoute(raw);
+    }
+    url() {
+        return this.page.url();
+    }
+    onMessage(handler) {
+        this.page.onMessage((message) => this.deliver("up", message, () => {
+            handler(message);
+        }));
+    }
+    onClose(handler) {
+        if (this.closes.push(handler) === 1)
+            this.page.onClose((code, reason) => this.closes.forEach((close) => close(code, reason)));
+    }
+    send(message) {
+        this.deliver("down", message, () => this.page.send(message));
+    }
+    close(options) {
+        return this.page.close(options);
+    }
+    connectToServer() {
+        const server = new PlaywrightWebSocketRoute(this.raw.connectToServer());
+        this.onMessage((message) => server.send(message));
+        server.onMessage((message) => this.send(message));
+        this.onClose((code, reason) => void server.close({ code, reason }).catch(() => undefined));
+        server.onClose((code, reason) => void this.page.close({ code, reason }).catch(() => undefined));
+        return server;
+    }
+}

package/adapters/browser/playwright/src/devices.d.ts

@@ -0,0 +1,14 @@
+import { type DeviceProfile } from "@parity/product-lab/domain/devices";
+/** Every named device: the desktop window, then Playwright's registry (landscape variants included). */
+export declare function playwrightDevices(): Readonly<Record<string, DeviceProfile>>;
+/** The browser context options that emulate `profile` (fixed for the context's life). */
+export declare function deviceContextOptions(profile: DeviceProfile): {
+    userAgent?: string | undefined;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    deviceScaleFactor: number;
+    isMobile: boolean;
+    hasTouch: boolean;
+};

package/adapters/browser/playwright/src/devices.js

@@ -0,0 +1,24 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { devices } from "playwright";
+import { DESKTOP_DEVICE } from "@parity/product-lab/domain/devices";
+let catalogue;
+export function playwrightDevices() {
+    catalogue ??= Object.freeze({
+        [DESKTOP_DEVICE.name]: DESKTOP_DEVICE,
+        ...Object.fromEntries(Object.entries(devices).map(([name, device]) => [
+            name,
+            { name, viewport: { ...device.viewport }, deviceScaleFactor: device.deviceScaleFactor, mobile: device.isMobile, touch: device.hasTouch, userAgent: device.userAgent },
+        ])),
+    });
+    return catalogue;
+}
+export function deviceContextOptions(profile) {
+    return {
+        viewport: { ...profile.viewport },
+        deviceScaleFactor: profile.deviceScaleFactor,
+        isMobile: profile.mobile,
+        hasTouch: profile.touch,
+        ...(profile.userAgent ? { userAgent: profile.userAgent } : {}),
+    };
+}

package/adapters/browser/playwright/src/errors.d.ts

@@ -0,0 +1,2 @@
+/** Whether `error` says the element or frame being used went away (Playwright's own words). */
+export declare function isDetached(error: unknown): boolean;

package/adapters/browser/playwright/src/errors.js

@@ -0,0 +1,6 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+const DETACHED = /not attached to the DOM|frame (?:was|got) detached/i;
+export function isDetached(error) {
+    return DETACHED.test(error instanceof Error ? error.message : String(error));
+}

package/adapters/browser/playwright/src/evidence-url.d.ts

@@ -0,0 +1,4 @@
+/** Evidence keeps endpoint shape and explicitly safe query fields, never URL credentials. */
+export declare function evidenceUrl(value: string): string;
+/** Protocol errors may include URLs; sanitize them before retaining a gap/detail. */
+export declare function evidenceText(value: string): string;

package/adapters/browser/playwright/src/evidence-url.js

@@ -0,0 +1,29 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export function evidenceUrl(value) {
+    try {
+        const url = new URL(value);
+        url.username = "";
+        url.password = "";
+        const safe = new Set(["chain", "network", "page", "limit", "offset", "lang", "locale", "format", "version", "v", "t", "timestamp"]);
+        const credentials = new Set(["token", "accesstoken", "refreshtoken", "idtoken", "auth", "authorization", "session", "sessionid", "secret", "password", "passwd", "credential", "credentials", "apikey", "csrf", "csrftoken", "jwt", "sid", "sig", "signature", "code"]);
+        const query = new URLSearchParams();
+        for (const [key, value] of url.searchParams) {
+            const normalized = key.toLowerCase().replace(/[_-]/g, "");
+            if (safe.has(normalized) && value)
+                query.append(key, value);
+            else
+                query.append(credentials.has(normalized) ? key : "[redacted]", "[redacted]");
+        }
+        url.search = query.toString();
+        if (url.hash)
+            url.hash = "[redacted]";
+        return url.href;
+    }
+    catch {
+        return "[unparseable endpoint]";
+    }
+}
+export function evidenceText(value) {
+    return value.replace(/\b[a-z][a-z0-9+.-]*:\/\/[^\s"'<>]+/gi, evidenceUrl);
+}

package/adapters/browser/playwright/src/faithful-web-socket.d.ts

@@ -0,0 +1,2 @@
+/** The page script: installed after the page's WebSocket route, before its first navigation. */
+export declare const FAITHFUL_WEB_SOCKET = "(() => {\n  const WebSocketClass = globalThis.WebSocket;\n  if (!WebSocketClass || Object.getOwnPropertyDescriptor(WebSocketClass.prototype, \"binaryType\")) return;\n  for (let proto = Object.getPrototypeOf(WebSocketClass.prototype); proto && proto !== EventTarget.prototype && proto !== Object.prototype; proto = Object.getPrototypeOf(proto))\n    for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(proto)))\n      if (key !== \"constructor\" && !Object.prototype.hasOwnProperty.call(WebSocketClass.prototype, key)) Object.defineProperty(WebSocketClass.prototype, key, descriptor);\n})();";

package/adapters/browser/playwright/src/faithful-web-socket.js

@@ -0,0 +1,9 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export const FAITHFUL_WEB_SOCKET = `(() => {
+  const WebSocketClass = globalThis.WebSocket;
+  if (!WebSocketClass || Object.getOwnPropertyDescriptor(WebSocketClass.prototype, "binaryType")) return;
+  for (let proto = Object.getPrototypeOf(WebSocketClass.prototype); proto && proto !== EventTarget.prototype && proto !== Object.prototype; proto = Object.getPrototypeOf(proto))
+    for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(proto)))
+      if (key !== "constructor" && !Object.prototype.hasOwnProperty.call(WebSocketClass.prototype, key)) Object.defineProperty(WebSocketClass.prototype, key, descriptor);
+})();`;

package/adapters/browser/playwright/src/free-loopback-port.d.ts

@@ -0,0 +1,2 @@
+/** A port the OS gives on 127.0.0.1, free when this returns (a browser's debugging port, `worker-hold.ts`). */
+export declare function freeLoopbackPort(): Promise<number>;

package/adapters/browser/playwright/src/free-loopback-port.js

@@ -0,0 +1,13 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { createServer } from "node:net";
+export function freeLoopbackPort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            server.close(() => (typeof address === "object" && address ? resolve(address.port) : reject(new Error("The OS gave no port on 127.0.0.1"))));
+        });
+    });
+}

package/adapters/browser/playwright/src/headless-app-surface.d.ts

@@ -0,0 +1,30 @@
+import type { AppSurface, BrowserTab, Locator, LocatorRoot } from "@parity/product-lab/ports/browser";
+/**
+ * The actor's own page as its app surface, for CI and Cucumber: the same
+ * action code as the visible lab window, with nobody watching. Works over any
+ * `BrowserTab` (it uses only the port); it lives here because ports hold no
+ * behaviour.
+ */
+export declare class HeadlessAppSurface implements AppSurface {
+    private readonly page;
+    readonly mode: "headless";
+    constructor(page: LocatorRoot & Pick<BrowserTab, "reload">);
+    get app(): LocatorRoot;
+    click(target: Locator): Promise<void>;
+    fill(target: Locator, text: string): Promise<void>;
+    press(target: Locator, key: string, options?: {
+        allowDocumentFocusClick?: boolean;
+    }): Promise<void>;
+    read(target: Locator): Promise<string>;
+    waitFor(target: Locator, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    reload(): Promise<void>;
+}
+/**
+ * Backlog 199 (8 October 2026), the rule for every screen read: a check passes only on what a person can see. The target
+ * is scrolled into view (nearest edge: nothing moves when it is in view already), as the lab window's reads do
+ * (`spotInFrame`), and counts only once at least part of it is inside the viewport and every box around it that clips
+ * (overflow other than visible); otherwise the read fails, naming it off screen.
+ */
+export declare function onScreen(target: Locator, timeout: number): Promise<void>;

package/adapters/browser/playwright/src/headless-app-surface.js

@@ -0,0 +1,68 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { pressTarget } from "./press-target.js";
+export class HeadlessAppSurface {
+    page;
+    mode = "headless";
+    constructor(page) {
+        this.page = page;
+    }
+    get app() {
+        return this.page;
+    }
+    click(target) {
+        return target.click();
+    }
+    fill(target, text) {
+        return target.fill(text);
+    }
+    async press(target, key, options = {}) {
+        await pressTarget(target, key, options);
+    }
+    async read(target) {
+        await onScreen(target, READ_BOUND_MS);
+        return ((await target.textContent()) ?? "").trim();
+    }
+    async waitFor(target, options = {}) {
+        await target.waitFor({ state: "visible", ...options });
+        await onScreen(target, options.timeout ?? READ_BOUND_MS);
+    }
+    async reload() {
+        await this.page.reload();
+    }
+}
+const READ_BOUND_MS = 10_000;
+export async function onScreen(target, timeout) {
+    const deadline = Date.now() + timeout;
+    for (;;) {
+        let reason;
+        try {
+            reason = await offScreen(target, 2_000);
+        }
+        catch (error) {
+            reason = error instanceof Error ? error.message : String(error);
+        }
+        if (reason === undefined)
+            return;
+        if (Date.now() >= deadline)
+            throw new Error(`The screen read's target is not where a person can see it: ${reason}`);
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+}
+async function offScreen(target, timeout) {
+    await target.scrollIntoViewIfNeeded({ timeout });
+    return target.evaluate((element) => {
+        const rect = element.getBoundingClientRect();
+        let outer = { top: 0, left: 0, bottom: window.innerHeight, right: window.innerWidth };
+        for (let box = element.parentElement;; box = box.parentElement) {
+            if (!(rect.bottom > outer.top && rect.top < outer.bottom && rect.right > outer.left && rect.left < outer.right))
+                return `it is off screen at (${Math.round(rect.left)}, ${Math.round(rect.top)}), outside ${box === element.parentElement ? "the view" : "a box that clips it"} (${Math.round(outer.left)}-${Math.round(outer.right)} x ${Math.round(outer.top)}-${Math.round(outer.bottom)} px; the view is ${window.innerWidth}x${window.innerHeight})`;
+            if (!box)
+                return undefined;
+            const style = getComputedStyle(box);
+            if (style.overflowX === "visible" && style.overflowY === "visible")
+                continue;
+            outer = box.getBoundingClientRect();
+        }
+    }, undefined, { timeout });
+}

package/adapters/browser/playwright/src/index.d.ts

@@ -0,0 +1,16 @@
+export { PlaywrightBrowser, type PlaywrightBrowserOptions } from "./playwright-browser.js";
+export { PlaywrightBrowserLauncher } from "./playwright-browser-launcher.js";
+export { PlaywrightBrowserContext } from "./playwright-browser-context.js";
+export { PlaywrightPage } from "./playwright-page.js";
+export { observeFramesNetwork } from "./network-evidence.js";
+export { PlaywrightRoute } from "./playwright-route.js";
+export { PlaywrightWebSocketRoute } from "./playwright-web-socket-route.js";
+export { HeadlessAppSurface } from "./headless-app-surface.js";
+export { pressTarget, type DocumentFocusClickReceipt } from "./press-target.js";
+export { PageFrameCapture, type PageFrameCaptureOptions } from "./page-frame-capture.js";
+export { axeScan } from "./axe-scan.js";
+export { deviceContextOptions, playwrightDevices } from "./devices.js";
+export { PageConsoleWatch } from "./page-console-watch.js";
+export { PageConditions } from "./page-conditions.js";
+export { pageVideo } from "./page-video.js";
+export { PlaywrightSlideRenderer } from "./playwright-slide-renderer.js";

package/adapters/browser/playwright/src/index.js

@@ -0,0 +1,18 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export { PlaywrightBrowser } from "./playwright-browser.js";
+export { PlaywrightBrowserLauncher } from "./playwright-browser-launcher.js";
+export { PlaywrightBrowserContext } from "./playwright-browser-context.js";
+export { PlaywrightPage } from "./playwright-page.js";
+export { observeFramesNetwork } from "./network-evidence.js";
+export { PlaywrightRoute } from "./playwright-route.js";
+export { PlaywrightWebSocketRoute } from "./playwright-web-socket-route.js";
+export { HeadlessAppSurface } from "./headless-app-surface.js";
+export { pressTarget } from "./press-target.js";
+export { PageFrameCapture } from "./page-frame-capture.js";
+export { axeScan } from "./axe-scan.js";
+export { deviceContextOptions, playwrightDevices } from "./devices.js";
+export { PageConsoleWatch } from "./page-console-watch.js";
+export { PageConditions } from "./page-conditions.js";
+export { pageVideo } from "./page-video.js";
+export { PlaywrightSlideRenderer } from "./playwright-slide-renderer.js";