@specific.dev/spectest 0.5.0 → 0.7.0

package/package.json

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

package/src/browser.ts

@@ -73,10 +73,19 @@ interface BunWebViewCtor {
 declare const Bun: { WebView: BunWebViewCtor };
 
 export interface BrowserOptions {
-  /** Viewport width in pixels. Default 1280. */
+  /** Viewport width in pixels. Default 1280. Ignored when `frame: "mobile"`
+   * (the device preset's viewport wins). */
   width?: number;
-  /** Viewport height in pixels. Default 720. */
+  /** Viewport height in pixels. Default 720. Ignored when `frame: "mobile"`. */
   height?: number;
+  /**
+   * Which device frame this session represents. `"browser"` (default) is a
+   * desktop viewport rendered as a browser window in the replay; `"mobile"`
+   * emulates a phone (viewport + DPR + mobile UA + touch via CDP) and the
+   * replay wraps the capture in a phone bezel. The mobile device is fixed
+   * (latest iPhone) and not caller-configurable — see `ctx.mobile`.
+   */
+  frame?: "browser" | "mobile";
   /** Initial URL to navigate to before the constructor returns. */
   url?: string;
   /**
@@ -200,6 +209,27 @@ export interface Browser {
   close(): Promise<void>;
 }
 
+/**
+ * A {@link Browser} with the lower-level touch primitives the mobile
+ * (`ctx.mobile`) facade is built on. Not exposed to test authors directly —
+ * `sdk/src/mobile.ts` wraps it in the ergonomic locator/gesture API. The
+ * touch ops dispatch real `Input.dispatchTouchEvent` sequences (so RN-Web's
+ * responder system sees genuine touches) and ride the same recorder + rrweb
+ * 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>;
+  /** Touch-drag from (x,y) by (dx,dy) over a short move sequence. */
+  swipeBy(x: number, y: number, dx: number, dy: number): Promise<void>;
+  /**
+   * Evaluate a JS expression in the page WITHOUT recording an event or
+   * draining rrweb — the locator layer's internal element resolver. rrweb
+   * keeps buffering page-side; the next recorded op drains it.
+   */
+  probe<T = unknown>(expression: string): Promise<T>;
+}
+
 // Default extra flags for headless Chromium inside a Firecracker microVM.
 // --no-sandbox: Chrome refuses to launch as root otherwise (no user
 //   namespaces in the guest).
@@ -222,6 +252,65 @@ const CHROME_ARGV = [
   "--dns-over-https-mode=off",
 ];
 
+// ────────────────────────────────────────────────────────────────────────
+// Device emulation (mobile frame)
+// ────────────────────────────────────────────────────────────────────────
+
+/** A device descriptor in the shape of Playwright's `devices[...]` entries
+ *  — the subset we feed to CDP. Not caller-configurable today; a single
+ *  fixed preset (latest iPhone) backs every `ctx.mobile(...)` session. */
+interface DevicePreset {
+  name: string;
+  viewport: { width: number; height: number };
+  deviceScaleFactor: number;
+  isMobile: boolean;
+  hasTouch: boolean;
+  userAgent: string;
+}
+
+/** The fixed mobile device. Logical resolution + DPR of a current iPhone;
+ *  the UA mirrors what Playwright emits for iOS so RN-Web's mobile branches
+ *  fire. We run Chromium under the hood, so the Safari UA is a deliberate
+ *  emulation lie (same as every device-emulation tool). */
+const LATEST_IPHONE: DevicePreset = {
+  name: "iPhone 15 Pro",
+  viewport: { width: 393, height: 852 },
+  deviceScaleFactor: 3,
+  isMobile: true,
+  hasTouch: true,
+  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",
+};
+
+/** 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. */
+async function applyDeviceEmulation(
+  view: BunWebViewInstance,
+  d: DevicePreset,
+): Promise<void> {
+  try {
+    await view.cdp("Emulation.setDeviceMetricsOverride", {
+      width: d.viewport.width,
+      height: d.viewport.height,
+      deviceScaleFactor: d.deviceScaleFactor,
+      mobile: d.isMobile,
+      screenWidth: d.viewport.width,
+      screenHeight: d.viewport.height,
+    });
+    await view.cdp("Emulation.setUserAgentOverride", { userAgent: d.userAgent });
+    await view.cdp("Emulation.setTouchEmulationEnabled", {
+      enabled: d.hasTouch,
+      maxTouchPoints: 5,
+    });
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn("[spectest] device emulation failed; using desktop view:", err);
+  }
+}
+
 // ────────────────────────────────────────────────────────────────────────
 // rrweb bootstrap
 // ────────────────────────────────────────────────────────────────────────
@@ -572,12 +661,32 @@ export async function prewarmViewPool(n = 1): Promise<void> {
  * the pre-opened pool when the caller uses the default viewport.
  */
 export async function openBrowser(opts: BrowserOptions = {}): Promise<Browser> {
-  const wantW = opts.width ?? 1280;
-  const wantH = opts.height ?? 720;
+  return openMobileBackend(opts);
+}
+
+/**
+ * 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.
+ */
+export async function openMobileBackend(
+  opts: BrowserOptions = {},
+): Promise<MobileBackend> {
+  const device = opts.frame === "mobile" ? LATEST_IPHONE : null;
+  const wantW = device ? device.viewport.width : opts.width ?? 1280;
+  const wantH = device ? device.viewport.height : opts.height ?? 720;
+  // Mobile views are never pooled — the pool holds only default-desktop
+  // views, and a mobile view needs its emulation applied fresh anyway.
   const pooled =
-    wantW === 1280 && wantH === 720 ? VIEW_POOL.pop() : undefined;
+    !device && wantW === 1280 && wantH === 720 ? VIEW_POOL.pop() : undefined;
   const { view, recordingInstalled } = pooled ?? (await createView(wantW, wantH));
 
+  if (device) await applyDeviceEmulation(view, device);
+
   const browser = wrapView(view, opts.recorder ?? null, recordingInstalled);
 
   // We deliberately don't forward `opts.url` to the constructor — going
@@ -593,7 +702,7 @@ function wrapView(
   view: BunWebViewInstance,
   recorder: BrowserSessionRecorder | null,
   recordingInstalled: boolean,
-): Browser {
+): MobileBackend {
   let closed = false;
   const sessionStart = Date.now();
   let stepSeq = 0;
@@ -803,6 +912,44 @@ function wrapView(
         /* already closed by the runtime */
       }
     },
+    // ── Mobile-only primitives ──────────────────────────────────────────
+    tapAt(x, y) {
+      // 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.
+      return instrumented("click", { x, y }, async () => {
+        await view.cdp("Input.dispatchTouchEvent", {
+          type: "touchStart",
+          touchPoints: [{ x, y, id: 0 }],
+        });
+        await view.cdp("Input.dispatchTouchEvent", {
+          type: "touchEnd",
+          touchPoints: [],
+        });
+      });
+    },
+    swipeBy(x, y, dx, dy) {
+      return instrumented("scroll", { dx, dy }, async () => {
+        const steps = 8;
+        await view.cdp("Input.dispatchTouchEvent", {
+          type: "touchStart",
+          touchPoints: [{ x, y, id: 0 }],
+        });
+        for (let i = 1; i <= steps; i++) {
+          await view.cdp("Input.dispatchTouchEvent", {
+            type: "touchMove",
+            touchPoints: [{ x: x + (dx * i) / steps, y: y + (dy * i) / steps, id: 0 }],
+          });
+        }
+        await view.cdp("Input.dispatchTouchEvent", {
+          type: "touchEnd",
+          touchPoints: [],
+        });
+      });
+    },
+    probe<T = unknown>(expression: string): Promise<T> {
+      return view.evaluate<T>(expression);
+    },
   };
 }
 

package/src/components/expo.ts

@@ -0,0 +1,138 @@
+// `expo()` — a ready-to-use service for an Expo / React Native app rendered
+// to the web, built for `ctx.mobile(...)`.
+//
+// Serving model: STATIC EXPORT. The image runs `expo export -p web` at build
+// time (producing `dist/`) and the container just serves those static files
+// with a tiny Node server. No Metro at runtime — so the ready-check is fast
+// and deterministic and the bundle rides the image-layer cache, instead of
+// paying a non-deterministic first-request bundle on every boot.
+//
+// The service's `helpers` factory returns a `MobileApp` handle (the resolved
+// in-VM URL), so a test drives it with `ctx.mobile(ctx.svc.app)` — no URL, no
+// `navigate`.
+
+import type { ServiceDefinition } from "../index.js";
+import { mobileApp } from "../mobile.js";
+import type { MobileApp } from "../mobile.js";
+
+export interface ExpoOptions {
+  /** Port the static server listens on. Default `8081`. */
+  port?: number;
+  /**
+   * App directory inside the project, relative to the build context root.
+   * Default `"."` (the project root is the Expo app). Set this when the
+   * Expo app lives in a subdirectory of a larger repo.
+   */
+  appDir?: string;
+  /** Node base image tag. Default `"20-bookworm-slim"`. */
+  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. */
+  env?: Record<string, string>;
+}
+
+/** The handle `expo()` exposes on `ctx.svc.<name>` — a {@link MobileApp}. */
+export type ExpoHelpers = MobileApp;
+
+// A dependency-free static file server with SPA fallback. Bind-mounted into
+// the container (so it isn't baked into the image build) and run as the
+// container command. Serves `dist/`, falling back to index.html for client
+// routes. Embedded as a file rather than `npx serve` so the container needs
+// no extra install at runtime.
+const STATIC_SERVER = String.raw`import { createServer } from "node:http";
+import { stat, readFile } from "node:fs/promises";
+import { join, extname, normalize, resolve } from "node:path";
+
+const root = resolve(process.argv[2] || "dist");
+const port = Number(process.argv[3] || 8081);
+const TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+  ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
+  ".gif": "image/gif", ".svg": "image/svg+xml", ".ico": "image/x-icon",
+  ".webp": "image/webp", ".woff": "font/woff", ".woff2": "font/woff2",
+  ".ttf": "font/ttf", ".otf": "font/otf", ".wasm": "application/wasm",
+};
+
+async function send(res, fp) {
+  const body = await readFile(fp);
+  res.writeHead(200, { "content-type": TYPES[extname(fp)] || "application/octet-stream" });
+  res.end(body);
+}
+
+createServer(async (req, res) => {
+  try {
+    let p = decodeURIComponent((req.url || "/").split("?")[0]);
+    if (p.endsWith("/")) p += "index.html";
+    let fp = normalize(join(root, p));
+    if (!fp.startsWith(root)) { res.writeHead(403); return res.end("forbidden"); }
+    try {
+      const s = await stat(fp);
+      if (s.isDirectory()) fp = join(fp, "index.html");
+      await send(res, fp);
+    } catch {
+      // SPA fallback: unknown path → index.html.
+      await send(res, join(root, "index.html"));
+    }
+  } catch (e) {
+    res.writeHead(500);
+    res.end(String(e));
+  }
+}).listen(port, "0.0.0.0", () => console.log("[expo-static] serving " + root + " on :" + port));
+`;
+
+/**
+ * A ready-to-use Expo (web) service. Drop into `environment.services` and
+ * drive it with `ctx.mobile`:
+ *
+ * ```ts
+ * services: { app: expo() }
+ * // in a test:
+ * const m = await ctx.mobile(ctx.svc.app);
+ * await m.getByText("Sign in").tap();
+ * ```
+ *
+ * The web build is produced once at image-build time; the container serves
+ * the static bundle. `ctx.svc.<key>` is the app's `MobileApp` handle.
+ */
+export function expo(opts: ExpoOptions = {}) {
+  const port = opts.port ?? 8081;
+  const appDir = opts.appDir ?? ".";
+  const nodeVersion = opts.nodeVersion ?? "20-bookworm-slim";
+  const outputDir = opts.outputDir ?? "dist";
+
+  // CI=1 keeps `expo export` non-interactive. Static export resolves the web
+  // bundle deterministically into `outputDir`.
+  const dockerfile = `FROM node:${nodeVersion}
+WORKDIR /app
+ENV CI=1
+COPY ${appDir}/ ./
+RUN npm install
+RUN npx expo export --platform web --output-dir ${outputDir}
+`;
+
+  return {
+    image: { type: "dockerfile", content: dockerfile },
+    files: [
+      { path: "/spectest-expo-serve.mjs", content: STATIC_SERVER },
+    ],
+    command: `node /spectest-expo-serve.mjs /app/${outputDir} ${port}`,
+    env: { ...(opts.env ?? {}) },
+    ports: [port],
+    readyCheck: { type: "http" as const, port, path: "/", timeoutSecs: 60 },
+    helpers: ({ name }: { name: string }): ExpoHelpers => {
+      // Use the multi-label `<name>.internal` alias (the daemon registers it
+      // for every service) rather than the bare single-label `<name>`:
+      // headless Chromium mishandles a single-label http navigation (it tries
+      // TLS → net::ERR_SSL_PROTOCOL_ERROR), while a dotted host navigates as
+      // plain HTTP. Node-side `fetch` is unaffected, but the mobile session
+      // drives a real browser, so the URL must be browser-navigable.
+      return mobileApp(`http://${name}.internal:${port}`);
+    },
+  } satisfies ServiceDefinition<ExpoHelpers>;
+}

package/src/components/index.ts

@@ -18,6 +18,11 @@ export {
   type K3sHelpers,
   type K3sClient,
 } from "./k3s.js";
+export {
+  expo,
+  type ExpoOptions,
+  type ExpoHelpers,
+} from "./expo.js";
 export {
   replayFake,
   type ReplayFakeOptions,

package/src/daemon.ts

@@ -24,9 +24,19 @@ import net from "node:net";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
-import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard } from "./index.js";
+import {
+  assert,
+  expect,
+  expectRaw,
+  lowerIngress,
+  dnsName as makeDnsDecl,
+  isWildcard,
+  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 type { Mobile, MobileApp } from "./mobile.js";
 import { openTerminal } from "./terminal.js";
 import {
   recordEnv,
@@ -1220,6 +1230,24 @@ const INGRESS_HTTP_SERVERS = new Map<number, any>();
 /** Running HTTPS servers per port (currently always {INGRESS_HTTPS_PORT}). */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const INGRESS_HTTPS_SERVERS = new Map<number, any>();
+/**
+ * Live per-port route tables, keyed by listen port (80 / 443 / fake ports).
+ * Each listener's `fetch` closure captures *this* Map object, so adding an
+ * entry takes effect immediately with no rebind — that's what lets a runtime
+ * `tls` (a `ctx.startService({ tls })`) bind a new ingress route after boot.
+ * Held at module scope so it's part of the live daemon process and forks
+ * with the snapshot, exactly like fake state / the names REGISTRY. Rebuilt on
+ * /load (cleared by {@link stopIngressServers}).
+ */
+const INGRESS_ROUTES_BY_PORT = new Map<number, Map<string, Route>>();
+/**
+ * The :443 SNI cert table: serverName → leaf. Unlike the route table, Bun's
+ * TLS config is fixed at `Bun.serve` time (reload won't add an SNI entry), so
+ * minting a cert for a *new* hostname requires rebinding the :443 listener
+ * (cheap, ~1ms — see {@link rebindHttpsListener}). A hostname already covered
+ * by an existing exact or wildcard cert needs no rebind, just a route entry.
+ */
+const HTTPS_CERT_BY_HOST = new Map<string, { cert: string; key: string }>();
 
 /**
  * Tear down listener servers between /load calls so the new project's
@@ -1244,6 +1272,8 @@ function stopIngressServers(): void {
     }
   }
   INGRESS_HTTPS_SERVERS.clear();
+  INGRESS_ROUTES_BY_PORT.clear();
+  HTTPS_CERT_BY_HOST.clear();
 }
 
 function buildIngress(project: Project): void {
@@ -1439,12 +1469,11 @@ async function startIngress(): Promise<void> {
   // before binding so the HTTPS listener has certs ready and a startup
   // failure aborts /bootstrap cleanly.
   const caPresent = existsSync(CA_PATH) && existsSync(CA_KEY_PATH);
-  const certByHost = new Map<string, { cert: string; key: string }>();
   if (caPresent) {
     for (const group of LOWERED.certificates) {
       if (group.hostnames.length === 0) continue;
       const leaf = await generateHostCert(group.hostnames[0], group.hostnames);
-      for (const h of group.hostnames) certByHost.set(h, leaf);
+      for (const h of group.hostnames) HTTPS_CERT_BY_HOST.set(h, leaf);
     }
   } else if (LOWERED.certificates.length > 0) {
     // eslint-disable-next-line no-console
@@ -1453,73 +1482,49 @@ async function startIngress(): Promise<void> {
     );
   }
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const Bun = (globalThis as any).Bun;
-  if (!Bun?.serve) {
-    throw new Error(
-      "ingress requires Bun.serve; the daemon must run under Bun (it does in-VM)",
-    );
-  }
-
-  // Resolve every ingress hostname to its handler. Fakes run an in-daemon
-  // handler; proxies reverse-proxy to a service:port. This single table
-  // drives both the HTTP and HTTPS listeners.
-  const routeByHost = new Map<string, Route>();
-  for (const fake of FAKES.values()) {
-    for (const h of fake.hostnames) routeByHost.set(h, { kind: "fake", fake });
-  }
-  for (const p of LOWERED.proxies) {
-    routeByHost.set(p.hostname, { kind: "proxy", service: p.service, port: p.port });
-  }
+  const Bun = requireBun();
 
-  // ── HTTP listeners: group routes by port, dispatch per-request by Host.
-  //    Proxies bind :80 (HTTPS, if any, is on :443); fakes use their
-  //    declared port. Skip :443 in the HTTP map — HTTPS wins.
-  const httpRoutesByPort = new Map<number, Map<string, Route>>();
+  // Resolve every ingress hostname to its handler into the live per-port
+  // route tables (module scope, so runtime `tls` can extend them later).
+  // Fakes run an in-daemon handler on their declared port; proxies
+  // reverse-proxy to a service:port and bind :80 (HTTPS, if any, is :443).
   const ensurePort = (port: number): Map<string, Route> => {
-    const m = httpRoutesByPort.get(port) ?? new Map<string, Route>();
-    httpRoutesByPort.set(port, m);
+    const m = INGRESS_ROUTES_BY_PORT.get(port) ?? new Map<string, Route>();
+    INGRESS_ROUTES_BY_PORT.set(port, m);
     return m;
   };
   for (const fake of FAKES.values()) {
     if (fake.port === INGRESS_HTTPS_PORT) continue;
     const routes = ensurePort(fake.port);
-    for (const h of fake.hostnames) routes.set(h, routeByHost.get(h)!);
+    for (const h of fake.hostnames) routes.set(h, { kind: "fake", fake });
   }
   if (LOWERED.proxies.length > 0) {
     const routes = ensurePort(INGRESS_HTTP_PORT);
-    for (const p of LOWERED.proxies) routes.set(p.hostname, routeByHost.get(p.hostname)!);
+    for (const p of LOWERED.proxies) {
+      routes.set(p.hostname, { kind: "proxy", service: p.service, port: p.port });
+    }
   }
-  for (const [port, byHost] of httpRoutesByPort) {
-    const label = `port ${port}`;
-    INGRESS_HTTP_SERVERS.set(port, bindIngressServer(Bun, port, byHost, label));
-    const hosts = [...byHost.keys()].join(", ");
-    // eslint-disable-next-line no-console
-    console.log(`[ingress] http :${port} for ${hosts}`);
+  // The :443 route table mirrors every certificated hostname's handler.
+  if (HTTPS_CERT_BY_HOST.size > 0) {
+    const httpsRoutes = ensurePort(INGRESS_HTTPS_PORT);
+    for (const h of HTTPS_CERT_BY_HOST.keys()) {
+      for (const fake of FAKES.values()) {
+        if (fake.hostnames.includes(h)) httpsRoutes.set(h, { kind: "fake", fake });
+      }
+      const proxy = LOWERED.proxies.find((p) => p.hostname === h);
+      if (proxy) httpsRoutes.set(h, { kind: "proxy", service: proxy.service, port: proxy.port });
+    }
   }
 
-  // ── HTTPS listener on INGRESS_HTTPS_PORT: SNI per certificated hostname.
-  if (certByHost.size > 0) {
-    const tlsEntries: Array<{ cert: string; key: string; serverName: string }> = [];
-    const byHostHttps = new Map<string, Route>();
-    for (const [h, leaf] of certByHost) {
-      tlsEntries.push({ cert: leaf.cert, key: leaf.key, serverName: h });
-      const route = routeByHost.get(h);
-      if (route) byHostHttps.set(h, route);
-    }
-    const label = `https :${INGRESS_HTTPS_PORT}`;
-    const server = bindIngressServer(
-      Bun,
-      INGRESS_HTTPS_PORT,
-      byHostHttps,
-      label,
-      tlsEntries,
-    );
-    INGRESS_HTTPS_SERVERS.set(INGRESS_HTTPS_PORT, server);
-    const hosts = [...byHostHttps.keys()].join(", ");
+  // ── HTTP listeners (one per non-443 port).
+  for (const [port, byHost] of INGRESS_ROUTES_BY_PORT) {
+    if (port === INGRESS_HTTPS_PORT) continue;
+    INGRESS_HTTP_SERVERS.set(port, bindIngressServer(Bun, port, byHost, `port ${port}`));
     // eslint-disable-next-line no-console
-    console.log(`[ingress] https :${INGRESS_HTTPS_PORT} for ${hosts}`);
+    console.log(`[ingress] http :${port} for ${[...byHost.keys()].join(", ")}`);
   }
+  // ── HTTPS listener on INGRESS_HTTPS_PORT: SNI per certificated hostname.
+  if (HTTPS_CERT_BY_HOST.size > 0) rebindHttpsListener(Bun);
 
   // Seed the resolver's names registry: ingress hostnames (fakes, TLS
   // proxies, dnsName(→ingress)) → bridge gateway, plus ingress-targeted
@@ -1528,6 +1533,148 @@ async function startIngress(): Promise<void> {
   await seedNamesRegistry({ servicesUp: false });
 }
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function requireBun(): any {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const Bun = (globalThis as any).Bun;
+  if (!Bun?.serve) {
+    throw new Error(
+      "ingress requires Bun.serve; the daemon must run under Bun (it does in-VM)",
+    );
+  }
+  return Bun;
+}
+
+/** Flatten {@link HTTPS_CERT_BY_HOST} into Bun's TLS-entry SNI array. */
+function tlsEntriesFromCerts(): Array<{ cert: string; key: string; serverName: string }> {
+  return [...HTTPS_CERT_BY_HOST].map(([serverName, leaf]) => ({
+    cert: leaf.cert,
+    key: leaf.key,
+    serverName,
+  }));
+}
+
+/**
+ * (Re)bind the :443 listener from the current cert table + route map. Bun's
+ * TLS config is immutable per `Bun.serve`, so adding an SNI cert means
+ * stopping the old listener and serving a fresh one — cheap (~1ms) and the
+ * window is sub-millisecond. The route Map is the persistent module object,
+ * so the new listener closes over the same table (later route additions need
+ * no rebind). No-ops to a plain rebind when only routes changed.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function rebindHttpsListener(Bun: any): void {
+  const routes = INGRESS_ROUTES_BY_PORT.get(INGRESS_HTTPS_PORT) ?? new Map<string, Route>();
+  INGRESS_ROUTES_BY_PORT.set(INGRESS_HTTPS_PORT, routes);
+  const old = INGRESS_HTTPS_SERVERS.get(INGRESS_HTTPS_PORT);
+  if (old) {
+    try {
+      old.stop(true);
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn("[ingress] failed to stop https listener for rebind:", err);
+    }
+  }
+  const server = bindIngressServer(
+    Bun,
+    INGRESS_HTTPS_PORT,
+    routes,
+    `https :${INGRESS_HTTPS_PORT}`,
+    tlsEntriesFromCerts(),
+  );
+  INGRESS_HTTPS_SERVERS.set(INGRESS_HTTPS_PORT, server);
+  // eslint-disable-next-line no-console
+  console.log(`[ingress] https :${INGRESS_HTTPS_PORT} for ${[...routes.keys()].join(", ")}`);
+}
+
+/** True if an exact or wildcard cert already covers `hostname` for SNI. */
+function certCovers(hostname: string): boolean {
+  if (HTTPS_CERT_BY_HOST.has(hostname)) return true;
+  for (const serverName of HTTPS_CERT_BY_HOST.keys()) {
+    if (isWildcard(serverName) && hostname.endsWith(wildcardSuffix(serverName))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Bind a runtime ingress route for one `tls: [{ hostname, port }]` entry on a
+ * {@link RuntimeServiceSpec} — the runtime twin of a boot service's `tls`.
+ * Mints a leaf cert (unless one already covers the hostname), stands up a
+ * TLS-terminating reverse proxy at `https://<hostname>/` → `service:port`,
+ * also serves plain `http://<hostname>/`, and points the hostname at the
+ * daemon gateway in the resolver registry. Idempotent per hostname.
+ *
+ * Everything it mutates (the live route tables, the :443 cert table, the
+ * names REGISTRY) is daemon-process state, so the binding forks with the
+ * per-test snapshot exactly like fake state — a `dependsOn` child inherits
+ * it, siblings forked from an earlier snapshot never see it.
+ */
+async function bindRuntimeTls(hostname: string, service: string, port: number): Promise<void> {
+  // Reuse the boot primitives for validation + lowercasing; throws on a
+  // malformed hostname / upstream just like a boot `tls` would at load.
+  const decl = makeProxyDecl(hostname, { service, port });
+  const host = decl.hostname;
+  if (!existsSync(CA_PATH) || !existsSync(CA_KEY_PATH)) {
+    throw new Error(
+      `runtime tls for ${JSON.stringify(host)} requires the in-VM root CA at ${CA_PATH}`,
+    );
+  }
+  const Bun = requireBun();
+  const route: Route = { kind: "proxy", service, port };
+
+  // Plain HTTP on :80 (parity with boot `tls`, which serves both schemes).
+  let httpRoutes = INGRESS_ROUTES_BY_PORT.get(INGRESS_HTTP_PORT);
+  if (!httpRoutes) {
+    httpRoutes = new Map<string, Route>();
+    INGRESS_ROUTES_BY_PORT.set(INGRESS_HTTP_PORT, httpRoutes);
+  }
+  httpRoutes.set(host, route);
+  if (!INGRESS_HTTP_SERVERS.has(INGRESS_HTTP_PORT)) {
+    INGRESS_HTTP_SERVERS.set(
+      INGRESS_HTTP_PORT,
+      bindIngressServer(Bun, INGRESS_HTTP_PORT, httpRoutes, `port ${INGRESS_HTTP_PORT}`),
+    );
+  }
+
+  // HTTPS on :443. A new cert forces a listener rebind; an already-covered
+  // hostname (exact dup or a boot wildcard) just needs the route entry.
+  const needCert = !certCovers(host);
+  if (needCert) {
+    HTTPS_CERT_BY_HOST.set(host, await generateHostCert(host, [host]));
+  }
+  const httpsRoutes = INGRESS_ROUTES_BY_PORT.get(INGRESS_HTTPS_PORT) ?? new Map<string, Route>();
+  INGRESS_ROUTES_BY_PORT.set(INGRESS_HTTPS_PORT, httpsRoutes);
+  httpsRoutes.set(host, route);
+  if (needCert || !INGRESS_HTTPS_SERVERS.has(INGRESS_HTTPS_PORT)) {
+    rebindHttpsListener(Bun);
+  }
+
+  // Resolve the hostname to the daemon gateway (where :443/:80 listen).
+  const gw = await bridgeGatewayIp();
+  REGISTRY.hosts[host] = gw;
+  await writeRegistry();
+  // eslint-disable-next-line no-console
+  console.log(`[ingress] runtime https ${host} -> ${service}:${port}`);
+}
+
+/**
+ * Undo {@link bindRuntimeTls} for one hostname when its runtime service is
+ * stopped: drop the route (so it 404s) and the registry entry. The cert is
+ * left in the SNI table — harmless without a route, and removing it would
+ * mean an avoidable :443 rebind.
+ */
+async function unbindRuntimeTls(hostname: string): Promise<void> {
+  const host = hostname.toLowerCase();
+  INGRESS_ROUTES_BY_PORT.get(INGRESS_HTTP_PORT)?.delete(host);
+  INGRESS_ROUTES_BY_PORT.get(INGRESS_HTTPS_PORT)?.delete(host);
+  if (host in REGISTRY.hosts) {
+    delete REGISTRY.hosts[host];
+    await writeRegistry();
+  }
+}
+
 /**
  * Spin up one Bun.serve listener bound to (port, optional TLS) that
  * dispatches every request to the matching Route by Host header.
@@ -2018,6 +2165,11 @@ async function startRuntimeService(spec: RuntimeServiceSpec): Promise<RuntimeSer
     await runContainer(svc, tag, flags, aliases);
     await waitForReady(svc);
     const ip = (await serviceContainerIp(svc.name)) ?? "";
+    // `tls` is the runtime twin of a boot service's: stand up a
+    // TLS-terminating reverse proxy at https://<hostname>/ → this container.
+    for (const entry of svc.tls ?? []) {
+      await bindRuntimeTls(entry.hostname, svc.name, entry.port);
+    }
     RUNTIME_SERVICES.set(svc.name, svc);
     recordEnv({
       op: "startService",
@@ -2044,8 +2196,10 @@ async function startRuntimeService(spec: RuntimeServiceSpec): Promise<RuntimeSer
 async function stopRuntimeService(name: string): Promise<void> {
   const t0 = Date.now();
   const resv = reserveEvent();
+  const svc = RUNTIME_SERVICES.get(name);
   await docker(["rm", "-f", name], 30_000);
   RUNTIME_SERVICES.delete(name);
+  for (const entry of svc?.tls ?? []) await unbindRuntimeTls(entry.hostname);
   recordEnv({ op: "stopService", service: name, durationMs: Date.now() - t0 }, resv);
 }
 
@@ -2521,6 +2675,10 @@ interface BrowserSessionRecord {
   openedAtMs: number;
   closedAtMs?: number;
   initialUrl?: string;
+  /** Replay frame: `"browser"` (desktop window, default) or `"mobile"`
+   * (phone bezel). Drives the dashboard's chrome; the rrweb events are
+   * identical either way. */
+  frame?: "browser" | "mobile";
   steps: BrowserSessionStep[];
 }
 
@@ -2546,7 +2704,11 @@ function newSessionId(idScope: string): string {
  * The returned `recorder` is what `openBrowser` writes into; the
  * returned `record` is the in-flight session object the daemon owns.
  */
-function newBrowserSession(testStart: number, idScope: string): {
+function newBrowserSession(
+  testStart: number,
+  idScope: string,
+  frame: "browser" | "mobile" = "browser",
+): {
   recorder: BrowserSessionRecorder;
   record: BrowserSessionRecord;
   markClosed(): void;
@@ -2554,6 +2716,7 @@ function newBrowserSession(testStart: number, idScope: string): {
   const record: BrowserSessionRecord = {
     sessionId: newSessionId(idScope),
     openedAtMs: Date.now() - testStart,
+    frame,
     steps: [],
   };
   let closed = false;
@@ -3252,7 +3415,9 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
   // 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 persisted to SQLite.
-  const openBrowsers: Browser[] = [];
+  // 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> }> = [];
   const sessions: Array<ReturnType<typeof newBrowserSession>> = [];
   const trackedOpenBrowser = async (opts?: BrowserOptions): Promise<Browser> => {
     const session = newBrowserSession(start, testCase.id);
@@ -3261,6 +3426,18 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     openBrowsers.push(b);
     return b;
   };
+  const trackedOpenMobile = async (app: MobileApp): Promise<Mobile> => {
+    if (!isMobileApp(app)) {
+      throw new Error(
+        "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 session = newBrowserSession(start, testCase.id, "mobile");
+    sessions.push(session);
+    const m = await openMobile({ url: app.url, recorder: session.recorder });
+    openBrowsers.push(m);
+    return m;
+  };
 
   // Build convenience handles (e.g. ctx.svc.db.client) from the loaded
   // project. Done before installing the timeout so a slow client factory
@@ -3281,6 +3458,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     terminal: recordedTerminal as unknown as TestContext<unknown>["terminal"],
     openTerminal: recordedOpenTerminal,
     browser: trackedOpenBrowser,
+    mobile: trackedOpenMobile,
     testName: testCase.name,
     parent,
     svc,
@@ -3509,7 +3687,7 @@ async function evalCode(
   // wrapped type is honest at runtime). Restored in the `finally` below.
   const restoreFetch = installFetchWrapper();
 
-  const openBrowsers: Browser[] = [];
+  const openBrowsers: Array<{ close(): Promise<void> }> = [];
   const sessions: Array<ReturnType<typeof newBrowserSession>> = [];
   const trackedOpenBrowser = async (opts?: BrowserOptions): Promise<Browser> => {
     const session = newBrowserSession(start, "eval");
@@ -3518,6 +3696,18 @@ async function evalCode(
     openBrowsers.push(b);
     return b;
   };
+  const trackedOpenMobile = async (app: MobileApp): Promise<Mobile> => {
+    if (!isMobileApp(app)) {
+      throw new Error(
+        "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 session = newBrowserSession(start, "eval", "mobile");
+    sessions.push(session);
+    const m = await openMobile({ url: app.url, recorder: session.recorder });
+    openBrowsers.push(m);
+    return m;
+  };
 
   // Terminal sessions — same shape as runOne, but eval has no active
   // recorder so we don't emit inline events; the asciicast frames
@@ -3580,6 +3770,7 @@ async function evalCode(
     terminal: evalTerminal as unknown as TestContext<undefined>["terminal"],
     openTerminal: evalOpenTerminal,
     browser: trackedOpenBrowser,
+    mobile: trackedOpenMobile,
     testName: "eval",
     parent: undefined,
     svc,

package/src/index.ts

@@ -42,6 +42,13 @@ export type {
 
 import type { Browser, BrowserOptions } from "./browser.js";
 
+// Mobile (Expo / React Native Web) surface: a phone-emulated session driven
+// with locators + touch gestures, replayed inside a phone bezel. Opened with
+// `ctx.mobile(ctx.svc.app)` where the app is registered via the `expo()`
+// component.
+export type { Mobile, MobileLocator, MobileApp } from "./mobile.js";
+import type { Mobile, MobileApp } from "./mobile.js";
+
 export type { Terminal, TerminalOpts, TerminalResult } from "./terminal.js";
 
 import type { Terminal, TerminalOpts, TerminalResult } from "./terminal.js";
@@ -341,22 +348,28 @@ export type ReadyCheck =
 /**
  * Spec for a service started at runtime via {@link TestContext.startService}
  * (or the `ctx` handed to a fake). It's a normal {@link ServiceConfig} plus a
- * required `name`, minus the two fields that only make sense at boot:
- *
- *  - `tls` — runtime services are reached *directly* by their own IP on
- *    `spectest-net` (like a real machine on a network), not through the
- *    daemon's HTTP ingress, so there's no proxy/cert to configure. Map a
- *    friendly DNS name onto one with {@link TestContext.dnsName}.
- *  - `dependsOn` — there is no boot DAG at runtime; the caller orders
- *    `startService` calls itself with `await`.
+ * required `name`, minus only `dependsOn` (there is no boot DAG at runtime;
+ * the caller orders `startService` calls itself with `await`).
  *
  * The container joins `spectest-net` with its own IP and is resolvable by
  * `name` (single-label, via the resolver / docker embedded DNS) and by any
  * `hostnames` (extra `--network-alias`es). Like everything else in the VM it
  * is captured by the per-test post-state snapshot, so a `dependsOn` child
  * inherits the live container while siblings never see it.
+ *
+ * `tls: [{ hostname, port }]` works exactly as it does for a boot service:
+ * the daemon mints a leaf cert from the in-VM root CA and stands up a
+ * TLS-terminating reverse proxy at `https://<hostname>/` (and plain
+ * `http://<hostname>/`) → the container's `port`, binding it onto the live
+ * `:443`/`:80` ingress listeners the moment the container is ready. The
+ * hostname resolves to the daemon gateway for tests, `ctx.browser()`, and
+ * peer containers. Because the route lives in daemon memory (and the
+ * resolver registry file), it forks with the per-test snapshot like fake
+ * state, and is torn down when the service is stopped. This lets a runtime
+ * provider mint a CA-trusted HTTPS endpoint on demand — e.g. a per-DB proxy
+ * the Neon serverless driver reaches at its *default* `https://<host>/sql`.
  */
-export interface RuntimeServiceSpec extends Omit<ServiceConfig, "tls" | "dependsOn"> {
+export interface RuntimeServiceSpec extends Omit<ServiceConfig, "dependsOn"> {
   /**
    * Container name and primary DNS name on `spectest-net`. Must be unique
    * within the current fork — generate a fresh one per provisioned instance
@@ -602,6 +615,26 @@ export interface TestContext<
    * release earlier if you're opening many.
    */
   browser(opts?: BrowserOptions): Promise<Browser>;
+  /**
+   * Open a phone-emulated session for a mobile app and return a {@link Mobile}
+   * handle already pointed at it — no `navigate`. Pass the app handle a
+   * mobile-app component exposes on `ctx.svc`, e.g. a service declared with
+   * `expo()`:
+   *
+   * ```ts
+   * services: { app: expo() }
+   * // in a test:
+   * const m = await ctx.mobile(ctx.svc.app);
+   * await m.getByTestId("email").typeText("a@b.com");
+   * await m.getByText("Sign in").tap();
+   * await m.getByText(/Welcome/).assertVisible();
+   * ```
+   *
+   * 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.
+   */
+  mobile(app: MobileApp): Promise<Mobile>;
   /** The test's display name. */
   readonly testName: string;
   /**

package/src/inspect.ts

@@ -44,8 +44,20 @@
 // `Carrier<T>` honest at runtime everywhere, instead of silently collapsing to
 // a raw value wherever recording happened to be off.
 
-export const OP_TAG = Symbol("spectest.opTag");
-export const UNWRAP = Symbol("spectest.unwrap");
+// Registered in the GLOBAL symbol registry (`Symbol.for`), not module-private
+// (`Symbol`), so a value tagged by ONE copy of this module unwraps correctly in
+// ANOTHER. This matters whenever two copies of the SDK load in the same runtime:
+// the in-VM daemon runs the baked SDK at /opt/spectest/sdk and mints the
+// provenance carriers (ctx.fetch / ctx.browser / db results), while a user's
+// test file resolving `@specific.dev/spectest` to a registry-pinned copy gets
+// its `expect`. With module-private symbols the two `UNWRAP`s differed, so
+// `expect`'s auto-unwrap silently no-op'd and wrapped assertions failed
+// nonsensically (`expect("Hello Spec").toContain("Hello")` -> false). The
+// control plane also repoints the dep at the baked copy so normally only one
+// copy loads; this is defense-in-depth for the cases where it can't (and only
+// takes full effect once both copies ship this `Symbol.for`).
+export const OP_TAG = Symbol.for("spectest.opTag");
+export const UNWRAP = Symbol.for("spectest.unwrap");
 
 // The escape hatch from a wrapped value to its raw form is the `.unwrap()`
 // method that lives on the `Carrier` / `WrappedObject` / `WrappedArray` /

package/src/mobile.ts

@@ -0,0 +1,379 @@
+// Mobile app handle for tests — drives an Expo/React-Native-Web app rendered
+// in a phone-emulated headless Chromium and recorded as an rrweb session that
+// the dashboard replays inside a phone bezel.
+//
+// `ctx.mobile(ctx.svc.app)` opens one of these already pointed at the app, so
+// there's no `navigate`. The surface is mobile-native (tap/typeText/swipe,
+// select-then-act locators that lean on testID) rather than the desktop
+// `Browser` verbs — see DESIGN. Under the hood it's a thin facade over a
+// `MobileBackend` (browser.ts): the heavy lifting (CDP device emulation, the
+// recorder, rrweb capture/drain) is shared with the desktop browser; this
+// file only adds the locator/gesture ergonomics.
+//
+// React Native Web renders `testID="x"` to `data-testid="x"` and
+// `accessibilityLabel` to `aria-label`, so `getByTestId`/`getByLabel` map to
+// plain DOM attribute selectors with no shimming.
+
+import { openMobileBackend } from "./browser.js";
+import type {
+  BrowserSessionRecorder,
+  MobileBackend,
+  ScreenshotOptions,
+} from "./browser.js";
+import type { Wrapped } from "./inspect.js";
+
+/** Branded handle a mobile-app component (e.g. `expo()`) exposes on
+ *  `ctx.svc.<name>`. The brand is a `Symbol.for` key so `JSON.stringify`
+ *  drops it (wire-invisible) while `ctx.mobile(...)` can still type-check
+ *  against it. */
+export const MOBILE_APP: unique symbol = Symbol.for("spectest.mobileApp");
+
+/** What `ctx.mobile(...)` accepts — produced by a mobile-app component's
+ *  `helpers` factory. Carries the in-VM URL the session auto-navigates to. */
+export interface MobileApp {
+  readonly [MOBILE_APP]: true;
+  /** Resolved in-VM URL of the app's web build (e.g. `http://app.internal:8081`). */
+  readonly url: string;
+}
+
+/** True if `x` is a {@link MobileApp} handle. */
+export function isMobileApp(x: unknown): x is MobileApp {
+  return (
+    typeof x === "object" &&
+    x !== null &&
+    (x as Record<symbol, unknown>)[MOBILE_APP] === true &&
+    typeof (x as { url?: unknown }).url === "string"
+  );
+}
+
+/** Build a {@link MobileApp} handle from a resolved URL. */
+export function mobileApp(url: string): MobileApp {
+  return { [MOBILE_APP]: true, url };
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Locators
+// ────────────────────────────────────────────────────────────────────────
+
+interface LocatorDesc {
+  kind: "testid" | "text" | "role" | "label" | "css";
+  value: string;
+  exact?: boolean;
+  regex?: { source: string; flags: string };
+  name?: string;
+  nameExact?: boolean;
+}
+
+/** A lazy reference to a single element, resolved (with auto-wait) at the
+ *  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>;
+  /** Tap to focus, then type `text` via real key events. */
+  typeText(text: string): Promise<void>;
+  /** Clear a text input's current value (RN-Web controlled input safe). */
+  clearText(): 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). */
+  waitFor(opts?: { timeoutMs?: number }): Promise<void>;
+  /** Assert the element becomes visible within the timeout (throws otherwise). */
+  assertVisible(opts?: { timeoutMs?: number }): Promise<void>;
+  /** Whether the element is currently present and visible. Wrapped so an
+   *  `expect(...)` on it nests under the read in the timeline. */
+  isVisible(): Promise<Wrapped<boolean>>;
+  /** The element's trimmed text content (or `null` if absent), wrapped. */
+  textContent(): Promise<Wrapped<string | null>>;
+}
+
+/** Build the in-page resolver expression for a descriptor. Returns the
+ *  matched element's center coords + visibility + text, or `{found:false}`.
+ *  `scroll` centers the element first (so a tap can reach an offscreen
+ *  target). Pure string ops — no regex literals — so it survives the
+ *  template-literal escaping. */
+function resolveExpr(desc: LocatorDesc, scroll: boolean): string {
+  return `(function(){
+    var desc = ${JSON.stringify(desc)};
+    var doScroll = ${scroll ? "true" : "false"};
+    function visible(el){
+      if(!el) return false;
+      var cs = window.getComputedStyle(el);
+      if(cs.display==='none'||cs.visibility==='hidden') return false;
+      if(parseFloat(cs.opacity||'1')===0) return false;
+      var r = el.getBoundingClientRect();
+      return r.width>0 && r.height>0;
+    }
+    function txt(el){ return (el.textContent||'').split(/\\s+/).join(' ').trim(); }
+    function esc(v){ return String(v).split('"').join('\\\\"'); }
+    function matchesText(el){
+      var t = txt(el);
+      if(desc.regex){ try{ return new RegExp(desc.regex.source, desc.regex.flags).test(t); }catch(e){ return false; } }
+      if(desc.exact) return t === desc.value;
+      return t.indexOf(desc.value) >= 0;
+    }
+    function collect(){
+      if(desc.kind==='css') return [].slice.call(document.querySelectorAll(desc.value));
+      if(desc.kind==='testid') return [].slice.call(document.querySelectorAll('[data-testid="'+esc(desc.value)+'"]'));
+      if(desc.kind==='label') return [].slice.call(document.querySelectorAll('[aria-label="'+esc(desc.value)+'"]'));
+      if(desc.kind==='role'){
+        var implicit = { button:'button,[type=button],[type=submit]', link:'a[href]', heading:'h1,h2,h3,h4,h5,h6', textbox:'input,textarea', img:'img', list:'ul,ol', listitem:'li', checkbox:'[type=checkbox]' };
+        var sel = '[role="'+esc(desc.value)+'"]';
+        if(implicit[desc.value]) sel += ','+implicit[desc.value];
+        var cands = [].slice.call(document.querySelectorAll(sel));
+        if(desc.name){
+          cands = cands.filter(function(el){
+            var n = el.getAttribute('aria-label') || txt(el);
+            return desc.nameExact ? n===desc.name : n.indexOf(desc.name)>=0;
+          });
+        }
+        return cands;
+      }
+      if(desc.kind==='text'){
+        var all = [].slice.call(document.querySelectorAll('body *'));
+        var hits = all.filter(matchesText);
+        // Keep only the innermost matches (drop ancestors of another hit).
+        return hits.filter(function(el){ return !hits.some(function(o){ return o!==el && el.contains(o); }); });
+      }
+      return [];
+    }
+    var els = collect();
+    var el = null;
+    for(var i=0;i<els.length;i++){ if(visible(els[i])){ el = els[i]; break; } }
+    if(!el) el = els[0] || null;
+    if(!el) return { found:false };
+    if(doScroll){ try{ el.scrollIntoView({block:'center', inline:'center'}); }catch(e){} }
+    var r = el.getBoundingClientRect();
+    return { found:true, visible: visible(el), x: r.left + r.width/2, y: r.top + r.height/2, text: txt(el) };
+  })()`;
+}
+
+interface ResolveResult {
+  found: boolean;
+  visible?: boolean;
+  x?: number;
+  y?: number;
+  text?: string | null;
+}
+
+/** Short human label for a descriptor, used in event descriptions. */
+function descLabel(desc: LocatorDesc): string {
+  if (desc.kind === "text") {
+    return desc.regex ? `text /${desc.regex.source}/` : `text ${JSON.stringify(desc.value)}`;
+  }
+  if (desc.kind === "role") {
+    return desc.name ? `role ${desc.value} ${JSON.stringify(desc.name)}` : `role ${desc.value}`;
+  }
+  return `${desc.kind} ${JSON.stringify(desc.value)}`;
+}
+
+function makeLocator(backend: MobileBackend, desc: LocatorDesc): MobileLocator {
+  const label = descLabel(desc);
+
+  // Poll the unrecorded resolver until the element is visible. Returns the
+  // tap coordinates. Throws a clear error on timeout.
+  async function waitCoords(timeoutMs: number): Promise<{ x: number; y: number }> {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      const r = await backend.probe<ResolveResult>(resolveExpr(desc, true));
+      if (r.found && r.visible && typeof r.x === "number" && typeof r.y === "number") {
+        return { x: r.x, y: r.y };
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(`mobile: ${label} not visible after ${timeoutMs}ms`);
+      }
+      await new Promise((res) => setTimeout(res, 100));
+    }
+  }
+
+  return {
+    async tap() {
+      const { x, y } = await waitCoords(5_000);
+      await backend.tapAt(x, y);
+    },
+    async typeText(text) {
+      const { x, y } = await waitCoords(5_000);
+      await backend.tapAt(x, y);
+      await backend.type(text);
+    },
+    async clearText() {
+      await waitCoords(5_000);
+      // Native value-setter + input event so RN-Web's controlled TextInput
+      // sees the change (a plain `.value = ""` is swallowed by React).
+      await backend.evaluate(
+        `clear ${label}`,
+        `(function(){
+          var r = ${resolveExpr(desc, false)};
+          var el = document.activeElement;
+          if(!el || !('value' in el)) return false;
+          var proto = el.tagName==='TEXTAREA' ? window.HTMLTextAreaElement.prototype : window.HTMLInputElement.prototype;
+          var setter = Object.getOwnPropertyDescriptor(proto,'value').set;
+          setter.call(el, '');
+          el.dispatchEvent(new Event('input', { bubbles: true }));
+          return true;
+        })()`,
+      );
+    },
+    async scrollIntoView() {
+      // Routed through the recorded evaluate so the scroll lands in the replay.
+      await backend.evaluate(`scrollIntoView ${label}`, resolveExpr(desc, true));
+    },
+    async waitFor(opts) {
+      await backend.waitFor(
+        `${label} visible`,
+        `(function(){ var r = ${resolveExpr(desc, false)}; return (r.found && r.visible) ? r : null; })()`,
+        { timeoutMs: opts?.timeoutMs ?? 5_000 },
+      );
+    },
+    async assertVisible(opts) {
+      try {
+        await this.waitFor(opts);
+      } catch {
+        throw new Error(`expected ${label} to be visible`);
+      }
+    },
+    isVisible() {
+      return backend.evaluate<boolean>(
+        `${label} visible?`,
+        `(function(){ var r = ${resolveExpr(desc, false)}; return !!(r.found && r.visible); })()`,
+      );
+    },
+    textContent() {
+      return backend.evaluate<string | null>(
+        `${label} text`,
+        `(function(){ var r = ${resolveExpr(desc, false)}; return r.found ? r.text : null; })()`,
+      );
+    },
+  };
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Mobile session
+// ────────────────────────────────────────────────────────────────────────
+
+/** A phone-emulated app session. Opened via `ctx.mobile(app)` already on the
+ *  app, so there is no `navigate`; interactions are mobile-native. */
+export interface Mobile {
+  /** Current page URL. */
+  readonly url: string;
+  /** Current page `<title>`. */
+  readonly title: string;
+  /** Select by `testID` (RN-Web `data-testid`). The primary mobile selector. */
+  getByTestId(testId: string): MobileLocator;
+  /** Select by visible text (substring by default; pass a RegExp for patterns). */
+  getByText(text: string | RegExp, opts?: { exact?: boolean }): MobileLocator;
+  /** Select by ARIA role, optionally narrowed by accessible name. */
+  getByRole(role: string, opts?: { name?: string; exact?: boolean }): MobileLocator;
+  /** Select by `accessibilityLabel` (RN-Web `aria-label`). */
+  getByLabel(text: string): MobileLocator;
+  /** Escape hatch: select by a raw CSS selector. */
+  locator(css: string): MobileLocator;
+  /** 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. */
+  scroll(dx: number, dy: number): Promise<void>;
+  /** Press a named key (`"Enter"`, `"Backspace"`, …) on the focused element. */
+  pressKey(key: string): Promise<void>;
+  /** Navigate back in history (the device back gesture). */
+  back(): Promise<void>;
+  /** Low-level escape hatch: evaluate JS in the page (recorded, wrapped). */
+  evaluate<T = unknown>(description: string, script: string): Promise<Wrapped<T>>;
+  /** Low-level escape hatch: poll a JS expression until truthy (recorded). */
+  waitFor<T = unknown>(
+    description: string,
+    expression: string,
+    options?: { timeoutMs?: number; intervalMs?: number },
+  ): Promise<Wrapped<T>>;
+  /** Capture a screenshot of the viewport. */
+  screenshot(options?: ScreenshotOptions): Promise<Uint8Array>;
+  /** Close the session. Idempotent; drains pending rrweb events. */
+  close(): Promise<void>;
+}
+
+function wrapMobile(backend: MobileBackend): Mobile {
+  return {
+    get url() {
+      return backend.url;
+    },
+    get title() {
+      return backend.title;
+    },
+    getByTestId(testId) {
+      return makeLocator(backend, { kind: "testid", value: testId });
+    },
+    getByText(text, opts) {
+      if (text instanceof RegExp) {
+        return makeLocator(backend, {
+          kind: "text",
+          value: text.source,
+          regex: { source: text.source, flags: text.flags },
+        });
+      }
+      return makeLocator(backend, { kind: "text", value: text, exact: opts?.exact });
+    },
+    getByRole(role, opts) {
+      return makeLocator(backend, {
+        kind: "role",
+        value: role,
+        name: opts?.name,
+        nameExact: opts?.exact,
+      });
+    },
+    getByLabel(text) {
+      return makeLocator(backend, { kind: "label", value: text });
+    },
+    locator(css) {
+      return makeLocator(backend, { kind: "css", value: css });
+    },
+    async swipe(direction, opts) {
+      const vp = await backend.probe<{ w: number; h: number }>(
+        "({ w: window.innerWidth, h: window.innerHeight })",
+      );
+      const cx = vp.w / 2;
+      const cy = vp.h / 2;
+      const horiz = direction === "left" || direction === "right";
+      const dist = opts?.distance ?? Math.round((horiz ? vp.w : vp.h) * 0.5);
+      const dx = direction === "left" ? -dist : direction === "right" ? dist : 0;
+      const dy = direction === "up" ? -dist : direction === "down" ? dist : 0;
+      await backend.swipeBy(cx, cy, dx, dy);
+    },
+    scroll(dx, dy) {
+      return backend.scroll(dx, dy);
+    },
+    pressKey(key) {
+      return backend.press(key);
+    },
+    back() {
+      return backend.back();
+    },
+    evaluate(description, script) {
+      return backend.evaluate(description, script);
+    },
+    waitFor(description, expression, options) {
+      return backend.waitFor(description, expression, options);
+    },
+    screenshot(options) {
+      return backend.screenshot(options);
+    },
+    close() {
+      return backend.close();
+    },
+  };
+}
+
+/**
+ * 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.
+ */
+export async function openMobile(opts: {
+  url?: string;
+  recorder: BrowserSessionRecorder | null;
+}): Promise<Mobile> {
+  const backend = await openMobileBackend({
+    frame: "mobile",
+    url: opts.url,
+    recorder: opts.recorder,
+  });
+  return wrapMobile(backend);
+}