@specific.dev/spectest 0.131.17 → 0.131.19

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

@@ -1,5 +1,5 @@
 // Headless browser handle for tests. Thin wrapper around playwright-core
-// driving the guest's system Chromium (pipe transport — `chromium.launch`
+// driving the guest's Headless Shell (pipe transport — `chromium.launch`
 // with an explicit `executablePath`). Electron attaches to the app-owned
 // Chromium over CDP instead; its client also lives inside the VM. The wrapper
 // keeps the public surface stable (we swapped from Bun.WebView to Playwright without
@@ -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;
@@ -108,7 +109,7 @@ const NAVIGATION_TIMEOUT_MS = 30_000;
 // ────────────────────────────────────────────────────────────────────────
 // Shared Chromium (playwright-core)
 // ────────────────────────────────────────────────────────────────────────
-// Default sessions share one Chromium per daemon, launched lazily and kept
+// Browser and mobile sessions share one Headless Shell per daemon, launched lazily and kept
 // for the daemon's lifetime. Fixture sessions own a process because the audio
 // source is a process-wide flag. Both ride snapshots: the process, playwright's
 // pipe connection to it, and every open page freeze into the VM snapshot
@@ -125,17 +126,18 @@ const VIEW_CLEANUPS = new WeakMap();
 // (mirroring the old one-Chrome-profile model), which left `close()` closing
 // the page only — cookies survived and the next session was still
 // authenticated.
-function chromiumPath() {
-    return (Bun.which("chromium") ??
-        Bun.which("chromium-browser") ??
-        Bun.which("google-chrome") ??
-        "/usr/bin/chromium");
+function browserExecutable() {
+    const executable = Bun.which("chromium-headless-shell") ?? Bun.which("chrome-headless-shell");
+    if (!executable) {
+        throw new Error("Chromium Headless Shell is required by this SDK but is missing from the runtime image. Rebuild the environment with a current Spectest golden image; for local development, install chromium-headless-shell on PATH.");
+    }
+    return executable;
 }
 async function ensurePlaywrightBrowser() {
     if (PW_BROWSER?.isConnected())
         return PW_BROWSER;
     PW_BROWSER = await chromium.launch({
-        executablePath: chromiumPath(),
+        executablePath: browserExecutable(),
         headless: true,
         args: CHROME_ARGV,
     });
@@ -166,7 +168,7 @@ async function newViewContext(width, height, device, opts = {}) {
     let browser;
     try {
         browser = fixture ? await chromium.launch({
-            executablePath: chromiumPath(), headless: true, args: [...CHROME_ARGV, fixture.arg],
+            executablePath: browserExecutable(), headless: true, args: [...CHROME_ARGV, fixture.arg],
         }) : await ensurePlaywrightBrowser();
         const context = await browser.newContext({
             ...(device
@@ -179,6 +181,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 +850,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 +1655,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.17",
+  "version": "0.131.19",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/browser-executable.test.ts

@@ -0,0 +1,21 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+test("SDK refuses a Chromium-only runtime instead of silently falling back", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "spectest-no-shell-"));
+  try {
+    await writeFile(join(dir, "chromium"), "#!/bin/sh\necho UNEXPECTED_CHROMIUM_LAUNCH >&2\nexit 1\n", { mode: 0o755 });
+    const browserModule = new URL("./browser.ts", import.meta.url).href;
+    const child = Bun.spawn([process.execPath, "-e", `
+      import { openBrowser } from ${JSON.stringify(browserModule)};
+      try { await openBrowser(); process.exit(2); }
+      catch (error) { console.error(error.message); process.exit(1); }
+    `], { env: { ...process.env, PATH: dir }, stdout: "pipe", stderr: "pipe" });
+    const stderr = await new Response(child.stderr).text();
+    expect(await child.exited).toBe(1);
+    expect(stderr).toContain("Headless Shell is required");
+    expect(stderr).not.toContain("UNEXPECTED_CHROMIUM_LAUNCH");
+  } finally { await rm(dir, { recursive: true, force: true }); }
+});

package/src/browser-finalization.test.ts

@@ -2,7 +2,7 @@ import { expect, test } from "bun:test";
 import { acquirePersistentBrowser } from "./browser.js";
 import { finalizeBrowserRecordings } from "./harness/deadline.js";
 
-const available = !!(Bun.which("chromium") ?? Bun.which("chromium-browser") ?? Bun.which("google-chrome"));
+const available = !!(Bun.which("chromium-headless-shell") ?? Bun.which("chrome-headless-shell"));
 
 test.skipIf(!available)("stuck replay drains are bounded warnings and late replies cannot change the recording or clear a later buffer", async () => {
   const chunks: unknown[] = [];

package/src/browser-navigation.test.ts

@@ -2,7 +2,7 @@ import { expect, test } from "bun:test";
 import { openBrowser } from "./browser.js";
 import { startRecording, stopRecording } from "./recorder.js";
 
-const available = !!(Bun.which("chromium") ?? Bun.which("chromium-browser") ?? Bun.which("google-chrome"));
+const available = !!(Bun.which("chromium-headless-shell") ?? Bun.which("chrome-headless-shell"));
 
 test.skipIf(!available)("public navigation options control goto/reload and remain visible in recordings", async () => {
   // The document commits immediately but load waits for an image. This

package/src/browser-screenshot.test.ts

@@ -0,0 +1,66 @@
+import { expect, test } from "bun:test";
+import { openBrowser, type BrowserSessionRecorder } from "./browser.js";
+import { readRaw } from "./inspect.js";
+
+const available =
+  Bun.which("chromium-headless-shell") ??
+  Bun.which("chrome-headless-shell");
+for (const frame of ["browser", "mobile"] as const) {
+  test.skipIf(!available)(
+    `${frame} public screenshot exports full PNG pixels after DOM changes`,
+    async () => {
+      const artifacts: Parameters<
+        NonNullable<BrowserSessionRecorder["registerArtifact"]>
+      >[0][] = [];
+      const browser = await openBrowser({
+        frame,
+        recorder: {
+          sessionId: `screenshot-${frame}`,
+          recordStep() {},
+          registerArtifact: (artifact) => artifacts.push(artifact),
+        },
+      });
+      const width = frame === "mobile" ? 393 : 1280;
+      const height = frame === "mobile" ? 852 : 720;
+      const dpr = frame === "mobile" ? 3 : 1;
+      try {
+        await browser.goto(
+          `data:text/html,${encodeURIComponent('<meta name="viewport" content="width=device-width,initial-scale=1"><style>body{margin:0;background:rgb(255,0,0)}</style>')}`,
+        );
+        for (const color of ["rgb(255,0,0)", "rgb(0,255,0)"]) {
+          await browser.evaluate(
+            "change background",
+            `document.body.style.background = ${JSON.stringify(color)}`,
+          );
+          const id = await browser.screenshot();
+          const artifact = artifacts.at(-1)!;
+          expect(artifact.id).toBe(id);
+          expect(artifact.contentType).toBe("image/png");
+          const png = Buffer.from(artifact.bytesBase64, "base64");
+          expect(artifact.sizeBytes).toBe(png.length);
+          expect([png.readUInt32BE(16), png.readUInt32BE(20)]).toEqual([
+            width * dpr,
+            height * dpr,
+          ]);
+          const pixel = readRaw(
+            await browser.evaluate(
+              "read captured bottom-right pixel",
+              `(async function () {
+          const img = new Image(); img.src = 'data:image/png;base64,${artifact.bytesBase64}'; 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(img.width-10,img.height-10,1,1).data];
+        })()`,
+            ),
+          );
+          expect(pixel).toEqual(
+            color.includes("255,0,0") ? [255, 0, 0, 255] : [0, 255, 0, 255],
+          );
+        }
+      } finally {
+        await browser.close();
+      }
+    },
+    20000,
+  );
+}

package/src/browser-surface.test.ts

@@ -0,0 +1,71 @@
+import { expect, test } from "bun:test";
+import { chromium } from "playwright-core";
+import { awaitBrowserSurface, captureBrowserScreenshot, reduceBrowserSurfaces } from "./browser-surface.js";
+
+const engines = {
+  chromium: Bun.which("chromium") ?? Bun.which("chromium-browser") ?? Bun.which("google-chrome"),
+  shell: Bun.which("chromium-headless-shell") ?? Bun.which("chrome-headless-shell"),
+};
+for (const [engine, executablePath] of Object.entries(engines)) for (const mobile of [false, true]) {
+  test.skipIf(!executablePath)(`${engine}: reduced surface preserves ${mobile ? "mobile" : "desktop"} behavior and screenshot pixels`, async () => {
+    const browser = await chromium.launch({ executablePath: 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-timezone.test.ts

@@ -21,7 +21,7 @@ async function settings(browser: Browser): Promise<Settings> {
   return readRaw(await browser.evaluate<Settings>("read initial regional settings", "window.settings")) as unknown as Settings;
 }
 
-describe.skipIf(!Bun.which("chromium") && !Bun.which("chromium-browser") && !Bun.which("google-chrome"))("browser timezone and locale", () => {
+describe.skipIf(!Bun.which("chromium-headless-shell") && !Bun.which("chrome-headless-shell"))("browser timezone and locale", () => {
   let server: ReturnType<typeof Bun.serve>;
   beforeAll(() => {
     server = Bun.serve({

package/src/browser.ts

@@ -1,5 +1,5 @@
 // Headless browser handle for tests. Thin wrapper around playwright-core
-// driving the guest's system Chromium (pipe transport — `chromium.launch`
+// driving the guest's Headless Shell (pipe transport — `chromium.launch`
 // with an explicit `executablePath`). Electron attaches to the app-owned
 // Chromium over CDP instead; its client also lives inside the VM. The wrapper
 // keeps the public surface stable (we swapped from Bun.WebView to Playwright without
@@ -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,
@@ -462,7 +463,7 @@ const NAVIGATION_TIMEOUT_MS = 30_000;
 // Shared Chromium (playwright-core)
 // ────────────────────────────────────────────────────────────────────────
 
-// Default sessions share one Chromium per daemon, launched lazily and kept
+// Browser and mobile sessions share one Headless Shell per daemon, launched lazily and kept
 // for the daemon's lifetime. Fixture sessions own a process because the audio
 // source is a process-wide flag. Both ride snapshots: the process, playwright's
 // pipe connection to it, and every open page freeze into the VM snapshot
@@ -480,19 +481,18 @@ const VIEW_CLEANUPS = new WeakMap<BrowserContext, () => Promise<void>>();
 // the page only — cookies survived and the next session was still
 // authenticated.
 
-function chromiumPath(): string {
-  return (
-    Bun.which("chromium") ??
-    Bun.which("chromium-browser") ??
-    Bun.which("google-chrome") ??
-    "/usr/bin/chromium"
-  );
+function browserExecutable(): string {
+  const executable = Bun.which("chromium-headless-shell") ?? Bun.which("chrome-headless-shell");
+  if (!executable) {
+    throw new Error("Chromium Headless Shell is required by this SDK but is missing from the runtime image. Rebuild the environment with a current Spectest golden image; for local development, install chromium-headless-shell on PATH.");
+  }
+  return executable;
 }
 
 async function ensurePlaywrightBrowser(): Promise<PlaywrightBrowser> {
   if (PW_BROWSER?.isConnected()) return PW_BROWSER;
   PW_BROWSER = await chromium.launch({
-    executablePath: chromiumPath(),
+    executablePath: browserExecutable(),
     headless: true,
     args: CHROME_ARGV,
   });
@@ -530,7 +530,7 @@ async function newViewContext(
   let browser: PlaywrightBrowser | undefined;
   try {
     browser = fixture ? await chromium.launch({
-      executablePath: chromiumPath(), headless: true, args: [...CHROME_ARGV, fixture.arg],
+      executablePath: browserExecutable(), headless: true, args: [...CHROME_ARGV, fixture.arg],
     }) : await ensurePlaywrightBrowser();
     const context = await browser.newContext({
       ...(device
@@ -543,6 +543,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 +1289,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 +2201,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");
+}

package/src/microphone-fixture.test.ts

@@ -77,7 +77,7 @@ async function peak(browser: MobileBackend): Promise<number> {
   }));
 }
 
-describe.skipIf(!Bun.which("chromium") && !Bun.which("chromium-browser") && !Bun.which("google-chrome"))("native Chromium microphone", () => {
+describe.skipIf(!Bun.which("chromium-headless-shell") && !Bun.which("chrome-headless-shell"))("native Chromium microphone", () => {
   let server: ReturnType<typeof Bun.serve>;
   beforeAll(() => { server = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: () => new Response("<html>microphone</html>", { headers: { "content-type": "text/html" } }) }); });
   afterAll(() => server.stop(true));

package/src/playwright-assertions.test.ts

@@ -200,7 +200,7 @@ describe.skipIf(!available)("Spectest assertions backed by real Playwright/Chrom
 
 // Exercise the production session branding/recording as well as the real
 // native engine above. browser.ts intentionally uses system Chromium.
-test.skipIf(!executablePath)("browser backend preserves assertion provenance and failure page capture", async () => {
+test.skipIf(!Bun.which("chromium-headless-shell") && !Bun.which("chrome-headless-shell"))("browser backend preserves assertion provenance and failure page capture", async () => {
   const { openBrowser } = await import("./browser.js");
   const replaySteps: unknown[] = [];
   const view = await openBrowser({