@specific.dev/spectest 0.15.0 → 0.16.0

package/package.json

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

package/src/browser.ts

@@ -167,6 +167,24 @@ export interface Browser {
    * test event log so the step list isn't a wall of minified code.
    */
   evaluate<T = unknown>(description: string, script: string): Promise<Wrapped<T>>;
+  /**
+   * Install a script that runs in every document loaded from now on, BEFORE
+   * any of the document's own scripts execute (CDP
+   * `Page.addScriptToEvaluateOnNewDocument` — the Playwright `addInitScript`
+   * equivalent). The deterministic way to plant shims and instrumentation
+   * (`fetch`/`XMLHttpRequest` wrappers, clock stubs, feature flags): unlike an
+   * `evaluate` racing the app bundle after a navigation, an init script is
+   * guaranteed to win.
+   *
+   * Does NOT run in the *current* document — call it before the `navigate`
+   * (or in-page `location.assign`) whose document needs it. Installed
+   * scripts persist for the browser session's lifetime, which for the
+   * persistent `ctx.browser()`/`ctx.mobile()` sessions means they ride
+   * snapshots into `dependsOn` children like the rest of the session state.
+   *
+   * `description` labels the step in the test event log.
+   */
+  addInitScript(description: string, source: string): Promise<void>;
   /**
    * Poll `expression` in the page until it returns a truthy value
    * (the returned value is what `waitFor` resolves with). Useful for
@@ -233,6 +251,10 @@ export interface Browser {
  * drain as the desktop verbs.
  */
 export interface MobileBackend extends Browser {
+  /** Safe-area insets emulated on this view (`null` on desktop views or
+   *  when the CDP override is unavailable). The daemon stamps these onto
+   *  the session record for the dashboard's replay. */
+  readonly safeAreaInsets: SafeAreaInsets | null;
   /** Touch-tap at viewport CSS coordinates (touchStart→touchEnd). */
   tapAt(x: number, y: number): Promise<void>;
   /** Touch-drag from (x,y) by (dx,dy) over a short move sequence. */
@@ -281,6 +303,15 @@ interface DevicePreset {
   isMobile: boolean;
   hasTouch: boolean;
   userAgent: string;
+  safeAreaInsets: SafeAreaInsets;
+}
+
+/** iOS safe-area insets (CSS `env(safe-area-inset-*)`), in CSS px. */
+export interface SafeAreaInsets {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
 }
 
 /** The fixed mobile device. Logical resolution + DPR of a current iPhone;
@@ -296,16 +327,28 @@ const LATEST_IPHONE: DevicePreset = {
   userAgent:
     "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) " +
     "AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1",
+  // Portrait safe area of the 393×852 iPhones (14 Pro through 16): 59pt
+  // status-bar/Dynamic-Island clearance on top, 34pt home-indicator strip
+  // at the bottom. Emulated via CDP so the app's `env(safe-area-inset-*)`
+  // padding fires exactly like on the real device.
+  safeAreaInsets: { top: 59, right: 0, bottom: 34, left: 0 },
 };
 
 /** Apply CDP device emulation to a freshly-created view. The overrides are
  *  CDP-session-global, so they persist across the app navigation that
  *  follows (we set them on the about:blank bootstrap page). Best-effort:
- *  a CDP failure degrades to a plain desktop view rather than aborting. */
+ *  a CDP failure degrades to a plain desktop view rather than aborting.
+ *
+ *  Returns the safe-area insets that actually took effect (`null` when the
+ *  override failed — Chromium < 135 lacks the CDP method). The caller
+ *  stamps them onto the session record so the dashboard can substitute the
+ *  same values for `env(safe-area-inset-*)` in the replayed CSS; stamping
+ *  only what was really applied keeps capture layout and replay layout in
+ *  lockstep (recorded touch coordinates would misalign otherwise). */
 async function applyDeviceEmulation(
   view: BunWebViewInstance,
   d: DevicePreset,
-): Promise<void> {
+): Promise<SafeAreaInsets | null> {
   try {
     await view.cdp("Emulation.setDeviceMetricsOverride", {
       width: d.viewport.width,
@@ -323,6 +366,17 @@ async function applyDeviceEmulation(
   } catch (err) {
     // eslint-disable-next-line no-console
     console.warn("[spectest] device emulation failed; using desktop view:", err);
+    return null;
+  }
+  try {
+    await view.cdp("Emulation.setSafeAreaInsetsOverride", {
+      insets: { ...d.safeAreaInsets },
+    });
+    return d.safeAreaInsets;
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn("[spectest] safe-area inset emulation unavailable:", err);
+    return null;
   }
 }
 
@@ -632,6 +686,13 @@ interface ViewHolder {
   device: DevicePreset | null;
   width: number;
   height: number;
+  /** Safe-area insets actually applied to the view (`null` for desktop
+   *  views or when the CDP override is unavailable). Stamped onto the
+   *  session record so the replay can mirror them. */
+  safeAreaInsets: SafeAreaInsets | null;
+  /** User scripts installed via `addInitScript`, kept so the DNS-recovery
+   *  rebuild can re-install them on the replacement view. */
+  initScripts: string[];
 }
 
 // Pre-opened view pool. Renderer spawn is the expensive part of
@@ -725,9 +786,11 @@ export async function openMobileBackend(
     device,
     width: wantW,
     height: wantH,
+    safeAreaInsets: null,
+    initScripts: [],
   };
 
-  if (device) await applyDeviceEmulation(holder.view, device);
+  if (device) holder.safeAreaInsets = await applyDeviceEmulation(holder.view, device);
 
   const { backend } = buildBackend(holder, opts.recorder ?? null, {
     persistent: false,
@@ -795,8 +858,16 @@ async function newHolder(
   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);
+  const holder: ViewHolder = {
+    view,
+    recordingInstalled,
+    device,
+    width,
+    height,
+    safeAreaInsets: null,
+    initScripts: [],
+  };
+  if (device) holder.safeAreaInsets = await applyDeviceEmulation(view, device);
   return holder;
 }
 
@@ -916,7 +987,12 @@ async function rebuildView(holder: ViewHolder): Promise<void> {
   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);
+  if (holder.device) {
+    holder.safeAreaInsets = await applyDeviceEmulation(holder.view, holder.device);
+  }
+  for (const source of holder.initScripts) {
+    await holder.view.cdp("Page.addScriptToEvaluateOnNewDocument", { source });
+  }
 }
 
 interface BackendBuildOptions {
@@ -1032,6 +1108,9 @@ function buildBackend(
     get title() {
       return holder.view.title;
     },
+    get safeAreaInsets() {
+      return holder.safeAreaInsets;
+    },
     navigate(url) {
       recorder?.noteNavigation?.(url);
       return instrumented("navigate", { url }, async () => {
@@ -1070,6 +1149,24 @@ function buildBackend(
         },
       ) as Promise<Wrapped<T>>;
     },
+    addInitScript(description: string, source: string): Promise<void> {
+      const truncated = truncateUtf8(source);
+      return instrumented(
+        "addInitScript",
+        {
+          description,
+          script: truncated.value,
+          scriptTruncated: truncated.truncated,
+        },
+        async () => {
+          await holder.view.cdp("Page.addScriptToEvaluateOnNewDocument", {
+            source,
+          });
+          // Remember it so a DNS-recovery view rebuild re-installs it.
+          holder.initScripts.push(source);
+        },
+      );
+    },
     async waitFor<T = unknown>(
       description: string,
       expression: string,

package/src/components/email.ts

@@ -176,6 +176,17 @@ export function email(opts: EmailOptions = {}) {
   } satisfies ServiceDefinition<EmailHelpers>;
 }
 
+/**
+ * Build the mailbox helpers for an `email()` service, by its services-map
+ * key. For components that expose a shared mailbox on their own handle
+ * (e.g. `supabase({ mail: true })` surfacing `ctx.svc.supabase.mail`) —
+ * the recorded `email` events carry `service` so the dashboard attributes
+ * them to the right container.
+ */
+export function emailHelpers(service: string, apiPort: number = API_PORT): EmailHelpers {
+  return buildHelpers(service, `http://${service}:${apiPort}`);
+}
+
 function buildHelpers(service: string, base: string): EmailHelpers {
   return {
     async lastEmail() {

package/src/components/supabase.ts

@@ -63,6 +63,7 @@ import {
   type ServicesMap,
 } from "../index.js";
 import { SQL, type SqlClient } from "../sql.js";
+import { email, emailHelpers, type EmailHelpers } from "./email.js";
 
 // ──────────────────────────────────────────────────────────────────────────
 // Pinned upstream image tags (github.com/supabase/supabase docker-compose.yml,
@@ -132,12 +133,45 @@ export interface SupabaseOptions {
    */
   hostname?: string;
 
+  /**
+   * Capture GoTrue's outgoing mail (magic links, OTPs, password recovery,
+   * invites — and signup confirmations with `autoconfirm: false`) with the
+   * standard `email()` component. **On by default**: the stack includes the
+   * capture server (`<name>-mail`) with GoTrue's SMTP wired at it, and tests
+   * read the mailbox through the typed helpers at `ctx.svc.<name>.mail`
+   * (`lastEmail` / `emails` / `clear`), each captured message rendering
+   * mail-client-style on the dashboard timeline.
+   *
+   * Signups stay one-step by default (`autoconfirm: true`) so the mailbox is
+   * purely additive; pass `{ autoconfirm: false }` to test real
+   * email-confirmation flows. Pass `{ service: "<key>" }` to point GoTrue at
+   * an `email()` service the environment already declares — keep a single
+   * mailbox per environment rather than one per component: if the app under
+   * test also sends mail, share one `email()` between it and Supabase
+   * instead of standing up a second capture server. `false` disables mail
+   * capture entirely.
+   */
+  mail?: boolean | SupabaseMailOptions;
+
+  /**
+   * Extra API keys the gateway accepts alongside the derived JWT keys — for
+   * clients that ship a hardcoded key (e.g. an `sb_publishable_…` /
+   * `sb_secret_…` pair baked into an app build). Each `anon` key is admitted
+   * with anon privileges and each `serviceRole` key with service-role
+   * privileges; Kong swaps the matching *derived JWT* in before proxying, so
+   * GoTrue/PostgREST/Realtime still receive a validly-signed token.
+   */
+  extraApiKeys?: { anon?: string[]; serviceRole?: string[] };
+
   /**
    * Auto-apply SQL migrations found in the project before any dependent service
    * starts. `true` (default) applies every `*.sql` under `supabase/migrations/`
    * (sorted, the Supabase convention), then `supabase/seed.sql` if present — a
    * no-op when the directory is absent. Pass a string to point at a different
    * directory (relative to the project root or absolute), or `false` to skip.
+   * An *explicitly configured* path that doesn't resolve is an error at env
+   * start (a silent no-op there surfaces much later as a confusing
+   * `relation … does not exist`).
    * Because `supabase/**` is project content, editing a migration correctly
    * forces a cold rebuild and re-apply (unlike `spectest/tests/**`).
    */
@@ -150,6 +184,28 @@ export interface SupabaseOptions {
   seed?: boolean | string;
 }
 
+/** Tuning for `SupabaseOptions.mail`. */
+export interface SupabaseMailOptions {
+  /**
+   * Reuse an `email()` service the environment already declares (its
+   * services-map key) instead of adding one to the group — the way to keep a
+   * single global mailbox when the app under test sends mail too. Assumes
+   * the service's default ports (SMTP 1025, API 8025).
+   */
+  service?: string;
+  /**
+   * Whether GoTrue autoconfirms signups. `true` (default): signups complete
+   * in one step and send no confirmation mail — recovery, magic-link and OTP
+   * mail is still sent and captured. Set `false` to exercise real
+   * email-confirmation flows (signups require the emailed verification).
+   */
+  autoconfirm?: boolean;
+  /** Sender address GoTrue mails from. Default `admin@example.com`. */
+  adminEmail?: string;
+  /** Sender display name. Default `Supabase`. */
+  senderName?: string;
+}
+
 /** Helpers the gateway service exposes on `ctx.svc.<name>`. */
 export interface SupabaseHelpers {
   /**
@@ -165,6 +221,18 @@ export interface SupabaseHelpers {
   anonKey: string;
   /** Long-lived `service_role` API key (HS256 JWT). Bypasses RLS — server-side only. */
   serviceRoleKey: string;
+  /**
+   * The captured-mail mailbox (`lastEmail` / `emails` / `clear`) — present
+   * unless the stack was built with `mail: false`. Wait for delivery with
+   * the standard `ctx.poll`:
+   *
+   * ```ts
+   * const mail = await ctx.poll("confirmation email", () =>
+   *   ctx.svc.supabase.mail!.lastEmail());
+   * expect(mail.to).toContain("alice@example.com");
+   * ```
+   */
+  mail?: EmailHelpers;
 }
 
 /** What `supabase()` returns: the service group plus the derived
@@ -185,6 +253,12 @@ export interface SupabaseStack {
   /** The gateway service key — use in a dependent service's `dependsOn` to wait
    *  for the whole stack (the gateway waits on the services behind it). */
   ready: string;
+  /**
+   * Where the stack's SMTP capture server listens (absent with
+   * `mail: false`) — point the app under test's own mail transport here to
+   * share the one mailbox: `env: { SMTP_HOST: sb.smtp.host, SMTP_PORT: String(sb.smtp.port) }`.
+   */
+  smtp?: { host: string; port: number };
   /** Ready-to-spread env for the app under test: `SUPABASE_URL`,
    *  `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY`, `DATABASE_URL`. */
   appEnv: Record<string, string>;
@@ -277,12 +351,32 @@ function buildBootstrapSql(
 // ──────────────────────────────────────────────────────────────────────────
 
 // The two Lua router expressions kong-entrypoint.sh emits when the opaque
-// `sb_`-style keys are NOT configured (our case): pass the incoming apikey (a
-// legacy HS256 JWT) through unchanged, preferring an existing non-`sb_`
-// Authorization header.
-const LUA_AUTH_EXPR =
-  "$((headers.authorization ~= nil and headers.authorization:sub(1, 10) ~= 'Bearer sb_' and headers.authorization) or headers.apikey)";
-const LUA_RT_WS_EXPR = "$(query_params.apikey)";
+// `sb_`-style keys are NOT configured: pass the incoming apikey (a legacy
+// HS256 JWT) through unchanged, preferring an existing non-`sb_`
+// Authorization header. `extraApiKeys` extends both: an extra key (arriving
+// as `apikey` header, `Authorization: Bearer <key>`, or the websocket
+// `?apikey=` query param) is swapped for the corresponding *derived JWT*
+// before proxying, so the upstream services still see a validly-signed token.
+function buildLuaExprs(
+  extra: Array<{ key: string; jwt: string }>,
+): { auth: string; realtimeWs: string } {
+  // Keep a client's `Authorization: Bearer <extraKey>` from winning the
+  // header-passthrough clause with the raw (non-JWT) key.
+  const guards = extra
+    .map((m) => ` and headers.authorization ~= 'Bearer ${m.key}'`)
+    .join("");
+  const mappings = extra
+    .map(
+      (m) =>
+        ` or ((headers.apikey == '${m.key}' or headers.authorization == 'Bearer ${m.key}') and 'Bearer ${m.jwt}')`,
+    )
+    .join("");
+  const auth = `$((headers.authorization ~= nil and headers.authorization:sub(1, 10) ~= 'Bearer sb_'${guards} and headers.authorization)${mappings} or headers.apikey)`;
+  const wsMappings = extra
+    .map((m) => `(query_params.apikey == '${m.key}' and '${m.jwt}') or `)
+    .join("");
+  return { auth, realtimeWs: `$(${wsMappings}query_params.apikey)` };
+}
 
 const KONG_YML_RAW = String.raw`_format_version: '2.1'
 _transform: true
@@ -631,9 +725,26 @@ function buildKongYaml(
     serviceRoleKey: string;
     dashboardUsername: string;
     dashboardPassword: string;
+    extraAnonKeys: string[];
+    extraServiceRoleKeys: string[];
   },
 ): string {
   let y = KONG_YML_RAW;
+  // Extra API keys land where kong-entrypoint.sh's opaque keys would: as
+  // additional keyauth credentials on the matching consumer. The template's
+  // placeholder lines are either expanded here or dropped by the filter below.
+  if (vals.extraAnonKeys.length > 0) {
+    y = y.replace(
+      "      - key: $SUPABASE_PUBLISHABLE_KEY",
+      vals.extraAnonKeys.map((k) => `      - key: ${k}`).join("\n"),
+    );
+  }
+  if (vals.extraServiceRoleKeys.length > 0) {
+    y = y.replace(
+      "      - key: $SUPABASE_SECRET_KEY",
+      vals.extraServiceRoleKeys.map((k) => `      - key: ${k}`).join("\n"),
+    );
+  }
   // Rewrite upstream bare service hosts → the group's final DNS names.
   y = y
     .replaceAll("http://auth:9999", `http://${key("auth")}:9999`)
@@ -644,9 +755,13 @@ function buildKongYaml(
     .replaceAll("http://functions:9000", `http://${key("functions")}:9000`)
     .replaceAll("realtime-dev.supabase-realtime", `realtime-dev.${key("realtime")}`);
   // Lua expressions first (they contain no `$SUPABASE_*` tokens).
-  y = y.replaceAll("$LUA_AUTH_EXPR", LUA_AUTH_EXPR).replaceAll(
+  const lua = buildLuaExprs([
+    ...vals.extraAnonKeys.map((k) => ({ key: k, jwt: vals.anonKey })),
+    ...vals.extraServiceRoleKeys.map((k) => ({ key: k, jwt: vals.serviceRoleKey })),
+  ]);
+  y = y.replaceAll("$LUA_AUTH_EXPR", lua.auth).replaceAll(
     "$LUA_RT_WS_EXPR",
-    LUA_RT_WS_EXPR,
+    lua.realtimeWs,
   );
   // API keys + dashboard credentials.
   y = y
@@ -707,14 +822,17 @@ async function applyMigrations(
   ctx: ServiceSetupContext,
   cfg: { migrations: boolean | string; seed: boolean | string },
 ): Promise<void> {
-  // Migrations directory.
+  // Migrations directory. An *explicitly configured* path that doesn't
+  // resolve is a hard error — a silent no-op here surfaces much later as a
+  // baffling `relation "public.…" does not exist`. Only the `true` default
+  // (conventional `supabase/migrations/`) is allowed to be absent.
   if (cfg.migrations !== false) {
-    const dir =
-      typeof cfg.migrations === "string"
-        ? cfg.migrations.startsWith("/")
-          ? cfg.migrations
-          : join(ctx.projectRoot, cfg.migrations)
-        : join(ctx.projectRoot, "supabase", "migrations");
+    const explicit = typeof cfg.migrations === "string";
+    const dir = explicit
+      ? (cfg.migrations as string).startsWith("/")
+        ? (cfg.migrations as string)
+        : join(ctx.projectRoot, cfg.migrations as string)
+      : join(ctx.projectRoot, "supabase", "migrations");
     if (existsSync(dir) && (await stat(dir)).isDirectory()) {
       const files = (await readdir(dir))
         .filter((f) => f.endsWith(".sql"))
@@ -723,19 +841,34 @@ async function applyMigrations(
         const sql = await ctx.readProjectFile(join(dir, f));
         await applySqlFile(ctx, sql, `migration ${f}`, "postgres");
       }
+    } else if (explicit) {
+      throw new Error(
+        `supabase: configured migrations path ${JSON.stringify(
+          cfg.migrations,
+        )} does not resolve to a directory (looked at ${dir}). ` +
+          `Fix the \`migrations\` option, or remove it to use the default ` +
+          `supabase/migrations/. Note the path is resolved inside the uploaded ` +
+          `project — check it isn't ignored (e.g. via .spectestignore).`,
+      );
     }
   }
-  // Seed file.
+  // Seed file — same contract: only the conventional default may be absent.
   if (cfg.seed !== false) {
-    const seedPath =
-      typeof cfg.seed === "string"
-        ? cfg.seed.startsWith("/")
-          ? cfg.seed
-          : join(ctx.projectRoot, cfg.seed)
-        : join(ctx.projectRoot, "supabase", "seed.sql");
+    const explicit = typeof cfg.seed === "string";
+    const seedPath = explicit
+      ? (cfg.seed as string).startsWith("/")
+        ? (cfg.seed as string)
+        : join(ctx.projectRoot, cfg.seed as string)
+      : join(ctx.projectRoot, "supabase", "seed.sql");
     if (existsSync(seedPath)) {
       const sql = await ctx.readProjectFile(seedPath);
       await applySqlFile(ctx, sql, "seed.sql", "postgres");
+    } else if (explicit) {
+      throw new Error(
+        `supabase: configured seed path ${JSON.stringify(cfg.seed)} not found ` +
+          `(looked at ${seedPath}). Fix the \`seed\` option or remove it to ` +
+          `use the default supabase/seed.sql.`,
+      );
     }
   }
 }
@@ -773,6 +906,29 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
   const withStudio = opts.studio ?? false;
   const withMeta = opts.meta ?? withStudio;
 
+  // Mail capture (see SupabaseOptions.mail) — on unless explicitly disabled.
+  // `mailKey` is the SMTP host GoTrue mails through — the in-group part
+  // (`<name>-mail`) or a user-declared `email()` service shared with the app
+  // under test.
+  const withMail = opts.mail !== false;
+  const mailOpts: SupabaseMailOptions =
+    typeof opts.mail === "object" ? opts.mail : {};
+  const mailExternal = mailOpts.service !== undefined;
+  const mailKey = mailOpts.service ?? `${name}-mail`;
+  const mailAutoconfirm = mailOpts.autoconfirm ?? true;
+
+  const extraAnonKeys = opts.extraApiKeys?.anon ?? [];
+  const extraServiceRoleKeys = opts.extraApiKeys?.serviceRole ?? [];
+  for (const k of [...extraAnonKeys, ...extraServiceRoleKeys]) {
+    // The keys are spliced into Kong's YAML and its quoted Lua expressions —
+    // restrict to the token charset real API keys use so neither can break.
+    if (!/^[A-Za-z0-9._-]+$/.test(k)) {
+      throw new Error(
+        `supabase(): extraApiKeys entries must match [A-Za-z0-9._-]+ (got ${JSON.stringify(k)})`,
+      );
+    }
+  }
+
   const anonKey = apiKey("anon", jwtSecret);
   const serviceRoleKey = apiKey("service_role", jwtSecret);
 
@@ -872,6 +1028,11 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
         readyCheck: { type: "tcp", port: 3000, timeoutSecs: 120 },
       };
 
+      // ── mail (SMTP capture, the standard email() component) ─────────
+      if (withMail && !mailExternal) {
+        parts.mail = email();
+      }
+
       // ── auth (GoTrue) ───────────────────────────────────────────────
       if (withAuth) {
         const apiExternalUrl = `${url}/auth/v1`;
@@ -894,14 +1055,39 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
             GOTRUE_JWT_ISSUER: apiExternalUrl,
             GOTRUE_EXTERNAL_EMAIL_ENABLED: "true",
             GOTRUE_EXTERNAL_ANONYMOUS_USERS_ENABLED: "true",
-            // Autoconfirm so tests can sign up without a mail server
-            // round-trip.
-            GOTRUE_MAILER_AUTOCONFIRM: "true",
+            // Autoconfirm defaults ON (one-step signups, no confirmation
+            // mail) so the always-on mailbox is purely additive; the mail
+            // option's `autoconfirm: false` opts into real confirmation
+            // flows.
+            GOTRUE_MAILER_AUTOCONFIRM:
+              withMail && !mailAutoconfirm ? "false" : "true",
             GOTRUE_EXTERNAL_PHONE_ENABLED: "false",
             GOTRUE_SMS_AUTOCONFIRM: "true",
+            ...(withMail
+              ? {
+                  GOTRUE_SMTP_HOST: mailKey,
+                  GOTRUE_SMTP_PORT: "1025",
+                  // Deliberately NO GOTRUE_SMTP_USER/PASS: the capture
+                  // server advertises AUTH, and with credentials set
+                  // GoTrue's Go smtp.PlainAuth refuses to send them over a
+                  // plaintext connection ("unencrypted connection" → every
+                  // mail 500s). Unauthenticated submission is accepted.
+                  GOTRUE_SMTP_ADMIN_EMAIL:
+                    mailOpts.adminEmail ?? "admin@example.com",
+                  GOTRUE_SMTP_SENDER_NAME: mailOpts.senderName ?? "Supabase",
+                  // GoTrue rate-limits repeat mail to the same address
+                  // (default 1/min) — far too slow for tests that
+                  // request an OTP, assert, and request again.
+                  GOTRUE_SMTP_MAX_FREQUENCY: "1s",
+                  GOTRUE_MAILER_URLPATHS_INVITE: "/auth/v1/verify",
+                  GOTRUE_MAILER_URLPATHS_CONFIRMATION: "/auth/v1/verify",
+                  GOTRUE_MAILER_URLPATHS_RECOVERY: "/auth/v1/verify",
+                  GOTRUE_MAILER_URLPATHS_EMAIL_CHANGE: "/auth/v1/verify",
+                }
+              : {}),
           },
           ports: [9999],
-          dependsOn: ["db"],
+          dependsOn: ["db", ...(withMail && !mailExternal ? ["mail"] : [])],
           readyCheck: { type: "http", port: 9999, path: "/health", timeoutSecs: 90 },
         };
       }
@@ -1071,6 +1257,8 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
               serviceRoleKey,
               dashboardUsername,
               dashboardPassword,
+              extraAnonKeys,
+              extraServiceRoleKeys,
             }),
           },
         ],
@@ -1087,6 +1275,7 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
       url,
       anonKey,
       serviceRoleKey,
+      ...(withMail ? { mail: emailHelpers(mailKey) } : {}),
     }),
   });
 
@@ -1105,5 +1294,6 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
     dbUrl,
     ready: name,
     appEnv,
+    ...(withMail ? { smtp: { host: mailKey, port: 1025 } } : {}),
   };
 }

package/src/daemon.ts

@@ -1478,6 +1478,88 @@ const HOP_BY_HOP_HEADERS = new Set([
   "host",
 ]);
 
+/**
+ * Is this a CORS preflight? A preflight is the browser's own probe (never
+ * app business logic): an `OPTIONS` carrying `Origin` +
+ * `Access-Control-Request-Method`. Plain `OPTIONS` calls (no `ACRM`) are real
+ * app requests and pass straight through to the upstream/fake.
+ */
+function isCorsPreflight(req: Request): boolean {
+  return (
+    req.method === "OPTIONS" &&
+    req.headers.has("origin") &&
+    req.headers.has("access-control-request-method")
+  );
+}
+
+/**
+ * Answer a CORS preflight at the ingress, permissively, reflecting exactly
+ * what the browser asked for.
+ *
+ * Why this belongs in the platform, not the app: inside the hermetic sandbox
+ * the app page's origin (e.g. `http://<svc>.internal:<port>`) and every host
+ * it fetches through this ingress (`https://api.example.com`) are *always*
+ * different origins, so any request with a non-safelisted header — which
+ * includes `Authorization`, and crucially `Cache-Control` / `Pragma` — is
+ * preflighted by the browser. If we forward the `OPTIONS` to the upstream, the
+ * request succeeds or fails on whether *that* app happens to enumerate the
+ * header in its `Access-Control-Allow-Headers`. Real apps list `Authorization`
+ * but almost never `Cache-Control`/`Pragma`, so a client that sends those (many
+ * HTTP libraries add `Cache-Control: no-cache` by default) fails the preflight
+ * with an instant "Failed to fetch" — even though the identical request works
+ * in production behind a permissive edge/gateway. Reflecting
+ * `Access-Control-Request-Headers` verbatim makes the ingress transparent to
+ * whatever header vocabulary the app under test uses.
+ */
+function corsPreflightResponse(req: Request): Response {
+  const origin = req.headers.get("origin") ?? "*";
+  const reqHeaders = req.headers.get("access-control-request-headers");
+  const reqMethod = req.headers.get("access-control-request-method");
+  const headers = new Headers();
+  headers.set("access-control-allow-origin", origin);
+  // Echo the specific origin (not `*`) so credentialed requests are allowed;
+  // `Allow-Origin: *` + `Allow-Credentials: true` is a spec violation browsers
+  // reject.
+  headers.set("access-control-allow-credentials", "true");
+  headers.set(
+    "access-control-allow-methods",
+    reqMethod && reqMethod.length > 0
+      ? reqMethod
+      : "GET,HEAD,PUT,PATCH,POST,DELETE,OPTIONS",
+  );
+  headers.set(
+    "access-control-allow-headers",
+    reqHeaders && reqHeaders.length > 0 ? reqHeaders : "*",
+  );
+  headers.set("access-control-max-age", "600");
+  // The response varies by the reflected origin/headers — keep caches honest.
+  headers.append("vary", "Origin");
+  headers.append("vary", "Access-Control-Request-Headers");
+  return new Response(null, { status: 204, headers });
+}
+
+/**
+ * Make sure the browser sees an `Access-Control-Allow-Origin` it accepts on the
+ * *actual* cross-origin response. Only fills one in when the upstream/fake
+ * didn't set its own, so an app that manages CORS itself keeps full control;
+ * this just stops a missing header from turning an otherwise-fine 200 into a
+ * "Failed to fetch". No-op for same-origin requests (no `Origin`).
+ */
+function augmentCorsResponse(req: Request, res: Response): Response {
+  const origin = req.headers.get("origin");
+  if (!origin) return res;
+  if (res.headers.has("access-control-allow-origin")) return res;
+  try {
+    res.headers.set("access-control-allow-origin", origin);
+    res.headers.set("access-control-allow-credentials", "true");
+    res.headers.append("vary", "Origin");
+  } catch {
+    // Some responses (e.g. a 101 upgrade stub) carry guarded/immutable
+    // headers — leave those untouched.
+  }
+  return res;
+}
+
 /**
  * Bring ingress servers up: bind one Bun.serve per unique HTTP port
  * (fakes' ports plus the always-on :80 for service proxies), plus a
@@ -1865,9 +1947,15 @@ async function dispatchIngress(
       { status: 404, headers: { "content-type": "text/plain" } },
     );
   }
+  // Answer CORS preflights at the ingress (see corsPreflightResponse) so a
+  // cross-origin browser request carrying any header — Authorization,
+  // Cache-Control, Pragma, … — isn't rejected by whatever the upstream happens
+  // to list in Access-Control-Allow-Headers.
+  if (isCorsPreflight(req)) return corsPreflightResponse(req);
   if (route.kind === "fake") {
     try {
-      return await route.fake.def.handler(req, route.fake.state, FAKE_CTX);
+      const res = await route.fake.def.handler(req, route.fake.state, FAKE_CTX);
+      return augmentCorsResponse(req, res);
     } catch (err) {
       const e = err as Error;
       return new Response(
@@ -1876,7 +1964,15 @@ async function dispatchIngress(
       );
     }
   }
-  return proxyToService(req, server, route.service, route.port, listenerLabel, proto);
+  const res = await proxyToService(
+    req,
+    server,
+    route.service,
+    route.port,
+    listenerLabel,
+    proto,
+  );
+  return augmentCorsResponse(req, res);
 }
 
 /**

package/src/mobile.ts

@@ -18,6 +18,7 @@ import { acquirePersistentMobileBackend, openMobileBackend } from "./browser.js"
 import type {
   BrowserSessionRecorder,
   MobileBackend,
+  SafeAreaInsets,
   ScreenshotOptions,
 } from "./browser.js";
 import type { Wrapped } from "./inspect.js";
@@ -278,6 +279,14 @@ export interface Mobile {
   back(): Promise<void>;
   /** Low-level escape hatch: evaluate JS in the page (recorded, wrapped). */
   evaluate<T = unknown>(description: string, script: string): Promise<Wrapped<T>>;
+  /**
+   * Install a script that runs before every *subsequent* document's own
+   * scripts (the Playwright `addInitScript` equivalent) — the deterministic
+   * way to plant shims/instrumentation that must win the race against the
+   * app bundle. Takes effect on the next navigation (e.g. a
+   * `location.assign` deep link), not the current document.
+   */
+  addInitScript(description: string, source: string): Promise<void>;
   /** Low-level escape hatch: poll a JS expression until truthy (recorded). */
   waitFor<T = unknown>(
     description: string,
@@ -349,6 +358,9 @@ function wrapMobile(backend: MobileBackend): Mobile {
     evaluate(description, script) {
       return backend.evaluate(description, script);
     },
+    addInitScript(description, source) {
+      return backend.addInitScript(description, source);
+    },
     waitFor(description, expression, options) {
       return backend.waitFor(description, expression, options);
     },
@@ -389,10 +401,22 @@ export async function openMobile(opts: {
 export async function openPersistentMobile(opts: {
   url: string;
   recorder: BrowserSessionRecorder | null;
-}): Promise<{ mobile: Mobile; attached: boolean; detach(): Promise<void> }> {
+}): Promise<{
+  mobile: Mobile;
+  attached: boolean;
+  detach(): Promise<void>;
+  /** Safe-area insets emulated on the view (`null` when the CDP override
+   *  is unavailable) — the daemon stamps them onto the session record. */
+  safeAreaInsets: SafeAreaInsets | null;
+}> {
   const { browser, attached, detach } = await acquirePersistentMobileBackend(
     opts.url,
     opts.recorder,
   );
-  return { mobile: wrapMobile(browser), attached, detach };
+  return {
+    mobile: wrapMobile(browser),
+    attached,
+    detach,
+    safeAreaInsets: browser.safeAreaInsets,
+  };
 }

package/src/recorder.ts

@@ -367,6 +367,7 @@ export interface EnvEvent extends BaseEvent {
 export type BrowserAction =
   | "navigate"
   | "evaluate"
+  | "addInitScript"
   | "waitFor"
   | "click"
   | "type"