@descryy/runtime-browser 0.2.0

package/dist/frontend-initiator-capture.js

@@ -0,0 +1,142 @@
+/**
+ * Fetch-initiator capture — the page-side half of resolving *which*
+ * frontend function issued an observed request, not merely which functions
+ * the graph says are capable of it (`resolveFrontendCallers`'s own
+ * structural limit, `@descryy/runtime-graph-correlator`).
+ *
+ * **This is a write, not a read**, in the sense
+ * `PROPOSAL-code-injection-into-observed-processes.md` asks every injection
+ * mechanism to state for itself: the wrapped `fetch()` adds a real header
+ * (`x-descry-initiator-id`) to a real outgoing request. That line does not
+ * run when Descry is not attached — a same-origin request can pick up a
+ * fresh CORS preflight it would not otherwise have had. That side effect is
+ * the one `PROPOSAL-observed-frontend-caller-needs-initiator-capture.md`
+ * asked a human to sign off on before this was built; nothing here reopens
+ * that call.
+ *
+ * The call-site stack itself never travels over the wire that carries the
+ * application's own traffic — only a short, opaque per-call id does, as the
+ * header value. The stack text instead travels over Playwright's own CDP
+ * binding channel (`page.exposeFunction`), straight to `take()` below,
+ * keyed by that same id.
+ *
+ * **Why the real `fetch()` is held until the exposed call returns.** Firing
+ * the buffering call and the real request concurrently would make
+ * correctness depend on which of two independent async channels — the CDP
+ * binding call, and Chromium's own network stack — happens to land at this
+ * process first. That is exactly the kind of timing assumption §27's
+ * "similarity must never be treated as causality" rules out. Awaiting the
+ * binding call before dispatching `fetch` makes the ordering true by
+ * construction instead: the real request cannot be sent until this module
+ * has already buffered the stack it will be looked up by.
+ *
+ * Chromium only — `page.addInitScript` + `page.exposeFunction` is the
+ * mechanism, and no non-CDP-based engine here exposes an equivalent pair.
+ * `fetch()` only, not `XMLHttpRequest`. Both boundaries are the scope
+ * `PROPOSAL-observed-frontend-caller-needs-initiator-capture.md` drew, not
+ * an oversight of this module.
+ */
+export const INITIATOR_HEADER_NAME = "x-descry-initiator-id";
+/**
+ * Bound on stacks buffered but never claimed. Without it, every request
+ * whose id is never looked up — the header stripped in transit, a page that
+ * never triggers a matching `onRequest` at all — would grow this map for
+ * the entire life of the page. FIFO eviction via `Map`'s own insertion
+ * order; a stack this old was never going to be claimed by the time
+ * something newer needs the room.
+ */
+const MAX_BUFFERED_STACKS = 2000;
+const CAPTURE_BINDING_NAME = "__descryCaptureInitiatorStack";
+export function createFrontendInitiatorCapture() {
+    const buffered = new Map();
+    function record(id, stackText) {
+        if (buffered.size >= MAX_BUFFERED_STACKS) {
+            const oldest = buffered.keys().next().value;
+            if (oldest !== undefined)
+                buffered.delete(oldest);
+        }
+        buffered.set(id, stackText);
+    }
+    return {
+        async install(page) {
+            await page.exposeFunction(CAPTURE_BINDING_NAME, record);
+            await page.addInitScript({ content: initScriptSource() });
+        },
+        take(id) {
+            const stackText = buffered.get(id);
+            buffered.delete(id);
+            return stackText;
+        },
+    };
+}
+/**
+ * The injected wrapper, as a plain string — `page.addInitScript`'s
+ * string form, so this never needs its own transpilation step and runs
+ * exactly as written in the page's own JS engine, not this process's.
+ *
+ * Every call site outcome degrades to "no id header" or "no functionName"
+ * rather than throwing: `bind(...)` is wrapped in its own `.catch`, and a
+ * `fetch()` whose `input` is neither a string, `URL`, nor `Request` still
+ * reaches `originalFetch` unmodified so the native `TypeError` a caller
+ * would have gotten anyway is the one they still get — this wrapper adds a
+ * header, it does not change what counts as a valid `fetch()` call.
+ */
+function initScriptSource() {
+    return `(() => {
+    const originalFetch = window.fetch;
+    if (typeof originalFetch !== "function") return;
+    const bind = window[${JSON.stringify(CAPTURE_BINDING_NAME)}];
+    if (typeof bind !== "function") return;
+    let counter = 0;
+    window.fetch = function descryFetch(input, init) {
+      const id = Date.now().toString(36) + "-" + Math.random().toString(36).slice(2) + "-" + (counter++);
+      const stack = (new Error()).stack || "";
+      const self = this;
+      const dispatch = () => {
+        let headerSource = init && init.headers !== undefined ? init.headers : undefined;
+        if (headerSource === undefined && typeof Request !== "undefined" && input instanceof Request) {
+          headerSource = input.headers;
+        }
+        const headers = new Headers(headerSource);
+        headers.set(${JSON.stringify(INITIATOR_HEADER_NAME)}, id);
+        if (typeof Request !== "undefined" && input instanceof Request) {
+          return originalFetch.call(self, new Request(input, { headers: headers }));
+        }
+        return originalFetch.call(self, input, Object.assign({}, init, { headers: headers }));
+      };
+      return bind(id, stack).catch(function () {}).then(dispatch);
+    };
+  })();`;
+}
+const FRAME_LINE = /^\s*at\s/;
+/**
+ * Strips `descryFetch`'s own frame from a raw V8 stack, so the remaining
+ * text's first frame is the real call site rather than this module's own
+ * wrapper.
+ *
+ * **Why this can be a fixed "drop the first frame line" rule rather than a
+ * search for a named function.** `new Error().stack` is captured
+ * synchronously, as the wrapper's first statement — before the `await`-
+ * shaped `.then(dispatch)` chain below it ever runs. V8's stack is built
+ * from the synchronous call chain live at capture time, so the innermost
+ * frame is deterministically `descryFetch` itself, every time, regardless
+ * of what called it. Stripping by *position* (first frame line) rather than
+ * by *name* also survives minification of this wrapper's own name, which a
+ * name-based strip would not.
+ *
+ * Applied to raw text, before parsing — same reasoning
+ * `rewriteScriptUrls`'s own doc gives for rewriting before rather than
+ * after: `createV8StackTraceParser` already treats frame 0 of whatever it
+ * receives as `primaryFrameIndex`, so removing the wrapper's line here
+ * means the parser's existing, already-tested convention does the right
+ * thing unmodified, instead of teaching every consumer a second index to
+ * skip.
+ */
+export function stripInitiatorWrapperFrame(rawStackText) {
+    const lines = rawStackText.split(/\r\n|\r|\n/);
+    const frameIndex = lines.findIndex((line) => FRAME_LINE.test(line));
+    if (frameIndex === -1)
+        return rawStackText;
+    return [...lines.slice(0, frameIndex), ...lines.slice(frameIndex + 1)].join("\n");
+}
+//# sourceMappingURL=frontend-initiator-capture.js.map

package/dist/frontend-initiator-capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontend-initiator-capture.js","sourceRoot":"","sources":["../src/frontend-initiator-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAIH,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAC;AAE7D;;;;;;;GAOG;AACH,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAEjC,MAAM,oBAAoB,GAAG,+BAA+B,CAAC;AAwB7D,MAAM,UAAU,8BAA8B;IAC5C,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE3C,SAAS,MAAM,CAAC,EAAU,EAAE,SAAiB;QAC3C,IAAI,QAAQ,CAAC,IAAI,IAAI,mBAAmB,EAAE,CAAC;YACzC,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YAC5C,IAAI,MAAM,KAAK,SAAS;gBAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACpD,CAAC;QACD,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;IAC9B,CAAC;IAED,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,IAAU;YACtB,MAAM,IAAI,CAAC,cAAc,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;YACxD,MAAM,IAAI,CAAC,aAAa,CAAC,EAAE,OAAO,EAAE,gBAAgB,EAAE,EAAE,CAAC,CAAC;QAC5D,CAAC;QACD,IAAI,CAAC,EAAU;YACb,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACpB,OAAO,SAAS,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,gBAAgB;IACvB,OAAO;;;0BAGiB,IAAI,CAAC,SAAS,CAAC,oBAAoB,CAAC;;;;;;;;;;;;;sBAaxC,IAAI,CAAC,SAAS,CAAC,qBAAqB,CAAC;;;;;;;;QAQnD,CAAC;AACT,CAAC;AAED,MAAM,UAAU,GAAG,UAAU,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,0BAA0B,CAAC,YAAoB;IAC7D,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAC/C,MAAM,UAAU,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACpE,IAAI,UAAU,KAAK,CAAC,CAAC;QAAE,OAAO,YAAY,CAAC;IAC3C,OAAO,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACpF,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export type { BrowserSessionOptions, BrowserSession, ChromiumUnavailable, ChromiumAvailability, BrowserSessionLaunch } from "./browser-session.ts";
+export { launchBrowserSession, launchBrowserSessionOrRefuse, resolveChromiumExecutable, BrowserUnavailableError, CHROMIUM_INSTALL_REMEDY, } from "./browser-session.ts";
+export type { DomElementSnapshot } from "./dom-evidence.ts";
+export { captureElementSnapshot } from "./dom-evidence.ts";
+export type { BrowserActionCollectorOptions, BrowserActionCollector, WaitForOptions } from "./browser-action-collector.ts";
+export { createBrowserActionCollector } from "./browser-action-collector.ts";
+export type { BrowserConsoleCollectorOptions } from "./browser-console-collector.ts";
+export { createBrowserConsoleCollector } from "./browser-console-collector.ts";
+export type { BrowserNetworkCollectorOptions } from "./browser-network-collector.ts";
+export { createBrowserNetworkCollector } from "./browser-network-collector.ts";
+export type { HeaderCorrelationIds } from "./network-correlation.ts";
+export { extractHeaderCorrelationIds } from "./network-correlation.ts";
+export type { ScriptUrlRewrite, SourceRootResolver } from "./script-url-mapping.ts";
+export { rewriteScriptUrls } from "./script-url-mapping.ts";
+export { INITIATOR_HEADER_NAME, stripInitiatorWrapperFrame } from "./frontend-initiator-capture.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,qBAAqB,EAAE,cAAc,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACnJ,OAAO,EACL,oBAAoB,EACpB,4BAA4B,EAC5B,yBAAyB,EACzB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,sBAAsB,CAAC;AAE9B,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,YAAY,EAAE,6BAA6B,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC3H,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAC;AAE7E,YAAY,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAC;AACrF,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AAE/E,YAAY,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAC;AACrF,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AAE/E,YAAY,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAEvE,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,OAAO,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+export { launchBrowserSession, launchBrowserSessionOrRefuse, resolveChromiumExecutable, BrowserUnavailableError, CHROMIUM_INSTALL_REMEDY, } from "./browser-session.js";
+export { captureElementSnapshot } from "./dom-evidence.js";
+export { createBrowserActionCollector } from "./browser-action-collector.js";
+export { createBrowserConsoleCollector } from "./browser-console-collector.js";
+export { createBrowserNetworkCollector } from "./browser-network-collector.js";
+export { extractHeaderCorrelationIds } from "./network-correlation.js";
+export { rewriteScriptUrls } from "./script-url-mapping.js";
+export { INITIATOR_HEADER_NAME, stripInitiatorWrapperFrame } from "./frontend-initiator-capture.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,oBAAoB,EACpB,4BAA4B,EAC5B,yBAAyB,EACzB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAG3D,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAC;AAG7E,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AAG/E,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AAG/E,OAAO,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAGvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,OAAO,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/network-correlation.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Correlation-id extraction from real HTTP headers (structured access, not
+ * text regex) -- covers the top three levels of plan §10's six-level
+ * preference order: trace ID, request ID, W3C trace context. Direct header
+ * access makes the W3C case cheap here in a way it wasn't for
+ * `backend-observation`'s `extractCorrelationIds`, which only ever sees
+ * unstructured log text and explicitly cuts W3C parsing as a documented
+ * V1 gap -- this collector doesn't need that same cut.
+ */
+export interface HeaderCorrelationIds {
+    readonly traceId: string | null;
+    readonly requestId: string | null;
+}
+export declare function extractHeaderCorrelationIds(headers: Readonly<Record<string, string>>): HeaderCorrelationIds;
+//# sourceMappingURL=network-correlation.d.ts.map

package/dist/network-correlation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-correlation.d.ts","sourceRoot":"","sources":["../src/network-correlation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAUD,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,oBAAoB,CAS3G"}

package/dist/network-correlation.js

@@ -0,0 +1,29 @@
+/**
+ * Correlation-id extraction from real HTTP headers (structured access, not
+ * text regex) -- covers the top three levels of plan §10's six-level
+ * preference order: trace ID, request ID, W3C trace context. Direct header
+ * access makes the W3C case cheap here in a way it wasn't for
+ * `backend-observation`'s `extractCorrelationIds`, which only ever sees
+ * unstructured log text and explicitly cuts W3C parsing as a documented
+ * V1 gap -- this collector doesn't need that same cut.
+ */
+// W3C Trace Context: "00-<32 hex trace-id>-<16 hex parent-id>-<2 hex flags>".
+const TRACEPARENT_PATTERN = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/i;
+function firstHeader(headers, names) {
+    for (const name of names) {
+        const value = headers[name];
+        if (value !== undefined && value.length > 0)
+            return value;
+    }
+    return null;
+}
+export function extractHeaderCorrelationIds(headers) {
+    const explicitTraceId = firstHeader(headers, ["x-trace-id", "trace-id"]);
+    const traceparent = headers["traceparent"];
+    const w3cTraceId = traceparent !== undefined ? (TRACEPARENT_PATTERN.exec(traceparent)?.[2] ?? null) : null;
+    return {
+        traceId: explicitTraceId ?? w3cTraceId,
+        requestId: firstHeader(headers, ["x-request-id", "request-id"]),
+    };
+}
+//# sourceMappingURL=network-correlation.js.map

package/dist/network-correlation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-correlation.js","sourceRoot":"","sources":["../src/network-correlation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,8EAA8E;AAC9E,MAAM,mBAAmB,GAAG,8DAA8D,CAAC;AAO3F,SAAS,WAAW,CAAC,OAAyC,EAAE,KAAwB;IACtF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;IAC5D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,OAAyC;IACnF,MAAM,eAAe,GAAG,WAAW,CAAC,OAAO,EAAE,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC,CAAC;IACzE,MAAM,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC3C,MAAM,UAAU,GAAG,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAE3G,OAAO;QACL,OAAO,EAAE,eAAe,IAAI,UAAU;QACtC,SAAS,EAAE,WAAW,CAAC,OAAO,EAAE,CAAC,cAAc,EAAE,YAAY,CAAC,CAAC;KAChE,CAAC;AACJ,CAAC"}

package/dist/script-url-mapping.d.ts

@@ -0,0 +1,40 @@
+/**
+ * RT-023's collector half: rewriting a browser script URL to the on-disk
+ * file it was served from, so a page-error stack can be parsed into real
+ * `SourceLocation`s instead of preserved as text.
+ *
+ * **The rewrite happens on the stack text, before parsing, deliberately.**
+ * A `StackTraceParser` and its `SourceLocationResolver` already know how to
+ * turn `at f (/abs/path.js:12:5)` into a resolved location — including
+ * source-map handling and staleness detection, which took real work to get
+ * right. Rewriting the URL first lets all of that apply unchanged, where
+ * post-processing parsed frames would mean reimplementing it here and
+ * keeping two copies honest.
+ *
+ * **What this can and cannot claim.** `CollectorContext.resolveSourceRoot`
+ * answers "which service's declared root does this origin belong to", and
+ * `ConfiguredServiceRoot.declaredCwd` is named for what it is: configured,
+ * not verified. So a successful rewrite proves the origin maps to a
+ * directory — **not** that the file the browser executed came from the
+ * checkout in it. The downstream resolver's own existence check is the real
+ * refusal point, and an unmapped or non-existent path degrades to the URL
+ * itself rather than to a fabricated file. That is RT-031's class again:
+ * a match on an observable proxy is not proof of the underlying identity.
+ *
+ * Nothing is rewritten when the resolver refuses, when it is absent, or
+ * when the URL is not one this execution spawned — a CDN script, a browser
+ * extension, `about:blank`. Those are routine, not failures.
+ */
+import type { ServiceRootLookup } from "@descryy/runtime-contracts";
+export type SourceRootResolver = (origin: string) => ServiceRootLookup;
+export interface ScriptUrlRewrite {
+    readonly text: string;
+    /** Every URL seen, and what happened to it — so a collector can report coverage rather than implying it. */
+    readonly outcomes: readonly {
+        readonly url: string;
+        readonly mapped: string | null;
+        readonly reason: string | null;
+    }[];
+}
+export declare function rewriteScriptUrls(stackText: string, resolveSourceRoot: SourceRootResolver | undefined): ScriptUrlRewrite;
+//# sourceMappingURL=script-url-mapping.d.ts.map

package/dist/script-url-mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"script-url-mapping.d.ts","sourceRoot":"","sources":["../src/script-url-mapping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEpE,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,iBAAiB,CAAC;AAKvE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4GAA4G;IAC5G,QAAQ,CAAC,QAAQ,EAAE,SAAS;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,EAAE,CAAC;CACxH;AAED,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,iBAAiB,EAAE,kBAAkB,GAAG,SAAS,GAAG,gBAAgB,CAoExH"}

package/dist/script-url-mapping.js

@@ -0,0 +1,96 @@
+/**
+ * RT-023's collector half: rewriting a browser script URL to the on-disk
+ * file it was served from, so a page-error stack can be parsed into real
+ * `SourceLocation`s instead of preserved as text.
+ *
+ * **The rewrite happens on the stack text, before parsing, deliberately.**
+ * A `StackTraceParser` and its `SourceLocationResolver` already know how to
+ * turn `at f (/abs/path.js:12:5)` into a resolved location — including
+ * source-map handling and staleness detection, which took real work to get
+ * right. Rewriting the URL first lets all of that apply unchanged, where
+ * post-processing parsed frames would mean reimplementing it here and
+ * keeping two copies honest.
+ *
+ * **What this can and cannot claim.** `CollectorContext.resolveSourceRoot`
+ * answers "which service's declared root does this origin belong to", and
+ * `ConfiguredServiceRoot.declaredCwd` is named for what it is: configured,
+ * not verified. So a successful rewrite proves the origin maps to a
+ * directory — **not** that the file the browser executed came from the
+ * checkout in it. The downstream resolver's own existence check is the real
+ * refusal point, and an unmapped or non-existent path degrades to the URL
+ * itself rather than to a fabricated file. That is RT-031's class again:
+ * a match on an observable proxy is not proof of the underlying identity.
+ *
+ * Nothing is rewritten when the resolver refuses, when it is absent, or
+ * when the URL is not one this execution spawned — a CDN script, a browser
+ * extension, `about:blank`. Those are routine, not failures.
+ */
+import { statSync } from "node:fs";
+import { join } from "node:path";
+/** `http://localhost:41237/public/app.js:12:5` — the trailing `:line:col` is left in place for the stack parser to read. */
+const SCRIPT_URL = /\bhttps?:\/\/[^\s()]+/g;
+export function rewriteScriptUrls(stackText, resolveSourceRoot) {
+    if (resolveSourceRoot === undefined) {
+        return { text: stackText, outcomes: [] };
+    }
+    const outcomes = [];
+    const text = stackText.replace(SCRIPT_URL, (match) => {
+        // Strip the stack's own `:line:column` suffix before treating the rest
+        // as a URL — `new URL()` would otherwise parse `:12` as part of the
+        // path and produce a file that never existed.
+        const suffix = /:(\d+):(\d+)$/.exec(match);
+        const urlText = suffix === null ? match : match.slice(0, match.length - suffix[0].length);
+        let url;
+        try {
+            url = new URL(urlText);
+        }
+        catch {
+            outcomes.push({ url: match, mapped: null, reason: "not a parseable URL" });
+            return match;
+        }
+        const lookup = resolveSourceRoot(url.origin);
+        if (!lookup.found) {
+            outcomes.push({ url: match, mapped: null, reason: lookup.message });
+            return match;
+        }
+        // `url.pathname` is always absolute; `join` would otherwise treat a
+        // leading slash as a fresh root and discard the service's own cwd.
+        const candidate = join(lookup.root.declaredCwd, url.pathname.replace(/^\/+/, ""));
+        // **`isFile()`, not `existsSync` — and the difference is not pedantry.**
+        // An inline `<script>` on a page served at `/` produces frames V8 names
+        // after the *document* URL, whose pathname is `/` and nothing else. That
+        // joins to `declaredCwd` itself: a real directory, so `existsSync` said
+        // yes and this function rewrote a stack frame to a directory no browser
+        // ever executed. The downstream `SourceLocationResolver` then reached
+        // `readFileSync(directory)`, threw `EISDIR`, and the whole
+        // `NETWORK_REQUEST` row was lost with it — an observation discarded to
+        // protect a nullable field. `statSync` answers the question that was
+        // always being asked (is there a FILE here?) rather than the weaker one
+        // that happened to be cheap.
+        //
+        // `statSync` throws on a missing path where `existsSync` returned false,
+        // so the absence case is caught rather than propagated: both branches end
+        // in the same refusal, with the reason naming which one it was.
+        let isFile;
+        try {
+            isFile = statSync(candidate).isFile();
+        }
+        catch {
+            outcomes.push({ url: match, mapped: null, reason: `resolved to "${candidate}", which does not exist on disk` });
+            return match;
+        }
+        if (!isFile) {
+            // The origin maps to a root and the pathname points at something that
+            // is not a file in it — a directory (the `/` case above), a socket, a
+            // device. Reported rather than rewritten: a path that is not a source
+            // file is worse than the URL, which at least says truthfully where the
+            // browser got it.
+            outcomes.push({ url: match, mapped: null, reason: `resolved to "${candidate}", which is not a file on disk` });
+            return match;
+        }
+        outcomes.push({ url: match, mapped: candidate, reason: null });
+        return suffix === null ? candidate : `${candidate}${suffix[0]}`;
+    });
+    return { text, outcomes };
+}
+//# sourceMappingURL=script-url-mapping.js.map

package/dist/script-url-mapping.js.map

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

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@descryy/runtime-browser",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Browser runtime: launch, isolated context, navigation, click/type/wait, DOM inspection, screenshots, console/page-error/network capture, all through the Collector contract (plan \u00a77/\u00a78). See documents/decisions-inbox/PROPOSAL-B-playwright-for-browser-runtime.md for the Playwright-vs-CDP call.",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.5"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "dependencies": {
+    "@descryy/runtime-contracts": "0.2.0",
+    "@descryy/runtime-backend-observation": "0.2.0",
+    "playwright-core": "^1.62.1",
+    "@descryy/runtime-adapter-typescript": "0.2.0"
+  },
+  "devDependencies": {
+    "@descryy/runtime-controller": "*",
+    "@descryy/runtime-evidence-store": "*"
+  }
+}