@specific.dev/spectest 0.41.0 → 0.44.0

package/dist/daemon.js

@@ -22,7 +22,7 @@ import net from "node:net";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, proxy as makeProxyDecl, } from "./index.js";
-import { acquirePersistentBrowser } from "./browser.js";
+import { acquirePersistentBrowser, mobileKey } from "./browser.js";
 import { isMobileApp, openPersistentMobile } from "./mobile.js";
 // Pure ingress hostname matching, ported out of this file (see
 // harness/hostmatch.ts). Keeping ONE implementation is the point: the
@@ -2686,6 +2686,19 @@ function newArtifactCollector() {
         },
     };
 }
+/**
+ * Normalise `ctx.browser(...)`'s two call shapes — `(opts?)` for the
+ * default session and `(name, opts?)` for a named one — into the
+ * `(name, opts)` pair the session registry keys on. The overloads make
+ * these the only two shapes that typecheck, but the implementation still
+ * has to tell them apart at runtime: an untyped caller (`eval`, plain JS)
+ * reaches the same function.
+ */
+function browserArgs(nameOrOpts, opts) {
+    return typeof nameOrOpts === "string"
+        ? { name: nameOrOpts, opts }
+        : { name: "", opts: nameOrOpts };
+}
 /**
  * Build the recorder sink + bookkeeping for a single Browser session.
  * The returned `recorder` is what `openBrowser` writes into; the
@@ -2694,11 +2707,15 @@ function newArtifactCollector() {
  * test-run sessions don't pass it, which is exactly what makes
  * `screenshot()` throw outside eval.
  */
-function newBrowserSession(testStart, idScope, frame = "browser", artifacts) {
+function newBrowserSession(testStart, idScope, frame = "browser", artifacts, name = "") {
     const record = {
         sessionId: newSessionId(idScope),
         openedAtMs: Date.now() - testStart,
         frame,
+        // Omit the key entirely for the default session rather than storing
+        // `""` — every consumer treats "no name" as "don't render a label",
+        // and an empty string would have to be special-cased in each of them.
+        ...(name ? { name } : {}),
         steps: [],
     };
     let closed = false;
@@ -2706,6 +2723,7 @@ function newBrowserSession(testStart, idScope, frame = "browser", artifacts) {
         record,
         recorder: {
             sessionId: record.sessionId,
+            ...(name ? { sessionName: name } : {}),
             recordStep(step) {
                 if (closed)
                     return;
@@ -3537,31 +3555,37 @@ async function runOne(testCase) {
     // an ancestor fork; its TEST_DATA entry travels with the snapshot.
     const parentId = testCase.dependsOn?.id;
     const parent = parentId !== undefined ? TEST_DATA.get(parentId) : undefined;
-    // Browser/mobile sessions are PERSISTENT: `ctx.browser()` acquires THE
-    // shared desktop browser and `ctx.mobile(app)` the one session for that
-    // app (browser.ts's module-scoped registry, which forks with the
-    // snapshot like fake state). At test end we DETACH — final rrweb drain,
-    // stop writing to this test's recorder — but deliberately keep the
+    // Browser/mobile sessions are PERSISTENT and keyed by NAME:
+    // `ctx.browser(name?)` acquires the desktop browser called `name` and
+    // `ctx.mobile(app, name?)` that name's session for that app (browser.ts's
+    // module-scoped registry, which forks with the snapshot like fake state).
+    // The default name is `""`, so an unnamed project has exactly the one
+    // session per device it always had. At test end we DETACH — final rrweb
+    // drain, stop writing to this test's recorder — but deliberately keep the
     // Chromium alive so the post-test snapshot captures it and dependsOn
-    // children resume the live page (cookies, localStorage, signed-in SPA
-    // state) instead of re-navigating. Each test still gets its own session
-    // record (attach re-arms rrweb with a fresh full snapshot, so replays
-    // stay per-case self-contained); records flow back to the control plane
-    // on RunResult.browserSessions and are archived to S3 as the case's
-    // replay bundle. Within one test repeated ctx.browser()/ctx.mobile(app)
-    // calls return the same handle (memoized below) so one test = one
-    // session per device. An explicit `.close()` destroys the shared
-    // instance — the memo is cleared so a later call starts fresh.
+    // children resume the live pages (cookies, localStorage, signed-in SPA
+    // state) instead of re-navigating; that inheritance is per name, so a
+    // parent that signed "alice" and "bob" in hands both down. Each test
+    // still gets its own session record per name (attach re-arms rrweb with a
+    // fresh full snapshot, so replays stay per-case self-contained); records
+    // flow back to the control plane on RunResult.browserSessions and are
+    // archived to S3 as the case's replay bundle. Within one test repeated
+    // calls for the SAME name return the same handle (memoized below) so one
+    // test = one session per (device, name). An explicit `.close()` destroys
+    // that name's instance — its memo entry is cleared so a later call for
+    // the same name starts fresh, and other names are untouched.
     const browserDetaches = [];
     const sessions = [];
-    let sharedBrowser = null;
+    const sharedBrowsers = new Map();
     const sharedMobiles = new Map();
-    const trackedOpenBrowser = async (opts) => {
-        if (sharedBrowser)
-            return sharedBrowser;
-        const session = newBrowserSession(start, testCase.id);
+    const trackedOpenBrowser = async (nameOrOpts, maybeOpts) => {
+        const { name, opts } = browserArgs(nameOrOpts, maybeOpts);
+        const memo = sharedBrowsers.get(name);
+        if (memo)
+            return memo;
+        const session = newBrowserSession(start, testCase.id, "browser", undefined, name);
         sessions.push(session);
-        const { browser, attached, detach } = await acquirePersistentBrowser({
+        const { browser, attached, detach } = await acquirePersistentBrowser(name, {
             ...(opts ?? {}),
             recorder: session.recorder,
         });
@@ -3580,23 +3604,25 @@ async function runOne(testCase) {
         const innerClose = browser.close.bind(browser);
         browser.close = async () => {
             await innerClose();
-            if (sharedBrowser === browser)
-                sharedBrowser = null;
+            if (sharedBrowsers.get(name) === browser)
+                sharedBrowsers.delete(name);
         };
-        sharedBrowser = browser;
+        sharedBrowsers.set(name, browser);
         return browser;
     };
-    const trackedOpenMobile = async (app) => {
+    const trackedOpenMobile = async (app, name = "") => {
         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 existing = sharedMobiles.get(app.url);
+        const key = mobileKey(name, app.url);
+        const existing = sharedMobiles.get(key);
         if (existing)
             return existing;
-        const session = newBrowserSession(start, testCase.id, "mobile");
+        const session = newBrowserSession(start, testCase.id, "mobile", undefined, name);
         sessions.push(session);
         const { mobile, attached, detach, safeAreaInsets } = await openPersistentMobile({
             url: app.url,
+            name,
             recorder: session.recorder,
             initScript: app.initScript,
         });
@@ -3612,10 +3638,10 @@ async function runOne(testCase) {
         const innerClose = mobile.close.bind(mobile);
         mobile.close = async () => {
             await innerClose();
-            if (sharedMobiles.get(app.url) === mobile)
-                sharedMobiles.delete(app.url);
+            if (sharedMobiles.get(key) === mobile)
+                sharedMobiles.delete(key);
         };
-        sharedMobiles.set(app.url, mobile);
+        sharedMobiles.set(key, mobile);
         return mobile;
     };
     // The shared context (svc/fakes handles, poll, project files, dnsName,
@@ -3975,14 +4001,16 @@ async function evalCode(code, secrets) {
     // Eval-only artifact sink — wiring it here (and nowhere in runOne) is
     // what gates screenshot() to eval context.
     const artifactCollector = newArtifactCollector();
-    let sharedBrowser = null;
+    const sharedBrowsers = new Map();
     const sharedMobiles = new Map();
-    const trackedOpenBrowser = async (opts) => {
-        if (sharedBrowser)
-            return sharedBrowser;
-        const session = newBrowserSession(start, "eval", "browser", artifactCollector);
+    const trackedOpenBrowser = async (nameOrOpts, maybeOpts) => {
+        const { name, opts } = browserArgs(nameOrOpts, maybeOpts);
+        const memo = sharedBrowsers.get(name);
+        if (memo)
+            return memo;
+        const session = newBrowserSession(start, "eval", "browser", artifactCollector, name);
         sessions.push(session);
-        const { browser, attached, detach } = await acquirePersistentBrowser({
+        const { browser, attached, detach } = await acquirePersistentBrowser(name, {
             ...(opts ?? {}),
             recorder: session.recorder,
         });
@@ -3999,23 +4027,25 @@ async function evalCode(code, secrets) {
         const innerClose = browser.close.bind(browser);
         browser.close = async () => {
             await innerClose();
-            if (sharedBrowser === browser)
-                sharedBrowser = null;
+            if (sharedBrowsers.get(name) === browser)
+                sharedBrowsers.delete(name);
         };
-        sharedBrowser = browser;
+        sharedBrowsers.set(name, browser);
         return browser;
     };
-    const trackedOpenMobile = async (app) => {
+    const trackedOpenMobile = async (app, name = "") => {
         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 existing = sharedMobiles.get(app.url);
+        const key = mobileKey(name, app.url);
+        const existing = sharedMobiles.get(key);
         if (existing)
             return existing;
-        const session = newBrowserSession(start, "eval", "mobile", artifactCollector);
+        const session = newBrowserSession(start, "eval", "mobile", artifactCollector, name);
         sessions.push(session);
         const { mobile, attached, detach, safeAreaInsets } = await openPersistentMobile({
             url: app.url,
+            name,
             recorder: session.recorder,
             initScript: app.initScript,
         });
@@ -4031,10 +4061,10 @@ async function evalCode(code, secrets) {
         const innerClose = mobile.close.bind(mobile);
         mobile.close = async () => {
             await innerClose();
-            if (sharedMobiles.get(app.url) === mobile)
-                sharedMobiles.delete(app.url);
+            if (sharedMobiles.get(key) === mobile)
+                sharedMobiles.delete(key);
         };
-        sharedMobiles.set(app.url, mobile);
+        sharedMobiles.set(key, mobile);
         return mobile;
     };
     // Terminal sessions — same shape as runOne, but eval has no active

package/dist/index.d.ts

@@ -936,20 +936,57 @@ export interface TestContext<P = undefined, S extends ServicesMap = ServicesMap,
     /**
      * Open the headless browser. Backed by Chromium-over-CDP inside the VM.
      *
-     * There is ONE persistent browser per environment: every `ctx.browser()`
-     * call returns it, and it stays alive across tests — the browser is part
-     * of the state a test's snapshot captures, so a `dependsOn` child resumes
-     * the exact live page its parent left (cookies, localStorage, signed-in
-     * SPA state). Sign in once in a parent test; every descendant is already
-     * signed in. Sibling tests fork from the same parent snapshot, so they
-     * can't see each other's browsing. A test with no browser-using ancestor
-     * gets a fresh browser on first call (first call's options win).
+     * There is one persistent browser PER NAME, and `ctx.browser()` is the
+     * default (unnamed) one: every call returns it, and it stays alive across
+     * tests — the browser is part of the state a test's snapshot captures, so
+     * a `dependsOn` child resumes the exact live page its parent left
+     * (cookies, localStorage, signed-in SPA state). Sign in once in a parent
+     * test; every descendant is already signed in. Sibling tests fork from
+     * the same parent snapshot, so they can't see each other's browsing. A
+     * test with no browser-using ancestor gets a fresh browser on first call
+     * (first call's options win).
+     *
+     * For a second, independent browser — a second user — name it:
+     * `ctx.browser("alice")`. See the named overload.
      *
      * `.close()` destroys the shared instance — the next `ctx.browser()`
      * starts fresh. Don't call it for routine cleanup; recording is detached
      * automatically at test end.
      */
     browser(opts?: BrowserOptions): Promise<Browser>;
+    /**
+     * Open the persistent browser called `name`, creating it on first use.
+     * Each name is its own browser — its own cookies, localStorage and page —
+     * so naming them is how one test drives two users.
+     *
+     * **Only name a browser when the test needs two or more isolated sessions
+     * at once.** Otherwise use `ctx.browser()`: a name is a second identity,
+     * not a label, and a lone `ctx.browser("main")` buys nothing over the
+     * default while adding its name to every step title in the dashboard.
+     *
+     * ```ts
+     * const alice = await ctx.browser("alice", { url: "https://app.test" });
+     * const bob = await ctx.browser("bob", { url: "https://app.test" });
+     * await alice.getByRole("button", { name: "Share" }).click();
+     * await bob.reload();
+     * await expect(bob.getByText("Shared with you")).toBeVisible();
+     * ```
+     *
+     * Every rule of the default browser applies per name: the session rides
+     * the snapshot, so a `dependsOn` child inherits *each* named browser
+     * exactly where its parent left it (sign both users in once, in the
+     * parent); repeat calls with the same name in one test return the same
+     * handle; the first call for a name wins its options; `.close()` discards
+     * only that name. Sessions are named for the roles under test, not per
+     * row of data — each one is a live browser captured in every snapshot
+     * from here on, and opening too many is an error.
+     *
+     * The dashboard titles each step with the browser that performed it
+     * (`bob: click "Share"`) and labels the replay with the same name, so a
+     * two-user timeline stays readable and selecting a step shows that
+     * browser's session.
+     */
+    browser(name: string, 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
@@ -968,13 +1005,18 @@ export interface TestContext<P = undefined, S extends ServicesMap = ServicesMap,
      * The session emulates the latest iPhone (viewport + DPR + mobile UA +
      * touch) and the dashboard replays it inside a phone bezel.
      *
-     * Sessions are persistent, one per app: like `ctx.browser()`, the live
-     * session is captured in the test's snapshot, so a `dependsOn` child
-     * picks up the app exactly where the parent left it (already signed in,
-     * mid-flow) instead of reloading it. `.close()` discards the session;
+     * Sessions are persistent, one per app per `name`: like `ctx.browser()`,
+     * the live session is captured in the test's snapshot, so a `dependsOn`
+     * child picks up the app exactly where the parent left it (already signed
+     * in, mid-flow) instead of reloading it. `.close()` discards the session;
      * the next `ctx.mobile(app)` opens the app fresh.
+     *
+     * Pass a `name` for a second phone running the same app — two users in
+     * one test: `ctx.mobile(ctx.svc.app, "alice")`. Names are independent
+     * sessions and are inherited per name by `dependsOn` children, exactly
+     * like named desktop browsers.
      */
-    mobile(app: MobileApp): Promise<Mobile>;
+    mobile(app: MobileApp, name?: string): Promise<Mobile>;
     /** The test's display name. */
     readonly testName: string;
     /**

package/dist/mobile.d.ts

@@ -49,14 +49,18 @@ export declare function openMobile(opts: {
     recorder: BrowserSessionRecorder | null;
 }): Promise<Mobile>;
 /**
- * Acquire the persistent phone-emulated session for an app (one per app URL,
- * created on first use). The daemon calls this from `ctx.mobile(app)` with a
- * per-test rrweb recorder; the resulting record carries `frame: "mobile"` so
- * the dashboard renders a phone bezel. `detach` is the test-end hook;
- * `mobile.close()` destroys the session for real.
+ * Acquire the persistent phone-emulated session for an app (one per app URL
+ * per `name`, created on first use). The daemon calls this from
+ * `ctx.mobile(app, name?)` with a per-test rrweb recorder; the resulting
+ * record carries `frame: "mobile"` so the dashboard renders a phone bezel.
+ * `detach` is the test-end hook; `mobile.close()` destroys the session for
+ * real.
  */
 export declare function openPersistentMobile(opts: {
     url: string;
+    /** Session name — `""` (the default) is the unnamed session every
+     *  `ctx.mobile(app)` call shares. Two names on one app are two phones. */
+    name?: string;
     recorder: BrowserSessionRecorder | null;
     /** Installed before the fresh session's first navigation (ignored on an
      *  attached session, which already carries it on the forked holder). */

package/dist/mobile.js

@@ -48,14 +48,15 @@ export async function openMobile(opts) {
     return backend;
 }
 /**
- * Acquire the persistent phone-emulated session for an app (one per app URL,
- * created on first use). The daemon calls this from `ctx.mobile(app)` with a
- * per-test rrweb recorder; the resulting record carries `frame: "mobile"` so
- * the dashboard renders a phone bezel. `detach` is the test-end hook;
- * `mobile.close()` destroys the session for real.
+ * Acquire the persistent phone-emulated session for an app (one per app URL
+ * per `name`, created on first use). The daemon calls this from
+ * `ctx.mobile(app, name?)` with a per-test rrweb recorder; the resulting
+ * record carries `frame: "mobile"` so the dashboard renders a phone bezel.
+ * `detach` is the test-end hook; `mobile.close()` destroys the session for
+ * real.
  */
 export async function openPersistentMobile(opts) {
-    const { browser, attached, detach } = await acquirePersistentMobileBackend(opts.url, opts.recorder, opts.initScript);
+    const { browser, attached, detach } = await acquirePersistentMobileBackend(opts.url, opts.name ?? "", opts.recorder, opts.initScript);
     return {
         mobile: browser,
         attached,

package/dist/recorder.d.ts

@@ -379,6 +379,16 @@ export interface BrowserEvent extends BaseEvent {
      * with a `BrowserSessionRecorder` attached (the daemon always does).
      */
     sessionId?: string;
+    /**
+     * Author-given name of that session — `ctx.browser("alice")` — absent
+     * for the default unnamed browser, so a single-browser test's steps
+     * carry no name and render exactly as they always have. Present, it is
+     * what the step list badges to say which browser acted. Duplicated here
+     * rather than resolved from the session record because the CLI's
+     * failure detail renders from persisted events alone, with no replay
+     * bundle to look the session up in.
+     */
+    sessionName?: string;
     /**
      * Wall-clock `Date.now()` captured at the moment this op *finished*.
      * Lives in the same time base as rrweb's `event.timestamp` fields,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.41.0",
+  "version": "0.44.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/browser.ts

@@ -136,6 +136,14 @@ export interface BrowserSessionRecorder {
    * the dashboard can link a browser event to its replay player.
    */
   readonly sessionId: string;
+  /**
+   * Author-given name of this session (`ctx.browser("alice")`), absent
+   * for the default unnamed one. Echoed onto every op's event so the
+   * step list can say WHICH browser acted without having to resolve the
+   * session record — which the CLI's failure detail can't do (it renders
+   * from the persisted events alone, with no replay bundle).
+   */
+  readonly sessionName?: string;
   /** Called for each drained chunk of rrweb events. */
   recordStep(step: BrowserSessionStep): void;
   /** Optional: called whenever `Browser.goto(url)` is invoked. */
@@ -1304,17 +1312,50 @@ export async function openMobileBackend(
 // Persistent sessions (the default behind ctx.browser / ctx.mobile)
 // ────────────────────────────────────────────────────────────────────────
 
-// One long-lived desktop browser plus one mobile session per app URL.
+// Long-lived sessions, keyed by NAME: one desktop browser per name, one
+// mobile session per (name, app URL). The default name is `""` — what
+// `ctx.browser()` / `ctx.mobile(app)` use — so an unnamed project keeps
+// exactly the one-session-per-device behaviour it had before names
+// existed. A name is the key and nothing else: two names are two
+// BrowserContexts in the one Chromium, i.e. two independent cookie jars
+// and localStorage, which is what modelling two users needs.
+//
 // Module state lives in daemon memory, so it forks with the snapshot the
-// same way fake `state` and TEST_DATA do: a test's browser — its live
-// page, cookies, localStorage, in-memory SPA state — is captured in the
+// same way fake `state` and TEST_DATA do: a test's browsers — their live
+// pages, cookies, localStorage, in-memory SPA state — are captured in the
 // post-test snapshot and inherited by `dependsOn` children, while sibling
 // forks never see each other's sessions. That's what lets a child test
 // continue where its parent left off (e.g. already signed in) instead of
-// re-navigating and re-authenticating.
-let SHARED_BROWSER: ViewHolder | null = null;
+// re-navigating and re-authenticating. The name is a plain string, so it
+// keys the same session on both sides of a fork.
+const SHARED_BROWSERS = new Map<string, ViewHolder>();
 const SHARED_MOBILE = new Map<string, ViewHolder>();
 
+/**
+ * Ceiling on live persistent sessions of one kind (desktop / mobile).
+ * Every session is a Chromium BrowserContext that rides every snapshot
+ * from here down the DAG, so a test that mints names in a loop
+ * (`ctx.browser(userId)`) would grow the VM's memory floor for the rest
+ * of the run. Failing loudly at a sane count beats a wedged guest.
+ */
+const MAX_PERSISTENT_SESSIONS = 8;
+
+/** Registry key for a named mobile session. NUL can't occur in a name or
+ *  a URL, so the two halves can never run together ambiguously. */
+export function mobileKey(name: string, url: string): string {
+  return `${name}\u0000${url}`;
+}
+
+/** Guard the session cap, naming the offender and what to do about it. */
+function checkSessionCap(kind: string, live: number, name: string): void {
+  if (live < MAX_PERSISTENT_SESSIONS) return;
+  throw new Error(
+    `too many ${kind} sessions: ${MAX_PERSISTENT_SESSIONS} are already open and "${name}" would be another. ` +
+      `Each named session is a live browser captured in every snapshot from here on — name them for the ` +
+      `roles under test (e.g. "buyer"/"seller") rather than per row of data, or close() the ones you're done with.`,
+  );
+}
+
 async function newHolder(
   width: number,
   height: number,
@@ -1395,53 +1436,61 @@ async function attachReset(holder: ViewHolder): Promise<void> {
 }
 
 /**
- * Acquire THE persistent desktop browser (creating it on first use). There
- * is deliberately a single one — `ctx.browser()` always returns it — so a
- * test DAG shares one browsing session along each branch. The first call's
- * options win; later calls attach to the existing view as-is.
+ * Acquire the persistent desktop browser called `name` (creating it on
+ * first use). There is one per name — `ctx.browser()` uses the default
+ * name `""` — so a test DAG shares each named browsing session along each
+ * branch, and two names are two independent users. The first call for a
+ * name wins its options; later calls attach to the existing view as-is.
  */
 export async function acquirePersistentBrowser(
+  name = "",
   opts: BrowserOptions = {},
 ): Promise<PersistentBrowser> {
   const device = opts.frame === "mobile" ? LATEST_IPHONE : null;
-  let attached = true;
-  if (!SHARED_BROWSER) {
-    attached = false;
-    SHARED_BROWSER = await newHolder(
+  let holder = SHARED_BROWSERS.get(name);
+  const attached = holder !== undefined;
+  if (holder) {
+    await attachReset(holder);
+  } else {
+    checkSessionCap("browser", SHARED_BROWSERS.size, name);
+    holder = await newHolder(
       device ? device.viewport.width : opts.width ?? 1280,
       device ? device.viewport.height : opts.height ?? 720,
       device,
     );
-  } else {
-    await attachReset(SHARED_BROWSER);
+    SHARED_BROWSERS.set(name, holder);
   }
-  const holder = SHARED_BROWSER;
-  const { backend, detach } = buildBackend(holder, opts.recorder ?? null, {
+  const view = holder;
+  const { backend, detach } = buildBackend(view, opts.recorder ?? null, {
     persistent: true,
     onDestroy: () => {
-      if (SHARED_BROWSER === holder) SHARED_BROWSER = null;
+      if (SHARED_BROWSERS.get(name) === view) SHARED_BROWSERS.delete(name);
     },
   });
   // Fresh session only: an attached view already carries the init script on
   // its (forked) holder, and first-call-wins means a later call's options
   // don't retroactively apply.
   if (!attached && opts.initScript !== undefined) {
-    await installInitScript(holder, opts.initScript);
+    await installInitScript(view, opts.initScript);
   }
   if (!attached && opts.url !== undefined) await backend.goto(opts.url);
   return { browser: backend, attached, detach };
 }
 
 /**
- * Acquire the persistent mobile session for an app URL (one per app). A
- * fresh session navigates to the app; an attach continues on the live page.
+ * Acquire the persistent mobile session for an app URL under `name` (one
+ * per name per app; `ctx.mobile(app)` uses the default name `""`). A fresh
+ * session navigates to the app; an attach continues on the live page.
  */
 export async function acquirePersistentMobileBackend(
   url: string,
+  name: string,
   recorder: BrowserSessionRecorder | null,
   initScript?: string,
 ): Promise<PersistentBrowser> {
-  const existing = SHARED_MOBILE.get(url);
+  const key = mobileKey(name, url);
+  const existing = SHARED_MOBILE.get(key);
+  if (!existing) checkSessionCap("mobile", SHARED_MOBILE.size, name);
   const holder =
     existing ??
     (await newHolder(
@@ -1452,12 +1501,12 @@ export async function acquirePersistentMobileBackend(
   if (existing) {
     await attachReset(holder);
   } else {
-    SHARED_MOBILE.set(url, holder);
+    SHARED_MOBILE.set(key, holder);
   }
   const { backend, detach } = buildBackend(holder, recorder, {
     persistent: true,
     onDestroy: () => {
-      if (SHARED_MOBILE.get(url) === holder) SHARED_MOBILE.delete(url);
+      if (SHARED_MOBILE.get(key) === holder) SHARED_MOBILE.delete(key);
     },
   });
   if (!existing) {
@@ -1549,6 +1598,18 @@ function buildBackend(
   // missing from the chunk we're about to drain (see `drainExpr`).
   let lastDrainUrl: string | null = null;
 
+  /** Session provenance stamped on every recorded op: which replay player
+   *  the step belongs to, which named browser it acted on, and where in
+   *  the player to seek (`endT`, in rrweb's clock). */
+  function sessionFields(endT: number): Record<string, unknown> {
+    if (!recorder) return {};
+    return {
+      sessionId: recorder.sessionId,
+      sessionTimestamp: endT,
+      ...(recorder.sessionName ? { sessionName: recorder.sessionName } : {}),
+    };
+  }
+
   async function drain(action: BrowserAction | "close"): Promise<void> {
     if (!holder.recordingInstalled || !recorder || recordingEnded) return;
     try {
@@ -1595,9 +1656,7 @@ function buildBackend(
       const seq = recordBrowser({
         action,
         ...fields,
-        ...(recorder
-          ? { sessionId: recorder.sessionId, sessionTimestamp: endT }
-          : {}),
+        ...sessionFields(endT),
         durationMs: endT - t,
       }, resv);
       await drain(action);
@@ -1614,9 +1673,7 @@ function buildBackend(
       recordBrowser({
         action,
         ...fields,
-        ...(recorder
-          ? { sessionId: recorder.sessionId, sessionTimestamp: endT }
-          : {}),
+        ...sessionFields(endT),
         durationMs: endT - t,
         error: e?.message ?? String(err),
       }, resv);
@@ -1988,9 +2045,7 @@ function buildBackend(
       const seq = recordBrowser({
         action,
         ...fields,
-        ...(recorder
-          ? { sessionId: recorder.sessionId, sessionTimestamp: endT }
-          : {}),
+        ...sessionFields(endT),
         durationMs: waitedMs,
         ...(error ? { error } : {}),
       }, reserveBackdated(waitedMs));