@specific.dev/spectest 0.131.16 → 0.131.18

package/README.md

@@ -83,6 +83,14 @@ 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

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/browser-surface.d.ts

@@ -0,0 +1,9 @@
+import type { BrowserContext, CDPSession, Page } from "playwright-core";
+export declare function reduceBrowserSurfaces(context: BrowserContext, options: {
+    mobile: boolean;
+    deviceScaleFactor: number;
+}): void;
+export declare function awaitBrowserSurface(page: Page): Promise<void>;
+export declare function captureBrowserScreenshot(page: Page, cdp: CDPSession): Promise<{
+    data: string;
+}>;

package/dist/browser-surface.js

@@ -0,0 +1,71 @@
+// Layout, input coordinates and the visual viewport retain their real size.
+// Only the compositor's output is clipped. Native frame scheduling (including
+// rAF on otherwise quiet pages) remains Chromium's responsibility.
+const SURFACES = new WeakMap();
+class Surface {
+    page;
+    cdp;
+    options;
+    tail = Promise.resolve();
+    constructor(page, cdp, options) {
+        this.page = page;
+        this.cdp = cdp;
+        this.options = options;
+    }
+    async apply(reduced) {
+        const viewport = this.page.viewportSize();
+        if (!viewport)
+            throw new Error("Browser surface requires a fixed viewport");
+        const landscape = viewport.width > viewport.height;
+        await this.cdp.send("Emulation.setDeviceMetricsOverride", {
+            ...viewport,
+            ...this.options,
+            screenWidth: viewport.width,
+            screenHeight: viewport.height,
+            screenOrientation: this.options.mobile
+                ? { angle: landscape ? 90 : 0, type: landscape ? "landscapePrimary" : "portraitPrimary" }
+                : { angle: 0, type: "landscapePrimary" },
+            ...(reduced ? { viewport: { x: 0, y: 0, width: 1, height: 1, scale: 1 } } : {}),
+        });
+    }
+    screenshot() {
+        // Concurrent screenshots must not shrink another capture's surface.
+        const result = this.tail.then(async () => {
+            try {
+                await this.apply(false);
+                // Capture through the same emulation agent: a different CDP session
+                // can read back mobile screenshots at the wrong device scale.
+                return await this.cdp.send("Page.captureScreenshot", { format: "png" });
+            }
+            finally {
+                if (!this.page.isClosed())
+                    await this.apply(true);
+            }
+        });
+        this.tail = result.catch(() => { });
+        return result;
+    }
+}
+export function reduceBrowserSurfaces(context, options) {
+    context.on("page", page => {
+        const pending = (async () => {
+            const surface = new Surface(page, await context.newCDPSession(page), options);
+            await surface.apply(true);
+            return surface;
+        })();
+        SURFACES.set(page, pending);
+        // spawnPage awaits this for SDK views. Popups have no spawnPage caller.
+        void pending.catch(error => {
+            if (!page.isClosed())
+                console.warn("[spectest] failed to reduce browser surface:", error);
+        });
+    });
+}
+export async function awaitBrowserSurface(page) {
+    await SURFACES.get(page);
+}
+export async function captureBrowserScreenshot(page, cdp) {
+    const surface = await SURFACES.get(page);
+    // Externally attached browsers (e.g. Electron) retain their own viewport.
+    return surface ? surface.screenshot() : cdp.send("Page.captureScreenshot", { format: "png" });
+}

package/dist/browser.js

@@ -43,6 +43,7 @@ import { describeUrlPattern, matchesUrl } from "./url-match.js";
 import { attachBrowserCoverage, browserCoverageActive, harvestBrowserCoverage, } from "./browser-coverage.js";
 import { attachBrowserProbe, DEFAULT_ACTION_TIMEOUT_MS, desktopStrategy, makeLocator, mobileStrategy, } from "./locator.js";
 import { chromium } from "playwright-core";
+import { reduceBrowserSurfaces, awaitBrowserSurface, captureBrowserScreenshot } from "./browser-surface.js";
 /** Decoded byte count of a base64 string, without decoding it. */
 function base64ByteLength(b64) {
     let padding = 0;
@@ -179,6 +180,7 @@ async function newViewContext(width, height, device, opts = {}) {
             timezoneId: opts.timezone,
             locale: opts.locale,
         });
+        reduceBrowserSurfaces(context, { mobile: !!device, deviceScaleFactor: device?.deviceScaleFactor ?? 1 });
         context.setDefaultTimeout(DEFAULT_ACTION_TIMEOUT_MS);
         context.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
         if (fixture) {
@@ -847,6 +849,7 @@ const VIEW_POOL = [];
  *  slow part (renderer process spawn). */
 async function spawnPage(context) {
     const page = await context.newPage();
+    await awaitBrowserSurface(page);
     const cdp = await context.newCDPSession(page);
     // Without Page.enable the addScriptToEvaluateOnNewDocument registration
     // silently never fires on this session (verified in the fork spike).
@@ -1651,9 +1654,7 @@ function buildBackend(holder, recorder, buildOpts) {
                 }
                 // Raw CDP rather than page.screenshot(): captures the viewport
                 // exactly like the pre-Playwright backend.
-                const res = (await holder.cdp.send("Page.captureScreenshot", {
-                    format: "png",
-                }));
+                const res = await captureBrowserScreenshot(holder.page, holder.cdp);
                 const id = generateId("art");
                 register({
                     id,

package/dist/daemon.js

@@ -52,6 +52,7 @@ import { ensureStickyBuildHeadroom } from "./harness/sticky-consumer.js";
 import { fakeFunctions, fakeFunctionParameters, callFakeFunction } from "./harness/fake-functions.js";
 import { dispatchFake } from "./harness/fake-websocket.js";
 import { casesMetadata as catalogueCases, groupsMetadata as catalogueGroups, } from "./harness/catalogue.js";
+import { shadowBuilder, shadowImage, shadowOutput, imageDigest, shadowTiming } from "./harness/shadow-builder.js";
 import { summarizeBuildKit } from "./harness/buildkit-progress.js";
 import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta, mergeServiceLogDeltas } from "./harness/log-delta.js";
 import { resolveHostPath as resolveVolumeHostPath, sanitizeSegment, } from "./harness/volume-paths.js";
@@ -1039,18 +1040,28 @@ async function runServiceBuild(name, image, tag) {
         // own layer cache, and the finished image is already in the store
         // dockerd reads. dockerd's built-in BuildKit is the fallback (a guest
         // with no store, or a daemon that would not start).
-        const useLocal = await ensureLocalBuildkitd();
+        const remote = await shadowBuilder();
+        const useLocal = !remote && await ensureLocalBuildkitd();
         // Both the in-VM daemon and dockerd's buildx are BuildKit, so both
         // emit per-step timing on stderr under `--progress=plain` (parsed
         // below). Only the legacy builder takes no progress flag.
-        const useBuildKit = useLocal || (await hasBuildx());
+        const useBuildKit = !!remote || useLocal || (await hasBuildx());
         const buildEnv = {};
         let buildArgs;
         // The user's `buildArgs`, as `--build-arg` flags; a plain client flag,
         // so every builder — in-VM BuildKit, dockerd's own, legacy — takes it.
         const argFlags = [...buildTargetFlags(image.target), ...buildArgFlags(image.buildArgs)];
         const contextDir = image.contextDir;
-        if (useLocal) {
+        const remoteReference = remote ? shadowImage(remote, name) : undefined;
+        const metadataPath = path.join(dfDir, "shadow-result.json");
+        const buildStarted = Date.now();
+        if (remote) {
+            buildArgs = ["buildx", "build", "--builder", remote.builder,
+                "--progress=plain", "--metadata-file", metadataPath,
+                "--output", shadowOutput(remoteReference), ...argFlags,
+                "-f", dfPath, contextDir];
+        }
+        else if (useLocal) {
             // The in-VM builder is BuildKit's containerd worker on this VM's
             // own image store (CONTAINER_STORE.md): the output is an image
             // record in dockerd's namespace, unpacked, so there is no `--load`
@@ -1129,9 +1140,23 @@ async function runServiceBuild(name, image, tag) {
             }
         });
         const log = `${build.stderr.trim()}\n${build.stdout.trim()}`;
+        if (remote)
+            await shadowTiming(name, "solve-export-push", buildStarted, { ok: build.code === 0 });
         if (build.code !== 0) {
             return { ok: false, log };
         }
+        if (remote) {
+            const digest = imageDigest(JSON.parse(await fs.readFile(metadataPath, "utf8")));
+            const immutable = `${remoteReference.split(":result")[0]}@${digest}`;
+            const pullStarted = Date.now();
+            const pulled = await shxStream("docker", ["pull", immutable], undefined, undefined, () => { });
+            await shadowTiming(name, "pull-unpack", pullStarted, { digest, ok: pulled.code === 0, lazy: false });
+            if (pulled.code !== 0)
+                return { ok: false, log: pulled.stderr };
+            const tagged = await docker(["tag", immutable, tag]);
+            if (tagged.code !== 0)
+                return { ok: false, log: tagged.stderr };
+        }
         if (useBuildKit) {
             // Keep only the slowest dozen steps ≥1s — enough to profile, small
             // enough to ride back in the /bootstrap response and the journal.
@@ -5133,7 +5158,7 @@ export function harnessMethods(state) {
     return {
         health: async () => ({
             ok: true,
-            capabilities: ["prepared-images-v1"],
+            capabilities: ["prepared-images-v1", "shadow-builder-v1"],
             // Optional discovery: old SDKs omit this field and are never sent the
             // new method. Check the loaded project, including after warm restore.
             setupInteractive: typeof loaded?.project.interactive?.seed === "function",

package/dist/harness/shadow-builder.d.ts

@@ -0,0 +1,12 @@
+export interface ShadowBuilder {
+    version: 1;
+    builder: string;
+    registry: string;
+    experiment: string;
+}
+export declare function validateShadowBuilder(value: unknown): ShadowBuilder;
+export declare function shadowBuilder(): Promise<ShadowBuilder | undefined>;
+export declare function shadowImage(c: ShadowBuilder, service: string): string;
+export declare function shadowOutput(reference: string): string;
+export declare function imageDigest(metadata: unknown): string;
+export declare function shadowTiming(service: string, phase: string, started: number, extra?: {}): Promise<void>;

package/dist/harness/shadow-builder.js

@@ -0,0 +1,36 @@
+/** Internal experiment configuration. Never selected by project configuration. */
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+export function validateShadowBuilder(value) {
+    const c = value;
+    if (!c || c.version !== 1 || !/^shadow-[a-z0-9-]+$/.test(c.builder)
+        || !/^[a-z0-9.-]+(?::[0-9]+)?$/.test(c.registry)
+        || !/^[a-z0-9-]{1,80}$/.test(c.experiment))
+        throw new Error("invalid shadow builder configuration");
+    return c;
+}
+export async function shadowBuilder() {
+    if (process.env.SPECTEST_SHADOW_BUILD !== "1")
+        return undefined;
+    // A missing configuration is an experiment failure, never a local build.
+    return validateShadowBuilder(JSON.parse(await fs.readFile("/run/spectest/shadow-builder.json", "utf8")));
+}
+export function shadowImage(c, service) {
+    const id = createHash("sha256").update(service).digest("hex").slice(0, 32);
+    return `${c.registry}/shadow/${c.experiment}/${id}:result`;
+}
+export function shadowOutput(reference) {
+    return `type=image,name=${reference},push=true,oci-mediatypes=true,compression=zstd`;
+}
+export function imageDigest(metadata) {
+    const digest = metadata?.["containerimage.digest"];
+    if (typeof digest !== "string" || !/^sha256:[0-9a-f]{64}$/.test(digest)) {
+        throw new Error("remote builder did not return an image digest");
+    }
+    return digest;
+}
+export async function shadowTiming(service, phase, started, extra = {}) {
+    await fs.appendFile("/run/spectest/shadow-timings.jsonl", JSON.stringify({
+        service, phase, startedMs: started, durationMs: Date.now() - started, ...extra,
+    }) + "\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.131.16",
+  "version": "0.131.18",
   "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/browser-surface.test.ts

@@ -0,0 +1,68 @@
+import { expect, test } from "bun:test";
+import { chromium } from "playwright-core";
+import { awaitBrowserSurface, captureBrowserScreenshot, reduceBrowserSurfaces } from "./browser-surface.js";
+
+const executablePath = Bun.which("chromium") ?? Bun.which("chromium-browser") ?? undefined;
+for (const mobile of [false, true]) {
+  test.skipIf(!executablePath)(`reduced surface preserves ${mobile ? "mobile" : "desktop"} behavior and screenshot pixels`, async () => {
+    const browser = await chromium.launch({ executablePath, headless: true, args: ["--no-sandbox"] });
+    const width = mobile ? 393 : 1280, height = mobile ? 852 : 720, dpr = mobile ? 3 : 1;
+    try {
+      const context = await browser.newContext({ viewport: { width, height }, isMobile: mobile, hasTouch: mobile, deviceScaleFactor: dpr });
+      reduceBrowserSurfaces(context, { mobile, deviceScaleFactor: dpr });
+      const page = await context.newPage();
+      await awaitBrowserSurface(page);
+      const cdp = await context.newCDPSession(page);
+      const html = `<meta name="viewport" content="width=device-width,initial-scale=1">
+        <style>body{margin:0;background:white}button{position:absolute;right:10px;top:600px;width:100px;height:50px;background:red;border:0;color:red}#below{position:absolute;top:1600px}iframe{width:200px;height:60px}</style>
+        <button onclick="window.clicks++">Click</button><div id="below">Below</div>
+        <iframe srcdoc="<button onclick='this.textContent=123'>Frame</button>"></iframe>
+        <script>window.clicks=0;window.raf=0;window.resizes=0;window.visible=false;
+        onresize=()=>window.resizes++;new IntersectionObserver(e=>window.visible=e[0].isIntersecting).observe(document.querySelector('button'));
+        function tick(){window.raf++;requestAnimationFrame(tick)}requestAnimationFrame(tick)</script>`;
+      await page.goto(`data:text/html,${encodeURIComponent(html)}`);
+      await page.waitForFunction(() => (window as any).visible && (window as any).raf > 2);
+      await page.getByRole("button", {name:"Click",exact:true}).click();
+      await page.frameLocator("iframe").getByRole("button").click();
+      expect(await page.frameLocator("iframe").getByRole("button").textContent()).toBe("123");
+      const state = () => page.evaluate(() => ({ inner:[innerWidth,innerHeight], visual:[visualViewport!.width,visualViewport!.height], screen:[screen.width,screen.height], dpr:devicePixelRatio, resizes:(window as any).resizes }));
+      // Script-visible rendering APIs and animation completion still progress.
+      expect(await page.evaluate(async () => {
+        const canvas = document.createElement("canvas");
+        canvas.width = canvas.height = 2;
+        const ctx = canvas.getContext("2d")!;
+        ctx.fillStyle = "#00ff00";ctx.fillRect(0,0,2,2);
+        const button = document.querySelector("button")!;
+        await button.animate([{transform:"translateX(0px)"},{transform:"translateX(-1px)"}],{duration:40}).finished;
+        return [...ctx.getImageData(0,0,1,1).data];
+      })).toEqual([0,255,0,255]);
+      const before = await state();
+      expect(before).toMatchObject({inner:[width,height],visual:[width,height],screen:[width,height],dpr});
+      const captures = await Promise.all([captureBrowserScreenshot(page, cdp), captureBrowserScreenshot(page, cdp)]);
+      for (const capture of captures) {
+        const png = Buffer.from(capture.data, "base64");
+        expect([png.readUInt32BE(16),png.readUInt32BE(20)]).toEqual([width*dpr,height*dpr]);
+        const pixel = await page.evaluate(async ({data,x,y}) => {
+          const img = new Image();img.src=`data:image/png;base64,${data}`;await img.decode();
+          const canvas=document.createElement('canvas');canvas.width=img.width;canvas.height=img.height;
+          const ctx=canvas.getContext('2d')!;ctx.drawImage(img,0,0);return [...ctx.getImageData(x,y,1,1).data];
+        },{data:capture.data,x:(width-60)*dpr,y:620*dpr});
+        expect(pixel).toEqual([255,0,0,255]);
+      }
+      expect(await state()).toEqual(before);
+      await page.locator("#below").scrollIntoViewIfNeeded();
+      await page.getByRole("button",{name:"Click",exact:true}).click();
+      expect(await page.evaluate(() => (window as any).clicks)).toBe(2);
+      if (mobile) {
+        const box = await page.getByRole("button",{name:"Click",exact:true}).boundingBox();
+        await page.touchscreen.tap(box!.x+box!.width/2,box!.y+box!.height/2);
+        expect(await page.evaluate(() => (window as any).clicks)).toBe(3);
+      }
+      // A newly opened tab is configured too, without changing its layout.
+      const popup = await context.newPage();await awaitBrowserSurface(popup);
+      await popup.goto(`data:text/html,${encodeURIComponent(html)}`);
+      await popup.getByRole("button",{name:"Click",exact:true}).click();
+      expect(await popup.evaluate(() => [innerWidth,innerHeight,(window as any).clicks])).toEqual([width,height,1]);
+    } finally { await browser.close(); }
+  },30000);
+}

package/src/browser-surface.ts

@@ -0,0 +1,70 @@
+import type { BrowserContext, CDPSession, Page } from "playwright-core";
+
+// Layout, input coordinates and the visual viewport retain their real size.
+// Only the compositor's output is clipped. Native frame scheduling (including
+// rAF on otherwise quiet pages) remains Chromium's responsibility.
+const SURFACES = new WeakMap<Page, Promise<Surface>>();
+
+class Surface {
+  private tail: Promise<unknown> = Promise.resolve();
+  constructor(private page: Page, private cdp: CDPSession,
+    private options: { mobile: boolean; deviceScaleFactor: number }) {}
+
+  async apply(reduced: boolean) {
+    const viewport = this.page.viewportSize();
+    if (!viewport) throw new Error("Browser surface requires a fixed viewport");
+    const landscape = viewport.width > viewport.height;
+    await this.cdp.send("Emulation.setDeviceMetricsOverride", {
+      ...viewport,
+      ...this.options,
+      screenWidth: viewport.width,
+      screenHeight: viewport.height,
+      screenOrientation: this.options.mobile
+        ? { angle: landscape ? 90 : 0, type: landscape ? "landscapePrimary" : "portraitPrimary" }
+        : { angle: 0, type: "landscapePrimary" },
+      ...(reduced ? { viewport: { x: 0, y: 0, width: 1, height: 1, scale: 1 } } : {}),
+    });
+  }
+
+  screenshot(): Promise<{ data: string }> {
+    // Concurrent screenshots must not shrink another capture's surface.
+    const result = this.tail.then(async () => {
+      try {
+        await this.apply(false);
+        // Capture through the same emulation agent: a different CDP session
+        // can read back mobile screenshots at the wrong device scale.
+        return await this.cdp.send("Page.captureScreenshot", { format: "png" });
+      } finally {
+        if (!this.page.isClosed()) await this.apply(true);
+      }
+    });
+    this.tail = result.catch(() => {});
+    return result;
+  }
+}
+
+export function reduceBrowserSurfaces(context: BrowserContext,
+  options: { mobile: boolean; deviceScaleFactor: number }) {
+  context.on("page", page => {
+    const pending = (async () => {
+      const surface = new Surface(page, await context.newCDPSession(page), options);
+      await surface.apply(true);
+      return surface;
+    })();
+    SURFACES.set(page, pending);
+    // spawnPage awaits this for SDK views. Popups have no spawnPage caller.
+    void pending.catch(error => {
+      if (!page.isClosed()) console.warn("[spectest] failed to reduce browser surface:", error);
+    });
+  });
+}
+
+export async function awaitBrowserSurface(page: Page): Promise<void> {
+  await SURFACES.get(page);
+}
+
+export async function captureBrowserScreenshot(page: Page, cdp: CDPSession): Promise<{ data: string }> {
+  const surface = await SURFACES.get(page);
+  // Externally attached browsers (e.g. Electron) retain their own viewport.
+  return surface ? surface.screenshot() : cdp.send("Page.captureScreenshot", { format: "png" });
+}

package/src/browser.ts

@@ -67,6 +67,7 @@ import type {
 } from "./locator.js";
 
 import { chromium } from "playwright-core";
+import { reduceBrowserSurfaces, awaitBrowserSurface, captureBrowserScreenshot } from "./browser-surface.js";
 import type {
   Browser as PlaywrightBrowser,
   BrowserContext,
@@ -543,6 +544,7 @@ async function newViewContext(
       timezoneId: opts.timezone,
       locale: opts.locale,
     });
+    reduceBrowserSurfaces(context, { mobile: !!device, deviceScaleFactor: device?.deviceScaleFactor ?? 1 });
     context.setDefaultTimeout(DEFAULT_ACTION_TIMEOUT_MS);
     context.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
     if (fixture) {
@@ -1288,6 +1290,7 @@ const VIEW_POOL: PooledView[] = [];
  *  slow part (renderer process spawn). */
 async function spawnPage(context: BrowserContext): Promise<SpawnedPage> {
   const page = await context.newPage();
+  await awaitBrowserSurface(page);
   const cdp = await context.newCDPSession(page);
   // Without Page.enable the addScriptToEvaluateOnNewDocument registration
   // silently never fires on this session (verified in the fork spike).
@@ -2199,9 +2202,7 @@ function buildBackend(
         }
         // Raw CDP rather than page.screenshot(): captures the viewport
         // exactly like the pre-Playwright backend.
-        const res = (await holder.cdp.send("Page.captureScreenshot", {
-          format: "png",
-        } as never)) as { data: string };
+        const res = await captureBrowserScreenshot(holder.page, holder.cdp);
         const id = generateId("art");
         register({
           id,

package/src/daemon.ts

@@ -109,6 +109,7 @@ import {
   type CaseMeta,
   type GroupMeta,
 } from "./harness/catalogue.js";
+import { shadowBuilder, shadowImage, shadowOutput, imageDigest, shadowTiming } from "./harness/shadow-builder.js";
 import { summarizeBuildKit, type BuildStep } from "./harness/buildkit-progress.js";
 import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta, mergeServiceLogDeltas } from "./harness/log-delta.js";
 import {
@@ -1364,18 +1365,27 @@ async function runServiceBuild(
     // own layer cache, and the finished image is already in the store
     // dockerd reads. dockerd's built-in BuildKit is the fallback (a guest
     // with no store, or a daemon that would not start).
-    const useLocal = await ensureLocalBuildkitd();
+    const remote = await shadowBuilder();
+    const useLocal = !remote && await ensureLocalBuildkitd();
     // Both the in-VM daemon and dockerd's buildx are BuildKit, so both
     // emit per-step timing on stderr under `--progress=plain` (parsed
     // below). Only the legacy builder takes no progress flag.
-    const useBuildKit = useLocal || (await hasBuildx());
+    const useBuildKit = !!remote || useLocal || (await hasBuildx());
     const buildEnv: Record<string, string> = {};
     let buildArgs: string[];
     // The user's `buildArgs`, as `--build-arg` flags; a plain client flag,
     // so every builder — in-VM BuildKit, dockerd's own, legacy — takes it.
     const argFlags = [...buildTargetFlags(image.target), ...buildArgFlags(image.buildArgs)];
     const contextDir = image.contextDir;
-    if (useLocal) {
+    const remoteReference = remote ? shadowImage(remote, name) : undefined;
+    const metadataPath = path.join(dfDir, "shadow-result.json");
+    const buildStarted = Date.now();
+    if (remote) {
+      buildArgs = ["buildx", "build", "--builder", remote.builder,
+        "--progress=plain", "--metadata-file", metadataPath,
+        "--output", shadowOutput(remoteReference!), ...argFlags,
+        "-f", dfPath, contextDir];
+    } else if (useLocal) {
       // The in-VM builder is BuildKit's containerd worker on this VM's
       // own image store (CONTAINER_STORE.md): the output is an image
       // record in dockerd's namespace, unpacked, so there is no `--load`
@@ -1452,9 +1462,20 @@ async function runServiceBuild(
         }
     });
     const log = `${build.stderr.trim()}\n${build.stdout.trim()}`;
+    if (remote) await shadowTiming(name, "solve-export-push", buildStarted, { ok: build.code === 0 });
     if (build.code !== 0) {
       return { ok: false, log };
     }
+    if (remote) {
+      const digest = imageDigest(JSON.parse(await fs.readFile(metadataPath, "utf8")));
+      const immutable = `${remoteReference!.split(":result")[0]}@${digest}`;
+      const pullStarted = Date.now();
+      const pulled = await shxStream("docker", ["pull", immutable], undefined, undefined, () => {});
+      await shadowTiming(name, "pull-unpack", pullStarted, { digest, ok: pulled.code === 0, lazy: false });
+      if (pulled.code !== 0) return { ok: false, log: pulled.stderr };
+      const tagged = await docker(["tag", immutable, tag]);
+      if (tagged.code !== 0) return { ok: false, log: tagged.stderr };
+    }
     if (useBuildKit) {
       // Keep only the slowest dozen steps ≥1s — enough to profile, small
       // enough to ride back in the /bootstrap response and the journal.
@@ -6101,7 +6122,7 @@ export function harnessMethods(state: RouteState): MethodTable {
   return {
     health: async () => ({
       ok: true,
-      capabilities: ["prepared-images-v1"],
+      capabilities: ["prepared-images-v1", "shadow-builder-v1"],
       // Optional discovery: old SDKs omit this field and are never sent the
       // new method. Check the loaded project, including after warm restore.
       setupInteractive: typeof loaded?.project.interactive?.seed === "function",

package/src/harness/shadow-builder.test.ts

@@ -0,0 +1,29 @@
+import { expect, test } from "bun:test";
+import { imageDigest, shadowBuilder, shadowImage, shadowOutput, validateShadowBuilder } from "./shadow-builder";
+const config = { version: 1, builder: "shadow-test", registry: "registry.example.com", experiment: "experiment-1" } as const;
+test("shadow image namespaces isolate experiments and hash untrusted service names", () => {
+  const a = shadowImage(config, "../../other,compression=gzip");
+  expect(a).toMatch(/^registry.example.com\/shadow\/experiment-1\/[a-f0-9]{32}:result$/);
+  expect(shadowImage({ ...config, experiment: "experiment-2" }, "api")).not.toBe(shadowImage(config, "api"));
+  expect(shadowOutput(a)).toContain("compression=zstd");
+});
+test("configuration rejects exporter and endpoint injection", () => {
+  expect(validateShadowBuilder(config)).toEqual(config);
+  for (const registry of ["https://example.com", "example.com,push=false", "user:secret@example.com", "example.com/path"]) {
+    expect(() => validateShadowBuilder({ ...config, registry })).toThrow();
+  }
+});
+test("delivery requires a content digest, never a mutable tag", () => {
+  expect(imageDigest({ "containerimage.digest": `sha256:${"a".repeat(64)}` })).toBe(`sha256:${"a".repeat(64)}`);
+  for (const value of [null, {}, { "containerimage.digest": "latest" }]) expect(() => imageDigest(value)).toThrow();
+});
+
+test("ordinary SDK execution never needs remote builder configuration", async () => {
+  const previous = process.env.SPECTEST_SHADOW_BUILD;
+  delete process.env.SPECTEST_SHADOW_BUILD;
+  try { expect(await shadowBuilder()).toBeUndefined(); }
+  finally {
+    if (previous === undefined) delete process.env.SPECTEST_SHADOW_BUILD;
+    else process.env.SPECTEST_SHADOW_BUILD = previous;
+  }
+});

package/src/harness/shadow-builder.ts

@@ -0,0 +1,41 @@
+/** Internal experiment configuration. Never selected by project configuration. */
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+
+export interface ShadowBuilder {
+  version: 1;
+  builder: string;
+  registry: string;
+  experiment: string;
+}
+export function validateShadowBuilder(value: unknown): ShadowBuilder {
+  const c = value as ShadowBuilder;
+  if (!c || c.version !== 1 || !/^shadow-[a-z0-9-]+$/.test(c.builder)
+    || !/^[a-z0-9.-]+(?::[0-9]+)?$/.test(c.registry)
+    || !/^[a-z0-9-]{1,80}$/.test(c.experiment)) throw new Error("invalid shadow builder configuration");
+  return c;
+}
+export async function shadowBuilder(): Promise<ShadowBuilder | undefined> {
+  if (process.env.SPECTEST_SHADOW_BUILD !== "1") return undefined;
+  // A missing configuration is an experiment failure, never a local build.
+  return validateShadowBuilder(JSON.parse(await fs.readFile("/run/spectest/shadow-builder.json", "utf8")));
+}
+export function shadowImage(c: ShadowBuilder, service: string): string {
+  const id = createHash("sha256").update(service).digest("hex").slice(0, 32);
+  return `${c.registry}/shadow/${c.experiment}/${id}:result`;
+}
+export function shadowOutput(reference: string): string {
+  return `type=image,name=${reference},push=true,oci-mediatypes=true,compression=zstd`;
+}
+export function imageDigest(metadata: unknown): string {
+  const digest = (metadata as Record<string, unknown>)?.["containerimage.digest"];
+  if (typeof digest !== "string" || !/^sha256:[0-9a-f]{64}$/.test(digest)) {
+    throw new Error("remote builder did not return an image digest");
+  }
+  return digest;
+}
+export async function shadowTiming(service: string, phase: string, started: number, extra = {}) {
+  await fs.appendFile("/run/spectest/shadow-timings.jsonl", JSON.stringify({
+    service, phase, startedMs: started, durationMs: Date.now() - started, ...extra,
+  }) + "\n");
+}