@descryy/runtime-browser 0.2.0

package/dist/browser-console-collector.d.ts

@@ -0,0 +1,33 @@
+/**
+ * §8's console evidence bucket (level · message · stack if present ·
+ * timestamp) plus page errors -- uncaught exceptions in the page's own JS,
+ * captured via Playwright's `pageerror` event. Both ride the same
+ * `EvidenceSource: "browser-console"` bucket the contracts already name.
+ *
+ * Page-error stack text is preserved verbatim in `payload.stack` (plan §9:
+ * "the runtime must preserve the original observation") but NOT
+ * structurally parsed into `StackTrace` frames with resolved
+ * `SourceLocation`s in V1 -- reflected honestly in `capabilities()`
+ * (`stackCapture`/`sourceMapping`: unavailable), not silently produced as
+ * a lesser version. Doing that for real would need mapping the browser's
+ * `http://` script URLs back to on-disk files via the frontend's static
+ * file server root, which this collector has no way to know -- a real,
+ * separate feature, not built here.
+ */
+import type { Collector } from "@descryy/runtime-contracts";
+import type { StackTraceParser } from "@descryy/runtime-backend-observation";
+import type { BrowserSession } from "./browser-session.ts";
+export interface BrowserConsoleCollectorOptions {
+    readonly session: BrowserSession;
+    readonly service?: string;
+    /**
+     * Injected, never constructed here — a browser page runs JavaScript, but
+     * this package stays language-neutral the same way `LogCollector` does:
+     * whoever wires the collector supplies the parser for the runtime it is
+     * actually watching. Omit it and page-error stacks are preserved as text
+     * exactly as before, with `capabilities()` saying so.
+     */
+    readonly stackTraceParser?: StackTraceParser;
+}
+export declare function createBrowserConsoleCollector(options: BrowserConsoleCollectorOptions): Collector;
+//# sourceMappingURL=browser-console-collector.d.ts.map

package/dist/browser-console-collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-console-collector.d.ts","sourceRoot":"","sources":["../src/browser-console-collector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAqF,MAAM,4BAA4B,CAAC;AAG/I,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAE7E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAI3D,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CAC9C;AAmDD,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,8BAA8B,GAAG,SAAS,CA8HhG"}

package/dist/browser-console-collector.js

@@ -0,0 +1,185 @@
+/**
+ * §8's console evidence bucket (level · message · stack if present ·
+ * timestamp) plus page errors -- uncaught exceptions in the page's own JS,
+ * captured via Playwright's `pageerror` event. Both ride the same
+ * `EvidenceSource: "browser-console"` bucket the contracts already name.
+ *
+ * Page-error stack text is preserved verbatim in `payload.stack` (plan §9:
+ * "the runtime must preserve the original observation") but NOT
+ * structurally parsed into `StackTrace` frames with resolved
+ * `SourceLocation`s in V1 -- reflected honestly in `capabilities()`
+ * (`stackCapture`/`sourceMapping`: unavailable), not silently produced as
+ * a lesser version. Doing that for real would need mapping the browser's
+ * `http://` script URLs back to on-disk files via the frontend's static
+ * file server root, which this collector has no way to know -- a real,
+ * separate feature, not built here.
+ */
+import { primaryFrameLocation } from "@descryy/runtime-contracts";
+import { extractCorrelationIds } from "@descryy/runtime-backend-observation";
+import { rewriteScriptUrls } from "./script-url-mapping.js";
+import { COLLECTOR_VERSION } from "./collector-version.js";
+function notThisCollectorsJob(what) {
+    return { availability: "unavailable", reason: `BrowserConsoleCollector handles console/page-error observation only, not ${what} -- see the dedicated collector.` };
+}
+const CAPABILITIES = {
+    domObservation: notThisCollectorsJob("DOM inspection"),
+    consoleObservation: { availability: "available", reason: null },
+    networkObservation: notThisCollectorsJob("network observation"),
+    backendLogAccess: { availability: "unavailable", reason: "this collector observes a browser page, not a backend process." },
+    distributedTrace: {
+        availability: "degraded",
+        reason: "extracts trace-id/request-id fields from console message text; does not parse W3C traceparent from console text.",
+    },
+    sourceMapping: {
+        availability: "unavailable",
+        reason: "page-error stack text is preserved but not structurally parsed/resolved to source locations in V1.",
+    },
+    stackCapture: {
+        availability: "unavailable",
+        reason: "raw page-error stack text is preserved in payload but not structurally parsed into StackTrace frames in V1.",
+    },
+    processLifecycle: notThisCollectorsJob("process lifecycle observation"),
+    databaseObservation: notThisCollectorsJob("database query observation"),
+    externalServiceObservation: notThisCollectorsJob("external service observation"),
+};
+/**
+ * RT-023 landed: with a parser injected and `CollectorContext.resolveSourceRoot`
+ * present, page-error stacks are parsed and their `http://` script URLs are
+ * rewritten to on-disk paths.
+ *
+ * `sourceMapping` stays **degraded**, not available, and the distinction is
+ * load-bearing: the origin-to-root lookup proves the origin maps to a
+ * configured directory, not that the file the browser executed came from
+ * the checkout in it (`declaredCwd` is named for exactly that). A script
+ * this execution did not serve — a CDN, an extension — is left as a URL.
+ */
+const CAPABILITIES_WITH_STACKS = {
+    ...CAPABILITIES,
+    sourceMapping: {
+        availability: "degraded",
+        reason: "page-error stacks are parsed and script URLs are rewritten to on-disk paths via the execution's configured service roots; " +
+            "a successful rewrite proves the origin maps to a configured directory, not that the served file came from that checkout, " +
+            "and a script this execution did not serve is left as a URL.",
+    },
+    stackCapture: { availability: "available", reason: null },
+};
+export function createBrowserConsoleCollector(options) {
+    const { session } = options;
+    const { page } = session;
+    let emit;
+    let resolveSourceRoot;
+    /** Only true once both halves are present: a parser to read the stack, and a way to map its URLs. */
+    let stacksParsed = false;
+    /**
+     * In-flight `onPageError` handlers.
+     *
+     * Parsing a stack is asynchronous, and Playwright's `pageerror` listener
+     * is not — so the handler starts work and returns, and `stop()` used to
+     * clear `emit` out from under it. Any page error whose parse had not
+     * finished was **silently deleted**: `emit?.()` on an undefined `emit` is
+     * a no-op, and nothing recorded that an observation had been dropped.
+     * `stop()` is called at the end of every execution, which is precisely
+     * when a page's last error arrives, so this was not a rare window.
+     *
+     * `stop()` now drains this set before clearing `emit`.
+     */
+    const inFlight = new Set();
+    function onConsole(msg) {
+        const text = msg.text();
+        const { traceId, requestId } = extractCorrelationIds(text);
+        emit?.({
+            timestamp: new Date().toISOString(),
+            source: "browser-console",
+            service: options.service ?? null,
+            process: null,
+            eventType: "CONSOLE_MESSAGE",
+            payload: { level: msg.type(), text, location: msg.location(), browserSessionId: session.sessionId },
+            traceId,
+            requestId,
+            correlationId: null,
+            graphNodeId: null,
+            sourceLocation: null,
+            stackTrace: null,
+            confidence: 1,
+            redactionStatus: "pending-redaction",
+            collectorVersion: COLLECTOR_VERSION,
+        });
+    }
+    function onPageError(error) {
+        const rawStack = error.stack ?? null;
+        const handled = (async () => {
+            let stackTrace = null;
+            let mapping = null;
+            if (stacksParsed && rawStack !== null && options.stackTraceParser !== undefined) {
+                mapping = rewriteScriptUrls(rawStack, resolveSourceRoot);
+                stackTrace = await options.stackTraceParser.parse(mapping.text);
+            }
+            emit?.({
+                timestamp: new Date().toISOString(),
+                source: "browser-console",
+                service: options.service ?? null,
+                process: null,
+                eventType: "EXCEPTION",
+                payload: {
+                    message: error.message,
+                    // The browser's own text, always, whatever the mapping did to it
+                    // (plan §9: preserve the original observation).
+                    stack: rawStack,
+                    browserSessionId: session.sessionId,
+                    // Per-URL outcomes rather than a boolean: "three scripts, two
+                    // mapped, one is a CDN" is a coverage statement, and collapsing
+                    // it would imply the unmapped one simply was not there.
+                    ...(mapping !== null ? { scriptUrlMapping: mapping.outcomes } : {}),
+                },
+                traceId: null,
+                requestId: null,
+                correlationId: null,
+                graphNodeId: null,
+                // Was its own `frames[0]` copy of a rule `backend-observation` had
+                // already moved onto `primaryFrameIndex` (RT-083). The two agreed
+                // only because V8 reports index 0 — a coincidence, not a shared
+                // rule. The full chain is in stackTrace either way.
+                sourceLocation: primaryFrameLocation(stackTrace),
+                stackTrace,
+                confidence: 1,
+                redactionStatus: "pending-redaction",
+                collectorVersion: COLLECTOR_VERSION,
+            });
+        })();
+        inFlight.add(handled);
+        void handled.finally(() => inFlight.delete(handled));
+    }
+    return {
+        collectorId: `browser-console:${session.sessionId}`,
+        start(context) {
+            if (!session.isUsable()) {
+                return Promise.resolve({ available: false, reason: "the browser session's page has already crashed or closed." });
+            }
+            emit = context.emit;
+            resolveSourceRoot = context.resolveSourceRoot;
+            // Both halves or neither: a parser with no way to map URLs would
+            // produce frames pointing at http:// locations nothing can open, and
+            // a mapper with no parser has nothing to map.
+            stacksParsed = options.stackTraceParser !== undefined && context.resolveSourceRoot !== undefined;
+            page.on("console", onConsole);
+            page.on("pageerror", onPageError);
+            return Promise.resolve({ available: true });
+        },
+        async stop() {
+            // Listeners off first, so nothing new joins the set while it drains.
+            page.off("console", onConsole);
+            page.off("pageerror", onPageError);
+            // Then drain, THEN clear `emit` — in that order. Clearing first is
+            // what silently deleted the last page error of every execution.
+            // `allSettled`: a handler that threw has already failed on its own
+            // terms, and stop() refusing to complete because of it would take the
+            // rest of the run's evidence down with it.
+            await Promise.allSettled([...inFlight]);
+            emit = undefined;
+        },
+        capabilities() {
+            return stacksParsed ? CAPABILITIES_WITH_STACKS : CAPABILITIES;
+        },
+    };
+}
+//# sourceMappingURL=browser-console-collector.js.map

package/dist/browser-console-collector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-console-collector.js","sourceRoot":"","sources":["../src/browser-console-collector.ts"],"names":[],"mappings":"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"}

package/dist/browser-network-collector.d.ts

@@ -0,0 +1,112 @@
+/**
+ * §8's network evidence bucket: method · URL · safe request metadata/body
+ * · response status · safe response metadata/body · timing · initiator
+ * where available. `NETWORK_REQUEST` on `request`; `NETWORK_RESPONSE` (and
+ * `HTTP_ERROR` alongside it for status >= 400) on `requestfinished`, which
+ * is when `request.timing()` is actually complete; a network-level
+ * failure with no HTTP response at all (`requestfailed` -- DNS, connection
+ * refused, aborted) also becomes `HTTP_ERROR`, with `status: null`
+ * distinguishing "never got a response" from "got a bad one."
+ *
+ * Auth headers/cookies/tokens are not stripped here -- `headers()` already
+ * lower-cases header names, and `EvidenceStore.write()`'s generic
+ * redaction (RT-015) deep-redacts `authorization`/`cookie`/`set-cookie`/
+ * etc. by key name unconditionally at persist time, so a header object
+ * passed straight into payload is already covered by an existing,
+ * already-tested guarantee -- reimplementing it here would be a second,
+ * divergent copy of the same rule.
+ *
+ * A third `status: null` case (RT-194): a request that gets neither
+ * `requestfinished` nor `requestfailed` within this collector's own
+ * timeout window (`networkTimeoutMs`, default `context.configuration.
+ * timeoutMs` -- RT-030's precedent, not a second disagreeing default) is
+ * reported as `HTTP_ERROR` with `networkError` describing a collector-side
+ * timeout, distinguishable from a real Playwright `requestfailed` (whose
+ * `networkError` carries Chromium's own `net::ERR_*` text). Nothing in
+ * Playwright itself imposes a timeout on an in-page `fetch`/`XHR` that
+ * never completes -- a hung server would otherwise produce silence
+ * forever, not evidence.
+ *
+ * **"initiator where available" above is no longer only `resourceType`.**
+ * With a `stackTraceParser` injected, `NETWORK_REQUEST.stackTrace` carries
+ * a real, resolved call-site stack for `fetch()` requests (Chromium only —
+ * see `frontend-initiator-capture.ts` for the mechanism and the write it
+ * makes to the observed page). This is still not the same claim as
+ * `@descryy/runtime-graph-correlator`'s `resolveObservedFrontendCaller`
+ * upgrading a structural candidate to `observed`: that join happens one
+ * layer up, against the graph. This collector's job stops at attaching the
+ * resolved stack to the evidence record.
+ *
+ * **RT-225: WebSocket traffic is a fourth listener here, not a sibling
+ * collector.** `page.on("request"/"requestfinished"/"requestfailed")` never
+ * fires for a WebSocket connection -- Playwright surfaces it through a
+ * wholly separate `page.on("websocket")` stream, and before this a refused
+ * or dropped WebSocket connection produced zero evidence of any kind, not
+ * degraded, silently absent
+ * (`documents/decisions-inbox/RT-PENDING-websocket-network-observation-gap.md`).
+ * This collector draws its boundary by domain watched (browser network
+ * traffic), not by wire protocol, so WS traffic belongs here.
+ *
+ * Three moments, three choices:
+ * - **connection attempt** (`page.on("websocket")` firing -- "Emitted when
+ *   WebSocket request is sent," Playwright's own doc for the event) reuses
+ *   `NETWORK_REQUEST`: a real outbound call to a URL, the same fact that
+ *   type exists to record. No `method`/`headers`/`postData` fields are
+ *   invented -- Playwright's `WebSocket` object exposes only `url()`, so
+ *   the payload states only what was actually observed, plus a `protocol:
+ *   "websocket"` discriminator.
+ * - **connection failure** (`socketerror`) reuses `HTTP_ERROR` with
+ *   `status: null` -- the identical "no usable response ever came back"
+ *   convention already applied above to a refused `fetch()`
+ *   (`requestfailed`) and to this collector's own timeout. A refused
+ *   WebSocket is the same class of fact under a different wire protocol,
+ *   not a different fact.
+ * - **close** gets its own type, `WEBSOCKET_CLOSED` (`runtime-event.ts`),
+ *   because there is no honest way to fold it into `NETWORK_RESPONSE`:
+ *   that type means a response with a status arrived, and a close is
+ *   neither a response nor does it carry a status. Measured, not assumed:
+ *   Playwright's public `WebSocket.on("close")` carries no code or reason
+ *   at all, and probing it directly (a clean server-sent 1000 close vs. a
+ *   raw abrupt TCP termination) produced byte-identical event shapes --
+ *   so this collector does not claim "normal" vs "abnormal" either, only
+ *   that the socket closed. Only emitted when no `socketerror` already
+ *   reported the same socket as failed, so one failure is never reported
+ *   twice.
+ *
+ * Deliberately **not** captured: per-message frame traffic
+ * (`framesent`/`framereceived`) -- high-volume and not what the proven gap
+ * asked for; `EventSource`/SSE, which shares the same uncovered shape but
+ * is unmeasured and explicitly out of scope for this change, same as the
+ * RT-PENDING note that proved this gap already said.
+ */
+import type { Collector } from "@descryy/runtime-contracts";
+import type { StackTraceParser } from "@descryy/runtime-backend-observation";
+import type { BrowserSession } from "./browser-session.ts";
+export interface BrowserNetworkCollectorOptions {
+    readonly session: BrowserSession;
+    readonly service?: string;
+    /**
+     * Overrides `context.configuration.timeoutMs` (the execution-wide
+     * default) for this collector's own no-response detection. Exists so a
+     * test can drive the timeout path in milliseconds rather than waiting
+     * out a real 30s execution timeout; production callers should leave
+     * this absent.
+     */
+    readonly networkTimeoutMs?: number;
+    /**
+     * Injected, never constructed here — the same language-neutrality
+     * `BrowserConsoleCollector` already holds itself to: this package does
+     * not know what runtime serves the frontend it is watching, so whoever
+     * wires the collector supplies the parser for it.
+     *
+     * When present (and `CollectorContext.resolveSourceRoot` is also
+     * present, same two-halves-or-neither rule as the console collector),
+     * this collector additionally installs `frontend-initiator-capture.ts`'s
+     * `fetch()` wrapper and attempts to resolve each `NETWORK_REQUEST`'s
+     * real call-site stack — Chromium + `fetch()` only. Absent, requests are
+     * captured exactly as before, with no header added to outgoing traffic.
+     */
+    readonly stackTraceParser?: StackTraceParser;
+}
+export declare function createBrowserNetworkCollector(options: BrowserNetworkCollectorOptions): Collector;
+//# sourceMappingURL=browser-network-collector.d.ts.map

package/dist/browser-network-collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-network-collector.d.ts","sourceRoot":"","sources":["../src/browser-network-collector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAqG,MAAM,4BAA4B,CAAC;AAE/J,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAE7E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAM3D,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CAC9C;AA6ED,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,8BAA8B,GAAG,SAAS,CAujBhG"}