@parity/product-lab 0.0.1-placeholder → 0.1.1

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

@@ -0,0 +1,11 @@
+/** Only classified metadata crosses from the lab-owned Chromium WebUI to Node. */
+export interface NativeRtcEvent {
+    peer?: string;
+    document?: string;
+    endpoint?: string;
+    at?: number;
+    detail?: string;
+    gap?: string;
+}
+/** Runs only in the diagnostic document, before Chromium installs its WebUI callback. */
+export declare function installNativeRtcReceiver(binding: string, safeUrl: (value: string) => string): void;

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

@@ -0,0 +1,89 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export function installNativeRtcReceiver(binding, safeUrl) {
+    const peers = new Map();
+    const seen = new Set();
+    let emitted = 0;
+    const send = (event) => {
+        if (emitted > 20_000)
+            return;
+        if (emitted++ === 20_000)
+            event = { gap: "Native WebRTC evidence exceeded 20000 events; later observations were discarded" };
+        const callback = globalThis[binding];
+        if (typeof callback === "function")
+            callback(JSON.stringify(event));
+    };
+    const gap = (text) => { if (!seen.has(text)) {
+        seen.add(text);
+        send({ gap: text });
+    } };
+    const update = (peer, value) => {
+        if (typeof value.type !== "string" || !/icecandidate/i.test(value.type))
+            return;
+        if (typeof value.value !== "string" || value.value.length > 65_536 || new TextEncoder().encode(value.value).byteLength > 65_536) {
+            gap("Native WebRTC candidate payload was unavailable or exceeded 65536 bytes");
+            return;
+        }
+        const candidate = value.value.match(/candidate:([^"\\]+)/)?.[1]?.trim().split(/\s+/);
+        if (!candidate)
+            return;
+        const [, , transport, , address, port] = candidate;
+        if (!address || address.length > 2_048 || !/^[A-Za-z0-9_.:%-]+$/.test(address) || !/^(udp|tcp)$/i.test(transport ?? "") || !/^\d+$/.test(port ?? "")) {
+            gap("Native WebRTC candidate endpoint could not be classified");
+            return;
+        }
+        const host = address.includes(":") ? `[${address}]` : address;
+        const at = typeof value.timestamp === "number" ? value.timestamp : Date.now();
+        send({ peer, document: peers.get(peer), endpoint: safeUrl(`${transport.toLowerCase()}://${host}:${port}`), at, detail: `${/^on/i.test(value.type) ? "Local" : "Remote"} WebRTC candidate; traffic payload is opaque` });
+    };
+    const add = (value) => {
+        if (typeof value.rid !== "number" || typeof value.lid !== "number" || !Number.isInteger(value.rid) || !Number.isInteger(value.lid)) {
+            gap("Native WebRTC peer identifiers were unavailable");
+            return;
+        }
+        const peer = `${value.rid}-${value.lid}`;
+        if (peers.has(peer))
+            return peer;
+        if (peers.size >= 1_024) {
+            gap("Native WebRTC peer tracking exceeded 1024 peers; later peers were discarded");
+            return;
+        }
+        const document = typeof value.url === "string" && value.url.length <= 2_048 ? safeUrl(value.url) : undefined;
+        if (!document)
+            gap("Native WebRTC document URL was unavailable or exceeded 2048 characters");
+        peers.set(peer, document ?? "");
+        send({ peer, document, endpoint: `webrtc://peer/${peer}`, at: typeof value.timestamp === "number" ? value.timestamp : Date.now(), detail: "WebRTC peer created; its complete remote endpoint and traffic payload are unavailable" });
+        return peer;
+    };
+    let native;
+    Object.defineProperty(globalThis, "cr", {
+        configurable: true,
+        get: () => native,
+        set: (value) => {
+            native = value;
+            value.webUIListenerCallback = (event, data) => {
+                if (event === "add-peer-connection" && data && typeof data === "object")
+                    add(data);
+                else if (event === "update-peer-connection" && data && typeof data === "object") {
+                    const updateData = data;
+                    const peer = `${updateData.rid}-${updateData.lid}`;
+                    if (!peers.has(peer))
+                        gap("Native WebRTC update had no observed peer creation");
+                    update(peer, updateData);
+                }
+                else if (event === "update-all-peer-connections" && Array.isArray(data)) {
+                    for (const value of data) {
+                        if (!value || typeof value !== "object")
+                            continue;
+                        const peer = add(value);
+                        if (peer && Array.isArray(value.log))
+                            for (const entry of value.log)
+                                if (entry && typeof entry === "object")
+                                    update(peer, entry);
+                    }
+                }
+            };
+            globalThis.productLabNativeRtcTrackerReady = true;
+        },
+    });
+}

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

@@ -0,0 +1,25 @@
+import type { Browser, Page } from "playwright";
+import type { AppNetworkEvidence, DirectConnection, WorkerHoldSetting } from "@parity/product-lab/domain";
+/**
+ * Holding new workers until they are watched (`worker-hold.ts`, `WorkerHoldSetting`): the browser's debugging port on
+ * 127.0.0.1, or why it is off. Off, a worker's first instant can race the observer, and the gap says why.
+ */
+export type { WorkerHoldSetting };
+/** The gap a worker whose start was not held leaves (it matches `coverage.workers`' test, so worker coverage is false). */
+export declare const workerRaceGap: (why?: string) => string;
+/** Classify transient payloads; the result never contains their bytes. */
+export declare function classifyPayload(payload: string | undefined, binary?: boolean): Pick<DirectConnection, "operation" | "method" | "detail">;
+/** `holding`: set by the browser's launch, the first time; later calls observe with what that first one set. */
+export declare function prepareNetworkObservation(browser: Browser, holding?: WorkerHoldSetting): Promise<void>;
+export declare function observePageNetwork(page: Page): Promise<{
+    evidence(): Promise<AppNetworkEvidence>;
+}>;
+/**
+ * C7: observe a page from before its first navigation (a lab window's, as it opens), and read its traffic by frame: a
+ * frame named `name` and everything inside it, its workers' traffic included (each worker's `parentFrameId`).
+ */
+export declare function observeFramesNetwork(page: Page, holding?: WorkerHoldSetting): Promise<{
+    frame(name: string): {
+        evidence(): Promise<AppNetworkEvidence>;
+    };
+}>;