rea-agents 4.1.0 → 6.0.0

package/dist/browser/PlaywrightScenarioSession.js

@@ -109,6 +109,8 @@ export class PlaywrightScenarioSession {
                 ownsContext: scenario.browser.mode === "launch",
                 enabled: new Set(scenario.capture.events),
                 secrets,
+                network: scenario.capture.network,
+                ...(options.signal === undefined ? {} : { signal: options.signal }),
             });
             const session = new PlaywrightScenarioSession(opened, {
                 mode: scenario.browser.mode,
@@ -170,7 +172,12 @@ export class PlaywrightScenarioSession {
                 ? "terminated-owned-process"
                 : "disconnected-external";
         this.closed = true;
-        await closePlaywrightScenarioBrowser(this.opened, this.signal);
+        try {
+            await this.eventCapture.finish();
+        }
+        finally {
+            await closePlaywrightScenarioBrowser(this.opened, this.signal);
+        }
         return this.mode === "launch"
             ? "terminated-owned-process"
             : "disconnected-external";

package/dist/browser/WebSourceMapFetcher.js

@@ -2,12 +2,14 @@ import * as t from "@babel/types";
 import { AnyMap, eachMapping } from "@jridgewell/trace-mapping";
 import { sanitizeBrowserUrl } from "../domain/browserObservation.js";
 import { isUrlLikeModuleSpecifier } from "../domain/webBundleAnalyzerAst.js";
-import { analyzeParsedJavaScriptSemantics } from "../domain/javascriptSemanticAnalysis.js";
-import { parseJavaScriptSource } from "../domain/javascriptSourceParser.js";
+import { analyzeParsedJavaScriptReferences } from "../domain/javascript/javascriptSemanticAnalysis.js";
+import { traverseJavaScriptAst } from "../domain/javascript/javascriptSemanticTraversal.js";
+import { parseJavaScriptSource } from "../domain/javascript/javascriptSourceParser.js";
 import { hasValidSourceMapContents } from "../domain/sourceMapContents.js";
 import { webSourceMapsSchema } from "../domain/webBundleAnalysis.js";
 import { createWebTextArtifact } from "../domain/webContentArtifact.js";
 import { safeParseJson } from "../domain/safeJson.js";
+import { flattenSourceMapLeaves, isVersion3Map, } from "../domain/sourceMapEnvelope.js";
 /** Fetch and validate approved source maps without browser credentials. */
 export const fetchWebSourceMaps = async (requests, input, signal, host = { fetch: globalThis.fetch }) => {
     const items = [];
@@ -150,32 +152,32 @@ const originalModuleEdges = (sources) => {
         if (parsed.errors.length > 0)
             incomplete.push(source.source);
         let unboundRequires;
-        t.traverseFast(parsed, (node) => {
-            const dependency = originalDependency(node);
-            if (dependency === null)
-                return;
-            const { kind, specifier } = dependency;
-            if (kind === "require" && t.isCallExpression(node)) {
-                unboundRequires ??= new Set(analyzeParsedJavaScriptSemantics(parsed)
-                    .references.filter(({ name, role, resolution }) => name === "require" &&
-                    role === "read" &&
-                    resolution === "unbound")
-                    .map(({ location }) => `${String(location.start.line)}:${String(location.start.column)}`));
-                const location = node.callee.loc?.start;
-                if (location === undefined ||
-                    !unboundRequires.has(`${String(location.line)}:${String(location.column)}`))
+        traverseJavaScriptAst(parsed, {
+            enter: (node) => {
+                const dependency = originalDependency(node);
+                if (dependency === null)
                     return;
-            }
-            const key = `${source.source}\0${kind}\0${specifier}`;
-            if (seen.has(key))
-                return;
-            seen.add(key);
-            edges.push({
-                from_source: source.source,
-                kind,
-                specifier,
-                resolved_source: resolveOriginalSource(specifier, source.source),
-            });
+                const { kind, specifier } = dependency;
+                if (kind === "require" && t.isCallExpression(node)) {
+                    unboundRequires ??= new Set(analyzeParsedJavaScriptReferences(parsed, "require")
+                        .filter(({ role, resolution }) => role === "read" && resolution === "unbound")
+                        .map(({ location }) => `${String(location.start.line)}:${String(location.start.column)}`));
+                    const location = node.callee.loc?.start;
+                    if (location === undefined ||
+                        !unboundRequires.has(`${String(location.line)}:${String(location.column)}`))
+                        return;
+                }
+                const key = `${source.source}\0${kind}\0${specifier}`;
+                if (seen.has(key))
+                    return;
+                seen.add(key);
+                edges.push({
+                    from_source: source.source,
+                    kind,
+                    specifier,
+                    resolved_source: resolveOriginalSource(specifier, source.source),
+                });
+            },
         });
     }
     return { edges, incomplete };
@@ -185,33 +187,13 @@ const validSourceMapEnvelope = (text) => {
     if (!parsedResult.ok)
         return false;
     const parsed = parsedResult.value;
-    if (!isRecord(parsed) || parsed.version !== 3)
-        return false;
-    if (typeof parsed.mappings === "string")
+    if (isVersion3Map(parsed) && typeof parsed.mappings === "string")
         return validSourceMapLeaf(parsed);
-    if (!Array.isArray(parsed.sections))
+    const leaves = flattenSourceMapLeaves(parsed, { validateOffsets: true });
+    if (leaves === undefined)
         return false;
-    const pending = [...parsed.sections];
-    while (pending.length > 0) {
-        const section = pending.pop();
-        if (!isRecord(section) ||
-            !isRecord(section.offset) ||
-            !validSourceMapOffset(section.offset.line) ||
-            !validSourceMapOffset(section.offset.column) ||
-            !("map" in section))
-            return false;
-        const map = section.map;
-        if (!isRecord(map) || map.version !== 3)
-            return false;
-        if (Array.isArray(map.sections))
-            for (const child of map.sections)
-                pending.push(child);
-        else if (!validSourceMapLeaf(map))
-            return false;
-    }
-    return true;
+    return leaves.every(validSourceMapLeaf);
 };
-const validSourceMapOffset = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
 const validSourceMapLeaf = (map) => typeof map.mappings === "string" &&
     Array.isArray(map.sources) &&
     Array.isArray(map.names) &&
@@ -265,10 +247,12 @@ const resolveOriginalSource = (specifier, base) => {
         return null;
     }
 };
-const sourceMediaType = (source) => source?.endsWith(".ts") || source?.endsWith(".tsx")
+const sourceMediaType = (source) => source?.endsWith(".ts") ||
+    source?.endsWith(".tsx") ||
+    source?.endsWith(".mts") ||
+    source?.endsWith(".cts")
     ? "text/typescript"
     : "text/javascript";
-const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const originalDependency = (node) => {
     if (t.isImportDeclaration(node) ||
         t.isExportAllDeclaration(node) ||

package/dist/browser/assets/LocalWebScriptArtifacts.js

@@ -0,0 +1,87 @@
+import { lstat, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
+import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
+import { normalizeArtifactPath } from "../../artifacts/ArtifactPaths.js";
+import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
+import { err, ok } from "../../domain/result.js";
+import { webScriptExportManifestSchema } from "../../domain/webScriptExport.js";
+import { decodeWebArtifact, readWebArtifactJson, webArtifactReadError, WebArtifactFormatFailure, } from "./WebArtifactReads.js";
+/** Read one digest-verified captured source under the manifest's current location. */
+export class LocalWebScriptArtifacts {
+    operation;
+    constructor(operation) {
+        this.operation = operation;
+    }
+    /** Read the selected source; relocated exports retain their reported original root. */
+    async load(input, options) {
+        let field = ["manifest_path"];
+        let targetPath = input.manifest_path;
+        try {
+            const manifestBytes = await readWebArtifactJson(input.manifest_path, 32 * 1024 * 1024, options?.signal);
+            const manifest = webScriptExportManifestSchema.parse(manifestBytes.value);
+            field = ["script_index"];
+            const selected = manifest.scripts[input.script_index];
+            if (selected === undefined)
+                throw new WebArtifactFormatFailure(`No script at index ${String(input.script_index)}; manifest contains ${String(manifest.scripts.length)} scripts.`);
+            if (selected.content.state !== "exported")
+                return err(new AnalysisCapabilityUnavailableError("web-module-artifacts", this.operation, "selected_source_unavailable", {
+                    userMessage: `Selected script ${String(input.script_index)} has unavailable source bytes (${selected.content.reason}): ${selected.content.message} Capture source bytes before tracing this script.`,
+                }));
+            const portable = normalizeArtifactPath(selected.content.relative_path);
+            if (portable !== selected.content.relative_path)
+                throw new ArtifactReaderFailure("path", `Selected source path changes during normalization: ${selected.content.relative_path}`);
+            const root = dirname(input.manifest_path);
+            const sourcePath = join(root, "files", portable);
+            targetPath = sourcePath;
+            await assertContained(root, sourcePath);
+            const sourceBytes = await readStableArtifact(sourcePath, 16 * 1024 * 1024, options?.signal);
+            await assertContained(root, sourcePath);
+            if (sourceBytes.sha256 !== selected.content.sha256 ||
+                sourceBytes.bytes.length !== selected.content.bytes)
+                throw new ArtifactReaderFailure("integrity", `Selected source identity mismatch: ${sourcePath}; expected sha256=${selected.content.sha256}, bytes=${String(selected.content.bytes)}; observed sha256=${sourceBytes.sha256}, bytes=${String(sourceBytes.bytes.length)}.`, undefined, {
+                    logicalPath: selected.content.relative_path,
+                    declaredSha256: selected.content.sha256,
+                    calculatedSha256: sourceBytes.sha256,
+                    unpacked: false,
+                });
+            const source = decodeWebArtifact(sourceBytes.bytes);
+            return ok({
+                manifest,
+                manifestFile: {
+                    path: input.manifest_path,
+                    sha256: manifestBytes.sha256,
+                    bytes: manifestBytes.bytes.length,
+                },
+                sourceFile: {
+                    path: sourcePath,
+                    sha256: sourceBytes.sha256,
+                    bytes: sourceBytes.bytes.length,
+                },
+                source,
+            });
+        }
+        catch (cause) {
+            return err(webArtifactReadError(cause, { operation: this.operation, field, targetPath }, options?.signal));
+        }
+    }
+}
+const assertContained = async (root, path) => {
+    const canonicalRoot = await realpath(root);
+    const canonicalFile = await realpath(path);
+    const fromRoot = relative(canonicalRoot, canonicalFile);
+    if (fromRoot === ".." ||
+        fromRoot.startsWith(`..${sep}`) ||
+        isAbsolute(fromRoot))
+        throw new ArtifactReaderFailure("path", `Selected source escapes its manifest directory: ${path}`);
+    let directory = dirname(path);
+    while (directory !== root) {
+        const stat = await lstat(directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new ArtifactReaderFailure("path", `Selected source directory is a symlink or not a directory: ${directory}`);
+        const parent = dirname(directory);
+        if (parent === directory)
+            throw new ArtifactReaderFailure("path", "Selected source has no containing manifest directory.");
+        directory = parent;
+    }
+};

package/dist/browser/assets/PageScriptCapture.js

@@ -0,0 +1,32 @@
+/** Project verified Debugger sources without fetching resource URLs. */
+export const pageScripts = (capture) => capture.scripts.items.map((script) => ({
+    source: {
+        kind: "page-script",
+        script_key: script.script_key,
+        frame_id: script.frame_id,
+        is_module: script.is_module,
+        language: script.language,
+        source_map_url: script.source_map_url,
+    },
+    url: script.url,
+    content: !script.source.included
+        ? {
+            state: "unavailable",
+            reason: "source-not-included",
+            message: script.source.reason || "Debugger source was not included.",
+        }
+        : script.language !== null && script.language !== "JavaScript"
+            ? {
+                state: "unavailable",
+                reason: "unsupported-language",
+                message: `Debugger reported language ${script.language}; JavaScript export was not inferred.`,
+            }
+            : {
+                state: "captured",
+                bytes: Buffer.from(script.source.artifact.text, "utf8"),
+                sha256: script.source.artifact.sha256,
+                media_type: script.source.artifact.media_type,
+                redacted: null,
+                representation: "debugger-source-utf8",
+            },
+}));

package/dist/browser/assets/PublishWebScripts.js

@@ -0,0 +1,74 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { Readable } from "node:stream";
+import { SafeOutputTree } from "../../artifacts/SafeOutputTree.js";
+import { webScriptExportManifestSchema, webScriptExportResultSchema, } from "../../domain/webScriptExport.js";
+import { planWebScriptExport } from "../../domain/webScriptExportPlan.js";
+import { WebScriptExportError } from "../../domain/webScriptExportError.js";
+const LIMITATIONS = [
+    "Only script bytes retained in this capture are exported. Sources are not refetched or executed, and a response or Debugger source does not prove execution.",
+    "Ordinary unambiguous URL paths preserve relative module layouts by origin. Query variants, collisions, inline sources, and unrepresentable paths are isolated; their browser module relationships remain unknown.",
+    "Local JavaScript analysis does not implement browser import maps, root-relative URL resolution, remote URL loading, or browser runtime behavior. It may strip import queries and fragments; isolated variants are not canonical targets.",
+    "Source-map declarations are retained as metadata. No source maps or missing dependencies are fetched or reconstructed.",
+    "Captured response bytes are browser-decoded bytes; Debugger sources are the exposed text encoded as UTF-8. Redacted bytes are exported exactly as retained, and may no longer parse as JavaScript.",
+];
+/** Exclusively publish verified bytes and a manifest, rolling back partial work. */
+export const publishWebScripts = async (input, capture, captureSha256, signal) => {
+    const planned = planWebScriptExport(capture.scripts);
+    const tree = await SafeOutputTree.create(input.output_directory);
+    try {
+        signal?.throwIfAborted();
+        const records = planned.map(({ record }) => record);
+        const manifest = webScriptExportManifestSchema.parse({
+            capture_path: input.capture_path,
+            capture_sha256: captureSha256,
+            capture_kind: capture.kind,
+            source_evidence_id: capture.sourceEvidenceId,
+            capture_completeness: capture.completeness,
+            output_directory: tree.outputRoot,
+            analysis_input: records.some(({ content }) => content.state === "exported")
+                ? { input_path: join(tree.outputRoot, "files"), format: "directory" }
+                : null,
+            scripts: records,
+            limitations: [
+                ...capture.limitations,
+                ...LIMITATIONS,
+                ...(records.some(({ content }) => content.state === "exported")
+                    ? []
+                    : [
+                        "No script bytes were exportable. Include script sources in inspect_web_page or select response_body in capture_browser_scenario, then capture again.",
+                    ]),
+            ],
+        });
+        const bytes = Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`);
+        const digest = createHash("sha256").update(bytes).digest("hex");
+        const result = webScriptExportResultSchema.parse({
+            ...manifest,
+            manifest: {
+                path: join(tree.outputRoot, "manifest.json"),
+                sha256: digest,
+                bytes: bytes.length,
+            },
+        });
+        for (const { script, record } of planned) {
+            signal?.throwIfAborted();
+            if (script.content.state === "captured" &&
+                record.content.state === "exported")
+                await tree.write(`files/${record.content.relative_path}`, Readable.from([script.content.bytes]), script.content.sha256, signal);
+        }
+        await tree.write("manifest.json", Readable.from([bytes]), digest, signal);
+        signal?.throwIfAborted();
+        await tree.commit();
+        return result;
+    }
+    catch (cause) {
+        try {
+            await tree.rollback();
+        }
+        catch (cleanupCause) {
+            throw new WebScriptExportError("io", tree.outputRoot, `Publication failed (${message(cause)}); rollback failed (${message(cleanupCause)}). Remove the residual output directory before retrying.`, [tree.outputRoot]);
+        }
+        throw cause;
+    }
+};
+const message = (cause) => cause instanceof Error ? cause.message : "Unknown publication failure";

package/dist/browser/assets/ScenarioScriptCapture.js

@@ -0,0 +1,76 @@
+/** Join script response bytes only through explicit transaction and event identity. */
+export const scenarioScripts = (capture) => {
+    const index = indexResponses(capture.events.items);
+    return capture.events.items.flatMap((request) => {
+        if (request.kind !== "request" || request.resource_type !== "script")
+            return [];
+        return [projectRequest(request, index)];
+    });
+};
+const indexResponses = (events) => {
+    const index = {
+        responses: new Map(),
+        contents: new Map(),
+        requests: new Map(),
+    };
+    for (const event of events) {
+        if (event.kind === "request" && event.transaction_id !== undefined)
+            index.requests.set(event.transaction_id, (index.requests.get(event.transaction_id) ?? 0) + 1);
+        if (event.kind === "response" && event.transaction_id !== undefined)
+            append(index.responses, event.transaction_id, event);
+        if (event.kind === "network-content" && event.phase === "response")
+            append(index.contents, event.source_event_sequence, event);
+    }
+    return index;
+};
+const projectRequest = (request, index) => {
+    const id = request.transaction_id;
+    const matches = id === undefined ? [] : (index.responses.get(id) ?? []);
+    const response = matches.length === 1 ? matches[0] : undefined;
+    const bodies = response === undefined ? [] : (index.contents.get(response.sequence) ?? []);
+    const body = bodies.length === 1 ? bodies[0]?.body : undefined;
+    const ambiguous = (id !== undefined && index.requests.get(id) !== 1) ||
+        matches.length > 1 ||
+        bodies.length > 1;
+    return {
+        source: {
+            kind: "scenario-response",
+            transaction_id: id ?? null,
+            request_sequence: request.sequence,
+            response_sequence: ambiguous ? null : (response?.sequence ?? null),
+            status: ambiguous ? null : (response?.status ?? null),
+        },
+        url: request.url.url,
+        content: projectBody(body, id, ambiguous),
+    };
+};
+const unavailable = (reason, message) => ({ state: "unavailable", reason, message });
+const projectBody = (body, transactionId, ambiguous) => {
+    if (ambiguous)
+        return unavailable("ambiguous-transaction", "The capture does not identify one request, response, and content record for this transaction.");
+    if (body === undefined)
+        return unavailable(transactionId === undefined
+            ? "transaction-identity-unavailable"
+            : "response-content-not-retained", "No selected, completed script response bytes were retained for this request.");
+    if (body.state === "unavailable")
+        return unavailable(body.reason, body.message);
+    if (body.state !== "captured")
+        return unavailable(body.state, "No selected, completed script response bytes were retained for this request.");
+    if (body.representation !== "browser-decoded-response-bytes")
+        return unavailable("unsupported-body-representation", `Captured representation ${body.representation} is not script response bytes.`);
+    return {
+        state: "captured",
+        bytes: Buffer.from(body.content, "base64"),
+        sha256: body.sha256,
+        media_type: body.media_type,
+        redacted: body.redacted,
+        representation: body.representation,
+    };
+};
+const append = (map, key, value) => {
+    const existing = map.get(key);
+    if (existing === undefined)
+        map.set(key, [value]);
+    else
+        existing.push(value);
+};

package/dist/browser/assets/ScriptCaptureAdapters.js

@@ -0,0 +1,57 @@
+import { webPageInspectionSchema } from "../../domain/browserObservation.js";
+import { browserScenarioCaptureSchema } from "../../domain/browserScenarioCapture.js";
+import { parseEvidence } from "../../domain/evidence.js";
+import { pageScripts } from "./PageScriptCapture.js";
+import { scenarioScripts } from "./ScenarioScriptCapture.js";
+/** Built-in adapters; add capture formats here without changing the publisher. */
+export const SCRIPT_CAPTURE_ADAPTERS = [
+    {
+        operation: "inspect_web_page",
+        parse: (input) => {
+            const parsed = webPageInspectionSchema.safeParse(input);
+            return parsed.success
+                ? {
+                    kind: "page-inspection",
+                    completeness: parsed.data.completeness,
+                    scripts: pageScripts(parsed.data),
+                    limitations: parsed.data.limitations,
+                }
+                : undefined;
+        },
+    },
+    {
+        operation: "capture_browser_scenario",
+        parse: (input) => {
+            const parsed = browserScenarioCaptureSchema.safeParse(input);
+            return parsed.success
+                ? {
+                    kind: "browser-scenario",
+                    completeness: parsed.data.completeness,
+                    scripts: scenarioScripts(parsed.data),
+                    limitations: parsed.data.limitations,
+                }
+                : undefined;
+        },
+    },
+];
+/** Reject unsupported/malformed captures and tampered Evidence before writing. */
+export const selectScriptCapture = (raw, adapters = SCRIPT_CAPTURE_ADAPTERS) => {
+    if (typeof raw === "object" &&
+        raw !== null &&
+        ("normalized_result" in raw || "evidence_id" in raw)) {
+        const evidence = parseEvidence(raw);
+        const selected = adapters
+            .find(({ operation }) => operation === evidence.operation)
+            ?.parse(evidence.normalized_result);
+        if (selected !== undefined)
+            return { ...selected, sourceEvidenceId: evidence.evidence_id };
+    }
+    else {
+        for (const adapter of adapters) {
+            const selected = adapter.parse(raw);
+            if (selected !== undefined)
+                return { ...selected, sourceEvidenceId: null };
+        }
+    }
+    throw new TypeError("Expected a valid inspect_web_page or capture_browser_scenario capture, with retained script sources or response bytes. Evidence envelopes must have a matching operation and semantic identifier.");
+};

package/dist/browser/assets/WebArtifactReads.js

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
+import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
+import { AnalysisCancelledError, AnalysisInputError, } from "../../domain/analysisErrorCore.js";
+import { ArtifactOperationError } from "../../domain/artifactOperationError.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { safeParseJson } from "../../domain/safeJson.js";
+/** A malformed producer document, distinct from host I/O failures. */
+export class WebArtifactFormatFailure extends Error {
+}
+/** Decode exact UTF-8 content, preserving a BOM for digest verification. */
+export const decodeWebArtifact = (bytes) => {
+    try {
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch (cause) {
+        throw new WebArtifactFormatFailure("Selected artifact is not valid UTF-8.", { cause });
+    }
+};
+/** Read one stable JSON artifact with a documented byte budget. */
+export const readWebArtifactJson = async (path, maximumBytes, signal) => {
+    const data = await readStableArtifact(path, maximumBytes, signal);
+    const value = safeParseJson(decodeWebArtifact(data.bytes));
+    if (!value.ok)
+        throw new WebArtifactFormatFailure(value.error);
+    return { ...data, value: value.value };
+};
+/** Preserve artifact format, integrity, OS I/O, and cancellation reasons. */
+export const webArtifactReadError = (cause, context, signal) => {
+    if (signal?.aborted === true)
+        return new AnalysisCancelledError(context.operation);
+    if (cause instanceof ArtifactReaderFailure)
+        return new ArtifactOperationError(context.operation, cause.reason, cause.details, cause.message);
+    if (cause instanceof Error &&
+        "code" in cause &&
+        typeof cause.code === "string" &&
+        "syscall" in cause &&
+        typeof cause.syscall === "string")
+        return new ArtifactOperationError(context.operation, "io", undefined, `${context.field.join(".")}: ${cause.code}: ${cause.message}`);
+    if (cause instanceof WebArtifactFormatFailure || cause instanceof z.ZodError)
+        return new AnalysisInputError(context.operation, { cause }, [
+            {
+                path: context.field,
+                reason: "invalid_format",
+                message: `${context.targetPath}: ${cause.message}`,
+            },
+        ]);
+    return new ProviderAdapterError("captured-web-artifacts", context.operation, {
+        cause,
+        diagnostics: {
+            target_path: context.targetPath,
+            field: context.field.join("."),
+            error_message: cause instanceof Error ? cause.message : String(cause),
+        },
+    });
+};

package/dist/browser/assets/WebSourceLocationArtifacts.js

@@ -0,0 +1,40 @@
+import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
+import { WEB_SOURCE_MAP_LIMITS, } from "../../domain/webSourceLocation.js";
+import { err, ok } from "../../domain/result.js";
+import { LocalWebScriptArtifacts } from "./LocalWebScriptArtifacts.js";
+import { decodeWebArtifact, webArtifactReadError } from "./WebArtifactReads.js";
+/** Read one verified capture source and the caller-selected map, without fetching. */
+export class LocalWebSourceLocationArtifacts {
+    scripts;
+    constructor(scripts = new LocalWebScriptArtifacts("trace_web_source_location")) {
+        this.scripts = scripts;
+    }
+    /** Preserve actual map identity separately from the selected deployment URL. */
+    async load(input, options) {
+        const loaded = await this.scripts.load(input, options);
+        if (!loaded.ok)
+            return loaded;
+        try {
+            const data = await readStableArtifact(input.source_map.path, WEB_SOURCE_MAP_LIMITS.mapBytes, options?.signal);
+            return ok({
+                ...loaded.value,
+                sourceMap: {
+                    file: {
+                        path: input.source_map.path,
+                        sha256: data.sha256,
+                        bytes: data.bytes.length,
+                    },
+                    url: input.source_map.url,
+                    text: decodeWebArtifact(data.bytes),
+                },
+            });
+        }
+        catch (cause) {
+            return err(webArtifactReadError(cause, {
+                operation: "trace_web_source_location",
+                field: ["source_map", "path"],
+                targetPath: input.source_map.path,
+            }, options?.signal));
+        }
+    }
+}

package/dist/browser/execution/CdpEventListeners.js

@@ -0,0 +1,79 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { runtimeListenersSchema } from "./CdpRuntimeProtocol.js";
+import { queryListenerSelector } from "./CdpListenerSelector.js";
+/** Inspect native DOM listener descriptors without evaluating JavaScript or invoking handlers. */
+export const captureWebEventListeners = async (input, sources, group) => {
+    const session = sources.session;
+    session.beginCompletion();
+    const unsubscribe = session.transport.connection.onEvent((event) => sources.ingest(event));
+    try {
+        for (const domain of ["Page", "Runtime", "Debugger", "DOM"])
+            await session.enable(domain);
+        await session.assertDocument();
+        const document = z
+            .object({ root: z.object({ nodeId: z.number().int().min(1) }) })
+            .parse(await session.command("DOM.getDocument", { depth: 0 }));
+        const selected = z
+            .object({ nodeId: z.number().int().min(0) })
+            .parse(await queryListenerSelector(session, document.root.nodeId, input.selector));
+        let backendNodeId = null;
+        let descriptors = [];
+        if (selected.nodeId !== 0) {
+            const described = z
+                .object({ node: z.object({ backendNodeId: z.number().int().min(1) }) })
+                .parse(await session.command("DOM.describeNode", {
+                nodeId: selected.nodeId,
+            }));
+            backendNodeId = described.node.backendNodeId;
+            const resolved = z
+                .object({ object: z.object({ objectId: z.string().min(1) }) })
+                .parse(await session.command("DOM.resolveNode", {
+                nodeId: selected.nodeId,
+                objectGroup: group,
+            }));
+            descriptors = runtimeListenersSchema.parse(await session.command("DOMDebugger.getEventListeners", {
+                objectId: resolved.object.objectId,
+                depth: 0,
+                pierce: false,
+            })).listeners;
+        }
+        const retained = await sources.read(descriptors
+            .map((listener) => listener.scriptId)
+            .filter((id) => id.length > 0));
+        await session.assertDocument();
+        sources.check();
+        return {
+            browser: session.discovery.version,
+            target: session.target,
+            inspected_at: new Date().toISOString(),
+            selected_node: {
+                selector: input.selector,
+                match: selected.nodeId === 0 ? "not_found" : "found",
+                backend_node_id: backendNodeId,
+            },
+            listeners: descriptors.map((listener) => ({
+                type: listener.type,
+                use_capture: listener.useCapture,
+                passive: listener.passive,
+                once: listener.once,
+                location: sources.location(listener.scriptId, sources.scripts.get(listener.scriptId)?.url ?? null, listener.lineNumber, listener.columnNumber),
+                execution: "unknown",
+            })),
+            sources: retained,
+            cleanup: "confirmed",
+            limitations: [
+                "Inspects listeners registered directly on the first native CSS match in the selected main document. Delegated ancestor listeners, descendants, closed shadow roots and framework registries are not enumerated.",
+                "Native CDP listener descriptors report callback locations; registration time, dispatch history and UI causality remain unknown. REA does not dispatch an event, evaluate JavaScript or invoke a handler.",
+                "Source identity uses this session's script ID and proven main-frame default-world metadata. Isolated or unknown worlds cannot establish website callback/source joins. A URL or sourceURL declaration never establishes identity or execution.",
+                "Source text is retained inline with its independently computed UTF-8 digest; the producer hash is preserved separately. Missing source ownership or collected scripts remain explicit.",
+                "REA releases its remote object group, disables enabled domains and detaches its transport; the externally owned page remains open.",
+            ],
+        };
+    }
+    finally {
+        unsubscribe();
+    }
+};
+/** Use an owned remote object namespace so cleanup does not release caller objects. */
+export const eventListenerObjectGroup = () => `rea-listeners-${randomUUID()}`;