@specific.dev/spectest 0.15.0 → 0.17.0

package/package.json

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

package/src/browser.ts

@@ -159,14 +159,34 @@ export interface Browser {
   /** Navigate to a URL; resolves when the main frame's load completes. */
   navigate(url: string): Promise<void>;
   /**
-   * Evaluate a JS expression in the page and return the
-   * JSON-deserialised result.
+   * Evaluate JS in the page and return the JSON-deserialised result.
+   * Accepts a single expression or a statement body (`const x = …;
+   * return x;`) — statement bodies are auto-wrapped in an async IIFE, so
+   * `return` and `await` work without manual wrapping.
    *
    * `description` is a short human-readable label for what the
    * snippet is doing ("read rendered todo list"); it surfaces in the
    * 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,8 +253,13 @@ export interface Browser {
  * drain as the desktop verbs.
  */
 export interface MobileBackend extends Browser {
-  /** Touch-tap at viewport CSS coordinates (touchStart→touchEnd). */
-  tapAt(x: number, y: number): Promise<void>;
+  /** 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 → short dwell →
+   *  touchEnd; `durationMs` overrides the dwell). */
+  tapAt(x: number, y: number, opts?: { durationMs?: number }): Promise<void>;
   /** Touch-drag from (x,y) by (dx,dy) over a short move sequence. */
   swipeBy(x: number, y: number, dx: number, dy: number): Promise<void>;
   /**
@@ -267,6 +292,32 @@ const CHROME_ARGV = [
   "--dns-over-https-mode=off",
 ];
 
+/** Default touchStart→touchEnd dwell for `tapAt` — see the comment there. */
+const TAP_DWELL_MS = 60;
+
+/**
+ * Make a user script evaluable by the page: Bun's `view.evaluate` accepts a
+ * single EXPRESSION (it wraps the source in `await (...)`), so a statement
+ * body (`const x = …; return x;`) is a syntax error. Rather than forcing
+ * authors to IIFE-wrap by hand, wrap it for them when it isn't an expression.
+ *
+ * The check is parse-only (`new Function` compiles without executing) and
+ * happens BEFORE the script runs — deciding by catching the page-side error
+ * and retrying would re-execute side-effecting expressions whose *runtime*
+ * error happens to look syntactic (`JSON.parse` throws SyntaxError too).
+ */
+function toEvaluable(script: string): string {
+  try {
+    new Function(`return (${script}\n);`);
+    return script;
+  } catch {
+    // Statement body — an async IIFE makes `return`, declarations, and
+    // multi-statement snippets valid, with `await` still available. The
+    // newlines keep a trailing line comment from eating the wrapper.
+    return `(async () => {\n${script}\n})()`;
+  }
+}
+
 // ────────────────────────────────────────────────────────────────────────
 // Device emulation (mobile frame)
 // ────────────────────────────────────────────────────────────────────────
@@ -281,6 +332,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 +356,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 +395,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 +715,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 +815,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 +887,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 +1016,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 +1137,9 @@ function buildBackend(
     get title() {
       return holder.view.title;
     },
+    get safeAreaInsets() {
+      return holder.safeAreaInsets;
+    },
     navigate(url) {
       recorder?.noteNavigation?.(url);
       return instrumented("navigate", { url }, async () => {
@@ -1065,11 +1173,29 @@ function buildBackend(
           scriptTruncated: truncatedScript.truncated,
         },
         async () => {
-          const v = await holder.view.evaluate<T>(script);
+          const v = await holder.view.evaluate<T>(toEvaluable(script));
           return v;
         },
       ) 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,
@@ -1086,6 +1212,8 @@ function buildBackend(
         scriptTruncated: truncatedScript.truncated,
         attempts: 0,
       };
+      // Normalised once up front — see `toEvaluable` (statement bodies work).
+      const evaluable = toEvaluable(expression);
       return instrumented<T>("waitFor", fields, async () => {
         const deadline = Date.now() + timeoutMs;
         // (return value wrapped by `instrumented`; cast below matches.)
@@ -1098,7 +1226,7 @@ function buildBackend(
           fields.attempts = (fields.attempts ?? 0) + 1;
           let v: unknown;
           try {
-            v = await holder.view.evaluate<unknown>(expression);
+            v = await holder.view.evaluate<unknown>(evaluable);
           } catch (err) {
             if (Date.now() >= deadline) throw err;
             await new Promise((r) => setTimeout(r, intervalMs));
@@ -1175,7 +1303,7 @@ function buildBackend(
       }
     },
     // ── Mobile-only primitives ──────────────────────────────────────────
-    tapAt(x, y) {
+    tapAt(x, y, opts) {
       // Recorded as a "click" (the event schema stays desktop-shaped; the
       // mobile facade owns the author-facing "tap" vocabulary). Dispatches
       // a real touch so RN-Web's responder system fires.
@@ -1184,6 +1312,13 @@ function buildBackend(
           type: "touchStart",
           touchPoints: [{ x, y, id: 0 }],
         });
+        // Dwell between start and end, like a real finger. An instant
+        // touchStart→touchEnd starves RN Pressables whose `onPressIn`
+        // mutates state (optimistic label flips, scale animations): React
+        // re-renders mid-gesture and the press never completes. The dwell
+        // lets that commit land before release; well under any long-press
+        // threshold (RN default 500ms).
+        await new Promise((r) => setTimeout(r, opts?.durationMs ?? TAP_DWELL_MS));
         await holder.view.cdp("Input.dispatchTouchEvent", {
           type: "touchEnd",
           touchPoints: [],

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/expo.ts

@@ -28,7 +28,12 @@ export interface ExpoOptions {
   nodeVersion?: string;
   /** Output dir `expo export` writes to (relative to the app dir). Default `"dist"`. */
   outputDir?: string;
-  /** Extra environment variables for the static server container. */
+  /**
+   * Extra environment variables. `EXPO_PUBLIC_*` keys are additionally baked
+   * into the image build so `expo export` inlines them into the bundle —
+   * Expo resolves them at export time, so runtime-only container env would be
+   * too late. Everything else applies to the static-server container only.
+   */
   env?: Record<string, string>;
 }
 
@@ -106,6 +111,23 @@ export function expo(opts: ExpoOptions = {}) {
   const nodeVersion = opts.nodeVersion ?? "20-bookworm-slim";
   const outputDir = opts.outputDir ?? "dist";
 
+  // Expo inlines EXPO_PUBLIC_* variables into the bundle at `expo export`
+  // time, so they must exist during the image build — runtime container env
+  // is too late. Bake them as ENV lines placed after `npm install` (an env
+  // edit re-exports without re-installing) and before the export RUN. They
+  // remain in `env` too, so server-side reads in the container agree.
+  const publicEnv = Object.entries(opts.env ?? {}).filter(([k]) =>
+    k.startsWith("EXPO_PUBLIC_"),
+  );
+  for (const [k, v] of publicEnv) {
+    if (/[\r\n]/.test(v)) {
+      throw new Error(`expo(): env ${k} must not contain newlines (baked into the Dockerfile)`);
+    }
+  }
+  const publicEnvLines = publicEnv
+    .map(([k, v]) => `ENV ${k}="${v.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`)
+    .join("\n");
+
   // CI=1 keeps `expo export` non-interactive. Static export resolves the web
   // bundle deterministically into `outputDir`.
   const dockerfile = `FROM node:${nodeVersion}
@@ -113,7 +135,7 @@ WORKDIR /app
 ENV CI=1
 COPY ${appDir}/ ./
 RUN npm install
-RUN npx expo export --platform web --output-dir ${outputDir}
+${publicEnvLines ? `${publicEnvLines}\n` : ""}RUN npx expo export --platform web --output-dir ${outputDir}
 `;
 
   return {

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

@@ -845,6 +845,19 @@ async function buildServiceImage(
     await fs.mkdir(dfDir, { recursive: true });
     const dfPath = path.join(dfDir, "Dockerfile");
     await fs.writeFile(dfPath, image.content);
+    // Per-service ignore: BuildKit resolves `<Dockerfile>.dockerignore`
+    // (next to the Dockerfile) in preference to the context root's
+    // `.dockerignore`, so this build sees the defaults plus ITS OWN
+    // `exclude` only — one service excluding `handhelds/**` no longer
+    // empties a sibling's build context. Verified on both the remote-buildx
+    // and DOCKER_BUILDKIT paths (client-side context filtering). The root
+    // union `.dockerignore` written at bootstrap stays as the fallback for
+    // the legacy non-BuildKit builder, which predates per-Dockerfile
+    // ignores.
+    await fs.writeFile(
+      `${dfPath}.dockerignore`,
+      [...DEFAULT_DOCKERIGNORE, ...(image.exclude ?? [])].join("\n") + "\n",
+    );
     const useRemote = await ensureRemoteBuilder();
     // Both the remote builder and a local buildx are BuildKit, so both emit
     // per-step timing on stderr under `--progress=plain` (parsed below). Only
@@ -1478,6 +1491,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 +1960,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 +1977,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);
 }
 
 /**
@@ -1949,6 +2058,16 @@ async function proxyToService(
   // the public hostname. Lets origin servers that vhost by Host header
   // continue to find the right virtual host.
   fwdHeaders.set("host", `${service}:${port}`);
+  // Fresh connection per upstream request — never reuse a pooled
+  // keep-alive conn. Upstreams with short idle timeouts (uvicorn defaults
+  // to 5s) close pooled connections under Bun's fetch, and the next
+  // request on the dead socket fails with "socket closed unexpectedly"
+  // even though the service is healthy. In-VM connects to a peer
+  // container are sub-ms, so per-request connects cost nothing at test
+  // scale. `connection: close` makes the upstream tear down immediately;
+  // `keepalive: false` on the fetch below keeps Bun from pooling its end.
+  // (Both verified effective on Bun 1.3.14.)
+  fwdHeaders.set("connection", "close");
 
   // Buffer bounded request bodies so a transient upstream connect failure
   // can be retried (a ReadableStream body is consumed by the first
@@ -1989,8 +2108,13 @@ async function proxyToService(
         redirect: "manual",
       });
       // decompress:false → forward the encoded body untouched (see fn doc).
+      // keepalive:false → fresh connection per request (see fwdHeaders above).
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const upstreamRes = await NATIVE_FETCH(upstreamReq, { decompress: false } as any);
+      const upstreamRes = await NATIVE_FETCH(upstreamReq, {
+        decompress: false,
+        keepalive: false,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any);
       // Strip hop-by-hop response headers; let Bun set content-length / TE.
       const respHeaders = new Headers();
       for (const [k, v] of upstreamRes.headers) {
@@ -2004,11 +2128,18 @@ async function proxyToService(
       });
     } catch (err) {
       lastErr = err;
-      // Only connect-class failures are safely retryable — if the request
-      // reached the upstream we must not replay it.
+      // Retry connection-level failures: connect errors, plus a socket
+      // that died before any response bytes ("socket closed unexpectedly",
+      // ECONNRESET, hang-up) — under boot-time bursts an upstream accepts
+      // and drops connections while still warming up. Pre-response
+      // failures are the standard retry class for reverse proxies
+      // (nginx's proxy_next_upstream error). Anything that produced a
+      // response is never replayed.
       const msg = (err as Error)?.message ?? String(err);
       const connectFailure =
-        /unable to connect|connection refused|connect|typo in the url/i.test(msg);
+        /unable to connect|connection refused|connect|typo in the url|socket closed|connection closed|econnreset|socket hang ?up|epipe/i.test(
+          msg,
+        );
       if (!connectFailure || attempt === attempts) break;
       // The cached IP may be stale (container recreated) — re-resolve.
       PROXY_IP_CACHE.delete(service);

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";
@@ -68,12 +69,13 @@ interface LocatorDesc {
  *  moment an action runs. Mirrors the select-then-act idiom shared by
  *  Playwright, Detox, and RN Testing Library. */
 export interface MobileLocator {
-  /** Wait for the element to be visible, then touch-tap its center. */
-  tap(): Promise<void>;
+  /** Wait for the element to be visible (default 5s, `timeoutMs` overrides),
+   *  then touch-tap its center. `durationMs` overrides the touch dwell. */
+  tap(opts?: { timeoutMs?: number; durationMs?: number }): Promise<void>;
   /** Tap to focus, then type `text` via real key events. */
-  typeText(text: string): Promise<void>;
+  typeText(text: string, opts?: { timeoutMs?: number }): Promise<void>;
   /** Clear a text input's current value (RN-Web controlled input safe). */
-  clearText(): Promise<void>;
+  clearText(opts?: { timeoutMs?: number }): Promise<void>;
   /** Scroll the element to the center of the viewport. */
   scrollIntoView(): Promise<void>;
   /** Wait until the element is attached and visible (throws on timeout). */
@@ -167,6 +169,11 @@ function descLabel(desc: LocatorDesc): string {
   return `${desc.kind} ${JSON.stringify(desc.value)}`;
 }
 
+/** Default wait for a locator action's target to become visible. Override
+ *  per action with `{ timeoutMs }` (animations that move elements mid-flight
+ *  often need more than the default). */
+const DEFAULT_ACTION_TIMEOUT_MS = 5_000;
+
 function makeLocator(backend: MobileBackend, desc: LocatorDesc): MobileLocator {
   const label = descLabel(desc);
 
@@ -187,17 +194,17 @@ function makeLocator(backend: MobileBackend, desc: LocatorDesc): MobileLocator {
   }
 
   return {
-    async tap() {
-      const { x, y } = await waitCoords(5_000);
-      await backend.tapAt(x, y);
+    async tap(opts) {
+      const { x, y } = await waitCoords(opts?.timeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS);
+      await backend.tapAt(x, y, { durationMs: opts?.durationMs });
     },
-    async typeText(text) {
-      const { x, y } = await waitCoords(5_000);
+    async typeText(text, opts) {
+      const { x, y } = await waitCoords(opts?.timeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS);
       await backend.tapAt(x, y);
       await backend.type(text);
     },
-    async clearText() {
-      await waitCoords(5_000);
+    async clearText(opts) {
+      await waitCoords(opts?.timeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS);
       // Native value-setter + input event so RN-Web's controlled TextInput
       // sees the change (a plain `.value = ""` is swallowed by React).
       await backend.evaluate(
@@ -268,6 +275,13 @@ export interface Mobile {
   getByLabel(text: string): MobileLocator;
   /** Escape hatch: select by a raw CSS selector. */
   locator(css: string): MobileLocator;
+  /**
+   * Touch-tap at viewport CSS coordinates — the escape hatch for targets no
+   * locator can select (unlabeled icon-only buttons, canvas hit areas). Same
+   * real-touch dispatch and dwell as a locator `tap()`. Prefer locators when
+   * the element has a testID/label; coordinates break on layout changes.
+   */
+  tapAt(x: number, y: number, opts?: { durationMs?: number }): Promise<void>;
   /** Swipe the screen in a direction (a touch drag from the center). */
   swipe(direction: "up" | "down" | "left" | "right", opts?: { distance?: number }): Promise<void>;
   /** Wheel-scroll the viewport by a pixel delta. */
@@ -278,6 +292,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,
@@ -325,6 +347,9 @@ function wrapMobile(backend: MobileBackend): Mobile {
     locator(css) {
       return makeLocator(backend, { kind: "css", value: css });
     },
+    tapAt(x, y, opts) {
+      return backend.tapAt(x, y, opts);
+    },
     async swipe(direction, opts) {
       const vp = await backend.probe<{ w: number; h: number }>(
         "({ w: window.innerWidth, h: window.innerHeight })",
@@ -349,6 +374,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 +417,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

@@ -115,8 +115,12 @@ export interface DbEvent extends BaseEvent {
   query: string;
   /** Parameter values. Best-effort JSON-safe; large/binary values stringified. */
   params?: unknown[];
-  /** Rows returned, when known. */
+  /** Rows returned — or rows AFFECTED when `rowsAffected` is set. */
   rowCount?: number;
+  /** Set when `rowCount` counts affected rows (a non-RETURNING
+   *  INSERT/UPDATE/DELETE) rather than a result set — rendered as
+   *  "N affected" so an `UPDATE → 0 rows` can't read as "nothing updated". */
+  rowsAffected?: boolean;
   /** Captured rows for table rendering in the web UI. Capped at
    *  MAX_DB_ROWS; `rowsTruncated` is set when there were more. */
   rows?: unknown[];
@@ -367,6 +371,7 @@ export interface EnvEvent extends BaseEvent {
 export type BrowserAction =
   | "navigate"
   | "evaluate"
+  | "addInitScript"
   | "waitFor"
   | "click"
   | "type"

package/src/sql.ts

@@ -124,6 +124,7 @@ export function instrumentSql(raw: RawSqlClient, label: string): SqlClient {
             query,
             params: params.length > 0 ? params.map(safeSerialize) : undefined,
             rowCount: rowCountOf(value),
+            rowsAffected: isAffectedCount(query, value) || undefined,
             rows,
             rowsTruncated,
             columns,
@@ -192,15 +193,34 @@ function reconstructSqlTemplate(
 }
 
 function rowCountOf(value: unknown): number | undefined {
-  if (Array.isArray(value)) return value.length;
   if (value && typeof value === "object") {
     const obj = value as { count?: unknown; rowCount?: unknown };
+    // Bun.SQL (postgres.js semantics): `.count` is rows RETURNED for
+    // SELECT/RETURNING queries and rows AFFECTED for other writes — where
+    // the result array itself is empty. Check it before `.length`, or a
+    // non-RETURNING `UPDATE` that touched 3 rows records a misleading 0.
     if (typeof obj.count === "number") return obj.count;
     if (typeof obj.rowCount === "number") return obj.rowCount;
   }
+  if (Array.isArray(value)) return value.length;
   return undefined;
 }
 
+/** True when the recorded count means "rows affected" rather than "rows
+ *  returned" — a write with no result set. Lets the dashboard render
+ *  `3 affected` instead of `3 rows` (and keeps `UPDATE … (0 rows)` from
+ *  reading as "nothing updated"). */
+function isAffectedCount(query: string, value: unknown): boolean {
+  if (Array.isArray(value) && value.length > 0) return false; // rows came back
+  const q = query.trimStart().slice(0, 8).toUpperCase();
+  return (
+    q.startsWith("INSERT") ||
+    q.startsWith("UPDATE") ||
+    q.startsWith("DELETE") ||
+    q.startsWith("MERGE")
+  );
+}
+
 const MAX_DB_ROWS = 50;
 
 function captureRows(value: unknown): {