@specific.dev/spectest 0.14.0 → 0.15.0

package/package.json

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

package/src/browser.ts

@@ -16,7 +16,14 @@
 // Headless-Linux specifics live here: we force the chrome backend, add
 // `--no-sandbox` (Chrome refuses to run as root otherwise) and
 // `--disable-dev-shm-usage` (Firecracker's /dev/shm is tiny).
+//
+// Sessions are PERSISTENT by default: `ctx.browser()` always hands back the
+// one shared desktop browser and `ctx.mobile(app)` the one session for that
+// app, kept alive across tests so snapshots capture the live Chromium and
+// dependsOn children resume exactly where the parent left off (signed-in
+// SPA state included). See the "Persistent sessions" section below.
 
+import { promises as dns } from "node:dns";
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -205,7 +212,15 @@ export interface Browser {
   reload(): Promise<void>;
   /** Capture a PNG/JPEG/WebP screenshot of the viewport. Returns raw bytes. */
   screenshot(options?: ScreenshotOptions): Promise<Uint8Array>;
-  /** Close the underlying view. Idempotent. Drains any pending rrweb events. */
+  /**
+   * Destroy the underlying view. Idempotent; drains any pending rrweb
+   * events first. For the persistent session behind `ctx.browser()` /
+   * `ctx.mobile()` this is the escape hatch to a FRESH browser — the
+   * shared instance is discarded and the next call creates a new one.
+   * Don't call it for routine cleanup: the daemon detaches recording at
+   * test end automatically and deliberately keeps the browser alive so
+   * dependent tests inherit its state.
+   */
   close(): Promise<void>;
 }
 
@@ -603,6 +618,22 @@ interface PooledView {
   recordingInstalled: boolean;
 }
 
+/**
+ * The unit a Browser/Mobile handle drives. `view` is deliberately mutable:
+ * the DNS-recovery path (see `navigate` in {@link buildBackend}) replaces a
+ * broken restored renderer with a freshly-spawned view in the same Chrome,
+ * and every wrapper reads through the holder so the swap is transparent.
+ * `device`/`width`/`height` are kept so a rebuilt view comes back with the
+ * same viewport and emulation.
+ */
+interface ViewHolder {
+  view: BunWebViewInstance;
+  recordingInstalled: boolean;
+  device: DevicePreset | null;
+  width: number;
+  height: number;
+}
+
 // Pre-opened view pool. Renderer spawn is the expensive part of
 // `ctx.browser()` — ~1.8s for the first view in a fresh Chrome and
 // (measured 2026-06-05) a constant ~1.2-1.5s per view in a Chrome that
@@ -659,6 +690,11 @@ export async function prewarmViewPool(n = 1): Promise<void> {
  * Open a browser view. Always uses the Chrome backend in the daemon
  * (Firecracker guest is Linux; WKWebView isn't available). Serves from
  * the pre-opened pool when the caller uses the default viewport.
+ *
+ * This is the EPHEMERAL path — `close()` destroys the view. The daemon's
+ * `ctx.browser()`/`ctx.mobile()` go through {@link acquirePersistentBrowser}
+ * / {@link acquirePersistentMobileBackend} instead, which keep one view
+ * alive across tests so it rides snapshots/forks.
  */
 export async function openBrowser(opts: BrowserOptions = {}): Promise<Browser> {
   return openMobileBackend(opts);
@@ -668,10 +704,9 @@ export async function openBrowser(opts: BrowserOptions = {}): Promise<Browser> {
  * Like {@link openBrowser} but returns the {@link MobileBackend} superset
  * (touch + probe). When `opts.frame === "mobile"` the view is created at the
  * fixed device viewport, bypasses the (desktop-sized) pool, and has CDP
- * device emulation applied before the first navigation. The mobile facade
- * (`sdk/src/mobile.ts`) calls this; desktop callers go through
- * {@link openBrowser} and get the narrower {@link Browser} view of the same
- * object.
+ * device emulation applied before the first navigation. Desktop callers go
+ * through {@link openBrowser} and get the narrower {@link Browser} view of
+ * the same object.
  */
 export async function openMobileBackend(
   opts: BrowserOptions = {},
@@ -683,27 +718,227 @@ export async function openMobileBackend(
   // views, and a mobile view needs its emulation applied fresh anyway.
   const pooled =
     !device && wantW === 1280 && wantH === 720 ? VIEW_POOL.pop() : undefined;
-  const { view, recordingInstalled } = pooled ?? (await createView(wantW, wantH));
+  const base = pooled ?? (await createView(wantW, wantH));
+  const holder: ViewHolder = {
+    view: base.view,
+    recordingInstalled: base.recordingInstalled,
+    device,
+    width: wantW,
+    height: wantH,
+  };
 
-  if (device) await applyDeviceEmulation(view, device);
+  if (device) await applyDeviceEmulation(holder.view, device);
 
-  const browser = wrapView(view, opts.recorder ?? null, recordingInstalled);
+  const { backend } = buildBackend(holder, opts.recorder ?? null, {
+    persistent: false,
+  });
 
   // We deliberately don't forward `opts.url` to the constructor — going
   // through our own `navigate()` keeps the recorder log uniform (one
   // event per navigation, with timing) and drains rrweb after the load.
   if (opts.url !== undefined) {
-    await browser.navigate(opts.url);
+    await backend.navigate(opts.url);
   }
-  return browser;
+  return backend;
 }
 
-function wrapView(
-  view: BunWebViewInstance,
+// ────────────────────────────────────────────────────────────────────────
+// Persistent sessions (the default behind ctx.browser / ctx.mobile)
+// ────────────────────────────────────────────────────────────────────────
+
+// One long-lived desktop browser plus one mobile session per app URL.
+// Module state lives in daemon memory, so it forks with the snapshot the
+// same way fake `state` and TEST_DATA do: a test's browser — its live
+// page, cookies, localStorage, in-memory SPA state — is captured in the
+// post-test snapshot and inherited by `dependsOn` children, while sibling
+// forks never see each other's sessions. That's what lets a child test
+// continue where its parent left off (e.g. already signed in) instead of
+// re-navigating and re-authenticating.
+let SHARED_BROWSER: ViewHolder | null = null;
+const SHARED_MOBILE = new Map<string, ViewHolder>();
+
+/**
+ * What acquiring a persistent session returns. `detach` is the test-end
+ * hook (final rrweb drain, stop writing to this test's recorder, keep the
+ * view alive); `browser.close()` is the author-facing escape hatch that
+ * actually destroys the view (the next `ctx.browser()` starts fresh).
+ */
+export interface PersistentBrowser {
+  browser: MobileBackend;
+  /** True when this call attached to a view inherited from an earlier
+   *  test (possibly across a snapshot fork) rather than creating one. */
+  attached: boolean;
+  /** Final rrweb drain + detach from the current recorder. The view stays
+   *  alive so the post-test snapshot captures it. Idempotent. */
+  detach(): Promise<void>;
+}
+
+// Runs in the page when a persistent view is attached to a new test's
+// recorder: drop whatever rrweb buffered since the previous detach (idle
+// mutations; the previous test's session already drained everything it
+// owns) and emit a fresh Meta + FullSnapshot so the new session's replay
+// is self-contained from its first event.
+const ATTACH_RESET_EXPR = `(function () {
+  window.__spectestRrwebEvents = [];
+  try {
+    if (typeof rrwebRecord === "function" &&
+        typeof rrwebRecord.takeFullSnapshot === "function") {
+      rrwebRecord.takeFullSnapshot();
+    }
+  } catch (e) { /* recording not active on this document */ }
+  return true;
+})()`;
+
+async function newHolder(
+  width: number,
+  height: number,
+  device: DevicePreset | null,
+): Promise<ViewHolder> {
+  const { view, recordingInstalled } = await createView(width, height);
+  const holder: ViewHolder = { view, recordingInstalled, device, width, height };
+  if (device) await applyDeviceEmulation(view, device);
+  return holder;
+}
+
+async function attachReset(holder: ViewHolder): Promise<void> {
+  if (!holder.recordingInstalled) return;
+  try {
+    await holder.view.evaluate(ATTACH_RESET_EXPR);
+  } catch {
+    // Page mid-navigation or renderer unhappy — the first drain forces a
+    // full snapshot when one is missing (drainExpr), so replay still works.
+  }
+}
+
+/**
+ * Acquire THE persistent desktop browser (creating it on first use). There
+ * is deliberately a single one — `ctx.browser()` always returns it — so a
+ * test DAG shares one browsing session along each branch. The first call's
+ * options win; later calls attach to the existing view as-is.
+ */
+export async function acquirePersistentBrowser(
+  opts: BrowserOptions = {},
+): Promise<PersistentBrowser> {
+  const device = opts.frame === "mobile" ? LATEST_IPHONE : null;
+  let attached = true;
+  if (!SHARED_BROWSER) {
+    attached = false;
+    SHARED_BROWSER = await newHolder(
+      device ? device.viewport.width : opts.width ?? 1280,
+      device ? device.viewport.height : opts.height ?? 720,
+      device,
+    );
+  } else {
+    await attachReset(SHARED_BROWSER);
+  }
+  const holder = SHARED_BROWSER;
+  const { backend, detach } = buildBackend(holder, opts.recorder ?? null, {
+    persistent: true,
+    onDestroy: () => {
+      if (SHARED_BROWSER === holder) SHARED_BROWSER = null;
+    },
+  });
+  if (!attached && opts.url !== undefined) await backend.navigate(opts.url);
+  return { browser: backend, attached, detach };
+}
+
+/**
+ * Acquire the persistent mobile session for an app URL (one per app). A
+ * fresh session navigates to the app; an attach continues on the live page.
+ */
+export async function acquirePersistentMobileBackend(
+  url: string,
+  recorder: BrowserSessionRecorder | null,
+): Promise<PersistentBrowser> {
+  const existing = SHARED_MOBILE.get(url);
+  const holder =
+    existing ??
+    (await newHolder(
+      LATEST_IPHONE.viewport.width,
+      LATEST_IPHONE.viewport.height,
+      LATEST_IPHONE,
+    ));
+  if (existing) {
+    await attachReset(holder);
+  } else {
+    SHARED_MOBILE.set(url, holder);
+  }
+  const { backend, detach } = buildBackend(holder, recorder, {
+    persistent: true,
+    onDestroy: () => {
+      if (SHARED_MOBILE.get(url) === holder) SHARED_MOBILE.delete(url);
+    },
+  });
+  if (!existing) await backend.navigate(url);
+  return { browser: backend, attached: existing !== undefined, detach };
+}
+
+/** True when a navigation failed on Chromium name resolution. */
+function isNameNotResolved(err: unknown): boolean {
+  return String((err as Error)?.message ?? err).includes("ERR_NAME_NOT_RESOLVED");
+}
+
+/**
+ * Whether the daemon's own resolver can look the URL's host up. Chromium
+ * runs with AsyncDns disabled (see CHROME_ARGV) so it uses the same
+ * getaddrinfo path — a host the daemon resolves but Chrome can't means
+ * the RENDERER is broken, not the name.
+ */
+async function daemonResolves(url: string): Promise<boolean> {
+  try {
+    await dns.lookup(new URL(url).hostname);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Replace a persistent holder's view with a freshly-spawned one in the same
+ * Chrome. Profile state — cookies, localStorage, the in-VM CA trust — is
+ * per-Chrome, so it survives; only renderer-held page state is lost, and
+ * this path only runs when that renderer already can't navigate.
+ *
+ * Known trigger: a renderer created before a snapshot fails its first
+ * post-restore navigation with `net::ERR_NAME_NOT_RESOLVED` even though a
+ * fresh view in the SAME restored Chrome resolves fine (root cause never
+ * found — see the disabled-prewarm note at the end of /bootstrap in
+ * daemon.ts). Persistent sessions walk into exactly that scenario whenever
+ * a child test navigates, so the recovery lives here: rebuild the view,
+ * retry once.
+ */
+async function rebuildView(holder: ViewHolder): Promise<void> {
+  try {
+    holder.view.close();
+  } catch {
+    /* view may already be gone */
+  }
+  const fresh = await createView(holder.width, holder.height);
+  holder.view = fresh.view;
+  holder.recordingInstalled = fresh.recordingInstalled;
+  if (holder.device) await applyDeviceEmulation(holder.view, holder.device);
+}
+
+interface BackendBuildOptions {
+  /** Persistent views get the DNS-recovery navigate and a close() that
+   *  clears them out of the shared registry; ephemeral views just close. */
+  persistent: boolean;
+  /** Called when close() destroys the underlying view — the acquire
+   *  functions use it to drop the holder from the shared registry. */
+  onDestroy?: () => void;
+}
+
+function buildBackend(
+  holder: ViewHolder,
   recorder: BrowserSessionRecorder | null,
-  recordingInstalled: boolean,
-): MobileBackend {
-  let closed = false;
+  buildOpts: BackendBuildOptions,
+): { backend: MobileBackend; detach(): Promise<void> } {
+  // All page access goes through `holder.view` — never capture the view in
+  // a local — because the DNS-recovery rebuild swaps it mid-wrapper.
+  // `recordingEnded` stops this wrapper's recorder writes (test end);
+  // `viewClosed` tracks actual destruction (author called close()).
+  let recordingEnded = false;
+  let viewClosed = false;
   const sessionStart = Date.now();
   let stepSeq = 0;
   // URL observed at the previous drain. A change means the main frame
@@ -713,11 +948,11 @@ function wrapView(
   let lastDrainUrl: string | null = null;
 
   async function drain(action: BrowserAction | "close"): Promise<void> {
-    if (!recordingInstalled || !recorder || closed) return;
+    if (!holder.recordingInstalled || !recorder || recordingEnded) return;
     try {
-      const urlChanged = view.url !== lastDrainUrl;
-      const events = await view.evaluate<unknown[]>(drainExpr(urlChanged));
-      lastDrainUrl = view.url;
+      const urlChanged = holder.view.url !== lastDrainUrl;
+      const events = await holder.view.evaluate<unknown[]>(drainExpr(urlChanged));
+      lastDrainUrl = holder.view.url;
       if (Array.isArray(events) && events.length > 0) {
         recorder.recordStep({
           stepSeq: stepSeq++,
@@ -783,16 +1018,37 @@ function wrapView(
     }
   }
 
-  return {
+  async function endRecording(): Promise<void> {
+    if (recordingEnded) return;
+    // Final drain before we stop writing to this recorder.
+    await drain("close");
+    recordingEnded = true;
+  }
+
+  const backend: MobileBackend = {
     get url() {
-      return view.url;
+      return holder.view.url;
     },
     get title() {
-      return view.title;
+      return holder.view.title;
     },
     navigate(url) {
       recorder?.noteNavigation?.(url);
-      return instrumented("navigate", { url }, () => view.navigate(url));
+      return instrumented("navigate", { url }, async () => {
+        try {
+          await holder.view.navigate(url);
+        } catch (err) {
+          // Restored-renderer DNS bug (see `rebuildView`): only when the
+          // view is persistent (so it may have lived through a snapshot
+          // restore) and the daemon itself CAN resolve the host — a name
+          // that's genuinely unknown must fail without discarding the live
+          // page state a rebuild would cost.
+          if (!buildOpts.persistent || !isNameNotResolved(err)) throw err;
+          if (!(await daemonResolves(url))) throw err;
+          await rebuildView(holder);
+          await holder.view.navigate(url);
+        }
+      });
     },
     async evaluate<T = unknown>(
       description: string,
@@ -809,7 +1065,7 @@ function wrapView(
           scriptTruncated: truncatedScript.truncated,
         },
         async () => {
-          const v = await view.evaluate<T>(script);
+          const v = await holder.view.evaluate<T>(script);
           return v;
         },
       ) as Promise<Wrapped<T>>;
@@ -842,7 +1098,7 @@ function wrapView(
           fields.attempts = (fields.attempts ?? 0) + 1;
           let v: unknown;
           try {
-            v = await view.evaluate<unknown>(expression);
+            v = await holder.view.evaluate<unknown>(expression);
           } catch (err) {
             if (Date.now() >= deadline) throw err;
             await new Promise((r) => setTimeout(r, intervalMs));
@@ -859,41 +1115,41 @@ function wrapView(
       }) as Promise<Wrapped<T>>;
     },
     click(selector) {
-      return instrumented("click", { selector }, () => view.click(selector));
+      return instrumented("click", { selector }, () => holder.view.click(selector));
     },
     clickAt(x, y) {
-      return instrumented("click", { x, y }, () => view.click(x, y));
+      return instrumented("click", { x, y }, () => holder.view.click(x, y));
     },
     type(text) {
       const t = truncateUtf8(text);
       return instrumented(
         "type",
         { text: t.value, textTruncated: t.truncated },
-        () => view.type(text),
+        () => holder.view.type(text),
       );
     },
     press(key) {
-      return instrumented("press", { key }, () => view.press(key));
+      return instrumented("press", { key }, () => holder.view.press(key));
     },
     scroll(dx, dy) {
-      return instrumented("scroll", { dx, dy }, () => view.scroll(dx, dy));
+      return instrumented("scroll", { dx, dy }, () => holder.view.scroll(dx, dy));
     },
     scrollTo(selector) {
-      return instrumented("scrollTo", { selector }, () => view.scrollTo(selector));
+      return instrumented("scrollTo", { selector }, () => holder.view.scrollTo(selector));
     },
     back() {
-      return instrumented("back", {}, () => view.back());
+      return instrumented("back", {}, () => holder.view.back());
     },
     forward() {
-      return instrumented("forward", {}, () => view.forward());
+      return instrumented("forward", {}, () => holder.view.forward());
     },
     reload() {
-      return instrumented("reload", {}, () => view.reload());
+      return instrumented("reload", {}, () => holder.view.reload());
     },
     async screenshot(options) {
       const format = options?.format ?? "png";
       return instrumented("screenshot", { format }, async () => {
-        const buf = await view.screenshot({
+        const buf = await holder.view.screenshot({
           encoding: "buffer",
           format,
           quality: options?.quality,
@@ -902,12 +1158,18 @@ function wrapView(
       });
     },
     async close() {
-      if (closed) return;
-      // Final drain before the page evaporates.
-      await drain("close");
-      closed = true;
+      // Ends this wrapper's recording AND destroys the view. For a
+      // persistent view this is the author-facing escape hatch to a fresh
+      // browser: `onDestroy` drops the holder from the shared registry, so
+      // the next `ctx.browser()`/`ctx.mobile()` creates a new one. The
+      // routine test-end path is `detach` (recording stops, view lives on
+      // into the post-test snapshot).
+      await endRecording();
+      if (viewClosed) return;
+      viewClosed = true;
+      buildOpts.onDestroy?.();
       try {
-        view.close();
+        holder.view.close();
       } catch {
         /* already closed by the runtime */
       }
@@ -918,11 +1180,11 @@ function wrapView(
       // mobile facade owns the author-facing "tap" vocabulary). Dispatches
       // a real touch so RN-Web's responder system fires.
       return instrumented("click", { x, y }, async () => {
-        await view.cdp("Input.dispatchTouchEvent", {
+        await holder.view.cdp("Input.dispatchTouchEvent", {
           type: "touchStart",
           touchPoints: [{ x, y, id: 0 }],
         });
-        await view.cdp("Input.dispatchTouchEvent", {
+        await holder.view.cdp("Input.dispatchTouchEvent", {
           type: "touchEnd",
           touchPoints: [],
         });
@@ -931,26 +1193,27 @@ function wrapView(
     swipeBy(x, y, dx, dy) {
       return instrumented("scroll", { dx, dy }, async () => {
         const steps = 8;
-        await view.cdp("Input.dispatchTouchEvent", {
+        await holder.view.cdp("Input.dispatchTouchEvent", {
           type: "touchStart",
           touchPoints: [{ x, y, id: 0 }],
         });
         for (let i = 1; i <= steps; i++) {
-          await view.cdp("Input.dispatchTouchEvent", {
+          await holder.view.cdp("Input.dispatchTouchEvent", {
             type: "touchMove",
             touchPoints: [{ x: x + (dx * i) / steps, y: y + (dy * i) / steps, id: 0 }],
           });
         }
-        await view.cdp("Input.dispatchTouchEvent", {
+        await holder.view.cdp("Input.dispatchTouchEvent", {
           type: "touchEnd",
           touchPoints: [],
         });
       });
     },
     probe<T = unknown>(expression: string): Promise<T> {
-      return view.evaluate<T>(expression);
+      return holder.view.evaluate<T>(expression);
     },
   };
+  return { backend, detach: endRecording };
 }
 
 interface RecordableFields {

package/src/components/email.ts

@@ -0,0 +1,387 @@
+// `email()` — a real SMTP server as a spectest service. The app under test
+// points its SMTP transport at `<key>:1025` and sends mail exactly as it
+// would in production; every message is captured instead of delivered.
+// Tests read the mailbox through typed helpers on `ctx.svc.<key>`
+// (`lastEmail`, `emails`, `clear`), each recorded as an `email` event on
+// the test timeline — single-message ops embed the full captured message
+// (HTML body included) so the dashboard renders the actual email the test
+// asserted against, and returns come back inspect-wrapped so
+// `expect(mail.subject)` links under the step. To wait for a message to
+// *arrive*, use the standard `ctx.poll` with `lastEmail` as the predicate
+// (it returns `undefined` while the mailbox is empty); the winning
+// iteration's `email` event survives poll truncation, so the message still
+// renders nested under the wait step.
+//
+// Captured mail lives in the server's process memory, so it snapshots and
+// forks with the rest of the environment: a `dependsOn` child inherits the
+// parent's mailbox, sibling forks never see each other's messages — the
+// same isolation contract as fake state.
+
+import type { ServiceDefinition } from "../index.js";
+import {
+  pauseRecording,
+  recordEmail,
+  reserveEvent,
+  resumeRecording,
+  truncateUtf8,
+  type EmailEventMessage,
+  type EmailEventSummary,
+} from "../recorder.js";
+import { wrap } from "../inspect.js";
+import type { Wrapped } from "../inspect.js";
+
+const DEFAULT_IMAGE = "axllent/mailpit:v1.30";
+const SMTP_PORT = 1025;
+const API_PORT = 8025;
+
+export interface EmailOptions {
+  /** TCP port the SMTP listener binds. Default `1025`. */
+  smtpPort?: number;
+  /** Override the underlying mail-server image. */
+  image?: string;
+  /** Extra environment variables forwarded to the container. */
+  env?: Record<string, string>;
+}
+
+export interface EmailAttachment {
+  filename: string;
+  contentType: string;
+  /** Decoded size in bytes. */
+  size: number;
+}
+
+/** A fully captured email, as returned by `lastEmail`. */
+export interface EmailMessage {
+  id: string;
+  /** Sender address. */
+  from: string;
+  /** Recipient addresses. */
+  to: string[];
+  cc: string[];
+  bcc: string[];
+  subject: string;
+  /** Message date, ISO-formatted. */
+  date: string;
+  /** Plain-text body ("" when the mail had none). */
+  text: string;
+  /** HTML body ("" when the mail had none). */
+  html: string;
+  attachments: EmailAttachment[];
+}
+
+/** A mailbox-listing row, as returned by `emails()`. */
+export interface EmailSummary {
+  id: string;
+  from: string;
+  to: string[];
+  subject: string;
+  /** Plain-text preview of the body. */
+  snippet: string;
+  date: string;
+  /** Attachment count. */
+  attachments: number;
+}
+
+/** Filter for `emails()` listings. All given fields must match. */
+export interface EmailMatch {
+  /** A recipient address, compared case-insensitively. */
+  to?: string;
+  /** The sender address, compared case-insensitively. */
+  from?: string;
+  /** Subject substring (string) or pattern (RegExp). */
+  subject?: string | RegExp;
+}
+
+/** Helpers an `email(...)` service exposes on `ctx.svc.<name>`. */
+export interface EmailHelpers {
+  /**
+   * The newest captured message, in full (or `undefined` while the mailbox
+   * is empty) — which makes it the natural `ctx.poll` predicate for waiting
+   * on delivery; assert on its fields once it returns:
+   *
+   * ```ts
+   * const mail = await ctx.poll("welcome email", () => ctx.svc.email.lastEmail());
+   * expect(mail.to).toContain("alice@example.com");
+   * ```
+   *
+   * To wait for a *specific* message when several are in flight, check
+   * fields inside the predicate:
+   *
+   * ```ts
+   * const mail = await ctx.poll("reset email", async () => {
+   *   const m = await ctx.svc.email.lastEmail();
+   *   return m && /reset/i.test(m.unwrap().subject) ? m : undefined;
+   * });
+   * ```
+   */
+  lastEmail(): Promise<Wrapped<EmailMessage> | undefined>;
+  /** All captured messages matching `match`, newest first. */
+  emails(match?: EmailMatch): Promise<Wrapped<EmailSummary[]>>;
+  /** Delete every captured message. */
+  clear(): Promise<void>;
+}
+
+/**
+ * A capture-everything SMTP server. Drop into `environment.services`:
+ *
+ * ```ts
+ * services: {
+ *   email: email(),
+ *   app: {
+ *     ...,
+ *     env: { SMTP_HOST: "email", SMTP_PORT: "1025" },
+ *   },
+ * }
+ * ```
+ *
+ * The app sends real SMTP (any or no credentials are accepted, no TLS
+ * required); tests assert on what arrived, using the standard `ctx.poll`
+ * to wait for delivery:
+ *
+ * ```ts
+ * const mail = await ctx.poll("welcome email", () => ctx.svc.email.lastEmail());
+ * expect(mail.to).toContain("alice@example.com");
+ * expect(mail.subject).toBe("Welcome!");
+ * expect(mail.html).toContain("Alice");
+ * ```
+ */
+export function email(opts: EmailOptions = {}) {
+  const smtpPort = opts.smtpPort ?? SMTP_PORT;
+  const reference = opts.image ?? DEFAULT_IMAGE;
+  // `satisfies` (not a return-type annotation) so the helpers factory's
+  // literal return type flows through to `ctx.svc.<name>` — see the note
+  // in postgres.ts.
+  return {
+    image: { type: "registry" as const, reference },
+    env: {
+      // Accept whatever AUTH the app offers (including none, over
+      // plaintext), so an app configured with production-style SMTP
+      // credentials runs unchanged against the capture server.
+      MP_SMTP_AUTH_ACCEPT_ANY: "1",
+      MP_SMTP_AUTH_ALLOW_INSECURE: "1",
+      ...(smtpPort !== SMTP_PORT
+        ? { MP_SMTP_BIND_ADDR: `0.0.0.0:${smtpPort}` }
+        : {}),
+      ...(opts.env ?? {}),
+    },
+    ports: [smtpPort, API_PORT],
+    readyCheck: {
+      type: "http" as const,
+      port: API_PORT,
+      path: "/livez",
+      timeoutSecs: 60,
+    },
+    helpers: ({ name }: { name: string }): EmailHelpers =>
+      buildHelpers(name, `http://${name}:${API_PORT}`),
+  } satisfies ServiceDefinition<EmailHelpers>;
+}
+
+function buildHelpers(service: string, base: string): EmailHelpers {
+  return {
+    async lastEmail() {
+      return instrumented(service, "lastEmail", undefined, async () => {
+        const [hit] = await listAll(base); // newest first
+        if (!hit) return { value: undefined, count: 0 };
+        const value = await getMessage(base, hit.id);
+        return { value, message: toEventMessage(value) };
+      });
+    },
+
+    emails(match) {
+      return instrumented(service, "emails", describeMatch(match), async () => {
+        const value = (await listAll(base)).filter((s) => matches(s, match));
+        return {
+          value,
+          count: value.length,
+          messages: value.slice(0, EVENT_LIST_CAP).map(toEventSummary),
+        };
+      });
+    },
+
+    async clear() {
+      await instrumented(service, "clear", undefined, async () => {
+        await api(base, "/api/v1/messages", { method: "DELETE" });
+        return { value: undefined };
+      });
+    },
+  };
+}
+
+/** Newest-first mailbox listing rows returned by `emails()` are capped at
+ *  this many entries on the recorded event (the return value itself is
+ *  never truncated). */
+const EVENT_LIST_CAP = 50;
+
+/** Run one helper op: reserve a timeline slot up front, record an `email`
+ *  event when the op settles, and hand the value back inspect-wrapped
+ *  against that event so assertions on it nest under the step. */
+async function instrumented<T>(
+  service: string,
+  op: string,
+  query: string | undefined,
+  body: () => Promise<{
+    value: T;
+    message?: EmailEventMessage;
+    messages?: EmailEventSummary[];
+    count?: number;
+  }>,
+): Promise<Wrapped<T>> {
+  const started = Date.now();
+  const resv = reserveEvent();
+  try {
+    const { value, message, messages, count } = await body();
+    const seq = recordEmail(
+      { service, op, query, message, messages, count, durationMs: Date.now() - started },
+      resv,
+    );
+    return wrap(value, seq) as Wrapped<T>;
+  } catch (err) {
+    const e = err as Error;
+    recordEmail(
+      {
+        service,
+        op,
+        query,
+        durationMs: Date.now() - started,
+        error: e?.message ?? String(err),
+      },
+      resv,
+    );
+    throw err;
+  }
+}
+
+/** Query the mail server's HTTP API. Recording is paused around the fetch
+ *  so these internal polls don't land as `http` events on the timeline —
+ *  the helper records one consolidated `email` event instead. */
+async function api(base: string, path: string, init?: RequestInit): Promise<unknown> {
+  pauseRecording();
+  try {
+    const res = await fetch(`${base}${path}`, init);
+    if (!res.ok) {
+      throw new Error(`email server API ${path} failed: HTTP ${res.status}`);
+    }
+    const text = await res.text();
+    if (text === "") return undefined;
+    try {
+      return JSON.parse(text);
+    } catch {
+      // Mutating endpoints reply with a plain-text acknowledgement.
+      return text;
+    }
+  } finally {
+    resumeRecording();
+  }
+}
+
+interface RawAddress {
+  Name?: string;
+  Address?: string;
+}
+
+function addresses(v: unknown): string[] {
+  if (!Array.isArray(v)) return [];
+  return v.map((a) => (a as RawAddress)?.Address ?? "").filter((a) => a !== "");
+}
+
+async function listAll(base: string): Promise<EmailSummary[]> {
+  const data = (await api(base, "/api/v1/messages?limit=500")) as {
+    messages?: unknown[];
+  };
+  return (data?.messages ?? []).map((raw) => {
+    const m = raw as Record<string, unknown>;
+    return {
+      id: (m.ID as string) ?? "",
+      from: (m.From as RawAddress)?.Address ?? "",
+      to: addresses(m.To),
+      subject: (m.Subject as string) ?? "",
+      snippet: (m.Snippet as string) ?? "",
+      date: (m.Created as string) ?? "",
+      attachments: (m.Attachments as number) ?? 0,
+    };
+  });
+}
+
+async function getMessage(base: string, id: string): Promise<EmailMessage> {
+  const m = (await api(base, `/api/v1/message/${encodeURIComponent(id)}`)) as Record<
+    string,
+    unknown
+  >;
+  return {
+    id: (m.ID as string) ?? "",
+    from: (m.From as RawAddress)?.Address ?? "",
+    to: addresses(m.To),
+    cc: addresses(m.Cc),
+    bcc: addresses(m.Bcc),
+    subject: (m.Subject as string) ?? "",
+    date: (m.Date as string) ?? "",
+    text: (m.Text as string) ?? "",
+    html: (m.HTML as string) ?? "",
+    attachments: (Array.isArray(m.Attachments) ? m.Attachments : []).map((raw) => {
+      const a = raw as Record<string, unknown>;
+      return {
+        filename: (a.FileName as string) ?? "",
+        contentType: (a.ContentType as string) ?? "",
+        size: (a.Size as number) ?? 0,
+      };
+    }),
+  };
+}
+
+function matches(s: EmailSummary, match?: EmailMatch): boolean {
+  if (!match) return true;
+  if (match.to !== undefined) {
+    const want = match.to.toLowerCase();
+    if (!s.to.some((a) => a.toLowerCase() === want)) return false;
+  }
+  if (match.from !== undefined && s.from.toLowerCase() !== match.from.toLowerCase()) {
+    return false;
+  }
+  if (match.subject !== undefined) {
+    if (typeof match.subject === "string") {
+      if (!s.subject.includes(match.subject)) return false;
+    } else if (!match.subject.test(s.subject)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function describeMatch(match?: EmailMatch): string | undefined {
+  if (!match) return undefined;
+  const parts: string[] = [];
+  if (match.to !== undefined) parts.push(`to ${match.to}`);
+  if (match.from !== undefined) parts.push(`from ${match.from}`);
+  if (match.subject !== undefined) parts.push(`subject ${String(match.subject)}`);
+  return parts.length > 0 ? parts.join(", ") : undefined;
+}
+
+function toEventSummary(s: EmailSummary): EmailEventSummary {
+  return {
+    from: s.from,
+    to: s.to,
+    subject: s.subject,
+    snippet: s.snippet,
+    date: s.date,
+  };
+}
+
+function toEventMessage(m: EmailMessage): EmailEventMessage {
+  const html = truncateUtf8(m.html);
+  const text = truncateUtf8(m.text);
+  return {
+    from: m.from,
+    to: m.to,
+    ...(m.cc.length > 0 ? { cc: m.cc } : {}),
+    ...(m.bcc.length > 0 ? { bcc: m.bcc } : {}),
+    subject: m.subject,
+    date: m.date,
+    ...(m.html !== ""
+      ? { html: html.value, ...(html.truncated ? { htmlTruncated: true } : {}) }
+      : {}),
+    ...(m.text !== ""
+      ? { text: text.value, ...(text.truncated ? { textTruncated: true } : {}) }
+      : {}),
+    ...(m.attachments.length > 0 ? { attachments: m.attachments } : {}),
+  };
+}

package/src/components/index.ts

@@ -37,6 +37,15 @@ export {
   type SupabaseHelpers,
   type SupabaseStack,
 } from "./supabase.js";
+export {
+  email,
+  type EmailOptions,
+  type EmailHelpers,
+  type EmailMessage,
+  type EmailSummary,
+  type EmailMatch,
+  type EmailAttachment,
+} from "./email.js";
 export {
   replayFake,
   type ReplayFakeOptions,

package/src/daemon.ts

@@ -34,8 +34,8 @@ import {
   proxy as makeProxyDecl,
 } from "./index.js";
 import type { DnsTarget, LoweredIngress } from "./index.js";
-import { openBrowser } from "./browser.js";
-import { openMobile, isMobileApp } from "./mobile.js";
+import { acquirePersistentBrowser } from "./browser.js";
+import { isMobileApp, openPersistentMobile } from "./mobile.js";
 import type { Mobile, MobileApp } from "./mobile.js";
 import { openTerminal } from "./terminal.js";
 import {
@@ -2574,6 +2574,13 @@ async function bootstrap(): Promise<BootstrapTimings> {
   // browser.ts:213 (the long-standing intermittent NAME_NOT_RESOLVED) and
   // the clocksource-regression notes. Re-enabling requires fixing the
   // restored-renderer DNS state, not just re-adding the prewarm call.
+  // NOTE: persistent sessions (ctx.browser/ctx.mobile keep one live view
+  // across tests, so restored forks navigate on a pre-snapshot renderer
+  // routinely) hit the same bug head-on; browser.ts handles it there by
+  // rebuilding the view in the same Chrome and retrying the navigation
+  // (`rebuildView`) — profile state survives, so auth carries over. That
+  // recovery is scoped to inherited-navigation failures and does NOT make
+  // the about:blank prewarm pool safe to re-enable.
 
   const result: BootstrapTimings = {
     totalMs: Date.now() - bootStart,
@@ -3645,22 +3652,49 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
   const parentId = testCase.dependsOn?.id;
   const parent = parentId !== undefined ? TEST_DATA.get(parentId) : undefined;
 
-  // Track every Browser opened during this test so we can close them in
-  // `finally` — leaked Chromium subprocesses would survive the snapshot
-  // and chew memory across forks. Each Browser also gets a session
-  // recorder; the records flow back to the control plane as part of
-  // RunResult.browserSessions and are archived to S3 as the case's
-  // replay bundle.
-  // Tracks both Browser and Mobile handles for cleanup — both expose an
-  // async close() that does the final rrweb drain before teardown.
-  const openBrowsers: Array<{ close(): Promise<void> }> = [];
+  // Browser/mobile sessions are PERSISTENT: `ctx.browser()` acquires THE
+  // shared desktop browser and `ctx.mobile(app)` the one session for that
+  // app (browser.ts's module-scoped registry, which forks with the
+  // snapshot like fake state). At test end we DETACH — final rrweb drain,
+  // stop writing to this test's recorder — but deliberately keep the
+  // Chromium alive so the post-test snapshot captures it and dependsOn
+  // children resume the live page (cookies, localStorage, signed-in SPA
+  // state) instead of re-navigating. Each test still gets its own session
+  // record (attach re-arms rrweb with a fresh full snapshot, so replays
+  // stay per-case self-contained); records flow back to the control plane
+  // on RunResult.browserSessions and are archived to S3 as the case's
+  // replay bundle. Within one test repeated ctx.browser()/ctx.mobile(app)
+  // calls return the same handle (memoized below) so one test = one
+  // session per device. An explicit `.close()` destroys the shared
+  // instance — the memo is cleared so a later call starts fresh.
+  const browserDetaches: Array<() => Promise<void>> = [];
   const sessions: Array<ReturnType<typeof newBrowserSession>> = [];
+  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, testCase.id);
     sessions.push(session);
-    const b = await openBrowser({ ...(opts ?? {}), recorder: session.recorder });
-    openBrowsers.push(b);
-    return b;
+    const { browser, attached, detach } = await acquirePersistentBrowser({
+      ...(opts ?? {}),
+      recorder: session.recorder,
+    });
+    // An attached session starts mid-page (no navigate event will fire) —
+    // stamp the inherited URL so the dashboard can still label the replay.
+    if (attached && session.record.initialUrl === undefined) {
+      session.record.initialUrl = browser.url;
+    }
+    browserDetaches.push(async () => {
+      await detach();
+      session.markClosed();
+    });
+    const innerClose = browser.close.bind(browser);
+    browser.close = async () => {
+      await innerClose();
+      if (sharedBrowser === browser) sharedBrowser = null;
+    };
+    sharedBrowser = browser;
+    return browser;
   };
   const trackedOpenMobile = async (app: MobileApp): Promise<Mobile> => {
     if (!isMobileApp(app)) {
@@ -3668,11 +3702,28 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
         "ctx.mobile(app): pass a mobile-app handle from ctx.svc, e.g. ctx.mobile(ctx.svc.app) for a service declared with expo().",
       );
     }
+    const existing = sharedMobiles.get(app.url);
+    if (existing) return existing;
     const session = newBrowserSession(start, testCase.id, "mobile");
     sessions.push(session);
-    const m = await openMobile({ url: app.url, recorder: session.recorder });
-    openBrowsers.push(m);
-    return m;
+    const { mobile, attached, detach } = await openPersistentMobile({
+      url: app.url,
+      recorder: session.recorder,
+    });
+    if (attached && session.record.initialUrl === undefined) {
+      session.record.initialUrl = mobile.url;
+    }
+    browserDetaches.push(async () => {
+      await detach();
+      session.markClosed();
+    });
+    const innerClose = mobile.close.bind(mobile);
+    mobile.close = async () => {
+      await innerClose();
+      if (sharedMobiles.get(app.url) === mobile) sharedMobiles.delete(app.url);
+    };
+    sharedMobiles.set(app.url, mobile);
+    return mobile;
   };
 
   // Build convenience handles (e.g. ctx.svc.db.client) from the loaded
@@ -3740,13 +3791,14 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     (process.stdout as any).write = origStdout;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     (process.stderr as any).write = origStderr;
-    // Best-effort browser cleanup. `close()` does a final rrweb drain
-    // before tearing the view down, so we must `await` it before
-    // collecting session records. Leaked Chromium subprocesses would
-    // survive the snapshot and chew memory across forks.
-    for (const b of openBrowsers) {
+    // Detach every browser/mobile session: final rrweb drain (must be
+    // awaited before collecting session records), then stop writing to
+    // this test's recorder. The Chromium itself deliberately stays alive
+    // — it's part of the state the post-test snapshot captures for
+    // dependsOn children (see the acquire comment above).
+    for (const detach of browserDetaches) {
       try {
-        await b.close();
+        await detach();
       } catch {
         /* ignore */
       }
@@ -3926,14 +3978,35 @@ async function evalCode(
   // wrapped type is honest at runtime). Restored in the `finally` below.
   const restoreFetch = installFetchWrapper();
 
-  const openBrowsers: Array<{ close(): Promise<void> }> = [];
+  // Same persistent acquire/detach as a test run (see runOne): the browser
+  // survives the eval, so successive `spectest env eval` calls continue one
+  // live session — and a snapshot taken afterwards carries it.
+  const browserDetaches: Array<() => Promise<void>> = [];
   const sessions: Array<ReturnType<typeof newBrowserSession>> = [];
+  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");
     sessions.push(session);
-    const b = await openBrowser({ ...(opts ?? {}), recorder: session.recorder });
-    openBrowsers.push(b);
-    return b;
+    const { browser, attached, detach } = await acquirePersistentBrowser({
+      ...(opts ?? {}),
+      recorder: session.recorder,
+    });
+    if (attached && session.record.initialUrl === undefined) {
+      session.record.initialUrl = browser.url;
+    }
+    browserDetaches.push(async () => {
+      await detach();
+      session.markClosed();
+    });
+    const innerClose = browser.close.bind(browser);
+    browser.close = async () => {
+      await innerClose();
+      if (sharedBrowser === browser) sharedBrowser = null;
+    };
+    sharedBrowser = browser;
+    return browser;
   };
   const trackedOpenMobile = async (app: MobileApp): Promise<Mobile> => {
     if (!isMobileApp(app)) {
@@ -3941,11 +4014,28 @@ async function evalCode(
         "ctx.mobile(app): pass a mobile-app handle from ctx.svc, e.g. ctx.mobile(ctx.svc.app) for a service declared with expo().",
       );
     }
+    const existing = sharedMobiles.get(app.url);
+    if (existing) return existing;
     const session = newBrowserSession(start, "eval", "mobile");
     sessions.push(session);
-    const m = await openMobile({ url: app.url, recorder: session.recorder });
-    openBrowsers.push(m);
-    return m;
+    const { mobile, attached, detach } = await openPersistentMobile({
+      url: app.url,
+      recorder: session.recorder,
+    });
+    if (attached && session.record.initialUrl === undefined) {
+      session.record.initialUrl = mobile.url;
+    }
+    browserDetaches.push(async () => {
+      await detach();
+      session.markClosed();
+    });
+    const innerClose = mobile.close.bind(mobile);
+    mobile.close = async () => {
+      await innerClose();
+      if (sharedMobiles.get(app.url) === mobile) sharedMobiles.delete(app.url);
+    };
+    sharedMobiles.set(app.url, mobile);
+    return mobile;
   };
 
   // Terminal sessions — same shape as runOne, but eval has no active
@@ -4058,9 +4148,11 @@ async function evalCode(
     (process.stdout as any).write = origStdout;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     (process.stderr as any).write = origStderr;
-    for (const b of openBrowsers) {
+    // Detach (final rrweb drain) — the browser itself stays alive; see
+    // the acquire comment above.
+    for (const detach of browserDetaches) {
       try {
-        await b.close();
+        await detach();
       } catch {
         /* ignore */
       }

package/src/index.ts

@@ -1061,9 +1061,20 @@ export interface TestContext<
    */
   openTerminal(service: string, opts?: TerminalOpts): Promise<Terminal>;
   /**
-   * Open a headless browser. Backed by Chromium-over-CDP inside the VM.
-   * Every view is auto-closed when the test finishes; call `.close()` to
-   * release earlier if you're opening many.
+   * Open the headless browser. Backed by Chromium-over-CDP inside the VM.
+   *
+   * There is ONE persistent browser per environment: every `ctx.browser()`
+   * call returns it, and it stays alive across tests — the browser is part
+   * of the state a test's snapshot captures, so a `dependsOn` child resumes
+   * the exact live page its parent left (cookies, localStorage, signed-in
+   * SPA state). Sign in once in a parent test; every descendant is already
+   * signed in. Sibling tests fork from the same parent snapshot, so they
+   * can't see each other's browsing. A test with no browser-using ancestor
+   * gets a fresh browser on first call (first call's options win).
+   *
+   * `.close()` destroys the shared instance — the next `ctx.browser()`
+   * starts fresh. Don't call it for routine cleanup; recording is detached
+   * automatically at test end.
    */
   browser(opts?: BrowserOptions): Promise<Browser>;
   /**
@@ -1082,8 +1093,13 @@ export interface TestContext<
    * ```
    *
    * The session emulates the latest iPhone (viewport + DPR + mobile UA +
-   * touch) and the dashboard replays it inside a phone bezel. Auto-closed
-   * when the test finishes.
+   * touch) and the dashboard replays it inside a phone bezel.
+   *
+   * Sessions are persistent, one per app: like `ctx.browser()`, the live
+   * session is captured in the test's snapshot, so a `dependsOn` child
+   * picks up the app exactly where the parent left it (already signed in,
+   * mid-flow) instead of reloading it. `.close()` discards the session;
+   * the next `ctx.mobile(app)` opens the app fresh.
    */
   mobile(app: MobileApp): Promise<Mobile>;
   /** The test's display name. */

package/src/mobile.ts

@@ -14,7 +14,7 @@
 // `accessibilityLabel` to `aria-label`, so `getByTestId`/`getByLabel` map to
 // plain DOM attribute selectors with no shimming.
 
-import { openMobileBackend } from "./browser.js";
+import { acquirePersistentMobileBackend, openMobileBackend } from "./browser.js";
 import type {
   BrowserSessionRecorder,
   MobileBackend,
@@ -362,9 +362,9 @@ function wrapMobile(backend: MobileBackend): Mobile {
 }
 
 /**
- * Open a phone-emulated session pointed at `url`. The daemon calls this from
- * `ctx.mobile(app)` with a per-session rrweb recorder; the resulting record
- * carries `frame: "mobile"` so the dashboard renders a phone bezel.
+ * Open an EPHEMERAL phone-emulated session pointed at `url` (`close()`
+ * destroys it). Library callers only — the daemon's `ctx.mobile(app)` goes
+ * through {@link openPersistentMobile} so sessions survive across tests.
  */
 export async function openMobile(opts: {
   url?: string;
@@ -377,3 +377,22 @@ export async function openMobile(opts: {
   });
   return wrapMobile(backend);
 }
+
+/**
+ * Acquire the persistent phone-emulated session for an app (one per app
+ * URL, created on first use — see the "Persistent sessions" section in
+ * browser.ts). The daemon calls this from `ctx.mobile(app)` with a
+ * per-test rrweb recorder; the resulting record carries `frame: "mobile"`
+ * so the dashboard renders a phone bezel. `detach` is the test-end hook;
+ * `mobile.close()` destroys the session for real.
+ */
+export async function openPersistentMobile(opts: {
+  url: string;
+  recorder: BrowserSessionRecorder | null;
+}): Promise<{ mobile: Mobile; attached: boolean; detach(): Promise<void> }> {
+  const { browser, attached, detach } = await acquirePersistentMobileBackend(
+    opts.url,
+    opts.recorder,
+  );
+  return { mobile: wrapMobile(browser), attached, detach };
+}

package/src/recorder.ts

@@ -25,7 +25,8 @@ export type TestEvent =
   | TerminalStepEvent
   | WaitEvent
   | FakeEvent
-  | EnvEvent;
+  | EnvEvent
+  | EmailEvent;
 
 interface BaseEvent {
   /** Order of *start* within the test. Reserved when an op begins (see
@@ -275,6 +276,69 @@ export interface FakeEvent extends BaseEvent {
   error?: string;
 }
 
+/**
+ * One captured email, as embedded on an {@link EmailEvent}. The HTML and
+ * text bodies ride along (truncated to the output cap) so the dashboard
+ * can render the actual email a test asserted against.
+ */
+export interface EmailEventMessage {
+  /** Sender address. */
+  from?: string;
+  /** Recipient addresses. */
+  to?: string[];
+  cc?: string[];
+  bcc?: string[];
+  subject?: string;
+  /** RFC date of the message, ISO-formatted. */
+  date?: string;
+  /** HTML body (truncated to the output cap). */
+  html?: string;
+  htmlTruncated?: boolean;
+  /** Plain-text body (truncated to the output cap). */
+  text?: string;
+  textTruncated?: boolean;
+  attachments?: { filename: string; contentType: string; size: number }[];
+}
+
+/** One row of a mailbox listing embedded on an {@link EmailEvent}. */
+export interface EmailEventSummary {
+  from?: string;
+  to?: string[];
+  subject?: string;
+  /** Plain-text preview of the body. */
+  snippet?: string;
+  date?: string;
+}
+
+/**
+ * One call to an email service's helpers (`ctx.svc.<name>.lastEmail(...)`
+ * etc.). Single-message ops embed the full captured message — including its
+ * HTML body — so timelines can render the email itself; listing ops embed
+ * compact summaries. The return value is `wrap()`ped against this event's
+ * seq, so `expect(...)` on it nests under this step (same mechanism as
+ * http/db/fake). Inside a `ctx.poll` predicate the event ride-alongs with
+ * the poll's iteration events: failed iterations get truncated, the winning
+ * one survives as a child of the `wait` event.
+ */
+export interface EmailEvent extends BaseEvent {
+  kind: "email";
+  /** Service key of the mail server (`ctx.svc.<service>`). */
+  service: string;
+  /** Helper called, e.g. `"lastEmail"`. */
+  op: string;
+  /** Human-readable match criteria, e.g. `to alice@example.com`. */
+  query?: string;
+  /** Number of matching messages (listing ops / mailbox size on error). */
+  count?: number;
+  /** The captured message (single-message ops). */
+  message?: EmailEventMessage;
+  /** Message summaries (listing ops). */
+  messages?: EmailEventSummary[];
+  durationMs: number;
+  /** Set if the op threw (e.g. the mail server's query API failed). */
+  error?: string;
+}
+
 /**
  * A runtime mutation of the environment — `ctx.startService` /
  * `ctx.stopService` / `ctx.dnsName`, whether called from a test or from a
@@ -663,6 +727,13 @@ export function recordEnv(
   return active() ? current!.push({ kind: "env", ...ev }, reservation) : undefined;
 }
 
+export function recordEmail(
+  ev: Omit<EmailEvent, "seq" | "tOffsetMs" | "kind">,
+  reservation?: EventReservation,
+): number | undefined {
+  return active() ? current!.push({ kind: "email", ...ev }, reservation) : undefined;
+}
+
 /**
  * Recorded once per `ctx.poll(...)` call. Stands in for the suppressed
  * intermediate iterations and gives downstream tagged values