@specific.dev/spectest 0.4.55 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.4.55",
+  "version": "0.6.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

@@ -27,6 +27,8 @@ import { pathToFileURL } from "node:url";
 import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard } 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,
@@ -2521,6 +2523,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 +2552,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 +2564,7 @@ function newBrowserSession(testStart: number, idScope: string): {
   const record: BrowserSessionRecord = {
     sessionId: newSessionId(idScope),
     openedAtMs: Date.now() - testStart,
+    frame,
     steps: [],
   };
   let closed = false;
@@ -3252,7 +3263,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 +3274,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 +3306,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 +3535,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 +3544,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 +3618,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";
@@ -602,6 +609,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);
+}