@specific.dev/spectest 0.19.1 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.19.1",
+  "version": "0.20.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/daemon.ts

@@ -2994,15 +2994,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 +3083,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 +4060,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 +4187,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 +4226,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 +4375,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 +4386,7 @@ async function evalCode(
         result: outcome.result,
         browserSessions: sessions.map((s) => s.record),
         terminalSessions,
+        artifacts: artifactCollector.artifacts,
       }
     : {
         ok: false,
@@ -4327,6 +4395,7 @@ async function evalCode(
         installed,
         browserSessions: sessions.map((s) => s.record),
         terminalSessions,
+        artifacts: artifactCollector.artifacts,
         error: outcome.error,
       };
 }

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";
 

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();