@specific.dev/spectest 0.57.0 → 0.59.0

package/dist/browser-coverage.d.ts

@@ -0,0 +1,20 @@
+import type { CDPSession } from "playwright-core";
+export interface BrowserCoverageConfig {
+    /** Which covered service (if any) serves scripts from this host. */
+    serviceForHost(host: string): string | undefined;
+}
+/** Set (or clear, with `null`) at /load. */
+export declare function configureBrowserCoverage(config: BrowserCoverageConfig | null): void;
+export declare function browserCoverageActive(): boolean;
+/** Turn coverage on for a page's CDP session. Idempotent; a no-op when no
+ *  service opted in. */
+export declare function attachBrowserCoverage(cdp: CDPSession): Promise<void>;
+/**
+ * Take the session's counters and fold them into the totals. Concurrent
+ * calls coalesce onto the in-flight one. Errors (a page mid-navigation,
+ * a closed view) are swallowed: the counters then stay in V8 for the next
+ * take, nothing is lost.
+ */
+export declare function harvestBrowserCoverage(cdp: CDPSession): Promise<void>;
+/** One lcov document per service that has any browser coverage. */
+export declare function browserCoverageReports(): Map<string, string>;

package/dist/browser-coverage.js

@@ -0,0 +1,185 @@
+// Browser coverage — the collector.
+//
+// One collector per CDP session (i.e. per page view). `attach` turns on
+// V8 precise coverage and tracks parsed scripts; `harvest` takes the
+// counters (which RESETS them — V8 reports nothing for a script that ran
+// nothing since the last take, so the counts are summed here across
+// takes), maps each script the browser loaded from a covered service back
+// to its original sources through the served source map, and folds the
+// result into a per-service total in module memory — which forks with the
+// daemon, so a child test inherits its ancestors' browser coverage exactly
+// as a container's counters are inherited.
+//
+// Harvest runs before every browser step (a click that navigates
+// cross-site replaces the renderer, and the old counters with it) and at
+// every coverage capture. `browserCoverageReports` renders the totals as
+// one lcov per service for the `case-coverage` bundle.
+//
+// Configured by the daemon at /load with the host → service table; a
+// project with no `coverage: { browser: true }` service never attaches
+// anything, so it costs nothing.
+import { createHash } from "node:crypto";
+import { decodeSourceMap, lcovDocument, mapToOriginal, mergeFileCounts, rangesToLineCounts, } from "./harness/browser-coverage.js";
+import { rawFetch } from "./harness/raw-fetch.js";
+let CONFIG = null;
+/** Set (or clear, with `null`) at /load. */
+export function configureBrowserCoverage(config) {
+    CONFIG = config;
+}
+export function browserCoverageActive() {
+    return CONFIG !== null;
+}
+/** service → file → line → count, summed over every harvest. */
+const TOTALS = new Map();
+const COLLECTORS = new WeakMap();
+/** Decoded maps by URL (or content hash for inline `data:` maps). */
+const SOURCE_MAPS = new Map();
+const SOURCE_MAP_FETCH_TIMEOUT_MS = 10_000;
+/** Turn coverage on for a page's CDP session. Idempotent; a no-op when no
+ *  service opted in. */
+export async function attachBrowserCoverage(cdp) {
+    if (!CONFIG || COLLECTORS.has(cdp))
+        return;
+    const collector = { cdp, scripts: new Map(), inFlight: null };
+    COLLECTORS.set(cdp, collector);
+    cdp.on("Debugger.scriptParsed", (ev) => {
+        if (!ev.url)
+            return;
+        collector.scripts.set(ev.scriptId, {
+            url: ev.url,
+            sourceMapURL: ev.sourceMapURL || undefined,
+        });
+    });
+    await cdp.send("Debugger.enable");
+    await cdp.send("Profiler.enable");
+    await cdp.send("Profiler.startPreciseCoverage", { callCount: true, detailed: true });
+}
+/**
+ * Take the session's counters and fold them into the totals. Concurrent
+ * calls coalesce onto the in-flight one. Errors (a page mid-navigation,
+ * a closed view) are swallowed: the counters then stay in V8 for the next
+ * take, nothing is lost.
+ */
+export async function harvestBrowserCoverage(cdp) {
+    const c = COLLECTORS.get(cdp);
+    if (!c || !CONFIG)
+        return;
+    if (c.inFlight)
+        return c.inFlight;
+    c.inFlight = harvestInner(c, CONFIG).catch(() => { }).finally(() => {
+        c.inFlight = null;
+    });
+    return c.inFlight;
+}
+async function harvestInner(c, config) {
+    const { result } = (await c.cdp.send("Profiler.takePreciseCoverage"));
+    for (const script of result) {
+        const info = c.scripts.get(script.scriptId) ?? (script.url ? { url: script.url } : undefined);
+        if (!info)
+            continue;
+        let url;
+        try {
+            url = new URL(info.url);
+        }
+        catch {
+            continue;
+        }
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            continue;
+        const service = config.serviceForHost(url.hostname);
+        if (!service)
+            continue;
+        if (info.source === undefined) {
+            try {
+                const r = (await c.cdp.send("Debugger.getScriptSource", {
+                    scriptId: script.scriptId,
+                }));
+                info.source = r.scriptSource;
+            }
+            catch {
+                continue; // script gone with its document
+            }
+            c.scripts.set(script.scriptId, info);
+        }
+        const generated = rangesToLineCounts(info.source, script.functions);
+        if (generated.size === 0)
+            continue;
+        if (info.map === undefined)
+            info.map = await sourceMapFor(info, url);
+        const files = info.map
+            ? mapToOriginal(info.map, generated)
+            : new Map([[url.pathname, generated]]);
+        let totals = TOTALS.get(service);
+        if (!totals) {
+            totals = new Map();
+            TOTALS.set(service, totals);
+        }
+        mergeFileCounts(totals, files);
+    }
+}
+/** Resolve, fetch (or inline-decode) and decode a script's source map. */
+async function sourceMapFor(info, scriptUrl) {
+    let ref = info.sourceMapURL;
+    if (!ref && info.source) {
+        const m = /\/\/[#@]\s*sourceMappingURL=(\S+)\s*$/.exec(info.source.slice(-4096));
+        if (m)
+            ref = m[1];
+    }
+    if (!ref)
+        return null;
+    if (ref.startsWith("data:")) {
+        const key = "data:" + createHash("sha1").update(ref).digest("hex");
+        const cached = SOURCE_MAPS.get(key);
+        if (cached !== undefined)
+            return cached;
+        const map = decodeSourceMap(parseDataUrl(ref));
+        SOURCE_MAPS.set(key, map);
+        return map;
+    }
+    let mapUrl;
+    try {
+        mapUrl = new URL(ref, scriptUrl).toString();
+    }
+    catch {
+        return null;
+    }
+    const cached = SOURCE_MAPS.get(mapUrl);
+    if (cached !== undefined)
+        return cached;
+    let map = null;
+    try {
+        const res = await rawFetch(mapUrl, { signal: AbortSignal.timeout(SOURCE_MAP_FETCH_TIMEOUT_MS) });
+        if (res.ok)
+            map = decodeSourceMap(await res.json());
+    }
+    catch {
+        map = null;
+    }
+    SOURCE_MAPS.set(mapUrl, map);
+    return map;
+}
+function parseDataUrl(ref) {
+    const comma = ref.indexOf(",");
+    if (comma < 0)
+        return null;
+    const meta = ref.slice(5, comma);
+    const payload = ref.slice(comma + 1);
+    try {
+        const text = /;base64$/i.test(meta)
+            ? Buffer.from(payload, "base64").toString("utf8")
+            : decodeURIComponent(payload);
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+/** One lcov document per service that has any browser coverage. */
+export function browserCoverageReports() {
+    const out = new Map();
+    for (const [service, files] of TOTALS) {
+        if (files.size > 0)
+            out.set(service, lcovDocument(files));
+    }
+    return out;
+}

package/dist/browser.js

@@ -35,6 +35,7 @@ import { generateId } from "./ids.js";
 import { recordBrowser, reserveBackdated, reserveEvent, truncateUtf8 } from "./recorder.js";
 import { wrap } from "./inspect.js";
 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";
 /** Decoded byte count of a base64 string, without decoding it. */
@@ -792,6 +793,14 @@ async function spawnPage(context) {
             console.warn("[spectest] failed to install rrweb recorder:", err);
         }
     }
+    // Frontend coverage (opt-in): turn on V8 precise coverage for this page.
+    // A no-op unless a service declared `coverage: { browser: true }`.
+    try {
+        await attachBrowserCoverage(cdp);
+    }
+    catch {
+        /* coverage is best-effort; a page without it still works */
+    }
     return { page, cdp, recordingInstalled };
 }
 /** Create a default-desktop view (plus its context) for the pool. */
@@ -1080,6 +1089,14 @@ async function rebuildView(holder) {
     catch {
         /* page may already be gone */
     }
+    // The old renderer's coverage counters die with its page; harvest what
+    // it had before the swap (rebuild is triggered on a fresh navigation).
+    try {
+        await harvestBrowserCoverage(holder.cdp);
+    }
+    catch {
+        /* best-effort */
+    }
     const fresh = await spawnPage(holder.context);
     holder.page = fresh.page;
     holder.cdp = fresh.cdp;
@@ -1164,6 +1181,17 @@ function buildBackend(holder, recorder, buildOpts) {
                 durationMs: endT - t,
             }, resv);
             await drain(action);
+            // Fold this page's V8 counters into the per-service totals now — a
+            // navigation to another origin replaces the renderer and its
+            // counters, so harvesting per op is what keeps them.
+            if (browserCoverageActive()) {
+                try {
+                    await harvestBrowserCoverage(holder.cdp);
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
             // Reads (`opts.wrap`) return user-visible JS values someone is likely to
             // assert on — provenance-wrap so `expect(...)` nests under this step.
             // Actions return void/internals; leave them raw to avoid Proxy surprises.
@@ -1193,6 +1221,14 @@ function buildBackend(holder, recorder, buildOpts) {
             return;
         // Final drain before we stop writing to this recorder.
         await drain("close");
+        if (browserCoverageActive()) {
+            try {
+                await harvestBrowserCoverage(holder.cdp);
+            }
+            catch {
+                /* best-effort */
+            }
+        }
         recordingEnded = true;
     }
     const strategy = holder.device ? mobileStrategy : desktopStrategy;

package/dist/coverage.d.ts

@@ -0,0 +1,124 @@
+import type { ServiceConfig } from "./index.js";
+import { COVERAGE_CONTAINER_DIR } from "./harness/coverage.js";
+export { COVERAGE_CONTAINER_DIR };
+/** Where `node()` mounts its hook inside the container. */
+export declare const NODE_COVERAGE_HOOK_PATH = "/spectest/coverage-hook.cjs";
+/** The socket the node hook answers on, relative to the coverage dir. */
+export declare const NODE_COVERAGE_SOCKET = ".ctl";
+/** What `configure` learns about the service it rewrites. */
+export interface CoverageConfigureInfo {
+    /** The services-map key. */
+    key: string;
+}
+/** The harness capabilities an adapter can ask for at `/load`. */
+export interface CoverageLoadContext {
+    /** The services-map key. */
+    service: string;
+    /**
+     * Collect V8 coverage for every script the guest browser
+     * (`ctx.browser()` / `ctx.mobile()`) loads from this service's origins:
+     * its key, `<key>.internal`, its `hostnames`/`dnsName` aliases, its
+     * `tls`/`proxy` hostnames and any service-targeted wildcard. The
+     * harness maps each script back to source through the served source
+     * map and keeps per-service totals in memory (they fork with the
+     * environment). `browser()` calls this and writes the totals
+     * at capture.
+     */
+    collectBrowserScripts(): void;
+}
+/** What one adapter's `capture` runs against. */
+export interface CoverageCaptureContext {
+    /** The services-map key. */
+    service: string;
+    /**
+     * The coverage directory, seen from the harness. It is the same
+     * directory the container sees at `/spectest/coverage/` (a bind
+     * mount), so a file written here is in the container and a socket the
+     * container bound here is reachable.
+     */
+    reportDir: string;
+    /** Run a shell command (`sh -c`) inside the container. Rejects on a
+     *  non-zero exit with the command's output in the message. */
+    exec(command: string): Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+    /** Write one report file (name relative to the directory). */
+    writeReport(name: string, content: string): Promise<void>;
+    /** Aborts when the per-service capture budget runs out. */
+    signal: AbortSignal;
+}
+export interface CoverageAdapter {
+    /** Names the adapter in errors (`coverage adapter "node" on service …`). */
+    name: string;
+    /**
+     * Rewrite the service at config time. Must be pure and deterministic
+     * (the result is hashed into the warm-template key) and must **append**
+     * to `env` values like `NODE_OPTIONS` rather than replace them.
+     */
+    configure?(service: ServiceConfig, info: CoverageConfigureInfo): ServiceConfig;
+    /** Ask the harness for capabilities, at `/load`. */
+    load?(ctx: CoverageLoadContext): void | Promise<void>;
+    /** Make the report appear in the directory. A throw fails the test. */
+    capture?(ctx: CoverageCaptureContext): void | Promise<void>;
+}
+/** `ServiceConfig.coverage`: the program writes its own reports, or a
+ *  list of adapters gets them out. */
+export type ServiceCoverage = true | {
+    adapters: readonly CoverageAdapter[];
+};
+/** Type an inline adapter. Identity at runtime. */
+export declare function defineAdapter(adapter: CoverageAdapter): CoverageAdapter;
+/** Check one service's `coverage` field. Exported so the daemon applies
+ *  the same rule to a runtime `startService` spec. */
+export declare function validateCoverage(service: string, cov: unknown): void;
+/** The adapters of a `coverage` value (`true` has none). */
+export declare function coverageAdapters(cov: ServiceCoverage | undefined): readonly CoverageAdapter[];
+/**
+ * Apply every adapter's `configure` to a service, in list order. Called by
+ * `defineEnvironment` (after group expansion, before validation) and by
+ * the daemon for a runtime `startService` spec. The adapter list stays on
+ * the returned config for the harness; on the wire it serializes as the
+ * adapter names (`toJSON`), never as functions.
+ */
+export declare function applyCoverageAdapters<S extends ServiceConfig>(key: string, svc: S): S;
+/** `env` with `value` appended to `name` (space-separated), or set. */
+export declare function appendEnvFlag(env: Readonly<Record<string, string>> | undefined, name: string, value: string): Record<string, string>;
+/**
+ * The hook `node()` mounts and `--require`s into every node
+ * process of the container. Node writes V8 coverage JSON into
+ * `NODE_V8_COVERAGE` when a process exits; a long-lived server never
+ * exits, so the hook binds a Unix socket in the coverage directory and
+ * calls `v8.takeCoverage()` for each connection. The first process to
+ * start owns the socket (a stale socket left by a dead process is
+ * reclaimed); a later process — a CLI run by `ctx.exec` — leaves it
+ * alone and writes at its own exit. No signal is used: signals are
+ * claimed by frameworks (SIGUSR2 stops a Temporal worker, restarts
+ * nodemon), a socket is nobody's.
+ */
+export declare const NODE_COVERAGE_HOOK: string;
+/**
+ * Coverage for a Node service. Sets `NODE_V8_COVERAGE` to the coverage
+ * directory (every node process in the container then writes V8
+ * coverage JSON when it exits) and `--require`s a hook that lets spectest
+ * ask the long-lived server process for a dump at capture time. Nothing
+ * for the app to write. Source maps: with `--enable-source-maps` (or a
+ * `sourceMappingURL` next to the file) Node records the map in the
+ * report, which is what maps a TypeScript service back to its sources.
+ */
+export declare function node(): CoverageAdapter;
+/**
+ * Coverage for the frontend a service serves. The code runs in the guest
+ * browser — spectest's own process — so no report can be written by the
+ * container; spectest collects V8 coverage for every script the browser
+ * loads from this service's origins, maps it back to source through the
+ * served source map, and writes one lcov per capture. Nothing ran yet on
+ * this branch ⇒ an lcov with no records, which is a report saying so.
+ */
+export declare function browser(): CoverageAdapter;
+/**
+ * Run `command` (via `sh -c`) in the container at every capture, so the
+ * service writes a fresh report into `/spectest/coverage/`. The escape
+ * hatch for a runtime with no shipped adapter.
+ */
+export declare function command(command: string): CoverageAdapter;

package/dist/coverage.js

@@ -0,0 +1,236 @@
+// Coverage adapters — how spectest gets a coverage report out of a service.
+//
+// A service opts in with `coverage: true` (the program writes its own
+// reports into `/spectest/coverage/`) or `coverage: { adapters: [...] }`
+// (spectest gets the reports out). An adapter has three optional moments:
+//
+//   configure  — config time, inside `defineEnvironment`. Rewrites the
+//                service (env, files, command). Pure: its output is part
+//                of the wire config and of the warm-template hash.
+//   load       — harness, at /load. Asks the harness for capabilities a
+//                container cannot supply itself (browser scripts).
+//   capture    — harness, after bring-up and after every test. Must leave
+//                a report in the directory.
+//
+// After every adapter ran, the harness reads the directory the same way
+// it does for `coverage: true`: at least one well-formed report (lcov or
+// V8 JSON), shipped verbatim. Adapters convert nothing — the control
+// plane derives what it needs from the stored bytes.
+//
+// Imported from `@specific.dev/spectest/coverage`. The three shipped
+// adapters: `node()` (V8 JSON through a hook spectest mounts), `browser()`
+// (scripts the guest browser loads from the service), `command(cmd)` (run
+// a command, then read). A project writes its own with `defineAdapter`.
+//
+//   import * as coverage from "@specific.dev/spectest/coverage";
+//   coverage: { adapters: [coverage.node(), coverage.browser()] }
+import { browserCoverageReports } from "./browser-coverage.js";
+import { COVERAGE_CONTAINER_DIR } from "./harness/coverage.js";
+export { COVERAGE_CONTAINER_DIR };
+/** Where `node()` mounts its hook inside the container. */
+export const NODE_COVERAGE_HOOK_PATH = "/spectest/coverage-hook.cjs";
+/** The socket the node hook answers on, relative to the coverage dir. */
+export const NODE_COVERAGE_SOCKET = ".ctl";
+/** Type an inline adapter. Identity at runtime. */
+export function defineAdapter(adapter) {
+    return adapter;
+}
+/** Check one service's `coverage` field. Exported so the daemon applies
+ *  the same rule to a runtime `startService` spec. */
+export function validateCoverage(service, cov) {
+    if (cov === undefined || cov === true)
+        return;
+    const adapters = cov?.adapters;
+    if (typeof cov === "object" && cov !== null && Array.isArray(adapters)) {
+        for (const a of adapters) {
+            const ok = typeof a === "object" &&
+                a !== null &&
+                typeof a.name === "string" &&
+                a.name.length > 0 &&
+                ["configure", "load", "capture"].every((k) => a[k] === undefined ||
+                    typeof a[k] === "function");
+            if (!ok) {
+                throw new Error(`service "${service}" has an invalid coverage adapter — an adapter is \`{ name, configure?, load?, capture? }\` (see \`defineAdapter\` in @specific.dev/spectest/coverage)`);
+            }
+        }
+        return;
+    }
+    throw new Error(`service "${service}" has an invalid \`coverage\` value — use \`true\` (the program writes its own reports) or \`{ adapters: [...] }\` from @specific.dev/spectest/coverage (\`node()\`, \`browser()\`, \`command("…")\`)`);
+}
+/** The adapters of a `coverage` value (`true` has none). */
+export function coverageAdapters(cov) {
+    return typeof cov === "object" && cov !== null ? cov.adapters : [];
+}
+/**
+ * Apply every adapter's `configure` to a service, in list order. Called by
+ * `defineEnvironment` (after group expansion, before validation) and by
+ * the daemon for a runtime `startService` spec. The adapter list stays on
+ * the returned config for the harness; on the wire it serializes as the
+ * adapter names (`toJSON`), never as functions.
+ */
+export function applyCoverageAdapters(key, svc) {
+    validateCoverage(key, svc.coverage);
+    const adapters = coverageAdapters(svc.coverage);
+    if (adapters.length === 0)
+        return svc;
+    let out = svc;
+    for (const a of adapters) {
+        if (a.configure)
+            out = a.configure(out, { key });
+    }
+    const wire = { adapters: adapters.map((a) => withWireName(a)) };
+    return { ...out, coverage: wire };
+}
+function withWireName(a) {
+    if (Object.prototype.hasOwnProperty.call(a, "toJSON"))
+        return a;
+    return Object.assign(Object.create(Object.getPrototypeOf(a)), a, {
+        toJSON: () => ({ adapter: a.name }),
+    });
+}
+/** `env` with `value` appended to `name` (space-separated), or set. */
+export function appendEnvFlag(env, name, value) {
+    const prior = env?.[name]?.trim();
+    return { ...env, [name]: prior ? `${prior} ${value}` : value };
+}
+// ── node ──────────────────────────────────────────────────────────
+/**
+ * The hook `node()` mounts and `--require`s into every node
+ * process of the container. Node writes V8 coverage JSON into
+ * `NODE_V8_COVERAGE` when a process exits; a long-lived server never
+ * exits, so the hook binds a Unix socket in the coverage directory and
+ * calls `v8.takeCoverage()` for each connection. The first process to
+ * start owns the socket (a stale socket left by a dead process is
+ * reclaimed); a later process — a CLI run by `ctx.exec` — leaves it
+ * alone and writes at its own exit. No signal is used: signals are
+ * claimed by frameworks (SIGUSR2 stops a Temporal worker, restarts
+ * nodemon), a socket is nobody's.
+ */
+export const NODE_COVERAGE_HOOK = `"use strict";
+// spectest coverage hook (coverage.node() adapter). See \`spectest docs /services/coverage\`.
+if (process.env.NODE_V8_COVERAGE) {
+  const net = require("node:net");
+  const fs = require("node:fs");
+  const v8 = require("node:v8");
+  const SOCK = require("node:path").join(process.env.NODE_V8_COVERAGE, ${JSON.stringify(NODE_COVERAGE_SOCKET)});
+  const server = net.createServer((conn) => {
+    // A dump is taken only on an explicit "dump" request: a bystander's
+    // liveness probe connects and closes without one.
+    let buf = "";
+    conn.on("data", (chunk) => {
+      buf += chunk;
+      if (!buf.includes("\\n")) return;
+      let reply;
+      try {
+        if (!buf.startsWith("dump")) throw new Error("unknown request");
+        v8.takeCoverage();
+        reply = "ok\\n";
+      } catch (err) {
+        reply = "error " + (err && err.message ? err.message : String(err)) + "\\n";
+      }
+      conn.end(reply);
+    });
+  });
+  server.unref();
+  server.on("error", (err) => {
+    if (err.code !== "EADDRINUSE") return;
+    // Someone holds the socket. If it answers, it is the live server and
+    // this process is a bystander; if not, it is a stale file.
+    const probe = net.connect(SOCK);
+    probe.on("connect", () => probe.destroy());
+    probe.on("error", () => {
+      try { fs.unlinkSync(SOCK); } catch {}
+      server.listen(SOCK);
+    });
+  });
+  server.listen(SOCK);
+}
+`;
+/**
+ * Coverage for a Node service. Sets `NODE_V8_COVERAGE` to the coverage
+ * directory (every node process in the container then writes V8
+ * coverage JSON when it exits) and `--require`s a hook that lets spectest
+ * ask the long-lived server process for a dump at capture time. Nothing
+ * for the app to write. Source maps: with `--enable-source-maps` (or a
+ * `sourceMappingURL` next to the file) Node records the map in the
+ * report, which is what maps a TypeScript service back to its sources.
+ */
+export function node() {
+    return {
+        name: "node",
+        configure(svc) {
+            const env = appendEnvFlag(svc.env, "NODE_OPTIONS", `--require ${NODE_COVERAGE_HOOK_PATH}`);
+            env.NODE_V8_COVERAGE = COVERAGE_CONTAINER_DIR;
+            return {
+                ...svc,
+                env,
+                files: [...(svc.files ?? []), { path: NODE_COVERAGE_HOOK_PATH, content: NODE_COVERAGE_HOOK }],
+            };
+        },
+        async capture(ctx) {
+            const { connect } = await import("node:net");
+            const path = await import("node:path");
+            const sock = path.join(ctx.reportDir, NODE_COVERAGE_SOCKET);
+            const reply = await new Promise((resolve, reject) => {
+                const chunks = [];
+                const c = connect(sock, () => c.write("dump\n"));
+                const onAbort = () => {
+                    c.destroy();
+                    reject(new Error("timed out waiting for the node hook to write a report"));
+                };
+                ctx.signal.addEventListener("abort", onAbort, { once: true });
+                c.on("data", (b) => chunks.push(b));
+                c.on("error", (err) => {
+                    ctx.signal.removeEventListener("abort", onAbort);
+                    reject(new Error(err.code === "ENOENT" || err.code === "ECONNREFUSED"
+                        ? `no node process is serving ${COVERAGE_CONTAINER_DIR}/${NODE_COVERAGE_SOCKET} — is the service's main process node, and does it run with the service's env (NODE_OPTIONS)?`
+                        : err.message));
+                });
+                c.on("close", () => {
+                    ctx.signal.removeEventListener("abort", onAbort);
+                    resolve(Buffer.concat(chunks).toString("utf8").trim());
+                });
+            });
+            if (reply !== "ok")
+                throw new Error(`the node hook answered: ${reply || "(nothing)"}`);
+        },
+    };
+}
+// ── browser ───────────────────────────────────────────────────────
+/**
+ * Coverage for the frontend a service serves. The code runs in the guest
+ * browser — spectest's own process — so no report can be written by the
+ * container; spectest collects V8 coverage for every script the browser
+ * loads from this service's origins, maps it back to source through the
+ * served source map, and writes one lcov per capture. Nothing ran yet on
+ * this branch ⇒ an lcov with no records, which is a report saying so.
+ */
+export function browser() {
+    return {
+        name: "browser",
+        load(ctx) {
+            ctx.collectBrowserScripts();
+        },
+        async capture(ctx) {
+            const lcov = browserCoverageReports().get(ctx.service) ?? "TN:\n";
+            await ctx.writeReport("browser.lcov", lcov);
+        },
+    };
+}
+// ── command ───────────────────────────────────────────────────────
+/**
+ * Run `command` (via `sh -c`) in the container at every capture, so the
+ * service writes a fresh report into `/spectest/coverage/`. The escape
+ * hatch for a runtime with no shipped adapter.
+ */
+export function command(command) {
+    if (typeof command !== "string" || command.trim().length === 0) {
+        throw new Error("coverage.command: `command` must be a non-empty shell command");
+    }
+    return {
+        name: "command",
+        async capture(ctx) {
+            await ctx.exec(command);
+        },
+    };
+}