@parity/product-lab 0.0.1-placeholder → 0.1.1

package/adapters/browser/playwright/src/page-conditions.js

@@ -0,0 +1,81 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { ONLINE, isLocalLink, trafficDecision } from "@parity/product-lab/domain/conditions";
+import { ConditionedSocket } from "./conditioned-socket.js";
+import { FAITHFUL_WEB_SOCKET } from "./faithful-web-socket.js";
+import { WireDelivery } from "./wire-delivery.js";
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const size = (message) => (typeof message === "string" ? Buffer.byteLength(message) : message.byteLength);
+export class PageConditions {
+    page;
+    routes;
+    unavailable;
+    condition = ONLINE;
+    exempt;
+    routing;
+    get ready() {
+        return this.routing;
+    }
+    cdp;
+    slowed = false;
+    sockets = new Set();
+    constructor(page, 
+    exempt, 
+    routes) {
+        this.page = page;
+        this.routes = routes;
+        this.exempt = typeof exempt === "function" ? exempt : () => exempt;
+        const chromium = page.context().browser()?.browserType().name() === "chromium";
+        if (!chromium)
+            this.unavailable = { cpu: "this browser cannot slow one page's CPU (only Chromium's can)" };
+        this.routing = this.route();
+    }
+    async network(condition) {
+        this.condition = condition;
+        await this.routing;
+        if (condition.kind === "offline")
+            for (const socket of [...this.sockets])
+                await socket.close({ code: 1001, reason: "offline" }).catch(() => undefined);
+    }
+    async cpu(slowdown) {
+        if (this.unavailable?.cpu)
+            throw new Error(this.unavailable.cpu);
+        const session = await (this.cdp ??= this.page.context().newCDPSession(this.page));
+        await session.send("Emulation.setCPUThrottlingRate", { rate: slowdown });
+        this.slowed = slowdown !== 1;
+    }
+    async reset() {
+        this.condition = ONLINE;
+        if (this.slowed)
+            await this.cpu(1);
+    }
+    async route() {
+        await this.page.route("**/*", async (route) => {
+            const request = route.request();
+            const decision = trafficDecision(this.condition, { url: request.url(), kind: "request", bytes: request.postDataBuffer()?.byteLength ?? 0 }, this.exempt());
+            if (decision.action === "abort")
+                return route.abort("internetdisconnected");
+            if (decision.action === "delay")
+                await sleep(decision.ms);
+            return route.fallback();
+        });
+        await this.page.routeWebSocket((url) => !isLocalLink(url.href, this.exempt()), (socket) => this.socket(socket));
+        await this.page.addInitScript({ content: FAITHFUL_WEB_SOCKET });
+    }
+    async socket(raw) {
+        const url = raw.url();
+        if (this.condition.kind === "offline") {
+            await raw.close({ code: 1001, reason: "offline" }).catch(() => undefined);
+            return;
+        }
+        const wires = { up: new WireDelivery("up"), down: new WireDelivery("down") };
+        const socket = new ConditionedSocket(raw, (direction, message, send) => wires[direction].push(this.condition, size(message), send));
+        this.sockets.add(socket);
+        socket.onClose(() => this.sockets.delete(socket));
+        const handler = this.routes?.handlerOf(url);
+        if (handler)
+            await handler(socket);
+        else
+            socket.connectToServer();
+    }
+}

package/adapters/browser/playwright/src/page-console-watch.d.ts

@@ -0,0 +1,12 @@
+import type { ConsoleMessage } from "@parity/product-lab/ports/browser";
+export declare class PageConsoleWatch {
+    /**
+     * Listen to what `document` prints: console messages with the browser's type, uncaught script errors as type
+     * `pageerror`. Returns the disposer, or why this document cannot be watched.
+     */
+    static watch(document: object, listener: (message: ConsoleMessage) => void, now?: () => number): {
+        stop: () => void;
+    } | {
+        unwatched: string;
+    };
+}

package/adapters/browser/playwright/src/page-console-watch.js

@@ -0,0 +1,43 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+const observing = (value) => "onConsole" in value && typeof value.onConsole === "function" && "onPageError" in value && typeof value.onPageError === "function";
+const framed = (value) => "page" in value && typeof value.page === "function" && "url" in value && typeof value.url === "function";
+const originOf = (url) => {
+    if (!URL.canParse(url))
+        return undefined;
+    const origin = new URL(url).origin;
+    return origin === "null" ? undefined : origin;
+};
+export class PageConsoleWatch {
+    static watch(document, listener, now = Date.now) {
+        if (observing(document)) {
+            const stops = [document.onConsole(listener), document.onPageError((text) => listener({ type: "pageerror", text, at: now() }))];
+            return { stop: () => stops.forEach((stop) => stop()) };
+        }
+        if (framed(document)) {
+            const page = document.page();
+            const mine = (url) => {
+                const origin = originOf(document.url());
+                return origin !== undefined && originOf(url) === origin;
+            };
+            const console = (message) => {
+                if (mine(message.location().url))
+                    listener({ type: message.type(), text: message.text(), at: now() });
+            };
+            const pageError = (error) => {
+                const origin = originOf(document.url());
+                if (origin && (error.stack ?? "").includes(origin))
+                    listener({ type: "pageerror", text: error.message, at: now() });
+            };
+            page.on("console", console);
+            page.on("pageerror", pageError);
+            return {
+                stop: () => {
+                    page.off("console", console);
+                    page.off("pageerror", pageError);
+                },
+            };
+        }
+        return { unwatched: "the app's document reports no console messages to the lab" };
+    }
+}

package/adapters/browser/playwright/src/page-frame-capture.d.ts

@@ -0,0 +1,32 @@
+import type { FrameMedia } from "@parity/product-lab/domain/recordings";
+import type { AccessibilityScan, CaptureOptions, CapturedFrame, CapturedVideo, FrameCapture, UnavailableFrame } from "@parity/product-lab/ports/recording";
+export interface PageFrameCaptureOptions {
+    /** The document identity `actorId`'s app runs in (a Playwright `Page` or `Frame`), or undefined when it has none. */
+    pages: (actorId: string) => object | undefined;
+    /** Whether the pages' browser uses a synthetic camera and microphone (default `unknown`). */
+    media?: FrameMedia;
+    /** How long one screenshot may take when the recorder names no limit (default 5000 ms). */
+    timeoutMs?: number;
+    /** Scans one app document for accessibility (backlog 40); absent: axe-core (`axeScan`), imported only when a scan runs. */
+    accessibility?: (document: object, options: {
+        rules?: readonly string[];
+        signal?: AbortSignal;
+    }) => Promise<AccessibilityScan | UnavailableFrame>;
+}
+export declare class PageFrameCapture implements FrameCapture {
+    private readonly options;
+    readonly source = "headless-page";
+    readonly media: FrameMedia;
+    constructor(options: PageFrameCaptureOptions);
+    capture(actorId: string, options?: CaptureOptions): Promise<CapturedFrame | UnavailableFrame>;
+    /**
+     * An accessibility scan of the identity's app document (backlog 40), with the scanner the environment gives
+     * (`PageFrameCaptureOptions.accessibility`) or axe-core.
+     */
+    accessibility(actorId: string, options?: {
+        rules?: readonly string[];
+        signal?: AbortSignal;
+    }): Promise<AccessibilityScan | UnavailableFrame>;
+    /** The video of the identity's page, when its browser records video (`PlaywrightBrowserOptions.recordVideo`). */
+    video(actorId: string): Promise<CapturedVideo | undefined>;
+}

package/adapters/browser/playwright/src/page-frame-capture.js

@@ -0,0 +1,87 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { unsettledReason } from "@parity/product-lab/domain/checks";
+import { axeScan } from "./axe-scan.js";
+import { isDetached } from "./errors.js";
+import { pageVideo } from "./page-video.js";
+import { PlaywrightPage } from "./playwright-page.js";
+const locating = (value) => "locator" in value && typeof value.locator === "function";
+async function settle(document, settled) {
+    const started = Date.now();
+    for (const selector of settled.selectors) {
+        const left = Math.max(1, settled.timeoutMs - (Date.now() - started));
+        try {
+            await document.locator(selector).first().waitFor({ state: "visible", timeout: left });
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "TimeoutError")
+                return unsettledReason(selector, settled.timeoutMs);
+            throw error;
+        }
+    }
+    return undefined;
+}
+const screenshots = (value) => "screenshot" in value && typeof value.screenshot === "function";
+const framed = (value) => "frameElement" in value && typeof value.frameElement === "function";
+export class PageFrameCapture {
+    options;
+    source = "headless-page";
+    media;
+    constructor(options) {
+        this.options = options;
+        this.media = options.media ?? "unknown";
+    }
+    async capture(actorId, options = {}) {
+        options.signal?.throwIfAborted();
+        const page = this.options.pages(actorId);
+        if (!page)
+            return { status: "unavailable", reason: `No page is open for identity ${actorId}` };
+        let settled = {};
+        if (options.settled?.selectors.length) {
+            if (!locating(page))
+                return { status: "unavailable", reason: `Identity ${actorId}'s app document cannot be waited on (no locators)` };
+            const started = Date.now();
+            const unsettled = await settle(page, options.settled);
+            if (unsettled)
+                return { status: "unavailable", reason: unsettled };
+            settled = { settledMs: Date.now() - started };
+            options.signal?.throwIfAborted();
+        }
+        const shot = { type: "png", caret: "hide", timeout: options.timeoutMs ?? this.options.timeoutMs ?? 5000 };
+        if (options.mask?.length) {
+            if (page instanceof PlaywrightPage)
+                shot.maskSelectors = options.mask;
+            else if (locating(page))
+                shot.mask = options.mask.map((selector) => page.locator(selector));
+            else
+                return { status: "unavailable", reason: `Identity ${actorId}'s app document cannot paint over elements (no locators)` };
+        }
+        const image = async (document) => screenshots(document) ? new Uint8Array(await document.screenshot(shot)) : framed(document) ? new Uint8Array(await (await document.frameElement()).screenshot(shot)) : undefined;
+        let bytes;
+        try {
+            bytes = await image(page);
+        }
+        catch (error) {
+            const again = isDetached(error) ? this.options.pages(actorId) : undefined;
+            if (!again)
+                throw error;
+            options.signal?.throwIfAborted();
+            bytes = await image(again);
+        }
+        if (bytes)
+            return { status: "captured", mediaType: "image/png", bytes, ...settled };
+        return { status: "unavailable", reason: `Identity ${actorId}'s app document offers no image capture` };
+    }
+    async accessibility(actorId, options = {}) {
+        options.signal?.throwIfAborted();
+        const page = this.options.pages(actorId);
+        if (!page)
+            return { status: "unavailable", reason: `No page is open for identity ${actorId}` };
+        return (this.options.accessibility ?? axeScan)(page, options);
+    }
+    async video(actorId) {
+        const page = this.options.pages(actorId);
+        const video = page ? await pageVideo(page) : undefined;
+        return video ? { ...video, mediaType: "video/webm" } : undefined;
+    }
+}

package/adapters/browser/playwright/src/page-video.d.ts

@@ -0,0 +1,15 @@
+import type { BrowserContext, Page } from "playwright";
+/** Note when `page` opened (a page made outside a watched context: `Browser.newPage`). */
+export declare function pageOpened(page: Page, at: number): void;
+/** Note when each page of `context` opens. */
+export declare function watchPageVideos(context: BrowserContext): void;
+export interface PageVideo {
+    name: string;
+    openedAt: number;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}
+/** The video `target` (a Page, a Frame or the adapter's page) is recorded into: its file name, when its page opened, its size. */
+export declare function pageVideo(target: object): Promise<PageVideo | undefined>;

package/adapters/browser/playwright/src/page-video.js

@@ -0,0 +1,25 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { basename } from "node:path";
+const opened = new WeakMap();
+export function pageOpened(page, at) {
+    if (!opened.has(page))
+        opened.set(page, at);
+}
+export function watchPageVideos(context) {
+    context.on("page", (page) => pageOpened(page, Date.now()));
+}
+const isPage = (value) => "video" in value && typeof value.video === "function";
+const isFrame = (value) => "page" in value && typeof value.page === "function";
+const isWrapped = (value) => "recordedVideo" in value && typeof value.recordedVideo === "function";
+export async function pageVideo(target) {
+    if (isWrapped(target))
+        return target.recordedVideo();
+    const page = isPage(target) ? target : isFrame(target) ? target.page() : undefined;
+    const video = page?.video();
+    const openedAt = page ? opened.get(page) : undefined;
+    if (!page || !video || openedAt === undefined)
+        return undefined;
+    const viewport = page.viewportSize();
+    return { name: basename(await video.path()), openedAt, ...(viewport ? { viewport } : {}) };
+}

package/adapters/browser/playwright/src/playwright-browser-context.d.ts

@@ -0,0 +1,20 @@
+import type { BrowserContext as PlaywrightContext } from "playwright";
+import type { BrowserContext, BrowserTab, RouteHandler, WebSocketRoute } from "@parity/product-lab/ports/browser";
+/** An isolated browser profile (the port's `BrowserContext`) over Playwright's. */
+export declare class PlaywrightBrowserContext implements BrowserContext {
+    private readonly context;
+    /** The socket routes given here, so a page's conditions hand each socket on to the one that decides it. */
+    private readonly sockets;
+    /** The faithful WebSocket prototype, installed with the context's first socket route. */
+    private faithful;
+    constructor(context: PlaywrightContext);
+    /** Install passive observation on a raw context before it opens an app page. */
+    static observe(context: PlaywrightContext): Promise<PlaywrightBrowserContext>;
+    newPage(): Promise<BrowserTab>;
+    route(url: string, handler: RouteHandler): Promise<unknown>;
+    routeWebSocket(url: string | ((url: URL) => boolean), handler: (socket: WebSocketRoute) => unknown): Promise<unknown>;
+    addInitScript(script: {
+        content: string;
+    }): Promise<unknown>;
+    close(): Promise<void>;
+}

package/adapters/browser/playwright/src/playwright-browser-context.js

@@ -0,0 +1,44 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { PlaywrightPage } from "./playwright-page.js";
+import { PlaywrightRoute } from "./playwright-route.js";
+import { PlaywrightWebSocketRoute } from "./playwright-web-socket-route.js";
+import { prepareNetworkObservation } from "./network-evidence.js";
+import { SocketRoutes } from "./socket-routes.js";
+import { FAITHFUL_WEB_SOCKET } from "./faithful-web-socket.js";
+export class PlaywrightBrowserContext {
+    context;
+    sockets = new SocketRoutes();
+    faithful;
+    constructor(context) {
+        this.context = context;
+    }
+    static async observe(context) {
+        const browser = context.browser();
+        if (browser)
+            await prepareNetworkObservation(browser);
+        return new PlaywrightBrowserContext(context);
+    }
+    async newPage() {
+        const browser = this.context.browser();
+        if (browser)
+            await prepareNetworkObservation(browser);
+        return PlaywrightPage.observe(await this.context.newPage(), this.sockets);
+    }
+    route(url, handler) {
+        return this.context.route(url, (route) => handler(new PlaywrightRoute(route)));
+    }
+    async routeWebSocket(url, handler) {
+        this.sockets.add(url, handler);
+        const routed = await this.context.routeWebSocket(url, (socket) => handler(new PlaywrightWebSocketRoute(socket)));
+        this.faithful ??= this.context.addInitScript({ content: FAITHFUL_WEB_SOCKET });
+        await this.faithful;
+        return routed;
+    }
+    addInitScript(script) {
+        return this.context.addInitScript(script);
+    }
+    close() {
+        return this.context.close();
+    }
+}

package/adapters/browser/playwright/src/playwright-browser-launcher.d.ts

@@ -0,0 +1,9 @@
+import type { BrowserPrerequisiteStatus, Browser, BrowserLauncher, BrowserLaunchOptions } from "@parity/product-lab/ports/browser";
+import { type PlaywrightBrowserOptions } from "./playwright-browser.js";
+export declare class PlaywrightBrowserLauncher implements BrowserLauncher {
+    private readonly defaults;
+    /** `defaults`: options every launch starts from (a launch's own options win). */
+    constructor(defaults?: Omit<PlaywrightBrowserOptions, "args">);
+    prerequisites(): Promise<BrowserPrerequisiteStatus>;
+    launch(options?: BrowserLaunchOptions): Promise<Browser>;
+}

package/adapters/browser/playwright/src/playwright-browser-launcher.js

@@ -0,0 +1,53 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { accessSync, constants, readFileSync, statSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { createRequire } from "node:module";
+import { chromium } from "playwright";
+import { PlaywrightBrowser } from "./playwright-browser.js";
+export class PlaywrightBrowserLauncher {
+    defaults;
+    constructor(defaults = {}) {
+        this.defaults = defaults;
+    }
+    async prerequisites() {
+        if (this.defaults.browserType || (this.defaults.channel && this.defaults.channel !== "chromium"))
+            throw new Error("Prerequisite inspection is unavailable for this configured browser type or channel");
+        const executable = chromium.executablePath();
+        const directory = executable.split(/[\\/]/).findLast((part) => /^chromium-\d+$/.test(part));
+        if (!directory)
+            throw new Error(`Cannot identify the Chromium revision from ${executable}`);
+        let browserDirectory = dirname(executable);
+        while (basename(browserDirectory) !== directory) {
+            const parent = dirname(browserDirectory);
+            if (parent === browserDirectory)
+                throw new Error(`Cannot identify the Chromium cache from ${executable}`);
+            browserDirectory = parent;
+        }
+        const cache = dirname(browserDirectory);
+        let present = false;
+        try {
+            accessSync(executable, constants.X_OK);
+            present = statSync(executable).isFile();
+        }
+        catch {
+        }
+        const manifestPath = createRequire(import.meta.url).resolve("playwright/package.json");
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+        return {
+            label: "Playwright Chromium", revision: directory.slice("chromium-".length), executable, present,
+            install: { command: "env", args: [`PLAYWRIGHT_BROWSERS_PATH=${cache}`, process.execPath, resolve(dirname(manifestPath), manifest.bin.playwright), "install", "chromium"] },
+        };
+    }
+    launch(options = {}) {
+        return new PlaywrightBrowser({
+            ...this.defaults,
+            ...(options.headless !== undefined ? { headless: options.headless } : {}),
+            ...(options.channel ? { channel: options.channel } : {}),
+            ...(options.args?.length ? { args: options.args } : {}),
+            ...(options.recordVideo ? { recordVideo: { dir: options.recordVideo.dir } } : {}),
+            ...(options.device ? { device: options.device } : {}),
+            ...(options.holdWorkers !== undefined ? { holdWorkers: options.holdWorkers } : {}),
+        }).launch();
+    }
+}

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

@@ -0,0 +1,57 @@
+import { type BrowserType } from "playwright";
+import type { Browser, BrowserContext, BrowserContextOptions, BrowserTab } from "@parity/product-lab/ports/browser";
+import { type DeviceProfile } from "@parity/product-lab/domain/devices";
+export interface PlaywrightBrowserOptions {
+    /** Default true; false opens a window a person can watch. */
+    headless?: boolean;
+    /** Browser channel. Default full `chromium`, which exposes native WebRTC diagnostics. */
+    channel?: string;
+    /**
+     * Extra browser arguments (for example `--host-resolver-rules=...`). Every launch also runs Chromium's synthetic
+     * camera and microphone (`SYNTHETIC_MEDIA_ARGS`, `@parity/product-lab/domain/devices`), first and with no way to turn them
+     * off, so no page of a lab browser can prompt for or take the machine's camera or microphone.
+     */
+    args?: readonly string[];
+    /**
+     * Let Playwright close the browser on SIGINT, SIGTERM and SIGHUP. Default
+     * false: the lab owns shutdown, and Playwright's handlers would exit the
+     * process before hosts and chains are stopped
+     * (docs/verification/2026-09-24-notes-example.md).
+     */
+    handleSignals?: boolean;
+    /** The Playwright browser type (default Chromium). */
+    browserType?: Pick<BrowserType, "launch">;
+    /** Record every page's video into `dir` (backlog 18b; `pageVideo` says which file and when its page opened). */
+    recordVideo?: {
+        dir: string;
+    };
+    /** Emulate this device in every context and page (backlog 31c): viewport, pixel ratio, mobile, touch, user agent. */
+    device?: DeviceProfile;
+    /**
+     * Hold each new worker until the network observer watches it (`worker-hold.ts`): `true` opens a debugging port on
+     * 127.0.0.1 (OS-assigned, closed with the browser; every local process of every user on the machine can reach it
+     * while it is open), so only for what is the lab's own. `{ off: why }`, or absent: no port, and the observer's
+     * worker gap says why. The composition root decides (`workerHoldPolicy`).
+     */
+    holdWorkers?: true | {
+        readonly off: string;
+    };
+}
+/**
+ * The port's `Browser` over Playwright. Constructing it starts nothing;
+ * `launch()` starts the browser and `close()` stops it.
+ */
+export declare class PlaywrightBrowser implements Browser {
+    private readonly options;
+    private browser;
+    constructor(options?: PlaywrightBrowserOptions);
+    /** True between `launch()` and `close()` while the browser is connected. */
+    get launched(): boolean;
+    launch(): Promise<this>;
+    newContext(options?: BrowserContextOptions): Promise<BrowserContext>;
+    newPage(options?: BrowserContextOptions): Promise<BrowserTab>;
+    private contextOptions;
+    private recorded;
+    close(): Promise<void>;
+    private running;
+}

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

@@ -0,0 +1,71 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { chromium } from "playwright";
+import { PlaywrightBrowserContext } from "./playwright-browser-context.js";
+import { PlaywrightPage } from "./playwright-page.js";
+import { freeLoopbackPort } from "./free-loopback-port.js";
+import { prepareNetworkObservation } from "./network-evidence.js";
+import { pageOpened, watchPageVideos } from "./page-video.js";
+import { deviceContextOptions } from "./devices.js";
+import { withSyntheticMedia } from "@parity/product-lab/domain/devices";
+export class PlaywrightBrowser {
+    options;
+    browser;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    get launched() {
+        return this.browser?.isConnected() ?? false;
+    }
+    async launch() {
+        if (this.browser)
+            throw new Error("The browser is already launched");
+        const signals = this.options.handleSignals ?? false;
+        const options = withSyntheticMedia({
+            headless: this.options.headless ?? true,
+            handleSIGINT: signals,
+            handleSIGTERM: signals,
+            handleSIGHUP: signals,
+            ...(!this.options.browserType || this.options.channel ? { channel: this.options.channel ?? "chromium" } : {}),
+            args: this.options.args ?? [],
+        });
+        const debuggingPort = this.options.holdWorkers === true ? await freeLoopbackPort() : undefined;
+        if (debuggingPort !== undefined)
+            options.args = [...(options.args ?? []), `--remote-debugging-port=${debuggingPort}`, "--remote-debugging-address=127.0.0.1"];
+        this.browser = await (this.options.browserType ?? chromium).launch(options);
+        await prepareNetworkObservation(this.browser, debuggingPort !== undefined ? { debuggingPort } : { off: typeof this.options.holdWorkers === "object" ? this.options.holdWorkers.off : "the lab did not ask for it for this browser" });
+        return this;
+    }
+    async newContext(options = {}) {
+        return PlaywrightBrowserContext.observe(this.recorded(await this.running().newContext(this.contextOptions(options))));
+    }
+    async newPage(options = {}) {
+        const asked = Date.now();
+        const page = await this.running().newPage(this.contextOptions(options));
+        if (this.options.recordVideo)
+            pageOpened(page, asked);
+        return PlaywrightPage.observe(page);
+    }
+    contextOptions(options) {
+        return {
+            ...(options.permissions ? { permissions: [...options.permissions] } : {}),
+            ...(this.options.recordVideo ? { recordVideo: { dir: this.options.recordVideo.dir } } : {}),
+            ...(this.options.device ? deviceContextOptions(this.options.device) : {}),
+        };
+    }
+    recorded(context) {
+        if (this.options.recordVideo)
+            watchPageVideos(context);
+        return context;
+    }
+    async close() {
+        const browser = this.browser;
+        this.browser = undefined;
+        await browser?.close();
+    }
+    running() {
+        if (!this.browser)
+            throw new Error("Launch the browser first (PlaywrightBrowser.launch())");
+        return this.browser;
+    }
+}

package/adapters/browser/playwright/src/playwright-page.d.ts

@@ -0,0 +1,68 @@
+import type { Page } from "playwright";
+import type { BrowserTab, ConsoleMessage, FrameElement, Locator, ObservedWebSocket, RouteHandler, Timeout } from "@parity/product-lab/ports/browser";
+import { PageConditions } from "./page-conditions.js";
+import type { SocketRoutes } from "./socket-routes.js";
+/**
+ * A top-level page (the port's `BrowserTab`) over Playwright's `Page`.
+ * Locators and frames are Playwright's own objects, which satisfy the port
+ * structurally (tests/structural.test.ts); routes are wrapped so a
+ * `Uint8Array` body reaches Playwright as a `Buffer`.
+ */
+export declare class PlaywrightPage implements BrowserTab {
+    private readonly page;
+    /** Its context's socket routes when the adapter's context opened it (`PageConditions` hands sockets on to them). */
+    private readonly sockets?;
+    private readonly observation;
+    constructor(page: Page, 
+    /** Its context's socket routes when the adapter's context opened it (`PageConditions` hands sockets on to them). */
+    sockets?: SocketRoutes | undefined);
+    /** Adopt a raw Playwright page before its first navigation, including its frames and workers. */
+    static observe(page: Page, sockets?: SocketRoutes): Promise<PlaywrightPage>;
+    networkEvidence(): Promise<import("@parity/product-lab/domain").AppNetworkEvidence>;
+    onPageError(listener: (message: string) => void): () => void;
+    onConsole(listener: (message: ConsoleMessage) => void): () => void;
+    url(): string;
+    evaluate<R, A>(fn: (arg: A) => R | Promise<R>, arg: A): Promise<R>;
+    /** Run a script given as text in the page (backlog 40: the accessibility scanner's own script). */
+    evaluateScript(source: string): Promise<unknown>;
+    waitForFunction<A>(fn: (arg: A) => unknown, arg: A, options?: Timeout): Promise<unknown>;
+    locator(selector: string): Locator;
+    getByLabel(text: string | RegExp, options?: {
+        exact?: boolean;
+    }): Locator;
+    getByRole(role: string, options?: {
+        name?: string | RegExp;
+        exact?: boolean;
+    }): Locator;
+    getByTestId(testId: string | RegExp): Locator;
+    getByText(text: string | RegExp, options?: {
+        exact?: boolean;
+    }): Locator;
+    goto(url: string, options?: Timeout): Promise<unknown>;
+    reload(options?: Timeout): Promise<unknown>;
+    route(url: string, handler: RouteHandler): Promise<unknown>;
+    waitForSelector(selector: string, options?: Timeout): Promise<FrameElement | null>;
+    /**
+     * Watch the page's WebSockets (Playwright's `websocket` event: the browser's own report of a socket the page
+     * opened, its frames and its close). Passive: nothing is intercepted, so it also reports a socket a context route
+     * connected to its server for the page.
+     */
+    onWebSocket(listener: (socket: ObservedWebSocket) => void): void;
+    private conditioned?;
+    /** Backlog 31: this page's conditions (one control per page), the identity's local link to its host exempt. */
+    conditions(exempt: readonly string[] | (() => readonly string[])): PageConditions;
+    close(): Promise<void>;
+    /**
+     * A PNG of the page's viewport. Not part of the Browser port: `PageFrameCapture` (Phase 9 run recordings) reads it
+     * when an environment offers its actors' pages for frames. Reads pixels only.
+     */
+    /** The video this page is recorded into, when its browser records video (backlog 18b; `pageVideo`). */
+    recordedVideo(): Promise<import("./page-video.js").PageVideo | undefined>;
+    /** `maskSelectors` (backlog 40): the page's own elements painted over in the image. */
+    screenshot(options: {
+        type: "png";
+        caret?: "hide";
+        timeout?: number;
+        maskSelectors?: readonly string[];
+    }): Promise<Uint8Array>;
+}