@specific.dev/spectest 0.19.1 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.19.1",
+  "version": "0.21.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./src/index.ts",

package/src/browser.ts

@@ -33,6 +33,7 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { generateId } from "./ids.js";
 import { recordBrowser, reserveEvent, truncateUtf8 } from "./recorder.js";
 import { wrap } from "./inspect.js";
 import type { Wrapped } from "./inspect.js";
@@ -76,13 +77,12 @@ export interface BrowserOptions {
   recorder?: BrowserSessionRecorder | null;
 }
 
-export type ScreenshotFormat = "png" | "jpeg" | "webp";
-
-export interface ScreenshotOptions {
-  /** Image format. WebP requires Chrome. Default PNG. */
-  format?: ScreenshotFormat;
-  /** JPEG/WebP quality 0–100. Ignored for PNG. */
-  quality?: number;
+/** Decoded byte count of a base64 string, without decoding it. */
+function base64ByteLength(b64: string): number {
+  let padding = 0;
+  if (b64.endsWith("==")) padding = 2;
+  else if (b64.endsWith("=")) padding = 1;
+  return (b64.length * 3) / 4 - padding;
 }
 
 /** One Browser-action's worth of rrweb events, in the order rrweb emitted them. */
@@ -114,6 +114,20 @@ export interface BrowserSessionRecorder {
   recordStep(step: BrowserSessionStep): void;
   /** Optional: called whenever `Browser.navigate(url)` is invoked. */
   noteNavigation?(url: string): void;
+  /**
+   * Optional: register a captured artifact (screenshot bytes) for upload.
+   * Present only in eval context — the daemon wires it to the per-eval
+   * collector, and its absence is what makes `screenshot()` throw during
+   * test runs (artifacts are eval-only for now). Throws when the eval's
+   * artifact byte budget is exhausted.
+   */
+  registerArtifact?(artifact: {
+    id: string;
+    kind: "screenshot";
+    contentType: string;
+    sizeBytes: number;
+    bytesBase64: string;
+  }): void;
 }
 
 /**
@@ -200,8 +214,14 @@ export interface Browser {
   forward(): Promise<void>;
   /** Reload the current page. */
   reload(): Promise<void>;
-  /** Capture a PNG/JPEG/WebP screenshot of the viewport. Returns raw bytes. */
-  screenshot(options?: ScreenshotOptions): Promise<Uint8Array>;
+  /**
+   * Capture a PNG screenshot of the viewport and upload it as a
+   * downloadable **artifact**. Resolves to the artifact's `art_…` id —
+   * fetch the image locally with `spectest artifact download <id>`.
+   * Only available inside an eval (`spectest_eval` / `spectest env eval`);
+   * throws with a clear message during test runs.
+   */
+  screenshot(): Promise<string>;
   /**
    * Destroy the underlying view. Idempotent; drains any pending rrweb
    * events first. For the persistent session behind `ctx.browser()` /
@@ -1521,16 +1541,39 @@ function buildBackend(
         await holder.page.reload();
       });
     },
-    async screenshot(options) {
-      const format = options?.format ?? "png";
-      return instrumented("screenshot", { format }, async () => {
-        // Raw CDP rather than page.screenshot(): CDP supports webp too, and
-        // captures the viewport exactly like the pre-Playwright backend.
+    async screenshot() {
+      const fields: Partial<RecordableFields> = { format: "png" };
+      return instrumented("screenshot", fields, async () => {
+        // Artifacts are eval-only for now: the daemon wires a
+        // registerArtifact sink onto eval sessions' recorders and nothing
+        // else's, so its absence means "test run / recorder-less browser".
+        const register = recorder?.registerArtifact;
+        if (!register) {
+          throw new Error(
+            "screenshot() uploads the capture as a downloadable artifact and is " +
+              "currently only available inside an eval (spectest_eval / `spectest env eval`) — " +
+              "it cannot be used in test runs.",
+          );
+        }
+        // Raw CDP rather than page.screenshot(): captures the viewport
+        // exactly like the pre-Playwright backend.
         const res = (await holder.cdp.send("Page.captureScreenshot", {
-          format,
-          ...(format === "png" ? {} : { quality: options?.quality ?? 90 }),
+          format: "png",
         } as never)) as { data: string };
-        return new Uint8Array(Buffer.from(res.data, "base64"));
+        const id = generateId("art");
+        register({
+          id,
+          kind: "screenshot",
+          contentType: "image/png",
+          // CDP already hands us base64 — pass it through un-recoded and
+          // derive the raw byte count from the encoding.
+          sizeBytes: base64ByteLength(res.data),
+          bytesBase64: res.data,
+        });
+        // Stamped onto the browser event before instrumented() records it —
+        // same mutate-fields-inside-fn() precedent as waitFor's `attempts`.
+        fields.artifactId = id;
+        return id;
       });
     },
     async close() {
@@ -1627,6 +1670,7 @@ interface RecordableFields {
   dy: number;
   x: number;
   y: number;
-  format: ScreenshotFormat;
+  format: string;
   attempts: number;
+  artifactId: string;
 }

package/src/components/replayFake.ts

@@ -519,10 +519,9 @@ function resolveExternalA(host: string): Promise<string[]> {
     sock.on("message", (msg) => {
       try {
         const res = dnsPacket.decode(msg);
-        const ips = (res.answers ?? [])
-          .filter((a) => a.type === "A")
-          .map((a) => a.data as string)
-          .filter((d) => typeof d === "string" && d.length > 0);
+        const ips = (res.answers ?? []).flatMap((a) =>
+          a.type === "A" && typeof a.data === "string" && a.data.length > 0 ? [a.data] : [],
+        );
         finish(ips);
       } catch {
         finish([]);
@@ -766,7 +765,7 @@ export function replayFake(
     state.recorded.push(interaction);
     state.dirty = true;
 
-    return new Response(upstream.bytes, {
+    return new Response(upstream.bytes as unknown as BodyInit, {
       status: upstream.status,
       headers: new Headers(respHeaders),
     });

package/src/daemon.ts

@@ -57,6 +57,7 @@ import {
 import { wrap, wrapResponse } from "./inspect.js";
 import type { SpectestFetch, Wrapped, WrappedResponse } from "./inspect.js";
 import { clearRecordSecrets, setRecordSecrets } from "./record-secrets.js";
+import { encodeReplayBundle, replayChunk } from "./replay-bundle.js";
 
 import type {
   Browser,
@@ -750,7 +751,7 @@ const BUILD_DEDUP = new Map<
   { name: string; promise: Promise<{ tag: string; buildSteps?: BuildStep[] }> }
 >();
 
-function buildContentKey(image: { content: string; exclude?: string[] }): string {
+function buildContentKey(image: { content: string; exclude?: readonly string[] }): string {
   return new Bun.CryptoHasher("sha256")
     .update(image.content)
     .update("\0")
@@ -836,7 +837,7 @@ async function prepareServiceImage(
 
 async function buildServiceImage(
   name: string,
-  image: { content: string; exclude?: string[] },
+  image: { content: string; exclude?: readonly string[] },
   tag: string,
 ): Promise<{ tag: string; buildSteps?: BuildStep[] }> {
   let buildSteps: BuildStep[] | undefined;
@@ -2802,6 +2803,38 @@ interface RunResult {
   error?: { message: string; stack?: string };
 }
 
+// ────────────────────────────────────────────────────────────────────────
+// Replay bundles (rrweb sessions → gzipped side-channel, pulled in chunks)
+// ────────────────────────────────────────────────────────────────────────
+//
+// `RunResult.browserSessions` never rides the `/run` reply: the vm-agent
+// caps proxied daemon responses at 16 MB and a browser-heavy case's
+// recording is tens of MB of JSON (see replay-bundle.ts for the whole
+// story). Instead the /run handler encodes the sessions into a gzipped,
+// asset-deduplicated bundle, parks it here keyed by case id, and replies
+// with a tiny `replay: { bytes }` ref; the control plane then pulls the
+// bundle via `POST /replay-chunk` in base64 chunks sized under the cap,
+// before it tears the fork down.
+//
+// The map is module memory, so it FORKS with the snapshot (the post-test
+// snapshot is captured before the control plane fetches). The size cap
+// keeps a long handoff chain from accreting every ancestor's (gzipped)
+// bundle in guest RAM — entries older than the last few are always
+// already-fetched leftovers frozen into some snapshot.
+const REPLAY_BUNDLES = new Map<string, Buffer>();
+const REPLAY_BUNDLES_MAX = 8;
+
+function stashReplayBundle(caseId: string, gz: Buffer): void {
+  // Re-insert to refresh recency (Map iterates in insertion order).
+  REPLAY_BUNDLES.delete(caseId);
+  REPLAY_BUNDLES.set(caseId, gz);
+  while (REPLAY_BUNDLES.size > REPLAY_BUNDLES_MAX) {
+    const oldest = REPLAY_BUNDLES.keys().next().value;
+    if (oldest === undefined) break;
+    REPLAY_BUNDLES.delete(oldest);
+  }
+}
+
 // ────────────────────────────────────────────────────────────────────────
 // Cumulative service logs (per-case deltas → S3, reconstructed on the web)
 // ────────────────────────────────────────────────────────────────────────
@@ -2846,6 +2879,32 @@ interface ServiceLogDelta {
   stderr: string;
   stderrTruncated: boolean;
   stderrReset: boolean;
+  /** The container was no longer running ("exited"/"dead") when this delta
+   *  was captured. Absent while running or when inspect fails (e.g. the
+   *  container was removed). Shown next to the service on the dashboard's
+   *  Logs page. */
+  stopped?: boolean;
+  /** docker's recorded exit code for the stopped container. */
+  exitCode?: number;
+}
+
+/**
+ * Inspect a container's run state for {@link ServiceLogDelta}: `{}` while
+ * running (or when inspect fails — a removed container has no state left to
+ * report), `{ stopped, exitCode }` once it has exited/died.
+ */
+async function containerStopState(
+  name: string,
+): Promise<{ stopped?: boolean; exitCode?: number }> {
+  const r = await docker(
+    ["inspect", "-f", "{{.State.Status}} {{.State.ExitCode}}", name],
+    15_000,
+  );
+  if (r.code !== 0) return {};
+  const [status, codeStr] = r.stdout.trim().split(/\s+/);
+  if (status !== "exited" && status !== "dead") return {};
+  const exitCode = Number.parseInt(codeStr ?? "", 10);
+  return Number.isFinite(exitCode) ? { stopped: true, exitCode } : { stopped: true };
 }
 
 /** Keep the head and tail of `s`, eliding the middle when it exceeds
@@ -2924,7 +2983,10 @@ async function captureServiceLogDeltas(): Promise<ServiceLogDelta[]> {
   const services = [...byName.values()];
   return Promise.all(
     services.map(async (svc): Promise<ServiceLogDelta> => {
-      const r = await docker(["logs", "--timestamps", svc.name], 30_000);
+      const [r, stop] = await Promise.all([
+        docker(["logs", "--timestamps", svc.name], 30_000),
+        containerStopState(svc.name),
+      ]);
       if (r.code !== 0) {
         // Container gone/renamed — surface the CLI error, leave markers put.
         const err = capMiddle(r.stderr || r.stdout, LOG_DELTA_MAX_BYTES);
@@ -2936,6 +2998,7 @@ async function captureServiceLogDeltas(): Promise<ServiceLogDelta[]> {
           stderr: err.value,
           stderrTruncated: err.truncated,
           stderrReset: false,
+          ...stop,
         };
       }
       const outKey = `${svc.name}stdout`;
@@ -2952,6 +3015,7 @@ async function captureServiceLogDeltas(): Promise<ServiceLogDelta[]> {
         stderr: err.delta,
         stderrTruncated: err.truncated,
         stderrReset: err.reset,
+        ...stop,
       };
     }),
   );
@@ -2994,15 +3058,71 @@ function newSessionId(idScope: string): string {
   return idScope ? `${idScope}:${randomUUID()}` : randomUUID();
 }
 
+/**
+ * One artifact captured during an eval (screenshot bytes), shipped inline
+ * (base64) on the `/eval` reply's `artifacts` array — parallel to
+ * `browserSessions`. The control plane uploads each to S3, records the
+ * metadata row, and strips `bytesBase64` before the reply reaches the
+ * caller. The id is minted in-VM by `ids.ts` (see its fork-frozen-RNG
+ * caveat) in the control plane's `art_0…` format.
+ */
+interface CapturedArtifact {
+  id: string;
+  kind: "screenshot";
+  contentType: string;
+  sizeBytes: number;
+  bytesBase64: string;
+}
+
+/**
+ * Cumulative raw-byte cap on one eval's artifacts. The bytes ride the
+ * `/eval` JSON reply base64'd (~1.33x), and the vm-agent hard-errors on
+ * proxied daemon responses over 16 MB (the same cap that pushed /run's
+ * replay bundles out-of-band — see REPLAY_BUNDLES). 8 MiB raw ≈ 10.7 MB
+ * encoded leaves headroom for the reply's sessions/log; screenshots are
+ * typically well under 2 MiB each. If artifacts ever need to grow past
+ * this, move them to the parked-chunk side channel instead of raising it.
+ */
+const MAX_EVAL_ARTIFACT_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Per-eval artifact sink. `register` throws (failing the screenshot() call,
+ * never the eval) once the byte budget is exhausted.
+ */
+function newArtifactCollector(): {
+  artifacts: CapturedArtifact[];
+  register(artifact: CapturedArtifact): void;
+} {
+  const artifacts: CapturedArtifact[] = [];
+  let total = 0;
+  return {
+    artifacts,
+    register(artifact) {
+      total += artifact.sizeBytes;
+      if (total > MAX_EVAL_ARTIFACT_BYTES) {
+        throw new Error(
+          `artifact byte budget for this eval exceeded (${MAX_EVAL_ARTIFACT_BYTES / (1024 * 1024)} MiB) — ` +
+            "capture fewer screenshots per eval",
+        );
+      }
+      artifacts.push(artifact);
+    },
+  };
+}
+
 /**
  * Build the recorder sink + bookkeeping for a single Browser session.
  * The returned `recorder` is what `openBrowser` writes into; the
  * returned `record` is the in-flight session object the daemon owns.
+ * `artifacts` (eval-only) wires `screenshot()`'s artifact registration —
+ * test-run sessions don't pass it, which is exactly what makes
+ * `screenshot()` throw outside eval.
  */
 function newBrowserSession(
   testStart: number,
   idScope: string,
   frame: "browser" | "mobile" = "browser",
+  artifacts?: ReturnType<typeof newArtifactCollector>,
 ): {
   recorder: BrowserSessionRecorder;
   record: BrowserSessionRecord;
@@ -3027,6 +3147,9 @@ function newBrowserSession(
         if (closed) return;
         if (record.initialUrl === undefined) record.initialUrl = url;
       },
+      ...(artifacts
+        ? { registerArtifact: (a: CapturedArtifact) => artifacts.register(a) }
+        : {}),
     },
     markClosed() {
       if (closed) return;
@@ -4001,6 +4124,9 @@ interface EvalResult {
   browserSessions: BrowserSessionRecord[];
   /** asciicast sessions for any ctx.terminal() call during the eval. */
   terminalSessions: TerminalSessionRecord[];
+  /** Artifacts captured during the eval (screenshot bytes, base64 inline —
+   * stripped by the control plane before the reply reaches the caller). */
+  artifacts: CapturedArtifact[];
   error?: { message: string; stack?: string };
 }
 
@@ -4125,11 +4251,14 @@ async function evalCode(
   // live session — and a snapshot taken afterwards carries it.
   const browserDetaches: Array<() => Promise<void>> = [];
   const sessions: Array<ReturnType<typeof newBrowserSession>> = [];
+  // Eval-only artifact sink — wiring it here (and nowhere in runOne) is
+  // what gates screenshot() to eval context.
+  const artifactCollector = newArtifactCollector();
   let sharedBrowser: Browser | null = null;
   const sharedMobiles = new Map<string, Mobile>();
   const trackedOpenBrowser = async (opts?: BrowserOptions): Promise<Browser> => {
     if (sharedBrowser) return sharedBrowser;
-    const session = newBrowserSession(start, "eval");
+    const session = newBrowserSession(start, "eval", "browser", artifactCollector);
     sessions.push(session);
     const { browser, attached, detach } = await acquirePersistentBrowser({
       ...(opts ?? {}),
@@ -4161,7 +4290,7 @@ async function evalCode(
     }
     const existing = sharedMobiles.get(app.url);
     if (existing) return existing;
-    const session = newBrowserSession(start, "eval", "mobile");
+    const session = newBrowserSession(start, "eval", "mobile", artifactCollector);
     sessions.push(session);
     const { mobile, attached, detach, safeAreaInsets } = await openPersistentMobile({
       url: app.url,
@@ -4310,6 +4439,8 @@ async function evalCode(
       });
     }
   }
+  // `artifacts` ships on the error branch too — a screenshot captured
+  // before a snippet crash is exactly the evidence the caller wants.
   return outcome.ok
     ? {
         ok: true,
@@ -4319,6 +4450,7 @@ async function evalCode(
         result: outcome.result,
         browserSessions: sessions.map((s) => s.record),
         terminalSessions,
+        artifacts: artifactCollector.artifacts,
       }
     : {
         ok: false,
@@ -4327,10 +4459,190 @@ async function evalCode(
         installed,
         browserSessions: sessions.map((s) => s.record),
         terminalSessions,
+        artifacts: artifactCollector.artifacts,
         error: outcome.error,
       };
 }
 
+// ────────────────────────────────────────────────────────────────────────
+// Typecheck
+//
+// `tsc --noEmit` over the user's spectest/ code (APP_DIR — the only tree the
+// daemon imports; app-under-test source has its own toolchain). Kicked off in
+// the background at /load-tests so it never sits on the start/run critical
+// path; the control plane collects the result via POST /typecheck (which
+// awaits the in-flight run) and attaches it to the SuiteResult as an
+// advisory report. It must never gate a run: the runtime accepts patterns
+// the types reject (e.g. bare global `fetch` is monkey-patched to record,
+// but its *type* stays raw), so a type error is a strong hint, not proof.
+//
+// The compiler is the native tsc baked into the base snapshot at
+// /opt/spectest/typecheck (see base.rs BASE_SETUP_SH); a project that ships
+// its own `typescript` in spectest/package.json wins. A project tsconfig.json
+// wins over the generated one the same way.
+// ────────────────────────────────────────────────────────────────────────
+
+const TYPECHECK_DIR = "/opt/spectest/typecheck";
+/** Cap on errors shipped in the report; `totalErrors` carries the true count. */
+const TYPECHECK_ERROR_CAP = 50;
+
+interface TypecheckError {
+  /** Path relative to the project's spectest/ dir (e.g. `tests/checkout.ts`). */
+  file: string;
+  line: number;
+  column: number;
+  /** `TS2345` etc. */
+  code: string;
+  message: string;
+}
+
+interface TypecheckReport {
+  status: "ok" | "errors" | "skipped" | "failed";
+  errors: TypecheckError[];
+  totalErrors: number;
+  durationMs: number;
+  /** Why the check was skipped / how it failed. */
+  detail?: string;
+}
+
+let TYPECHECK: Promise<TypecheckReport> | null = null;
+
+/** Fire-and-forget kickoff; the promise is parked for POST /typecheck. */
+function startTypecheck(): void {
+  TYPECHECK = runTypecheck().catch((err) => ({
+    status: "failed" as const,
+    errors: [],
+    totalErrors: 0,
+    durationMs: 0,
+    detail: err instanceof Error ? err.message : String(err),
+  }));
+  // Parked promises must never surface as unhandled rejections.
+  TYPECHECK.catch(() => {});
+}
+
+/** The tsconfig used when the project doesn't ship its own. `lib` is left to
+ *  the target default (which includes DOM — browser.evaluate callbacks
+ *  reference `document`); `types` pulls Bun's ambient globals from the baked
+ *  install via `typeRoots` (the walk-up from APP_DIR never reaches it). */
+function generatedTsconfig(): string {
+  return JSON.stringify(
+    {
+      compilerOptions: {
+        target: "esnext",
+        module: "esnext",
+        moduleResolution: "bundler",
+        strict: true,
+        noEmit: true,
+        skipLibCheck: true,
+        esModuleInterop: true,
+        resolveJsonModule: true,
+        jsx: "react-jsx",
+        types: ["bun"],
+        typeRoots: [
+          path.join(APP_DIR, "node_modules", "@types"),
+          path.join(TYPECHECK_DIR, "node_modules", "@types"),
+        ],
+      },
+      include: ["**/*.ts", "**/*.tsx"],
+      exclude: ["node_modules"],
+    },
+    null,
+    2,
+  );
+}
+
+/** Parse `--pretty false` tsc output: `file(line,col): error TScode: msg`,
+ *  with indented elaboration lines folded into the preceding error. */
+function parseTscOutput(output: string): {
+  errors: TypecheckError[];
+  total: number;
+  suppressed: number;
+} {
+  const errors: TypecheckError[] = [];
+  let total = 0;
+  let suppressed = 0;
+  let last: TypecheckError | null = null;
+  for (const line of output.split("\n")) {
+    const m = /^(.+?)\((\d+),(\d+)\): error (TS\d+): (.*)$/.exec(line);
+    if (!m) {
+      // Elaboration lines are indented; fold them into the last kept error.
+      if (last && /^\s+\S/.test(line)) last.message += `\n${line.trimEnd()}`;
+      continue;
+    }
+    const [, rawFile, ln, col, code, message] = m;
+    // Keep only diagnostics in the user's files. tsc runs with cwd=APP_DIR
+    // (the daemon's cwd), so project files come out relative ("tests/x.ts")
+    // and anything outside — the SDK at /opt/spectest/sdk, node_modules —
+    // is `../…` or absolute. Errors in our own SDK are ours to fix, not the
+    // user's to read.
+    const abs = path.resolve(APP_DIR, rawFile!);
+    const inApp = abs.startsWith(APP_DIR + path.sep) && !abs.includes(`${path.sep}node_modules${path.sep}`);
+    if (!inApp) {
+      suppressed += 1;
+      last = null;
+      continue;
+    }
+    total += 1;
+    const err: TypecheckError = {
+      file: path.relative(APP_DIR, abs),
+      line: Number(ln),
+      column: Number(col),
+      code: code!,
+      message: message!,
+    };
+    if (errors.length < TYPECHECK_ERROR_CAP) {
+      errors.push(err);
+      last = err;
+    } else {
+      last = null;
+    }
+  }
+  return { errors, total, suppressed };
+}
+
+async function runTypecheck(): Promise<TypecheckReport> {
+  const started = Date.now();
+  // The project's own typescript wins over the baked copy.
+  const tsc = [
+    path.join(APP_DIR, "node_modules", "typescript", "bin", "tsc"),
+    path.join(TYPECHECK_DIR, "node_modules", "typescript", "bin", "tsc"),
+  ].find((p) => existsSync(p));
+  if (!tsc) {
+    return {
+      status: "skipped",
+      errors: [],
+      totalErrors: 0,
+      durationMs: 0,
+      detail: "typescript is not installed (base image predates the baked typechecker)",
+    };
+  }
+  let config = path.join(APP_DIR, "tsconfig.json");
+  if (!existsSync(config)) {
+    config = path.join(APP_DIR, ".spectest-tsconfig.json");
+    await fs.writeFile(config, generatedTsconfig());
+  }
+  const res = await shx(process.execPath, [tsc, "--noEmit", "--pretty", "false", "-p", config], 120_000);
+  const durationMs = Date.now() - started;
+  if (res.code === 124) {
+    return { status: "failed", errors: [], totalErrors: 0, durationMs, detail: "typecheck timed out" };
+  }
+  const { errors, total, suppressed } = parseTscOutput(res.stdout + res.stderr);
+  if (errors.length === 0) {
+    // Exit 0 → clean. Non-zero with no *user-file* diagnostics is either
+    // all-suppressed (still ok from the user's perspective) or a compiler
+    // crash (config not found, OOM) — surface the latter.
+    if (res.code !== 0 && suppressed === 0) {
+      const tail = (res.stderr || res.stdout).trim().split("\n").slice(-5).join("\n");
+      return { status: "failed", errors: [], totalErrors: 0, durationMs, detail: tail || `tsc exited ${res.code}` };
+    }
+    if (suppressed > 0) {
+      console.warn(`[typecheck] ${suppressed} diagnostic(s) outside the project suppressed`);
+    }
+    return { status: "ok", errors: [], totalErrors: 0, durationMs };
+  }
+  return { status: "errors", errors, totalErrors: total, durationMs };
+}
+
 // ────────────────────────────────────────────────────────────────────────
 // HTTP server
 // ────────────────────────────────────────────────────────────────────────
@@ -4395,6 +4707,11 @@ async function handle(req: http.IncomingMessage, res: http.ServerResponse, state
     // resulting catalogue. Called after the warm snapshot (cold path) or
     // against a freshly restored VM (warm path).
     await loadTests();
+    // Background typecheck of the freshly-uploaded app tree — both paths
+    // (cold and warm) funnel through here after the upload, so the check
+    // always sees the current code. Never on the critical path: the reply
+    // doesn't wait, POST /typecheck collects.
+    startTypecheck();
     const l = requireLoaded();
     jsonResponse(res, 200, {
       environment: l.project.environment,
@@ -4404,6 +4721,15 @@ async function handle(req: http.IncomingMessage, res: http.ServerResponse, state
     return;
   }
 
+  if (method === "POST" && url === "/typecheck") {
+    // Await the run kicked off at /load-tests (or start one on demand —
+    // e.g. a legacy single-file project loaded before this daemon shipped
+    // the kickoff, or a direct debug call).
+    if (!TYPECHECK) startTypecheck();
+    jsonResponse(res, 200, await TYPECHECK!);
+    return;
+  }
+
   if (method === "POST" && url === "/unload") {
     loaded = null;
     jsonResponse(res, 200, { unloaded: true });
@@ -4557,13 +4883,55 @@ async function handle(req: http.IncomingMessage, res: http.ServerResponse, state
     state.inFlightTest = exec;
     try {
       const result = await exec;
-      jsonResponse(res, 200, result);
+      // Recordings go out-of-band: encode + park the bundle, reply with a
+      // size ref only (see the REPLAY_BUNDLES comment). A bundle-encoding
+      // failure drops the recordings (warn) rather than failing the case —
+      // and never falls back to inlining, which is exactly the >16 MB
+      // response this path exists to avoid.
+      const { browserSessions, ...wire } = result;
+      let replay: { bytes: number } | undefined;
+      if (browserSessions.length > 0) {
+        try {
+          const gz = encodeReplayBundle(caseId, browserSessions);
+          stashReplayBundle(caseId, gz);
+          replay = { bytes: gz.length };
+        } catch (err) {
+          // eslint-disable-next-line no-console
+          console.warn("[replay] bundle encode failed; dropping recordings:", err);
+        }
+      }
+      jsonResponse(res, 200, { ...wire, replay });
     } finally {
       state.inFlightTest = null;
     }
     return;
   }
 
+  if (method === "POST" && url === "/replay-chunk") {
+    // One chunk of a parked replay bundle (see REPLAY_BUNDLES). POST with
+    // a JSON body — case ids are arbitrary user strings, and a body dodges
+    // URL-encoding across both providers' daemon_http transports.
+    const body = await readBody(req);
+    let parsed: { caseId?: string; offset?: number; limit?: number };
+    try {
+      parsed = JSON.parse(body || "{}");
+    } catch {
+      jsonResponse(res, 400, { error: "invalid JSON body" });
+      return;
+    }
+    if (!parsed.caseId) {
+      jsonResponse(res, 400, { error: "caseId is required" });
+      return;
+    }
+    const gz = REPLAY_BUNDLES.get(parsed.caseId);
+    if (!gz) {
+      jsonResponse(res, 404, { error: `no replay bundle for case: ${parsed.caseId}` });
+      return;
+    }
+    jsonResponse(res, 200, replayChunk(gz, parsed.offset, parsed.limit));
+    return;
+  }
+
   jsonResponse(res, 404, { error: "not found" });
 }
 

package/src/ids.ts

@@ -0,0 +1,89 @@
+// Stripe-style resource ids minted in-VM — format-compatible with the
+// control plane's `crates/control-plane/src/ids.rs` (`generate`):
+// `<prefix>_0<20 chars>` where the chars are Crockford base32 (lowercase,
+// minus the ambiguous i/l/o/u) and the `0` after the underscore is the
+// format-version digit. If the scheme changes there, change it here in
+// lockstep (`env.rs::valid_artifact_id` checks this exact shape at the
+// trust boundary).
+//
+// LANDMINE — why the entropy here is NOT just `crypto.getRandomValues`:
+// Bun serves those from a userspace pool that is FROZEN into snapshots, so
+// sibling forks of one snapshot draw identical bytes (verified 2026-07-14:
+// two forks' first screenshot() minted the same id). We therefore hash
+// together, per mint:
+//   - 16 bytes read straight off /dev/urandom (bypasses Bun's pool; the
+//     guest kernel CRNG reseeds across restores — see the VM-determinism
+//     notes — so forks diverge),
+//   - Date.now() (wall clock is re-synced per post-mortem fork start) and
+//     performance.now() (sub-ms), which de-collide even if the kernel pool
+//     hasn't diverged yet,
+//   - a process-local counter (multiple mints in one tick).
+// This makes duplicates practically impossible, but the control plane
+// still treats an id here as untrusted: shape-validated, and a duplicate
+// insert is flagged per-artifact rather than clobbering anything.
+
+import { createHash } from "node:crypto";
+import { closeSync, openSync, readSync } from "node:fs";
+
+/** Crockford base32, lowercased, minus `i`/`l`/`o`/`u` — mirrors ids.rs. */
+const ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
+
+/** Random base32 chars after the version digit (100 bits of entropy). */
+const RANDOM_LEN = 20;
+
+let mintCounter = 0;
+
+/** Mint a fresh id, e.g. `generateId("art")` → `art_0c3k9mpq…`. */
+export function generateId(prefix: string): string {
+  const digest = createHash("sha256")
+    .update(urandom(16))
+    .update(String(Date.now()))
+    .update(String(performance.now()))
+    .update(String(mintCounter++))
+    .digest();
+  return `${prefix}_0${base32Crockford(digest.subarray(0, 16)).slice(0, RANDOM_LEN)}`;
+}
+
+/** Read `n` bytes directly from /dev/urandom (NOT Bun's cached pool). */
+function urandom(n: number): Uint8Array {
+  const buf = new Uint8Array(n);
+  try {
+    const fd = openSync("/dev/urandom", "r");
+    try {
+      let off = 0;
+      while (off < n) {
+        const read = readSync(fd, buf, off, n - off, null);
+        if (read <= 0) break;
+        off += read;
+      }
+    } finally {
+      closeSync(fd);
+    }
+  } catch {
+    // Non-Linux host (SDK types compiled locally) or exotic failure — the
+    // clock + counter inputs still make the hash unique in practice.
+    crypto.getRandomValues(buf);
+  }
+  return buf;
+}
+
+/** Encode bytes as Crockford base32 (no padding). 16 bytes → 26 chars. */
+function base32Crockford(bytes: Uint8Array): string {
+  let out = "";
+  let acc = 0;
+  let bits = 0;
+  for (const b of bytes) {
+    acc = (acc << 8) | b;
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      out += ALPHABET[(acc >> bits) & 0x1f];
+    }
+    // Keep the accumulator within 32-bit safe range for the `<<` operator.
+    acc &= (1 << bits) - 1;
+  }
+  if (bits > 0) {
+    out += ALPHABET[(acc << (5 - bits)) & 0x1f];
+  }
+  return out;
+}

package/src/index.ts

@@ -44,12 +44,7 @@ export { SQL, type SqlClient, type SqlOptions } from "./sql.js";
 export { RedisClient, type RedisClientLike, type RedisOptions } from "./redis.js";
 export { S3Client, type S3ClientLike, type S3File, type S3ClientOptions } from "./s3.js";
 
-export type {
-  Browser,
-  BrowserOptions,
-  ScreenshotFormat,
-  ScreenshotOptions,
-} from "./browser.js";
+export type { Browser, BrowserOptions } from "./browser.js";
 
 import type { Browser, BrowserOptions } from "./browser.js";
 
@@ -126,14 +121,14 @@ export interface ServiceConfig {
    * postgres's `docker-entrypoint.sh` initialization. Mutually
    * exclusive with {@link command}.
    */
-  args?: string[];
+  args?: readonly string[];
   env?: Record<string, string>;
   /**
    * Ports the container listens on. Advisory only — surfaced in
    * `spectest list` output. Peer services reach each other by `<service>:<port>`
    * without any port declaration.
    */
-  ports?: number[];
+  ports?: readonly number[];
   /**
    * Extra DNS names this service answers to inside the environment.
    * Each entry must be a fully-qualified, multi-label hostname (e.g.
@@ -149,7 +144,7 @@ export interface ServiceConfig {
    * answers to `<name>.internal` in addition to its bare `<name>`, and
    * user-supplied hostnames may not end in `.internal`.
    */
-  hostnames?: string[];
+  hostnames?: readonly string[];
   /**
    * Expose this service over HTTPS via a TLS-terminating reverse proxy
    * hosted in the spectest-daemon. Each entry maps a fully-qualified
@@ -166,9 +161,9 @@ export interface ServiceConfig {
    * multi-label, lowercase, no `.internal` suffix, no collision with
    * services, other service TLS hostnames, or fakes.
    */
-  tls?: ServiceTls[];
+  tls?: readonly ServiceTls[];
   /** Bind-mounted volumes for state that survives snapshot/fork. */
-  volumes?: VolumeMount[];
+  volumes?: readonly VolumeMount[];
   /**
    * Files seeded into the container's filesystem **before it starts**.
    * Each entry's `content` is written to a VM-host staging path and
@@ -178,9 +173,9 @@ export interface ServiceConfig {
    * `/etc/rancher/k3s/registries.yaml`, which must exist before
    * `k3s server` starts.
    */
-  files?: FileMount[];
+  files?: readonly FileMount[];
   /** Other services (keys in the services map) that must be ready first. */
-  dependsOn?: string[];
+  dependsOn?: readonly string[];
   readyCheck?: ReadyCheck;
   /** Container workdir override. */
   workdir?: string;
@@ -196,7 +191,7 @@ export interface ServiceConfig {
    * non-persistent. Snapshots/forks preserve tmpfs contents along with
    * the rest of process memory.
    */
-  tmpfs?: string[];
+  tmpfs?: readonly string[];
   /**
    * Cgroup namespace mode — `"host"` or `"private"`. Omit for docker's
    * default. k3s needs `"host"` so its embedded containerd can manage
@@ -690,7 +685,7 @@ export type ServiceImage =
        */
       content: string;
       /** Extra glob patterns to exclude from the build context. */
-      exclude?: string[];
+      exclude?: readonly string[];
     };
 
 export interface VolumeMount {
@@ -1284,7 +1279,7 @@ export interface FakeDefinition<
    * lowercase, no `.internal` suffix, no collisions with services or
    * other fakes.
    */
-  hostnames: string[];
+  hostnames: readonly string[];
   /** TCP port the fake listens on. Default `80`. */
   port?: number;
   /**
@@ -1329,7 +1324,7 @@ export interface FakeDefinition<
    * files, the config hash, or a cassette. Not part of the authoring
    * surface; `JSON.stringify` ignores it (fakes never serialize to config).
    */
-  secretRefs?: string[];
+  secretRefs?: readonly string[];
 }
 
 /**

package/src/mobile.ts

@@ -23,7 +23,6 @@ import type {
   BrowserSessionRecorder,
   MobileBackend,
   SafeAreaInsets,
-  ScreenshotOptions,
 } from "./browser.js";
 import type { Locator, Page } from "playwright-core";
 import type { Wrapped } from "./inspect.js";
@@ -312,8 +311,13 @@ export interface Mobile {
     expression: string,
     options?: { timeoutMs?: number; intervalMs?: number },
   ): Promise<Wrapped<T>>;
-  /** Capture a screenshot of the viewport. */
-  screenshot(options?: ScreenshotOptions): Promise<Uint8Array>;
+  /**
+   * Capture a PNG screenshot of the viewport and upload it as a
+   * downloadable artifact. Resolves to the artifact's `art_…` id
+   * (`spectest artifact download <id>`). Eval-only for now — throws with a
+   * clear message during test runs.
+   */
+  screenshot(): Promise<string>;
   /** Close the session. Idempotent; drains pending rrweb events. */
   close(): Promise<void>;
 }
@@ -386,8 +390,8 @@ function wrapMobile(backend: MobileBackend): Mobile {
     waitFor(description, expression, options) {
       return backend.waitFor(description, expression, options);
     },
-    screenshot(options) {
-      return backend.screenshot(options);
+    screenshot() {
+      return backend.screenshot();
     },
     close() {
       return backend.close();

package/src/replay-bundle.ts

@@ -0,0 +1,108 @@
+// Replay-bundle encoding: a case's rrweb sessions → one gzipped JSON blob
+// with large inlined assets deduplicated.
+//
+// Why this exists: recordings must NOT ride the `/run` response. The
+// vm-agent proxies daemon HTTP through a 16 MB response cap, and a
+// browser-heavy case blows straight past it — rrweb's `inlineImages`
+// re-inlines every image into every full snapshot, and animation-heavy
+// apps (e.g. Reanimated's per-frame inline-style writes) emit mutation
+// streams in the tens of MB. The daemon parks the encoded bundle in
+// memory instead and the control plane pulls it in chunks via
+// `POST /replay-chunk` (see daemon.ts), each chunk sized under the cap.
+//
+// Inside the bundle, every large base64 `data:` URI is extracted into an
+// `assets` table keyed by content hash and replaced with a
+// `data:x-spectest-asset/<hash>` token — the N re-inlined copies of one
+// image collapse to one asset plus N short tokens. The dashboard's case
+// viewer substitutes the real URI back into the raw JSON text before
+// parsing (mirror of this file's token format lives in
+// `web/case_viewer.rs::rehydrateAssets`). Only base64 URIs are extracted:
+// their charset needs no JSON escaping, so plain text substitution in
+// either direction cannot corrupt the surrounding JSON document.
+
+import { createHash } from "node:crypto";
+import { gzipSync } from "node:zlib";
+
+/** Minimum data: URI payload length (chars) worth extracting. Below this
+ * the token + asset-table overhead rivals the URI itself. */
+const ASSET_MIN_BASE64_CHARS = 1024;
+
+/** Base64 `data:` URIs, ≥1 KiB of payload. Mediatype + parameters are
+ * restricted to charsets that never need JSON escaping — a match taken
+ * from serialized JSON text is therefore byte-identical to the logical
+ * string value it sits inside. */
+const ASSET_RX = new RegExp(
+  "data:[A-Za-z0-9.+-]+/[A-Za-z0-9.+-]+(?:;[A-Za-z0-9.=+-]+)*;base64," +
+    `[A-Za-z0-9+/=]{${ASSET_MIN_BASE64_CHARS},}`,
+  "g",
+);
+
+/** Token an extracted asset is replaced with. Still a syntactically valid
+ * data: URI so anything that merely carries it along stays well-formed;
+ * it never renders (the viewer rehydrates before the events reach rrweb). */
+export function assetToken(hash: string): string {
+  return `data:x-spectest-asset/${hash}`;
+}
+
+/**
+ * Serialize `sessions` and pull every large base64 data: URI out into a
+ * content-addressed asset table. Returns the deduplicated sessions as a
+ * JSON *string* (already serialized — splice it into the bundle document
+ * verbatim) plus the asset table.
+ */
+export function extractReplayAssets(sessions: unknown): {
+  sessionsJson: string;
+  assets: Record<string, string>;
+} {
+  const assets: Record<string, string> = {};
+  const raw = JSON.stringify(sessions);
+  const sessionsJson = raw.replace(ASSET_RX, (uri) => {
+    // 16 hex chars (64 bits) of SHA-256: collision-safe at replay-asset
+    // scale (dozens of assets per case), and short enough that a token is
+    // negligible next to the URI it replaces.
+    const hash = createHash("sha256").update(uri).digest("hex").slice(0, 16);
+    assets[hash] = uri;
+    return assetToken(hash);
+  });
+  return { sessionsJson, assets };
+}
+
+/**
+ * Encode a case's sessions as the gzipped replay-bundle document the
+ * control plane archives to S3 verbatim:
+ * `{ caseId, sessions: [...], assets: { <hash>: <dataUri> } }` — the
+ * shape of `storage.rs::CaseReplayBundle`.
+ */
+export function encodeReplayBundle(caseId: string, sessions: unknown): Buffer {
+  const { sessionsJson, assets } = extractReplayAssets(sessions);
+  const doc = `{"caseId":${JSON.stringify(caseId)},"sessions":${sessionsJson},"assets":${JSON.stringify(assets)}}`;
+  return gzipSync(Buffer.from(doc));
+}
+
+/** Per-chunk raw-byte ceiling for `/replay-chunk` replies. Base64 inflates
+ * 4/3× and the JSON reply must clear the vm-agent's 16 MB response cap
+ * with headroom. The control plane's `fetch_replay_bundle` requests
+ * exactly this much per round trip. */
+export const REPLAY_CHUNK_MAX_BYTES = 6 * 1024 * 1024;
+
+/**
+ * One `/replay-chunk` reply: base64 of `gz[offset, offset+limit)`, with
+ * offset/limit clamped to sane values (never more than
+ * `REPLAY_CHUNK_MAX_BYTES` raw bytes). An out-of-range offset yields an
+ * empty `b64`, which the control plane treats as an error — it only ever
+ * asks for offsets below the advertised total.
+ */
+export function replayChunk(
+  gz: Buffer,
+  offsetIn: unknown,
+  limitIn: unknown,
+): { total: number; offset: number; b64: string } {
+  const offset = Math.max(0, Math.floor(Number(offsetIn) || 0));
+  const wanted = Math.floor(Number(limitIn) || REPLAY_CHUNK_MAX_BYTES);
+  const limit = Math.min(Math.max(1, wanted), REPLAY_CHUNK_MAX_BYTES);
+  return {
+    total: gz.length,
+    offset,
+    b64: gz.subarray(offset, offset + limit).toString("base64"),
+  };
+}