@specific.dev/spectest 0.88.3 → 0.89.0

package/README.md

@@ -15,6 +15,42 @@ Install the [Spectest CLI](https://github.com/specific-dev/spectest/releases/lat
 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
@@ -54,11 +90,15 @@ 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`. Defaults are `npm ci` with a
+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.
+`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

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/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

package/dist/inspect.d.ts

@@ -163,7 +163,7 @@ export type Provenanced = {
  * recovered at runtime by {@link adoptNullishTag}; `Provenanced` admits it because
  * it includes `null | undefined`.
  */
-export type Wrapped<T> = T extends null | undefined ? T : T extends readonly (infer U)[] ? WrappedArray<U> : T extends (...args: never[]) => unknown ? T : T extends object ? WrappedObject<T> : Carrier<T>;
+export type Wrapped<T> = T extends null | undefined ? T : T extends readonly (infer U)[] ? WrappedArray<U> : T extends ArrayBuffer | SharedArrayBuffer ? WrappedBuffer<T> : T extends ArrayBufferView ? WrappedBinaryView<T> : T extends File ? WrappedFile : T extends Blob ? WrappedBlob : T extends FormData ? WrappedFormData : T extends ReadableStream<infer C> ? WrappedStream<C> : T extends (...args: never[]) => unknown ? T : T extends object ? WrappedObject<T> : Carrier<T>;
 /** A wrapped object: every own property is itself {@link Wrapped}, plus an
  *  `.unwrap()` that recovers the fully-raw value (all nested leaves raw). */
 export type WrappedObject<T> = {
@@ -214,6 +214,69 @@ export interface WrappedArray<U> {
     /** Iteration yields *raw* elements (the runtime forwards the raw iterator). */
     [Symbol.iterator](): IterableIterator<U>;
 }
+/** Native objects need their own views: getters and methods must receive the
+ * real native receiver, and method results must be wrapped after they resolve.
+ * Iteration, callbacks, and control-flow flags on stream readers remain raw.
+ */
+type NativeResult<T> = T extends Promise<infer R> ? Promise<Wrapped<R>> : Wrapped<T>;
+type NativeView<T, K extends keyof T> = Omit<T, K> & {
+    readonly [P in K]: T[P] extends (...args: infer A) => infer R ? (...args: A) => NativeResult<R> : Wrapped<T[P]>;
+} & {
+    unwrap(): T;
+    transform<R>(label: string, fn: (raw: T) => R): Wrapped<R>;
+};
+export type WrappedBuffer<T extends ArrayBuffer | SharedArrayBuffer = ArrayBuffer> = NativeView<T, Extract<keyof T, "byteLength" | "maxByteLength" | "resizable" | "growable" | "detached" | "slice" | "transfer" | "transferToFixedLength">>;
+declare const BINARY_METHOD_NAMES: readonly ["at", "slice", "subarray", "includes", "indexOf", "lastIndexOf", "find", "findLast", "findIndex", "findLastIndex", "some", "every", "filter", "map", "join", "fill", "copyWithin", "reverse", "sort", "toReversed", "toSorted", "with", "toHex", "toBase64", "getInt8", "getUint8", "getInt16", "getUint16", "getInt32", "getUint32", "getFloat16", "getFloat32", "getFloat64", "getBigInt64", "getBigUint64"];
+/** Numeric indexes carry provenance. Like WrappedArray, length and iteration
+ * stay raw; callbacks receive native values. Unwrap for native API inputs. */
+export type WrappedBinaryView<T extends ArrayBufferView> = NativeView<T, Extract<keyof T, number | "buffer" | "byteLength" | "byteOffset" | typeof BINARY_METHOD_NAMES[number]>>;
+export type WrappedBytes = WrappedBinaryView<Uint8Array>;
+export type WrappedBlob = NativeView<Blob, "size" | "type" | "slice" | "text" | "bytes" | "arrayBuffer" | "stream">;
+export type WrappedFile = NativeView<File, "name" | "lastModified" | "webkitRelativePath" | "size" | "type" | "slice" | "text" | "bytes" | "arrayBuffer" | "stream">;
+export type WrappedFormData = NativeView<FormData, "get" | "getAll" | "has">;
+export type WrappedReadResult<T> = {
+    done: false;
+    value: Wrapped<T>;
+} | {
+    done: true;
+    value: Wrapped<T> | undefined;
+};
+export interface WrappedReader<T> extends Omit<ReadableStreamDefaultReader<T>, "read"> {
+    read(): Promise<WrappedReadResult<T>>;
+    unwrap(): ReadableStreamDefaultReader<T>;
+}
+export interface WrappedBYOBReader extends Omit<ReadableStreamBYOBReader, "read"> {
+    read<T extends ArrayBufferView>(view: T, options?: {
+        min?: number;
+    }): Promise<WrappedReadResult<T>>;
+    unwrap(): ReadableStreamBYOBReader;
+}
+export interface WrappedStream<T> extends Omit<ReadableStream<T>, "getReader" | "tee" | "pipeThrough"> {
+    getReader(): WrappedReader<T>;
+    getReader(options: {
+        mode: "byob";
+    }): WrappedBYOBReader;
+    getReader(options: ReadableStreamGetReaderOptions): WrappedReader<T> | WrappedBYOBReader;
+    tee(): [WrappedStream<T>, WrappedStream<T>];
+    pipeThrough<R>(transform: ReadableWritablePair<R, any>, options?: StreamPipeOptions): WrappedStream<R>;
+    unwrap(): ReadableStream<T>;
+    transform<R>(label: string, fn: (raw: ReadableStream<T>) => R): Wrapped<R>;
+}
+/** Response headers whose lookups retain the originating HTTP call's provenance.
+ * Missing headers remain `null`; `expect(headers.get(name)).toBe(null)` still
+ * links to the call. Iterators and other native methods return raw values.
+ */
+export interface WrappedHeaders extends Omit<Headers, "get" | "has" | "getSetCookie" | "getAll" | "toJSON" | "count"> {
+    get(name: string): Carrier<string> | null;
+    /** Unwrap before using the result as a condition. */
+    has(name: string): Carrier<boolean>;
+    getSetCookie(): WrappedArray<string>;
+    getAll(name: "set-cookie" | "Set-Cookie"): WrappedArray<string>;
+    toJSON(): Wrapped<Record<string, string | string[]>>;
+    readonly count: Carrier<number>;
+    unwrap(): Headers;
+    transform<R = unknown>(label: string, fn: (raw: Headers) => R): Wrapped<R>;
+}
 /**
  * The view `ctx.fetch` resolves to in every context (a spectest op wraps
  * unconditionally): a {@link Response} whose status-line accessors are
@@ -222,8 +285,9 @@ export interface WrappedArray<U> {
  * used to silently always be false. Compare `res.status.unwrap() === 200`
  * or `res.unwrap().status === 200`, or assert with `expect(res.status)`.
  *
- * `json<T>()` / `text()` return {@link Wrapped} body values; `.unwrap()`
- * (or {@link unwrap the whole response}) recovers the plain `Response`.
+ * All body readers return provenance-carrying values, including binary bodies,
+ * blobs and form data. `.unwrap()` recovers the native response or body value.
+ * Stream reader `done` and stream `locked` remain raw control-flow booleans.
  */
 export interface WrappedResponse {
     readonly status: Carrier<number>;
@@ -232,13 +296,15 @@ export interface WrappedResponse {
     readonly url: Carrier<string>;
     readonly redirected: Carrier<boolean>;
     readonly type: Carrier<string>;
-    readonly headers: Headers;
-    readonly bodyUsed: boolean;
+    readonly headers: WrappedHeaders;
+    readonly bodyUsed: Carrier<boolean>;
+    readonly body: WrappedStream<Uint8Array> | null;
     json<T = unknown>(): Promise<Wrapped<T>>;
     text(): Promise<Carrier<string>>;
-    arrayBuffer(): Promise<ArrayBuffer>;
-    blob(): Promise<Blob>;
-    formData(): Promise<FormData>;
+    arrayBuffer(): Promise<WrappedBuffer>;
+    bytes(): Promise<WrappedBytes>;
+    blob(): Promise<WrappedBlob>;
+    formData(): Promise<WrappedFormData>;
     clone(): WrappedResponse;
     /** Recover the underlying raw {@link Response} (a real `number` status,
      *  an unwrapped body, etc.). */
@@ -246,12 +312,19 @@ export interface WrappedResponse {
 }
 /** The signature of `ctx.fetch`: a `fetch` that resolves to a
  *  {@link WrappedResponse} so reads carry provenance into assertions. */
-export type SpectestFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<WrappedResponse>;
+export type SpectestFetch = (input: RequestInfo | URL, init?: SpectestRequestInit) => Promise<WrappedResponse>;
+export interface SpectestRequestInit extends RequestInit {
+    /** Skip the recorder's body capture for open-ended streams. SSE skips it
+     * automatically. The response and assertions remain recorded. */
+    captureBody?: boolean;
+}
 /**
  * Bespoke wrapper for `fetch` responses. Reads on `status` / `ok` /
  * `statusText` / `url` / `redirected` / `type` return carriers tagged
- * to `sourceSeq`. The body-reading methods (`json`, `text`) return the
- * resolved value wrapped under `path: ["body"]`. Everything else passes
- * through bound to the real Response.
+ * to `sourceSeq`. Every body-reading method returns its resolved value
+ * wrapped under `path: ["body"]`. Header lookups carry paths
+ * under `headers`, and clones retain the same provenance. Everything else
+ * passes through bound to the real Response.
  */
 export declare function wrapResponse(res: Response, sourceSeq: number | undefined): WrappedResponse;
+export {};

package/dist/inspect.js

@@ -210,6 +210,20 @@ export function wrap(raw, sourceSeq, path = []) {
         return raw;
     const t = typeof raw;
     if (t === "object") {
+        const native = readRaw(raw);
+        if (native instanceof ArrayBuffer || (typeof SharedArrayBuffer !== "undefined" && native instanceof SharedArrayBuffer)) {
+            return wrapNative(native, sourceSeq, path, new Set(["byteLength", "maxByteLength", "resizable", "growable", "detached"]), new Set(["slice", "transfer", "transferToFixedLength"]));
+        }
+        if (ArrayBuffer.isView(native)) {
+            return wrapNative(native, sourceSeq, path, new Set(["buffer", "byteLength", "byteOffset"]), BINARY_METHODS, true);
+        }
+        if (native instanceof Blob) {
+            return wrapNative(native, sourceSeq, path, new Set(["size", "type", "name", "lastModified", "webkitRelativePath"]), new Set(["slice", "text", "bytes", "arrayBuffer", "stream"]));
+        }
+        if (native instanceof FormData)
+            return wrapFormData(native, sourceSeq, path);
+        if (native instanceof ReadableStream)
+            return wrapStream(native, sourceSeq, path);
         return wrapObject(raw, sourceSeq, path);
     }
     if (t === "function")
@@ -437,15 +451,140 @@ export function field(value, ...path) {
         return cur;
     return retag(cur, tag.sourceSeq, [...tag.path, ...path.map(String)]);
 }
+const BINARY_METHOD_NAMES = [
+    "at", "slice", "subarray", "includes", "indexOf", "lastIndexOf", "find", "findLast",
+    "findIndex", "findLastIndex", "some", "every", "filter", "map", "join",
+    "fill", "copyWithin", "reverse", "sort", "toReversed", "toSorted", "with", "toHex", "toBase64",
+    "getInt8", "getUint8", "getInt16", "getUint16", "getInt32", "getUint32",
+    "getFloat16", "getFloat32", "getFloat64", "getBigInt64", "getBigUint64",
+];
+const BINARY_METHODS = new Set(BINARY_METHOD_NAMES);
+function wrapNative(raw, sourceSeq, path, properties, methods, indexes = false) {
+    const tag = { sourceSeq, path };
+    return new Proxy(raw, {
+        get(target, prop) {
+            if (prop === OP_TAG)
+                return tag;
+            if (prop === UNWRAP)
+                return target;
+            if (prop === "unwrap")
+                return () => target;
+            if (prop === "transform")
+                return makeTransform(target, sourceSeq, path);
+            const value = Reflect.get(target, prop, target);
+            if (typeof prop === "string") {
+                if (properties.has(prop) || (indexes && /^(0|[1-9]\d*)$/.test(prop))) {
+                    return wrapChild(value, sourceSeq, [...path, prop]);
+                }
+                if (methods.has(prop) && typeof value === "function") {
+                    return (...args) => {
+                        const result = value.apply(target, args);
+                        const resultPath = [...path, `<${prop}>`];
+                        return result instanceof Promise
+                            ? result.then((v) => wrapChild(v, sourceSeq, resultPath))
+                            : wrapChild(result, sourceSeq, resultPath);
+                    };
+                }
+            }
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+        has(target, prop) {
+            return prop === OP_TAG || prop === UNWRAP || Reflect.has(target, prop);
+        },
+    });
+}
+function wrapFormData(raw, sourceSeq, path) {
+    const base = wrapNative(raw, sourceSeq, path, new Set(), new Set());
+    return new Proxy(base, {
+        get(target, prop) {
+            if (prop === "get" || prop === "getAll" || prop === "has") {
+                return (name) => wrapChild(raw[prop](name), sourceSeq, prop === "get" ? [...path, name] : [...path, name, `<${prop}>`]);
+            }
+            return Reflect.get(target, prop);
+        },
+    });
+}
+function wrapStream(raw, sourceSeq, path) {
+    const base = wrapNative(raw, sourceSeq, path, new Set(), new Set(["pipeThrough"]));
+    return new Proxy(base, {
+        get(target, prop) {
+            if (prop === "tee")
+                return () => raw.tee().map((s, i) => wrapStream(s, sourceSeq, [...path, `<tee>`, String(i)]));
+            if (prop === "getReader")
+                return (options) => {
+                    const reader = raw.getReader(options);
+                    let index = 0;
+                    return new Proxy(reader, {
+                        get(r, key) {
+                            if (key === "unwrap" || key === UNWRAP)
+                                return key === "unwrap" ? () => r : r;
+                            if (key === OP_TAG)
+                                return { sourceSeq, path };
+                            if (key === "read")
+                                return async (...args) => {
+                                    const read = r.read;
+                                    const result = await read.apply(r, args);
+                                    const valuePath = [...path, "<read>", String(index++)];
+                                    // done stays a real boolean so normal reader loops terminate.
+                                    return { done: result.done, get value() { return wrapChild(result.value, sourceSeq, valuePath); } };
+                                };
+                            const value = Reflect.get(r, key, r);
+                            return typeof value === "function" ? value.bind(r) : value;
+                        },
+                        has(r, key) { return key === UNWRAP || key === OP_TAG || Reflect.has(r, key); },
+                    });
+                };
+            return Reflect.get(target, prop);
+        },
+    });
+}
+function wrapHeaders(headers, sourceSeq) {
+    const path = ["headers"];
+    const tag = { sourceSeq, path };
+    return new Proxy(headers, {
+        get(target, prop) {
+            if (prop === OP_TAG)
+                return tag;
+            if (prop === UNWRAP)
+                return target;
+            if (prop === "unwrap")
+                return () => target;
+            if (prop === "transform")
+                return makeTransform(target, sourceSeq, path);
+            if (prop === "get" || prop === "has") {
+                return (name) => wrapChild(target[prop](name), sourceSeq, prop === "get" ? [...path, name.toLowerCase()] : [...path, name.toLowerCase(), "<has>"]);
+            }
+            if (prop === "count")
+                return wrap(target.count, sourceSeq, [...path, "count"]);
+            if (prop === "getAll")
+                return (name) => wrap(target.getAll(name), sourceSeq, [...path, name.toLowerCase()]);
+            if (prop === "toJSON")
+                return () => wrap(target.toJSON(), sourceSeq, path);
+            if (prop === "getSetCookie") {
+                return () => wrap(target.getSetCookie(), sourceSeq, [...path, "set-cookie"]);
+            }
+            const value = Reflect.get(target, prop, target);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+        has(target, prop) {
+            if (prop === OP_TAG || prop === UNWRAP)
+                return true;
+            return Reflect.has(target, prop);
+        },
+    });
+}
 /**
  * Bespoke wrapper for `fetch` responses. Reads on `status` / `ok` /
  * `statusText` / `url` / `redirected` / `type` return carriers tagged
- * to `sourceSeq`. The body-reading methods (`json`, `text`) return the
- * resolved value wrapped under `path: ["body"]`. Everything else passes
- * through bound to the real Response.
+ * to `sourceSeq`. Every body-reading method returns its resolved value
+ * wrapped under `path: ["body"]`. Header lookups carry paths
+ * under `headers`, and clones retain the same provenance. Everything else
+ * passes through bound to the real Response.
  */
 export function wrapResponse(res, sourceSeq) {
     const tag = { sourceSeq, path: [] };
+    let headers;
+    let body;
     const carrierProps = new Set([
         "status",
         "ok",
@@ -453,8 +592,9 @@ export function wrapResponse(res, sourceSeq) {
         "url",
         "redirected",
         "type",
+        "bodyUsed",
     ]);
-    const bodyMethods = new Set(["json", "text"]);
+    const bodyMethods = new Set(["json", "text", "bytes", "arrayBuffer", "blob", "formData"]);
     const handler = {
         get(target, prop) {
             if (prop === OP_TAG)
@@ -466,6 +606,15 @@ export function wrapResponse(res, sourceSeq) {
                 return () => readRaw(target);
             if (prop === "then")
                 return undefined;
+            if (prop === "headers")
+                return headers ??= wrapHeaders(target.headers, sourceSeq);
+            if (prop === "body") {
+                if (target.body === null)
+                    return wrapChild(null, sourceSeq, ["body"]);
+                return body ??= wrapStream(target.body, sourceSeq, ["body"]);
+            }
+            if (prop === "clone")
+                return () => wrapResponse(target.clone(), sourceSeq);
             if (typeof prop === "string" && carrierProps.has(prop)) {
                 const value = target[prop];
                 return wrap(value, sourceSeq, [prop]);
@@ -476,7 +625,7 @@ export function wrapResponse(res, sourceSeq) {
                     return fn;
                 return async (...args) => {
                     const value = await fn.apply(target, args);
-                    return wrap(value, sourceSeq, ["body"]);
+                    return wrapChild(value, sourceSeq, ["body"]);
                 };
             }
             const value = target[prop];

package/package.json

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