@specific.dev/spectest 0.88.2 → 0.89.0

package/README.md

@@ -0,0 +1,108 @@
+# Spectest SDK
+
+Spectest runs your application and its dependencies in isolated environments.
+Tests can fork a parent's live state, including memory and files, then drive
+user flows with recorded assertions and graphical replays.
+
+Install the SDK in your project's `spectest/` directory:
+
+```sh
+mkdir -p spectest
+npm install --prefix spectest --save-exact @specific.dev/spectest@0.88.3
+```
+
+Install the [Spectest CLI](https://github.com/specific-dev/spectest/releases/latest)
+and run `spectest docs /installation` for project setup and authentication.
+`spectest docs` contains the complete offline authoring guide.
+
+## HTTP assertions
+
+`ctx.fetch()` returns a wrapped response. Status fields, header lookups, and
+all body readers retain the HTTP call's provenance, so assertions appear under
+that call on the timeline:
+
+```ts
+const response = await ctx.fetch("http://app:3000/image.png");
+expect(response.status).toBe(200);
+expect(response.headers.get("content-type")).toBe("image/png");
+const bytes = await response.bytes();
+expect(bytes).toHaveLength(70);
+expect(bytes[0]).toBe(0x89);
+expect(bytes.slice(0, 8)).toEqual(new Uint8Array([0x89, 0x50, 0x4e, 0x47, 13, 10, 26, 10]));
+```
+
+`arrayBuffer()` wraps buffer metadata and slices. `blob()` wraps metadata and
+its body readers. `formData()` wraps `get()`, `getAll()`, and `has()`, including
+uploaded files and their metadata. Headers also support wrapped `getSetCookie()`
+and Bun's `getAll()`, `toJSON()`, and `count`. Missing fields remain `null`, with
+provenance recovered by an immediately following `expect`.
+
+Use `.unwrap()` to pass a wrapped value to a native API, such as
+`new TextDecoder().decode(bytes.unwrap())`. Use `.transform("text", bytes =>
+new TextDecoder().decode(bytes))` when the derived value should retain provenance.
+Iteration and callback arguments remain raw, as do array/typed-array `length`
+and stream control flags (`done`, `locked`). Use `expect(bytes).toHaveLength(n)`
+for a linked length assertion. `bodyUsed` is wrapped: unwrap it for control flow.
+
+For an open-ended stream, pass `{ captureBody: false }` to return without waiting
+for recorder body capture. SSE (`text/event-stream`) skips capture automatically.
+The HTTP event and assertions are still recorded; the event omits the body.
+`response.body.getReader().read()` returns a raw `done` flag and wrapped `value`.
+BYOB readers, `tee()`, and `pipeThrough()` preserve provenance too. Release reader
+locks and cancel streams when finished, as with native fetch.
+
+## Electron apps
+
+Use `electron()` to build and run a real Linux Electron app under Xvfb, with
+its main process, preload, IPC and renderer. Spectest supplies the container
+setup; no custom Dockerfile is needed.
+
+Create `spectest/index.ts`:
+
+```ts
+import { defineEnvironment } from "@specific.dev/spectest";
+import { electron } from "@specific.dev/spectest/components";
+
+export const env = defineEnvironment({
+  name: "desktop-app",
+  services: { app: electron() },
+});
+
+export default env.project();
+```
+
+Create `spectest/tests/notes.ts`, using your app's labels:
+
+```ts
+import { expect } from "@specific.dev/spectest";
+import { env } from "../index";
+
+env.test("Save a note", async (ctx) => {
+  const app = await ctx.desktop(ctx.svc.app);
+  await app.getByRole("textbox", { name: "New note" }).fill("Hello desktop");
+  await app.getByRole("button", { name: "Add note", exact: true }).click();
+  await expect(app.getByRole("listitem")).toHaveText(["Hello desktop"]);
+});
+```
+
+Run `spectest test .` from the project root. The dashboard records desktop
+interactions and replays the app with window chrome derived from its Electron
+configuration. Child tests using `dependsOn` inherit the live app state,
+including unsaved input, in their own isolated environment.
+
+The app must declare Electron in `package.json` (its own or, with `context`
+set to a monorepo root, the root one). Defaults are `npm ci` with a
+package lock (otherwise `npm install`), `npm run build`, and the package's
+`main` entry. Use `appDir`, `installCommand`, `buildCommand`, `entry`, and
+`nodeVersion` to customize the build. `env` supplies runtime variables;
+`dependsOn` waits for backend services in the same environment. Expose the
+backend through the built-in proxy (`tls: [{ hostname, port }]`) and give the
+app its `https://` URL: a renderer Content Security Policy usually refuses a
+plain `http://` service address.
+
+Applications need Linux-compatible dependencies and binaries. Native OS dialogs
+and macOS-specific APIs are outside this basic support. Replays capture the
+renderer DOM from acquisition onward, not native OS surfaces.
+
+Run `spectest docs /components/electron` for the full configuration reference,
+backend setup, session behavior, and replay scope (CLI 0.2.124 or later).

package/dist/components/electron-chrome.d.ts

@@ -1 +1,2 @@
+export declare const ELECTRON_CA_TRUST: string;
 export declare const ELECTRON_CHROME_HOOK: string;

package/dist/components/electron-chrome.js

@@ -1,7 +1,54 @@
+// Trust for the environment CA, applied per session. Chromium on Linux
+// reads its own root store (NSS), never the container's mounted bundle, so
+// the renderer rejects every certificate the environment mints while Node
+// in the main process accepts them through NODE_EXTRA_CA_CERTS. This verify
+// procedure accepts exactly the chains that CA issued for the requested
+// host, and defers to Chromium's own verdict for everything else. An app
+// that installs its own procedure later replaces it, as in production.
+// Kept free of Electron so the unit test can run it under Bun.
+export const ELECTRON_CA_TRUST = String.raw `
+const { X509Certificate } = require('node:crypto');
+function loadEnvironmentCa(path) {
+  try { return path ? new X509Certificate(require('node:fs').readFileSync(path)) : null; }
+  catch { return null; }
+}
+// request: { hostname, errorCode, certificate: { data, issuerCert? } }.
+// Returns true only for a chain that ends at the CA and names the host.
+function issuedByEnvironmentCa(ca, request) {
+  try {
+    const leaf = new X509Certificate(request.certificate.data);
+    const host = request.hostname;
+    const named = leaf.checkHost(host) !== undefined || leaf.checkIP(host) !== undefined;
+    if (!named) return false;
+    const chain = [leaf];
+    for (let c = request.certificate; c.issuerCert && c.issuerCert !== c && chain.length < 8; c = c.issuerCert) {
+      chain.push(new X509Certificate(c.issuerCert.data));
+    }
+    for (let i = 0; i < chain.length; i++) {
+      const cert = chain[i];
+      if (cert.fingerprint256 === ca.fingerprint256) return i > 0;
+      const issuer = chain[i + 1] ?? ca;
+      if (!cert.checkIssued(issuer) || !cert.verify(issuer.publicKey)) return false;
+    }
+    return true;
+  } catch { return false; }
+}
+`;
 // Runs before the application's main entry, like Playwright's Electron loader.
 // Observe constructor options; do not replace the app entry, preload, IPC, or OS.
 export const ELECTRON_CHROME_HOOK = String.raw `
 const electron = require('electron');
+${ELECTRON_CA_TRUST}
+const environmentCa = loadEnvironmentCa(process.env.NODE_EXTRA_CA_CERTS);
+if (environmentCa) {
+  // Every session, including the default one and app-created partitions.
+  electron.app.on('session-created', session => {
+    session.setCertificateVerifyProc((request, callback) => {
+      if (request.errorCode === 0) return callback(0);
+      callback(issuedByEnvironmentCa(environmentCa, request) ? 0 : -3);
+    });
+  });
+}
 const NativeBrowserWindow = electron.BrowserWindow;
 const WrappedBrowserWindow = new Proxy(NativeBrowserWindow, {
   construct(Target, args, NewTarget) {

package/dist/components/electron.d.ts

@@ -1,7 +1,16 @@
 import { type DesktopApp } from "../desktop.js";
 export interface ElectronOptions {
-    /** Project-relative app directory; must contain package.json and Electron. */
+    /** Project-relative app directory; must contain package.json. Electron must
+     * be declared here or in the context's package.json. */
     appDir?: string;
+    /**
+     * Image build context, relative to the project root. Default `appDir`.
+     * Set it to the repository root when the app is one workspace of a
+     * monorepo and resolves packages from above its own directory. The
+     * context is copied to `/app`; `installCommand` runs at the context root,
+     * `buildCommand` and Electron run in the app directory below it.
+     */
+    context?: string;
     /** Debian Node image tag, default 24-bookworm-slim. */
     nodeVersion?: string;
     /** Build the main/preload/renderer output; default npm run build. */
@@ -31,6 +40,7 @@ export declare function electron(options?: ElectronOptions): {
     command: string;
     env: {
         SPECTEST_ELECTRON_ENTRY: string;
+        SPECTEST_ELECTRON_APP_DIR: string;
     };
     dependsOn: string[] | undefined;
     ports: number[];

package/dist/components/electron.js

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
+import { posix } from "node:path";
 import { resolveProjectPath } from "../project-files.js";
 import { desktopApp } from "../desktop.js";
 import { ELECTRON_CHROME_HOOK } from "./electron-chrome.js";
@@ -9,13 +10,14 @@ export const ELECTRON_LAUNCHER = String.raw `
 import http from 'node:http';
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
-const require = createRequire('/app/package.json');
+const appDir = process.env.SPECTEST_ELECTRON_APP_DIR || '/app';
+const require = createRequire(appDir + '/package.json');
 const child = spawn(require('electron'), [
   ...(process.getuid?.() === 0 ? ['--no-sandbox'] : []),
   '--disable-dev-shm-usage', '--remote-debugging-port=9222',
   '-r', '/spectest-electron-chrome.cjs',
   process.env.SPECTEST_ELECTRON_ENTRY || '.',
-], { cwd: '/app', stdio: 'inherit', env: process.env });
+], { cwd: appDir, stdio: 'inherit', env: process.env });
 const upstream = req => ({
   host: '127.0.0.1', port: 9222, path: req.url, method: req.method,
   headers: { ...req.headers, host: '127.0.0.1:9222' },
@@ -50,19 +52,41 @@ child.on('error', error => { console.error(error); process.exit(1); });
 child.on('exit', code => process.exit(code ?? 1));
 for (const signal of ['SIGTERM', 'SIGINT']) process.on(signal, () => child.kill(signal));
 `;
+/** Read a package.json and tell whether it declares electron. */
+function declaresElectron(manifest) {
+    if (!existsSync(manifest))
+        return false;
+    const pkg = JSON.parse(readFileSync(manifest, "utf8"));
+    return Boolean(pkg.dependencies?.electron || pkg.devDependencies?.electron);
+}
+/** The app directory as a path inside the build context: "." or "a/b". */
+function appPathInContext(appDir, context) {
+    const rel = posix.relative(posix.normalize(context), posix.normalize(appDir));
+    if (rel === "")
+        return ".";
+    if (rel.startsWith("..") || posix.isAbsolute(rel)) {
+        throw new Error(`electron(): appDir ${JSON.stringify(appDir)} must be inside context ${JSON.stringify(context)}`);
+    }
+    return rel;
+}
 /** Real Linux Electron under Xvfb, with a generated image and graphical replay.
  * Like expo(), returns an app handle for the matching context method.
  * Requires Linux-compatible application dependencies and binaries. */
 export function electron(options = {}) {
     const appDir = options.appDir ?? ".";
+    const context = options.context ?? appDir;
+    const appPath = appPathInContext(appDir, context);
     const manifest = resolveProjectPath(`${appDir}/package.json`);
     if (!existsSync(manifest))
         throw new Error(`electron(): no package.json in ${appDir}`);
-    const pkg = JSON.parse(readFileSync(manifest, "utf8"));
-    if (!pkg.dependencies?.electron && !pkg.devDependencies?.electron) {
-        throw new Error("electron(): declare electron in the app's dependencies or devDependencies");
+    // A monorepo declares electron in the workspace or at the root; both work
+    // because the app resolves `electron` upward from its own directory.
+    if (!declaresElectron(manifest) && !declaresElectron(resolveProjectPath(`${context}/package.json`))) {
+        throw new Error("electron(): declare electron in the app's dependencies or devDependencies" +
+            (context === appDir ? "" : ` (in ${appDir} or in the context ${context})`));
     }
-    const locked = existsSync(resolveProjectPath(`${appDir}/package-lock.json`));
+    // The install runs at the context root, so that is where the lockfile counts.
+    const locked = existsSync(resolveProjectPath(`${context}/package-lock.json`));
     const node = options.nodeVersion ?? "24-bookworm-slim";
     if (!/^[\w.-]+$/.test(node))
         throw new Error("electron(): invalid Node image tag");
@@ -71,18 +95,22 @@ export function electron(options = {}) {
     if ([install, build].some(command => /[\r\n]/.test(command))) {
         throw new Error("electron(): build/install commands must be single-line shell commands");
     }
+    // Electron can be hoisted to the context root, so find its install script
+    // through Node's resolution from the app directory instead of a fixed path.
+    const inApp = appPath === "." ? "" : `cd ${appPath} && `;
+    const fetchElectron = `${inApp}node "$(node -p "require.resolve('electron/install.js')")"`;
     return {
         image: {
             type: "dockerfile",
-            context: appDir,
+            context,
             exclude: ["node_modules", "**/node_modules", "out", "test-results", ".data"],
             content: `FROM node:${node}
 RUN apt-get update && apt-get install -y --no-install-recommends xvfb xauth libgtk-3-0 libnss3 libgbm1 libasound2 fonts-liberation ca-certificates && rm -rf /var/lib/apt/lists/*
 WORKDIR /app
 COPY . .
 RUN ${install}
-RUN node node_modules/electron/install.js
-RUN ${build}
+RUN ${fetchElectron}
+RUN ${inApp}${build}
 `,
         },
         files: [
@@ -90,7 +118,11 @@ RUN ${build}
             { path: "/spectest-electron-chrome.cjs", content: ELECTRON_CHROME_HOOK },
         ],
         command: "xvfb-run -a node /spectest-electron.mjs",
-        env: { ...options.env, SPECTEST_ELECTRON_ENTRY: options.entry ?? "." },
+        env: {
+            ...options.env,
+            SPECTEST_ELECTRON_ENTRY: options.entry ?? ".",
+            SPECTEST_ELECTRON_APP_DIR: appPath === "." ? "/app" : `/app/${appPath}`,
+        },
         dependsOn: options.dependsOn,
         ports: [9223],
         readyCheck: { type: "http", port: 9223, path: "/json/version", timeoutSecs: 60 },

package/dist/components/emulate/entry.mjs

@@ -0,0 +1,242 @@
+// The `socialAuth()` container's entry point.
+//
+// It runs one emulator per configured provider (the `@emulators/*` packages
+// from vercel-labs/emulate) and puts all of them behind ONE port, routed by
+// `Host` header. That is what lets the component answer at the providers'
+// real endpoints: the daemon owns DNS and TLS for those names and proxies
+// every one of them here.
+//
+// The engine is generic. Everything provider-specific — which hosts to
+// claim, which paths differ from the real ones, which discovery values to
+// correct — arrives as JSON in SPECTEST_AUTH_CONFIG, built by
+// `../social-auth.ts`. Add a provider there, not here.
+//
+// Four things happen to a response on the way out:
+//
+//   * discovery — the emulator advertises every endpoint on its own single
+//     origin. Real providers spread them over several hosts. We merge the
+//     real URLs in.
+//   * JWKS — we serve one RSA public key, for every provider.
+//   * id_token — we re-issue it: same claims, RS256, our key, and an
+//     explicit `iss` where the provider declares one. The Google emulator
+//     signs HS256 and serves an empty JWKS, so no client can verify its
+//     token. Providers whose issuer differs from their base URL can
+//     declare it explicitly. No signature check is needed on the way in: the
+//     token comes from an in-process function call, not from the network.
+//   * the account picker page — each button gets a `data-testid`, so a
+//     browser test has a stable locator.
+//
+// Every request is logged. Per-case service logs reach the dashboard, so
+// the whole OAuth exchange is readable on the case page with no helper API.
+
+import { createServer } from "@emulators/core";
+import { SignJWT, decodeJwt, exportJWK } from "jose";
+
+const CONFIG = JSON.parse(process.env.SPECTEST_AUTH_CONFIG ?? "{}");
+const PORT = Number(CONFIG.port ?? 4000);
+/** Key id published in the JWKS and stamped on every re-issued id_token. */
+const KID = "spectest-social-auth";
+
+// ──────────────────────────────────────────────────────────────────────────
+// Signing key
+//
+// Generated once, at boot — which is before the warm-template snapshot, so
+// every fork of this environment holds the same key and a token minted in a
+// parent stays valid in a child. Never generate it later: after a fork the
+// guest RNG is frozen, and sibling forks would produce identical keys.
+// ──────────────────────────────────────────────────────────────────────────
+
+const KEY_PAIR = await crypto.subtle.generateKey(
+  {
+    name: "RSASSA-PKCS1-v1_5",
+    modulusLength: 2048,
+    publicExponent: new Uint8Array([1, 0, 1]),
+    hash: "SHA-256",
+  },
+  true,
+  ["sign", "verify"],
+);
+const JWKS = {
+  keys: [{ ...(await exportJWK(KEY_PAIR.publicKey)), kid: KID, use: "sig", alg: "RS256" }],
+};
+
+// ──────────────────────────────────────────────────────────────────────────
+// Providers
+// ──────────────────────────────────────────────────────────────────────────
+
+/** host → runtime record. One emulator can claim several hosts. */
+const BY_HOST = new Map();
+
+for (const spec of CONFIG.providers ?? []) {
+  const mod = await import(spec.module);
+  const plugin = mod[spec.pluginExport];
+  if (!plugin) {
+    throw new Error(
+      `social-auth: ${spec.module} has no export ${spec.pluginExport}`,
+    );
+  }
+
+  // `port` only feeds the emulator's default base URL, which we always
+  // override — nothing listens on it. Each emulator is a fetch handler.
+  const { app, store, webhooks } = createServer(plugin, {
+    port: PORT,
+    baseUrl: spec.baseUrl,
+    fallbackUser: spec.fallbackUser,
+  });
+  plugin.seed?.(store, spec.baseUrl);
+  if (spec.seed && mod.seedFromConfig) {
+    mod.seedFromConfig(store, spec.baseUrl, spec.seed, webhooks);
+  }
+
+  const runtime = {
+    name: spec.name,
+    baseUrl: spec.baseUrl,
+    oidc: spec.oidc !== false,
+    issuer: spec.issuer,
+    discovery: spec.discovery ?? {},
+    jwksPath: spec.jwksPath ? new RegExp(spec.jwksPath) : null,
+    aliases: spec.aliases,
+    rewrites: (spec.rewrites ?? []).map((r) => ({ re: new RegExp(r.from), to: r.to })),
+    fetch: app.fetch,
+  };
+  for (const host of spec.hosts) BY_HOST.set(host.toLowerCase(), runtime);
+  console.log(`[social-auth] ${spec.name} → ${spec.hosts.join(", ")}`);
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Response rewriting
+// ──────────────────────────────────────────────────────────────────────────
+
+const DISCOVERY_RE = /\/\.well-known\/openid-configuration$/;
+
+/** Correct the discovery document: real hosts per endpoint, and RS256,
+ *  which is what we actually sign with after `reissueIdToken`. */
+async function patchDiscovery(res, provider) {
+  const doc = await res.json();
+  const patched = {
+    ...doc,
+    ...provider.discovery,
+    id_token_signing_alg_values_supported: ["RS256"],
+  };
+  return json(patched, res.status);
+}
+
+/** Re-issue the id_token on a token response. Claims pass through
+ *  unchanged except `iss`, which only a provider that cannot derive it
+ *  from its base URL overrides. */
+async function patchTokenResponse(res, provider) {
+  const body = await res.json();
+  if (typeof body.id_token !== "string") return json(body, res.status);
+
+  const claims = decodeJwt(body.id_token);
+  if (provider.issuer) claims.iss = provider.issuer;
+  body.id_token = await new SignJWT(claims)
+    .setProtectedHeader({ alg: "RS256", kid: KID, typ: "JWT" })
+    .sign(KEY_PAIR.privateKey);
+  return json(body, res.status);
+}
+
+/** Give every account button on the picker page a stable test id, and mark
+ *  the page itself. The hidden field that identifies the account is named
+ *  differently per provider, and does not always hold the address — GitHub
+ *  identifies an account by its login — so `aliases` maps it back. The test
+ *  id is the account's email on every provider. */
+async function patchPickerPage(res, provider) {
+  let html = await res.text();
+  html = html.replace(/<form class="user-form"[\s\S]*?<\/form>/g, (form) => {
+    const id = /<input type="hidden" name="(?:email|login|sub|username|user_ref)" value="([^"]*)"/.exec(form);
+    if (!id) return form;
+    const account = provider.aliases?.[id[1]] ?? id[1];
+    return form.replace(
+      "<button type=\"submit\"",
+      `<button type="submit" data-testid="spectest-user-${account}"`,
+    );
+  });
+  html = html.replace("<body", '<body data-spectest-signin="1"');
+  return new Response(html, { status: res.status, headers: res.headers });
+}
+
+function json(value, status) {
+  return new Response(JSON.stringify(value), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Server
+// ──────────────────────────────────────────────────────────────────────────
+
+Bun.serve({
+  port: PORT,
+  // The default 10s kills nothing here, but an authorize page fetched by a
+  // cold browser can be slower than it looks. Ingress uses the same margin.
+  idleTimeout: 60,
+  async fetch(req) {
+    const url = new URL(req.url);
+
+    // Answered on any Host, because the ready check probes the container's
+    // own IP and never sends a provider name.
+    if (url.pathname === "/healthz") return new Response("ok\n");
+
+    // The daemon reverse-proxies us and rewrites `Host` to the service-net
+    // name, so the provider the client asked for only survives in
+    // `X-Forwarded-Host`. Read that first; `Host` covers a direct call.
+    const host = (req.headers.get("x-forwarded-host") ?? req.headers.get("host") ?? "")
+      .toLowerCase()
+      .replace(/:\d+$/, "");
+    const provider = BY_HOST.get(host);
+    if (!provider) {
+      return new Response(
+        `spectest social-auth: no provider claims Host=${JSON.stringify(host)}\n` +
+          `claimed hosts: ${[...BY_HOST.keys()].join(", ")}\n`,
+        { status: 404, headers: { "content-type": "text/plain" } },
+      );
+    }
+
+    // Real path → the path this emulator serves it on. Identity by default,
+    // which is also what carries the emulator's own internal endpoints (the
+    // picker's POST target) through untouched.
+    let path = url.pathname;
+    for (const rule of provider.rewrites) {
+      if (rule.re.test(path)) {
+        path = path.replace(rule.re, rule.to);
+        break;
+      }
+    }
+
+    let res;
+    if (provider.oidc && provider.jwksPath?.test(path)) {
+      // Our key, never the emulator's — we re-sign every id_token.
+      res = json(JWKS, 200);
+    } else {
+      const body =
+        req.method === "GET" || req.method === "HEAD" ? undefined : await req.arrayBuffer();
+      // Restore the Host the client used, so an emulator that reads it sees
+      // the provider rather than our container.
+      const headers = new Headers(req.headers);
+      headers.set("host", host);
+      const inner = new Request(new URL(path + url.search, provider.baseUrl), {
+        method: req.method,
+        headers,
+        body,
+      });
+      res = await provider.fetch(inner);
+
+      const type = res.headers.get("content-type") ?? "";
+      if (type.includes("json")) {
+        if (DISCOVERY_RE.test(path)) res = await patchDiscovery(res, provider);
+        else if (provider.oidc) res = await patchTokenResponse(res, provider);
+      } else if (type.includes("text/html")) {
+        res = await patchPickerPage(res, provider);
+      }
+    }
+
+    console.log(
+      `[social-auth] ${provider.name} ${req.method} ${host}${url.pathname} → ${res.status}`,
+    );
+    return res;
+  },
+});
+
+console.log(`[social-auth] listening on :${PORT}`);

package/dist/harness/fetch.js

@@ -61,8 +61,7 @@ export function isTransportError(err) {
 export function installFetchWrapper() {
     const original = globalThis.fetch;
     // SDK internals (the MCP client, its OAuth flow) must not see the
-    // wrapper: a wrapped `res.ok` is an object, and the wrapper reads every
-    // body to the end, which never finishes for an SSE stream.
+    // wrapper: its response properties and body readers return wrapped values.
     setRawFetch(original);
     const wrappedFn = async (input, init) => {
         const scope = currentInstrumentationScope();
@@ -85,7 +84,12 @@ export function installFetchWrapper() {
             const contentType = res.headers.get("content-type");
             const contentLength = () => parseContentLength(res.headers.get("content-length"));
             const textual = isTextualContentType(contentType);
-            if (textual === false) {
+            const streaming = contentType?.split(";")[0]?.trim().toLowerCase() === "text/event-stream";
+            if (init?.captureBody === false || streaming) {
+                // Return on headers: an open-ended stream must not be drained (or
+                // cloned into an unbounded background buffer) by the recorder.
+            }
+            else if (textual === false) {
                 responseBody = omittedBody("binary", contentType, contentLength());
             }
             else {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { strict as nodeAssert } from "node:assert";
-export type { Carrier, Wrapped, WrappedObject, WrappedArray, WrappedResponse, Provenanced, SpectestFetch, Unwrap, } from "./inspect.js";
+export type { Carrier, Wrapped, WrappedObject, WrappedArray, WrappedHeaders, WrappedBuffer, WrappedBinaryView, WrappedBytes, WrappedBlob, WrappedFile, WrappedFormData, WrappedStream, WrappedReader, WrappedBYOBReader, WrappedReadResult, WrappedResponse, Provenanced, SpectestFetch, SpectestRequestInit, Unwrap, } from "./inspect.js";
 import type { Provenanced, SpectestFetch, Wrapped } from "./inspect.js";
 export { field } from "./inspect.js";
 export { annotate } from "./annotate.js";
@@ -300,11 +300,15 @@ export interface SpectestContext<S extends ServicesMap = ServicesMap, F extends
     /**
      * Instrumented `fetch`. In a test each call is recorded on the timeline
      * and resolves to a {@link WrappedResponse}: reads carry provenance so
-     * `expect(res.status)` / `expect(await res.json())` nest under the HTTP
+     * `expect(res.status)`, `expect(res.headers.get("content-type"))`, and
+     * `expect(await res.json())` nest under the HTTP
      * call. Because the status-line accessors are {@link Carrier}s, a raw
      * `res.status === 200` is a *type error* — use `res.status.unwrap()` /
      * `res.unwrap().status`, or assert via `expect`. Outside a test the
      * result is wrapped the same way, just with no timeline to link to.
+     * Body readers (`bytes`, `arrayBuffer`, `blob`, `formData`, `json`, `text`)
+     * and stream reader values also retain provenance. Use `captureBody: false`
+     * for open-ended streams; SSE responses skip recorder body capture automatically.
      *
      * (The plain global `fetch` is wrapped the same way at runtime but keeps
      * the standard `Response` type, so prefer `ctx.fetch` for honestly-typed