@specific.dev/spectest 0.131.15 → 0.131.17

package/README.md

@@ -83,6 +83,36 @@ Pub/Sub integrations are project-owned as of SDK 0.98.0. The former
 Use a local service definition or `serviceGroup()` wrapper; the repository’s
 `examples/google-pubsub` demonstrates this using public SDK APIs.
 
+## Browser coverage across navigation (0.131.17)
+
+Browser coverage keeps script identities separate when Chromium changes renderers
+during cross-site navigation, including login redirects. Anonymous browser code
+cannot inherit an earlier script’s URL or source map. No application configuration
+change is needed. A script identity change during capture is reported as incomplete
+coverage instead of publishing uncertain attribution.
+
+## Next.js coverage (0.131.16)
+
+Use `coverage.next({ appDir: "ops", sourceRoot: "." })` in your Spectest
+service configuration to collect server and browser coverage. Keep Next's
+server and browser source maps in the runtime image. `appDir` is relative to
+the container working directory; `sourceRoot` identifies the repository
+directory represented by the build's source-map root.
+
+Standalone servers launched through Node wrappers can change working directory:
+the adapter preserves the launcher's generated dependency identity in children.
+Turbopack's generated image modules, including SVG data-URL wrappers, are
+excluded automatically wherever the asset lives. Authored asset and application
+sources are not excluded.
+
+For Next 16.4.3, the adapter also corrects a reproduced Turbopack Edge source-map
+path defect using Next's resolved build manifest (`appDir`, `distDir`, and
+`turbopack.root`). This happens while the collector reads a map, before it creates
+the coverage record. No application build-script workaround is required. The
+correction is scoped to that verified version and layout; correctly emitted maps
+and other versions retain normal source-map interpretation. Unknown source paths
+remain unresolved and cannot authorize subset selection.
+
 ## Supabase function coverage (0.122.0)
 
 `supabase({ dir: "supabase" })` automatically collects coverage for its edge

package/dist/browser-coverage.js

@@ -47,8 +47,9 @@ export async function attachBrowserCoverage(cdp) {
     COLLECTORS.set(cdp, collector);
     LIVE_COLLECTORS.add(collector);
     cdp.on("Debugger.scriptParsed", (ev) => {
-        if (!ev.url)
-            return;
+        // IDs belong to a renderer, not the lifetime of this CDP session. A
+        // cross-site navigation can reuse an old named ID for anonymous code.
+        // Replace anonymous entries too, invalidating the previous URL/source/map.
         collector.scripts.set(ev.scriptId, {
             url: ev.url,
             sourceMapURL: ev.sourceMapURL || undefined,
@@ -108,6 +109,7 @@ export async function harvestBrowserCoverage(cdp, signal) {
     }
 }
 async function harvestInner(c, config, signal) {
+    const scriptsAtTake = new Map(c.scripts);
     let result;
     try {
         ({ result } = (await c.cdp.send("Profiler.takePreciseCoverage")));
@@ -119,12 +121,13 @@ async function harvestInner(c, config, signal) {
         throw err;
     }
     for (const script of result) {
-        const info = c.scripts.get(script.scriptId) ?? (script.url ? { url: script.url } : undefined);
-        if (!info)
+        // The profiler's URL identifies this execution. Never supply a URL from
+        // an earlier renderer to an anonymous result.
+        if (!script.url)
             continue;
         let url;
         try {
-            url = new URL(info.url);
+            url = new URL(script.url);
         }
         catch {
             continue;
@@ -134,19 +137,34 @@ async function harvestInner(c, config, signal) {
         const service = config.serviceForHost(url.hostname);
         if (!service)
             continue;
+        let info = c.scripts.get(script.scriptId);
+        const before = scriptsAtTake.get(script.scriptId);
+        const changed = () => {
+            c.incomplete = new Error("Browser script identity changed during coverage capture; coverage is incomplete");
+            return c.incomplete;
+        };
+        if ((before && before !== info) || (info && info.url !== script.url))
+            throw changed();
+        if (!info) {
+            info = { url: script.url };
+            c.scripts.set(script.scriptId, info);
+        }
         if (info.source === undefined) {
             try {
                 const r = (await c.cdp.send("Debugger.getScriptSource", {
                     scriptId: script.scriptId,
                 }));
                 signal.throwIfAborted();
+                if (c.scripts.get(script.scriptId) !== info)
+                    throw changed();
                 info.source = r.scriptSource;
             }
             catch {
                 signal.throwIfAborted();
+                if (c.incomplete)
+                    throw c.incomplete;
                 continue; // script gone with its document
             }
-            c.scripts.set(script.scriptId, info);
         }
         const generated = rangesToLineCounts(info.source, script.functions);
         if (generated.size === 0)

package/dist/coverage-next.js

@@ -15,7 +15,8 @@ const root = process.env.SPECTEST_COVERAGE_ROOT || process.cwd();
 process.env.SPECTEST_COVERAGE_ROOT = root;
 const app = path.resolve(root, options.appDir || ".");
 const dist = path.resolve(app, options.distDir || ".next");
-function manifest() { return JSON.parse(fs.readFileSync(path.join(dist, "required-server-files.json"), "utf8")); }
+let build;
+function manifest() { return build ||= JSON.parse(fs.readFileSync(path.join(dist, "required-server-files.json"), "utf8")); }
 function launcher(m) {
   const file = path.join(app, "server.js");
   if (m.config.output !== "standalone" || !fs.existsSync(file)) return null;
@@ -29,6 +30,55 @@ try {
     ...new Set([...JSON.parse(process.env.SPECTEST_COVERAGE_GENERATED_FILES || "[]"), file])
   ]);
 } catch {} // Capture reports a useful error; do not change application startup.
+
+// Next 16.4.3 gives its Edge chunker the offset from distDir to turbopack.root,
+// although the chunker's output root is distDir/server/edge. Recover the exact
+// serialized prefix from the build configuration, not from repository suffixes.
+// See docs/validation/next-coverage-20261102.md for the unmodified-build repro
+// and upstream implementation. Other versions/layouts keep normal map semantics.
+let edgePolicy;
+function edgeSourcePolicy() {
+  if (edgePolicy !== undefined) return edgePolicy;
+  edgePolicy = null;
+  try {
+    const version = JSON.parse(fs.readFileSync(require.resolve("next/package.json", {paths:[app]}), "utf8")).version;
+    if (version !== "16.4.3") return null;
+    const m = manifest(), config = m.config;
+    const buildRoot = config.turbopack && config.turbopack.root;
+    if (typeof m.appDir !== "string" || !path.isAbsolute(m.appDir) ||
+        typeof buildRoot !== "string" || !path.isAbsolute(buildRoot) ||
+        typeof config.distDir !== "string") return null;
+    const offset = path.relative(path.resolve(m.appDir, config.distDir), buildRoot);
+    if (!offset || !offset.split(path.sep).every(p => p === "..")) return null;
+    edgePolicy = {root:path.join(dist, "server/edge"), offset};
+  } catch {} // Unknown build metadata cannot authorize a source correction.
+  return edgePolicy;
+}
+exports.normalizeSourceMap = function(data, mapFile) {
+  const policy = edgeSourcePolicy();
+  if (!policy) return;
+  const relative = path.relative(policy.root, mapFile);
+  if (!relative.startsWith("chunks" + path.sep) || path.isAbsolute(relative) || relative.split(path.sep).includes("..")) return;
+  const prefix = path.relative(path.dirname(mapFile), policy.root).split(path.sep).join("/") + "/" + policy.offset.split(path.sep).join("/") + "/";
+  function visit(map, depth) {
+    if (!map || typeof map !== "object" || depth > 32 || map.sourceRoot) return;
+    if (Array.isArray(map.sections)) {
+      for (const section of map.sections) if (section && !section.url) visit(section.map, depth + 1);
+    }
+    if (!Array.isArray(map.sources)) return;
+    map.sources = map.sources.map(source => {
+      if (typeof source !== "string" || !source.startsWith(prefix)) return source;
+      const suffix = source.slice(prefix.length);
+      let decoded;
+      try { decoded = decodeURIComponent(suffix); } catch { return source; }
+      // Correctly emitted paths have two extra '..' components. Never rewrite
+      // those, absolute/virtual sources, escapes or another root's sources.
+      if (/[\\:\0?#]/.test(decoded) || decoded.split("/").some(p => !p || p === "." || p === "..")) return source;
+      return "turbopack:///[project]/" + suffix;
+    });
+  }
+  visit(data, 0);
+};
 if (require.main === module) {
   try {
     const m = manifest();
@@ -54,8 +104,9 @@ const GENERATED_SOURCES = [
     "*/data:* <text/javascript>", // Turbopack virtual modules, including action proxies.
     "*/.next-internal/server/app/*/actions.js (server actions loader)",
     "*/app/*--route-entry.js",
-    "*/*.mjs (structured image object)",
-    "*/*.mjs (structured image object with data url)",
+    "turbopack:///[project]/*.mjs (structured image object)",
+    "turbopack:///[project]/*.mjs (structured image object with data url)",
+    "*/app/*.mjs (structured image object)", // Older Next map identities.
 ];
 /** Server + browser coverage for a built Next app. Build-time maps are required;
  * enable native Next source maps and retain them in the runtime image.
@@ -90,7 +141,8 @@ export function next(options = {}) {
                 env: { ...configured.env,
                     NODE_OPTIONS: `--require ${NEXT_COVERAGE_HELPER_PATH} ${configured.env.NODE_OPTIONS}`,
                     SPECTEST_NEXT_COVERAGE_OPTIONS: JSON.stringify(options),
-                    SPECTEST_COVERAGE_SERVICE: info.key, },
+                    SPECTEST_COVERAGE_SERVICE: info.key,
+                    SPECTEST_COVERAGE_SOURCE_MAP_ADAPTER: NEXT_COVERAGE_HELPER_PATH, },
                 files: [...configured.files, { path: NEXT_COVERAGE_HELPER_PATH, content: NEXT_COVERAGE_HELPER }],
             };
         },

package/dist/coverage.js

@@ -353,6 +353,8 @@ export const NODE_COVERAGE_HOOK = `"use strict";
     return "generated:" + process.env.SPECTEST_COVERAGE_SERVICE + ":" + file + "#" + crypto.createHash("sha256").update(text).digest("hex");
   }
   const SELF = url.pathToFileURL(__filename).href;
+  const SOURCE_MAP_ADAPTER = process.env.SPECTEST_COVERAGE_SOURCE_MAP_ADAPTER;
+  const SOURCE_MAP_ADAPTER_URL = SOURCE_MAP_ADAPTER ? url.pathToFileURL(path.resolve(SOURCE_MAP_ADAPTER)).href : null;
   const SCRIPTS = path.join(dir, ${JSON.stringify(NODE_COVERAGE_SCRIPTS_SUBDIR)});
   const MARKERS = path.join(dir, ${JSON.stringify(NODE_COVERAGE_MARKERS_SUBDIR)});
   // V8 script ids identify a compiled script within this process. A URL
@@ -365,7 +367,7 @@ export const NODE_COVERAGE_HOOK = `"use strict";
   fs.writeFileSync(path.join(dir, ".attached-" + (bunRuntime ? "bun" : "node")), "");
 
   function isApp(u) {
-    return typeof u === "string" && u.startsWith("file://") && u.indexOf("/node_modules/") < 0 && u.indexOf("/.cache/") < 0 && u !== SELF;
+    return typeof u === "string" && u.startsWith("file://") && u.indexOf("/node_modules/") < 0 && u.indexOf("/.cache/") < 0 && u !== SELF && u !== SOURCE_MAP_ADAPTER_URL;
   }
   function isDep(u) {
     return typeof u === "string" && u.startsWith("file://") && u.indexOf("/node_modules/") >= 0 && u !== SELF;
@@ -462,6 +464,10 @@ export const NODE_COVERAGE_HOOK = `"use strict";
     } catch (e) {
       return null;
     }
+    // Framework policy runs before dependency attribution and before the final
+    // descriptor is hashed. The collector remains the sole owner of record IDs,
+    // deduplication, dump references and cleanup (including exit-time captures).
+    if (SOURCE_MAP_ADAPTER) require(SOURCE_MAP_ADAPTER).normalizeSourceMap(data, mapUrl ? url.fileURLToPath(mapUrl) : scriptPath);
     // A source inside node_modules is a dependency: its unit id rides
     // beside the map (\`sourceUnits[i]\`, null for the project's own), so
     // the control plane never has to know what node_modules is.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.131.15",
+  "version": "0.131.17",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/browser-coverage-deadline.test.ts

@@ -27,7 +27,10 @@ test("an ambiguous coverage timeout is retained and a late CDP result cannot pub
     await Bun.sleep(0);
     expect(sourceReads).toBe(0);
     expect(browserCoverageReports().has("coverage-deadline-test")).toBe(false);
-    await expect(harvestAllBrowserCoverage()).rejects.toThrow("Browser coverage capture was interrupted; coverage is incomplete");
+    // Other tests may also retain incomplete collectors. Global harvest must
+    // reject; this session must retain its own interruption reason.
+    await expect(harvestAllBrowserCoverage()).rejects.toThrow("coverage is incomplete");
+    await expect(harvestBrowserCoverage(cdp)).rejects.toThrow("Browser coverage capture was interrupted; coverage is incomplete");
     expect(takes).toBe(1);
   } finally { configureBrowserCoverage(null); }
 });

package/src/browser-coverage-identity.test.ts

@@ -0,0 +1,87 @@
+import { expect, test } from "bun:test";
+import { EventEmitter } from "node:events";
+import type { CDPSession } from "playwright-core";
+import {
+  attachBrowserCoverage, configureBrowserCoverage, harvestBrowserCoverage,
+  takeBrowserCoverageReport,
+} from "./browser-coverage.js";
+
+function session() {
+  const events = new EventEmitter();
+  let source = "globalThis.ran = true;";
+  let url = "http://app.test/app.js";
+  const cdp = Object.assign(events, {
+    async send(method: string): Promise<any> {
+      if (method === "Profiler.takePreciseCoverage") return { result: [{ scriptId: "4", url,
+        functions: [{ ranges: [{ startOffset: 0, endOffset: source.length, count: 1 }] }] }] };
+      if (method === "Debugger.getScriptSource") return { scriptSource: source };
+      return {};
+    },
+  }) as unknown as CDPSession;
+  return { cdp, parsed(nextUrl = url, nextSource = source, sourceMapURL?: string) {
+    url = nextUrl; source = nextSource;
+    events.emit("Debugger.scriptParsed", { scriptId: "4", url, sourceMapURL });
+  } };
+}
+
+const inlineMap = (source: string) => "data:application/json;base64," + Buffer.from(JSON.stringify({
+  version: 3, sources: [source], names: [], mappings: "AAAA",
+})).toString("base64");
+
+test("a reused named ID replaces cached source maps even when its URL is unchanged", async () => {
+  const s = session();
+  configureBrowserCoverage({ serviceForHost: () => "identity-maps" });
+  try {
+    await attachBrowserCoverage(s.cdp);
+    s.parsed(undefined, undefined, inlineMap("src/old.ts"));
+    await harvestBrowserCoverage(s.cdp);
+    expect(takeBrowserCoverageReport("identity-maps")).toContain("SF:src/old.ts");
+    s.parsed(undefined, undefined, inlineMap("src/new.ts"));
+    await harvestBrowserCoverage(s.cdp);
+    const report = takeBrowserCoverageReport("identity-maps");
+    expect(report).toContain("SF:src/new.ts");
+    expect(report).not.toContain("src/old.ts");
+  } finally { configureBrowserCoverage(null); takeBrowserCoverageReport("identity-maps"); }
+});
+
+test("the profiler's anonymous URL cannot inherit a stale named URL", async () => {
+  const s = session();
+  configureBrowserCoverage({ serviceForHost: () => "identity-anonymous" });
+  try {
+    await attachBrowserCoverage(s.cdp);
+    s.parsed();
+    const send = s.cdp.send.bind(s.cdp);
+    s.cdp.send = (async (method: string) => {
+      if (method === "Profiler.takePreciseCoverage") {
+        const result = await send(method as any) as any;
+        result.result[0].url = "";
+        return result;
+      }
+      return send(method as any);
+    }) as CDPSession["send"];
+    await harvestBrowserCoverage(s.cdp);
+    expect(takeBrowserCoverageReport("identity-anonymous")).toBe("TN:\n");
+  } finally { configureBrowserCoverage(null); }
+});
+
+for (const phase of ["Profiler.takePreciseCoverage", "Debugger.getScriptSource"]) {
+  test(`script replacement during ${phase} retains an incomplete-capture error`, async () => {
+    const s = session();
+    const service = `identity-race-${phase}`;
+    configureBrowserCoverage({ serviceForHost: () => service });
+    try {
+      await attachBrowserCoverage(s.cdp);
+      s.parsed();
+      const send = s.cdp.send.bind(s.cdp);
+      s.cdp.send = (async (method: string) => {
+        const result = await send(method as any);
+        // The same URL and ID now refer to a different renderer's script.
+        if (method === phase) s.parsed(undefined, "globalThis.replacement = true;");
+        return result;
+      }) as CDPSession["send"];
+      await expect(harvestBrowserCoverage(s.cdp)).rejects.toThrow("identity changed during coverage capture");
+      expect(takeBrowserCoverageReport(service)).toBe("TN:\n");
+      await expect(harvestBrowserCoverage(s.cdp)).rejects.toThrow("coverage is incomplete");
+    } finally { configureBrowserCoverage(null); takeBrowserCoverageReport(service); }
+  });
+}

package/src/browser-coverage-navigation.test.ts

@@ -0,0 +1,54 @@
+import { expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import { chromium } from "playwright-core";
+import {
+  attachBrowserCoverage, configureBrowserCoverage, harvestBrowserCoverage,
+  takeBrowserCoverageReport,
+} from "./browser-coverage.js";
+
+const executablePath = Bun.which("chromium") ?? Bun.which("chromium-browser") ??
+  Bun.which("google-chrome") ?? chromium.executablePath();
+
+test.skipIf(!existsSync(executablePath))("cross-site script ID reuse cannot attribute anonymous code to an earlier empty script", async () => {
+  const emptyScript = "/ingest/static/1.438.19/exception-autocapture.js";
+  const map = Buffer.from(JSON.stringify({ version: 3, sources: ["src/customer.ts"], names: [], mappings: "AAAA" })).toString("base64");
+  const server = Bun.serve({ hostname: "0.0.0.0", port: 0, fetch(request) {
+    const url = new URL(request.url);
+    if (url.pathname === emptyScript) return new Response("", { headers: { "content-type": "application/javascript" } });
+    if (url.pathname === "/app.js") return new Response(`globalThis.appRan = true;\n//# sourceMappingURL=data:application/json;base64,${map}`, { headers: { "content-type": "application/javascript" } });
+    return new Response(url.hostname === "127.0.0.1"
+      ? `<script src="${emptyScript}"></script><script src="/app.js"></script><p>Application</p>`
+      : "<p>External login</p>", { headers: { "content-type": "text/html", "cache-control": "no-store" } });
+  } });
+  const browser = await chromium.launch({ executablePath, headless: true, args: ["--no-sandbox", "--site-per-process"] });
+  try {
+    const page = await browser.newPage();
+    const cdp = await page.context().newCDPSession(page);
+    const urls = new Map<string, string>();
+    let anonymousReuse = false;
+    cdp.on("Debugger.scriptParsed", event => {
+      if (urls.get(event.scriptId)?.endsWith(emptyScript) && !event.url) anonymousReuse = true;
+      urls.set(event.scriptId, event.url);
+    });
+    configureBrowserCoverage({ serviceForHost: host => host === "127.0.0.1" ? "navigation-test" : undefined });
+    await attachBrowserCoverage(cdp);
+    // Use different sites to force a renderer swap, then return to the app.
+    // Keep collected application counts across navigation until service capture.
+    for (const host of ["127.0.0.1", "127.0.0.2", "127.0.0.1", "127.0.0.2"]) {
+      await page.goto(`http://${host}:${server.port}/`);
+      await page.evaluate("(() => { const value = 1; return value + 1; })()");
+      await harvestBrowserCoverage(cdp);
+    }
+    expect(anonymousReuse).toBe(true); // Prove the regression's trigger happened.
+    const report = takeBrowserCoverageReport("navigation-test");
+    expect(report).toContain("SF:src/customer.ts\nDA:1,2\n");
+    expect(report).not.toContain(emptyScript);
+    expect(report.match(/^SF:/gm)).toHaveLength(1);
+    await cdp.detach();
+  } finally {
+    configureBrowserCoverage(null);
+    takeBrowserCoverageReport("navigation-test");
+    await browser.close();
+    server.stop(true);
+  }
+}, 15000);

package/src/browser-coverage.ts

@@ -87,7 +87,9 @@ export async function attachBrowserCoverage(cdp: CDPSession): Promise<void> {
   COLLECTORS.set(cdp, collector);
   LIVE_COLLECTORS.add(collector);
   cdp.on("Debugger.scriptParsed", (ev: { scriptId: string; url: string; sourceMapURL?: string }) => {
-    if (!ev.url) return;
+    // IDs belong to a renderer, not the lifetime of this CDP session. A
+    // cross-site navigation can reuse an old named ID for anonymous code.
+    // Replace anonymous entries too, invalidating the previous URL/source/map.
     collector.scripts.set(ev.scriptId, {
       url: ev.url,
       sourceMapURL: ev.sourceMapURL || undefined,
@@ -141,6 +143,7 @@ export async function harvestBrowserCoverage(cdp: CDPSession, signal?: AbortSign
 }
 
 async function harvestInner(c: Collector, config: BrowserCoverageConfig, signal: AbortSignal): Promise<void> {
+  const scriptsAtTake = new Map(c.scripts);
   let result: { scriptId: string; url: string; functions: V8FunctionCoverage[] }[];
   try {
     ({ result } = (await c.cdp.send("Profiler.takePreciseCoverage")) as { result: typeof result });
@@ -150,29 +153,42 @@ async function harvestInner(c: Collector, config: BrowserCoverageConfig, signal:
     throw err;
   }
   for (const script of result) {
-    const info = c.scripts.get(script.scriptId) ?? (script.url ? { url: script.url } : undefined);
-    if (!info) continue;
+    // The profiler's URL identifies this execution. Never supply a URL from
+    // an earlier renderer to an anonymous result.
+    if (!script.url) continue;
     let url: URL;
     try {
-      url = new URL(info.url);
+      url = new URL(script.url);
     } catch {
       continue;
     }
     if (url.protocol !== "http:" && url.protocol !== "https:") continue;
     const service = config.serviceForHost(url.hostname);
     if (!service) continue;
+    let info = c.scripts.get(script.scriptId);
+    const before = scriptsAtTake.get(script.scriptId);
+    const changed = () => {
+      c.incomplete = new Error("Browser script identity changed during coverage capture; coverage is incomplete");
+      return c.incomplete;
+    };
+    if ((before && before !== info) || (info && info.url !== script.url)) throw changed();
+    if (!info) {
+      info = { url: script.url };
+      c.scripts.set(script.scriptId, info);
+    }
     if (info.source === undefined) {
       try {
         const r = (await c.cdp.send("Debugger.getScriptSource", {
           scriptId: script.scriptId,
         })) as { scriptSource: string };
         signal.throwIfAborted();
+        if (c.scripts.get(script.scriptId) !== info) throw changed();
         info.source = r.scriptSource;
       } catch {
         signal.throwIfAborted();
+        if (c.incomplete) throw c.incomplete;
         continue; // script gone with its document
       }
-      c.scripts.set(script.scriptId, info);
     }
     const generated = rangesToLineCounts(info.source, script.functions);
     if (generated.size === 0) continue;

package/src/coverage-next.test.ts

@@ -1,6 +1,7 @@
 import { describe, test, expect } from "bun:test";
 import { next, NEXT_COVERAGE_HELPER, NEXT_COVERAGE_HELPER_PATH, type NextBuildMetadata } from "./coverage-next.js";
 import { applyCoverageAdapters, resolveCoverageSourceOptions, attachCoverageSourceOptions, node, browser, NODE_COVERAGE_HOOK, NODE_COVERAGE_SCRIPTS_SUBDIR, NODE_COVERAGE_MARKERS_SUBDIR, type CoverageSourceContext } from "./coverage.js";
+import { createHash } from "node:crypto";
 import { applyCoverageDelta, encodeCoverageBundle } from "./harness/coverage.js";
 import { gunzipSync } from "node:zlib";
 import { promises as fs } from "node:fs";
@@ -45,6 +46,7 @@ describe("Next adapter", () => {
       const configured = applyCoverageAdapters("web", {image, coverage:{adapters:[adapter]}});
       const env = {...process.env, ...configured.env,
         SPECTEST_COVERAGE_DIR:reports,
+        ...(kind === "next" ? { SPECTEST_COVERAGE_SOURCE_MAP_ADAPTER: helper } : {}),
         NODE_OPTIONS: `${kind === "next" ? `--require ${helper} ` : ""}--require ${hook}`,
       } as NodeJS.ProcessEnv;
       const ctx: CoverageSourceContext = {
@@ -70,8 +72,8 @@ describe("Next adapter", () => {
     const policies = await resolveCoverageSourceOptions([next({appDir:"ops"})], context());
     const capture = attachCoverageSourceOptions({reports:[{name:"node-1.json"},{name:"browser.lcov"}]}, policies);
     for (const report of capture.reports) {
-      expect(report.sourceOptions!.excludeSources).toContain("*/*.mjs (structured image object)");
-      expect(report.sourceOptions!.excludeSources).toContain("*/*.mjs (structured image object with data url)");
+      expect(report.sourceOptions!.excludeSources).toContain("turbopack:///[project]/*.mjs (structured image object)");
+      expect(report.sourceOptions!.excludeSources).toContain("turbopack:///[project]/*.mjs (structured image object with data url)");
       expect(report.sourceOptions!.excludeSources).not.toContain("*/public/*");
     }
   });
@@ -146,4 +148,164 @@ describe("Next adapter", () => {
       expect(probe).toThrow();
     } finally {await fs.rm(dir,{recursive:true,force:true});}
   });
+
+  test("generated image wrappers are excluded across asset locations without excluding authored modules", async () => {
+    const policies = await resolveCoverageSourceOptions([next()], context());
+    const patterns = policies[0]!.options!.excludeSources!;
+    // The wire contract treats only '*' as special (including '/').
+    const excluded = (source: string) => patterns.some(pattern => new RegExp("^" +
+      pattern.split("*").map(part => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$").test(source));
+    for (const folder of ["app", "ops/public", "packages/ui/assets", "src/images"]) {
+      for (const suffix of ["structured image object", "structured image object with data url"]) {
+        expect(excluded(`turbopack:///[project]/${folder}/invoice.svg.mjs (${suffix})`)).toBe(true);
+      }
+      expect(excluded(`turbopack:///[project]/${folder}/invoice.svg`)).toBe(false);
+      expect(excluded(`turbopack:///[project]/${folder}/image.mjs`)).toBe(false);
+    }
+    expect(excluded("turbopack:///[project]/ops/src/middleware.ts")).toBe(false);
+    expect(excluded("https://example.com/image.mjs (structured image object with data url)")).toBe(false);
+  });
+
+  test("a cwd-changing wrapper keeps launcher units consistent and Edge source records valid across captures", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "next-child-cov-"));
+    const reports = path.join(dir, "reports");
+    const helper = path.join(dir, "next-helper.cjs");
+    const hook = path.join(dir, "hook.cjs");
+    const adapter = next({ appDir: "ops" });
+    const config = adapter.configure!({ image }, { key: "web" });
+    const sourceText = "export function middleware() { return 42; }\n";
+    const source = "ops/src/middleware.ts";
+    const digest = (text: string) => createHash("sha256").update(text).digest("hex");
+    const env: NodeJS.ProcessEnv = { ...process.env, ...config.env, SPECTEST_COVERAGE_DIR: reports,
+      NODE_OPTIONS: `--require ${helper} --require ${hook}`,
+      SPECTEST_COVERAGE_SOURCE_MAP_ADAPTER: helper };
+    delete env.SPECTEST_COVERAGE_ROOT;
+    const ctx = {
+      service: "web", reportDir: reports, signal: new AbortController().signal,
+      projectFiles: async () => [source],
+      readProjectFile: async (file: string) => file === source ? sourceText : null,
+      writeReport: (name: string, content: string) => fs.writeFile(path.join(reports, name), content),
+      async exec(command: string) {
+        const proc = Bun.spawn(["sh", "-c", command.replace(NEXT_COVERAGE_HELPER_PATH, helper)],
+          { cwd: dir, env: { ...env, NODE_OPTIONS: "" }, stdout: "pipe", stderr: "pipe" });
+        const stdout = await new Response(proc.stdout).text();
+        const stderr = await new Response(proc.stderr).text();
+        if (await proc.exited !== 0) throw new Error(stderr);
+        return { stdout, stderr };
+      },
+    };
+    try {
+      await fs.mkdir(path.join(dir, "ops/.next/server/edge/chunks"), { recursive: true });
+      await fs.mkdir(path.join(dir, "ops/.next/static"), { recursive: true });
+      await fs.mkdir(reports);
+      await fs.mkdir(path.join(dir, "node_modules/next"), { recursive: true });
+      await fs.writeFile(path.join(dir, "node_modules/next/package.json"), JSON.stringify({ version: "16.4.3" }));
+      await fs.writeFile(helper, NEXT_COVERAGE_HELPER);
+      await fs.writeFile(hook, NODE_COVERAGE_HOOK);
+      await fs.writeFile(path.join(dir, "ops/.next/required-server-files.json"), JSON.stringify({ appDir: "/build/ops", config: { output: "standalone", distDir: ".next", turbopack: { root: "/build" } } }));
+      await fs.writeFile(path.join(dir, "ops/.next/static/browser.js.map"), "{}");
+      const edge = path.join(dir, "ops/.next/server/edge/chunks/middleware.js");
+      await fs.writeFile(edge, "globalThis.edgeValue = 42;\n");
+      await fs.writeFile(edge + ".map", JSON.stringify({ version: 3, sections: [{ offset: { line: 0, column: 0 }, map: {
+        version: 3, sources: ["../../../ops/src/middleware.ts"], sourcesContent: [sourceText], mappings: "AAAA", names: [],
+      } }] }));
+      const launcher = '// __NEXT_PRIVATE_STANDALONE_CONFIG next/dist/server/lib/start-server\nrequire("./.next/server/edge/chunks/middleware.js");\n';
+      await fs.writeFile(path.join(dir, "ops/server.js"), launcher);
+      // Also exercise process.chdir before spawn, not just the spawn cwd option.
+      await fs.writeFile(path.join(dir, "wrapper.cjs"), `
+        process.chdir("ops");
+        require("node:child_process").execFileSync(process.execPath, ["server.js"], { cwd: process.cwd(), stdio: "inherit" });
+      `);
+      const run = () => execFileSync("node", ["wrapper.cjs"], { cwd: dir, env, stdio: ["ignore", "pipe", "pipe"] });
+      const unit = `generated:web:ops/server.js#${digest(launcher)}`;
+      let correctedId: string | undefined;
+      for (let capture = 0; capture < 2; capture++) {
+        run();
+        // The exit hook must already have written the final descriptor and ID,
+        // before harness metadata/capture executes or reads project files.
+        const rawRecords = await Promise.all((await fs.readdir(path.join(reports, "scripts")))
+          .map(async name => [name, await fs.readFile(path.join(reports, "scripts", name), "utf8")] as const));
+        await resolveCoverageSourceOptions([adapter], ctx);
+        await adapter.capture!(ctx);
+        const dumps = await Promise.all((await fs.readdir(reports)).filter(n => /^node-.*\.json$/.test(n))
+          .map(async n => JSON.parse(await fs.readFile(path.join(reports, n), "utf8"))));
+        expect(dumps.flatMap(d => d.units ?? [])).toContain(unit);
+        expect(dumps.flatMap(d => d.result).some(s => s.url.endsWith("/ops/server.js"))).toBe(false);
+        const executed = dumps.flatMap(d => d.result).find(s => s.url.endsWith("/middleware.js"));
+        expect(executed).toBeDefined();
+        if (capture === 0) {
+          correctedId = executed.spectestScript;
+          const text = await fs.readFile(path.join(reports, "scripts", `${correctedId}.json`), "utf8");
+          expect(digest(text).slice(0, 32)).toBe(correctedId);
+          const map = JSON.parse(text).spectestScript.sourceMap.data.sections[0].map;
+          expect(map.sources).toEqual(["turbopack:///[project]/ops/src/middleware.ts"]);
+          expect(map.sourcesContent).toBeUndefined();
+          expect(map.x_spectestSourceHashes).toBeUndefined();
+          expect(rawRecords.find(([name]) => name === `${correctedId}.json`)?.[1]).toBe(text);
+        } else {
+          // Node deduplicates the original record; the second capture must
+          // reference the corrected record archived with the first capture.
+          expect(executed.spectestScript).toBe(correctedId);
+          expect(await fs.readdir(path.join(reports, "scripts"))).toEqual([]);
+        }
+      }
+      expect(await adapter.inventory!(ctx)).toContain(unit);
+    } finally { await fs.rm(dir, { recursive: true, force: true }); }
+  });
+});
+
+describe("Next Edge build configuration", () => {
+  async function normalize({ appDir = "ops", distDir = ".next", buildApp = "/build/ops", buildRoot = "/build",
+    version = "16.4.3", source, sourceRoot, outside = false, indexed = false,
+  }: { appDir?: string; distDir?: string; buildApp?: string; buildRoot?: string; version?: string;
+    source: string; sourceRoot?: string; outside?: boolean; indexed?: boolean }) {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "next-map-config-"));
+    try {
+      const app = path.join(dir, appDir);
+      const dist = path.join(app, distDir);
+      const helper = path.join(dir, "helper.cjs");
+      await fs.mkdir(dist, { recursive: true });
+      await fs.mkdir(path.join(app, "node_modules/next"), { recursive: true });
+      await fs.writeFile(path.join(app, "node_modules/next/package.json"), JSON.stringify({ version }));
+      await fs.writeFile(path.join(dist, "required-server-files.json"), JSON.stringify({ appDir: buildApp,
+        config: { output: "standalone", distDir, turbopack: { root: buildRoot } } }));
+      await fs.writeFile(helper, NEXT_COVERAGE_HELPER);
+      const leaf = { version: 3, sources: [source], sourceRoot, names: [], mappings: "AAAA", ignoreList: [0] };
+      const map = indexed ? { version: 3, sections: [{ offset: { line: 2, column: 4 }, map: leaf }] } : leaf;
+      const script = `const map = ${JSON.stringify(map)};
+        require(${JSON.stringify(helper)}).normalizeSourceMap(map, ${JSON.stringify(path.join(dist, outside ? "server/chunks/a.js.map" : "server/edge/chunks/a.js.map"))});
+        process.stdout.write(JSON.stringify(map));`;
+      const result = JSON.parse(execFileSync("node", ["-e", script], { cwd: dir,
+        env: { ...process.env, NODE_OPTIONS: "", SPECTEST_COVERAGE_ROOT: dir,
+          SPECTEST_NEXT_COVERAGE_OPTIONS: JSON.stringify({ appDir, distDir }) } }).toString());
+      const resultLeaf = indexed ? result.sections[0].map : result;
+      expect(resultLeaf.ignoreList).toEqual([0]);
+      expect(resultLeaf.mappings).toBe("AAAA");
+      if (indexed) expect(result.sections[0].offset).toEqual({ line: 2, column: 4 });
+      return resultLeaf.sources[0];
+    } finally { await fs.rm(dir, { recursive: true, force: true }); }
+  }
+
+  test("uses the recorded build root and distDir independently of runtime relocation", async () => {
+    expect(await normalize({ source: "../../../ops/src/middleware.ts" }))
+      .toBe("turbopack:///[project]/ops/src/middleware.ts");
+    expect(await normalize({ appDir: ".", buildApp: "/build", source: "../../src/middleware.ts" }))
+      .toBe("turbopack:///[project]/src/middleware.ts");
+    expect(await normalize({ appDir: "deployed/web", buildApp: "/builder/packages/apps/web", buildRoot: "/builder/packages",
+      distDir: ".output", source: "../../../../apps/web/src/my%20middleware.ts", indexed: true }))
+      .toBe("turbopack:///[project]/apps/web/src/my%20middleware.ts");
+  });
+
+  test("preserves fixed maps, external sources, explicit roots and unknown producers", async () => {
+    for (const source of ["../../../../../ops/src/middleware.ts", "turbopack:///[project]/ops/src/middleware.ts",
+      "file:///build/ops/src/middleware.ts", "https://example.com/a.ts", "../../../%2e%2e/secret.ts",
+      "../../../ops/src/%ZZ.ts", "../../../C%3A/secret.ts", "../../../ops//middleware.ts"]) {
+      expect(await normalize({ source })).toBe(source);
+    }
+    const source = "../../../ops/src/middleware.ts";
+    for (const extra of [{ sourceRoot: "/build" }, { outside: true }, { version: "16.4.4" },
+      { buildRoot: "/another-root" }, { buildApp: "relative/app" }]) {
+      expect(await normalize({ source, ...extra })).toBe(source);
+    }
+  });
 });

package/src/coverage-next.ts

@@ -27,7 +27,8 @@ const root = process.env.SPECTEST_COVERAGE_ROOT || process.cwd();
 process.env.SPECTEST_COVERAGE_ROOT = root;
 const app = path.resolve(root, options.appDir || ".");
 const dist = path.resolve(app, options.distDir || ".next");
-function manifest() { return JSON.parse(fs.readFileSync(path.join(dist, "required-server-files.json"), "utf8")); }
+let build;
+function manifest() { return build ||= JSON.parse(fs.readFileSync(path.join(dist, "required-server-files.json"), "utf8")); }
 function launcher(m) {
   const file = path.join(app, "server.js");
   if (m.config.output !== "standalone" || !fs.existsSync(file)) return null;
@@ -41,6 +42,55 @@ try {
     ...new Set([...JSON.parse(process.env.SPECTEST_COVERAGE_GENERATED_FILES || "[]"), file])
   ]);
 } catch {} // Capture reports a useful error; do not change application startup.
+
+// Next 16.4.3 gives its Edge chunker the offset from distDir to turbopack.root,
+// although the chunker's output root is distDir/server/edge. Recover the exact
+// serialized prefix from the build configuration, not from repository suffixes.
+// See docs/validation/next-coverage-20261102.md for the unmodified-build repro
+// and upstream implementation. Other versions/layouts keep normal map semantics.
+let edgePolicy;
+function edgeSourcePolicy() {
+  if (edgePolicy !== undefined) return edgePolicy;
+  edgePolicy = null;
+  try {
+    const version = JSON.parse(fs.readFileSync(require.resolve("next/package.json", {paths:[app]}), "utf8")).version;
+    if (version !== "16.4.3") return null;
+    const m = manifest(), config = m.config;
+    const buildRoot = config.turbopack && config.turbopack.root;
+    if (typeof m.appDir !== "string" || !path.isAbsolute(m.appDir) ||
+        typeof buildRoot !== "string" || !path.isAbsolute(buildRoot) ||
+        typeof config.distDir !== "string") return null;
+    const offset = path.relative(path.resolve(m.appDir, config.distDir), buildRoot);
+    if (!offset || !offset.split(path.sep).every(p => p === "..")) return null;
+    edgePolicy = {root:path.join(dist, "server/edge"), offset};
+  } catch {} // Unknown build metadata cannot authorize a source correction.
+  return edgePolicy;
+}
+exports.normalizeSourceMap = function(data, mapFile) {
+  const policy = edgeSourcePolicy();
+  if (!policy) return;
+  const relative = path.relative(policy.root, mapFile);
+  if (!relative.startsWith("chunks" + path.sep) || path.isAbsolute(relative) || relative.split(path.sep).includes("..")) return;
+  const prefix = path.relative(path.dirname(mapFile), policy.root).split(path.sep).join("/") + "/" + policy.offset.split(path.sep).join("/") + "/";
+  function visit(map, depth) {
+    if (!map || typeof map !== "object" || depth > 32 || map.sourceRoot) return;
+    if (Array.isArray(map.sections)) {
+      for (const section of map.sections) if (section && !section.url) visit(section.map, depth + 1);
+    }
+    if (!Array.isArray(map.sources)) return;
+    map.sources = map.sources.map(source => {
+      if (typeof source !== "string" || !source.startsWith(prefix)) return source;
+      const suffix = source.slice(prefix.length);
+      let decoded;
+      try { decoded = decodeURIComponent(suffix); } catch { return source; }
+      // Correctly emitted paths have two extra '..' components. Never rewrite
+      // those, absolute/virtual sources, escapes or another root's sources.
+      if (/[\\:\0?#]/.test(decoded) || decoded.split("/").some(p => !p || p === "." || p === "..")) return source;
+      return "turbopack:///[project]/" + suffix;
+    });
+  }
+  visit(data, 0);
+};
 if (require.main === module) {
   try {
     const m = manifest();
@@ -73,8 +123,9 @@ const GENERATED_SOURCES = [
   "*/data:* <text/javascript>", // Turbopack virtual modules, including action proxies.
   "*/.next-internal/server/app/*/actions.js (server actions loader)",
   "*/app/*--route-entry.js",
-  "*/*.mjs (structured image object)",
-  "*/*.mjs (structured image object with data url)",
+  "turbopack:///[project]/*.mjs (structured image object)",
+  "turbopack:///[project]/*.mjs (structured image object with data url)",
+  "*/app/*.mjs (structured image object)", // Older Next map identities.
 ];
 
 /** Server + browser coverage for a built Next app. Build-time maps are required;
@@ -109,6 +160,7 @@ export function next(options: NextCoverageOptions = {}): CoverageAdapter {
           NODE_OPTIONS: `--require ${NEXT_COVERAGE_HELPER_PATH} ${configured.env!.NODE_OPTIONS}`,
           SPECTEST_NEXT_COVERAGE_OPTIONS: JSON.stringify(options),
           SPECTEST_COVERAGE_SERVICE: info.key,
+          SPECTEST_COVERAGE_SOURCE_MAP_ADAPTER: NEXT_COVERAGE_HELPER_PATH,
         },
         files: [...configured.files!, { path: NEXT_COVERAGE_HELPER_PATH, content: NEXT_COVERAGE_HELPER }],
       };

package/src/coverage.ts

@@ -531,6 +531,8 @@ export const NODE_COVERAGE_HOOK = `"use strict";
     return "generated:" + process.env.SPECTEST_COVERAGE_SERVICE + ":" + file + "#" + crypto.createHash("sha256").update(text).digest("hex");
   }
   const SELF = url.pathToFileURL(__filename).href;
+  const SOURCE_MAP_ADAPTER = process.env.SPECTEST_COVERAGE_SOURCE_MAP_ADAPTER;
+  const SOURCE_MAP_ADAPTER_URL = SOURCE_MAP_ADAPTER ? url.pathToFileURL(path.resolve(SOURCE_MAP_ADAPTER)).href : null;
   const SCRIPTS = path.join(dir, ${JSON.stringify(NODE_COVERAGE_SCRIPTS_SUBDIR)});
   const MARKERS = path.join(dir, ${JSON.stringify(NODE_COVERAGE_MARKERS_SUBDIR)});
   // V8 script ids identify a compiled script within this process. A URL
@@ -543,7 +545,7 @@ export const NODE_COVERAGE_HOOK = `"use strict";
   fs.writeFileSync(path.join(dir, ".attached-" + (bunRuntime ? "bun" : "node")), "");
 
   function isApp(u) {
-    return typeof u === "string" && u.startsWith("file://") && u.indexOf("/node_modules/") < 0 && u.indexOf("/.cache/") < 0 && u !== SELF;
+    return typeof u === "string" && u.startsWith("file://") && u.indexOf("/node_modules/") < 0 && u.indexOf("/.cache/") < 0 && u !== SELF && u !== SOURCE_MAP_ADAPTER_URL;
   }
   function isDep(u) {
     return typeof u === "string" && u.startsWith("file://") && u.indexOf("/node_modules/") >= 0 && u !== SELF;
@@ -640,6 +642,10 @@ export const NODE_COVERAGE_HOOK = `"use strict";
     } catch (e) {
       return null;
     }
+    // Framework policy runs before dependency attribution and before the final
+    // descriptor is hashed. The collector remains the sole owner of record IDs,
+    // deduplication, dump references and cleanup (including exit-time captures).
+    if (SOURCE_MAP_ADAPTER) require(SOURCE_MAP_ADAPTER).normalizeSourceMap(data, mapUrl ? url.fileURLToPath(mapUrl) : scriptPath);
     // A source inside node_modules is a dependency: its unit id rides
     // beside the map (\`sourceUnits[i]\`, null for the project's own), so
     // the control plane never has to know what node_modules is.