@e2e-dev/mobile 0.11.1-nightly-20261012095456 → 0.12.0

package/README.md

@@ -95,7 +95,7 @@ spread.
   `modifiers` on `tap` or `doubleTap`, focus on a control, and other keys fail with
   `UNSUPPORTED_CAPABILITY`.
 - **Location**: every `screen` query, plus agent-device selectors through
-  `device.locator('role=NavigationBar id=General')`.
+  `device.locator('role=navigation-bar id=General')`.
 - **Viewport swipe**, `app.back()`, `app.restart()`, `app.clearState()`, and
   redacted screenshots under the attempt artifact directory: the bounds of
   every secure field are painted black before the file is kept, and a
@@ -126,12 +126,11 @@ Deterministic device management, recorded as `device.<method>` steps. Import
 import { test } from '@e2e-dev/mobile';
 import { expect } from 'e2e';
 
-test('shows the version offline in dark mode', async ({ agent, device, screen }) => {
+test('shows the version in dark mode', async ({ agent, device, screen }) => {
   await device.setAppearance('dark');
-  await device.setNetwork('offline');
   await agent.act('go to General, then About');
   await expect(screen.getByRole('button', /^iOS Version/)).toBeVisible();
-  await expect(device.locator('role=NavigationBar id=About')).toBeVisible();
+  await expect(device.locator('role=navigation-bar id=About')).toBeVisible();
 });
 ```
 
@@ -141,6 +140,14 @@ Methods: `setNetwork`, `setAirplaneMode`, `setPermission`, `setLocation`,
 `foregroundApp`, `home`, `back`, `alert`, `dismissKeyboard`, `clipboard`,
 `setClipboard`, and the `locator` accessor.
 
+`setNetwork('offline')` and `setAirplaneMode(true)` are Android only. An iOS
+simulator shares the Mac's network, and simctl can only change its status
+bar, so on iOS both fail with `UNSUPPORTED_CAPABILITY`; going back online
+does nothing there, so a shared cleanup hook passes. On Android,
+`setNetwork('offline')` turns off Wi-Fi alone, so the app can stay online
+over cellular; `setAirplaneMode(true)` (Android 11 or later) takes it
+offline.
+
 `installApp(appPath, { app, reinstall })` puts a build on the device from a
 test, for upgrade and fresh-install paths the target's `app.appPath` cannot
 express.

package/dist/.build.json

@@ -1 +1 @@
-{"version":"0.11.1-nightly-20261012095456"}
+{"version":"0.12.0"}

package/dist/bindings.d.ts

@@ -44,14 +44,6 @@ export interface SlotBinding {
      * lease: with it the worker hands the lease to the provider's `record`.
      */
     readonly leaseId?: string | undefined;
-    /**
-     * App the warm-up in `prepare` opened in the slot's session, which the
-     * worker resumes: a permission command there already acts on it. Absent
-     * when nothing was opened, or the open failed. Every worker of the slot
-     * reads it, but only a worker that finds the session still open keeps it:
-     * one retired after a failing test closed it.
-     */
-    readonly sessionApp?: string | undefined;
 }
 /**
  * Where a pool's devices come from. `bind` runs once per run and target in

package/dist/bindings.js

@@ -45,7 +45,6 @@ export function encodeBindings(bindings) {
         client: binding.client,
         installedApp: binding.installedApp,
         leaseId: binding.leaseId,
-        sessionApp: binding.sessionApp,
     })));
     const bytes = Buffer.byteLength(encoded);
     if (bytes > MAX_BINDINGS_ENV_BYTES) {
@@ -74,12 +73,11 @@ function isOptionalString(value) {
 export function isSlotBinding(value) {
     if (typeof value !== 'object' || value === null)
         return false;
-    const { device, deviceId, daemon, client, installedApp, leaseId, sessionApp } = value;
+    const { device, deviceId, daemon, client, installedApp, leaseId } = value;
     return (isOptionalString(device) &&
         isOptionalString(deviceId) &&
         isOptionalString(installedApp) &&
         isOptionalString(leaseId) &&
-        isOptionalString(sessionApp) &&
         (daemon === undefined || isDaemon(daemon)) &&
         (client === undefined || isClientConfig(client)));
 }

package/dist/device.d.ts

@@ -18,19 +18,29 @@ export interface ForegroundApp {
 export interface Device {
     /**
      * A locator from an agent-device selector (`'id=SW_VERSION_SPECIFIER'`,
-     * `'role=StaticText label="26.2"'`), for nodes the closed `screen` query
+     * `'role=text label="26.2"'`), for nodes the closed `screen` query
      * vocabulary cannot name. Same polling and strictness as any locator.
      */
     locator(selector: string): Locator;
-    /** Toggles the device's Wi-Fi. */
+    /**
+     * Switches an Android device's Wi-Fi. Cellular data stays on, so an
+     * emulator hands the app over to its cellular link; `setAirplaneMode(true)`
+     * cuts both. On iOS `offline` is `UNSUPPORTED_CAPABILITY`, since a
+     * simulator shares the Mac's network and simctl can only repaint its status
+     * bar; `online` sends nothing there, so a cleanup hook shared with Android
+     * passes.
+     */
     setNetwork(state: 'online' | 'offline'): Promise<void>;
-    /** Toggles airplane mode. */
+    /**
+     * Switches an Android device's airplane mode, Wi-Fi and cellular together;
+     * Android 11 or newer. On iOS, as for `setNetwork`, `true` is
+     * `UNSUPPORTED_CAPABILITY` and `false` sends nothing.
+     */
     setAirplaneMode(enabled: boolean): Promise<void>;
     /**
-     * Grants, denies, or resets one permission for the pinned app, brought to
-     * the foreground first when the session is on no app. A change terminates
-     * a running app on iOS, a revoke one on Android, so it goes before the
-     * `app.open()` a test starts with.
+     * Grants, denies, or resets one permission for the pinned app, which need
+     * not be running. A change terminates a running app on iOS, a revoke one
+     * on Android, so it goes before the `app.open()` a test starts with.
      */
     setPermission(permission: DevicePermission, state: PermissionState): Promise<void>;
     /** Sets the simulated location, switching location services on first on Android. */
@@ -45,12 +55,16 @@ export interface Device {
     /** Rotates the device. */
     setOrientation(orientation: DeviceOrientation): Promise<void>;
     /**
-     * Puts a foldable iOS simulator (iPhone Duo) in a hinge pose and resolves
-     * once agent-device reads the angle back from CoreDevice at that pose,
-     * typically 10 to 16 seconds later. `closed` lights the outer display;
-     * `half-open` (a 130° book) and `open` light the inner one, whose app
-     * window has a different size, so the next observation reads a new screen.
-     * Any device without a hinge is `UNSUPPORTED_CAPABILITY`.
+     * Puts a foldable simulator or emulator in a hinge pose. On the iPhone Duo
+     * it resolves once agent-device reads the angle back from CoreDevice at
+     * that pose, typically 10 to 16 seconds later; `closed` lights the outer
+     * display, `half-open` (a 130° book) and `open` light the inner one. On a
+     * foldable Android emulator it sets the emulator console posture and
+     * resolves once the guest commits the matching device state, within a few
+     * seconds; `half-open` is the profile's own angle there (90° on the Pixel
+     * folds), and a fold to the cover display dismisses the lock screen it
+     * raises. Either way the app window changes size, so the next observation
+     * reads a new screen. Any device without a hinge is `UNSUPPORTED_CAPABILITY`.
      */
     fold(pose: FoldPose): Promise<void>;
     /** Simulates one biometric attempt on the open app. */

package/dist/device.js

@@ -5,14 +5,34 @@
  * `device.<method>` step bounded by the action timeout.
  */
 import { linkLabel, linkTarget } from './links.js';
+import { unsupported } from './support.js';
+/**
+ * Why iOS refuses to take the device offline, before any device command:
+ * agent-device's iOS `wifi` and `airplane` settings only override a
+ * simulator's status bar, and a physical iPhone takes no settings at all. A
+ * success would let a test read the repainted indicator as the app going
+ * offline. Going back online sends nothing there, like a toggle already in
+ * the wanted state, so a cleanup hook shared with Android still passes.
+ */
+const IOS_OFFLINE = "on iOS agent-device can only repaint a simulator's status bar, since the simulator shares the Mac's network, and cannot switch an iPhone's radios, so the app would stay online";
 /** Builds the device fixture for one attempt. */
 export function createDeviceFixture(surface, context) {
     const device = {
         locator: (selector) => context.locator({ kind: 'selector', selector }),
         async setNetwork(state) {
+            if (surface.options.platform === 'ios') {
+                if (state === 'offline')
+                    throw unsupported(`device.setNetwork('offline') turns off an Android device's Wi-Fi; ${IOS_OFFLINE}`);
+                return;
+            }
             await surface.command('device.setNetwork', (client) => client.settings.update({ setting: 'wifi', state: state === 'offline' ? 'off' : 'on' }), context.signal);
         },
         async setAirplaneMode(enabled) {
+            if (surface.options.platform === 'ios') {
+                if (enabled)
+                    throw unsupported(`device.setAirplaneMode(true) cuts an Android device's radios; ${IOS_OFFLINE}`);
+                return;
+            }
             await surface.command('device.setAirplaneMode', (client) => client.settings.update({ setting: 'airplane', state: enabled ? 'on' : 'off' }), context.signal);
         },
         async setPermission(permission, state) {

package/dist/errors.d.ts

@@ -5,7 +5,7 @@
  * | ----------------------------------------------------------- | ---------------------------- |
  * | already an EngineError / runner error                       | passed through untouched     |
  * | AbortError                                                  | CANCELLED                    |
- * | no active session / session not found / requires a session  | INVALID_STATE                |
+ * | SESSION_NOT_FOUND, or a session-or-device-selector refusal  | INVALID_STATE                |
  * | UNSUPPORTED_OPERATION, NOT_IMPLEMENTED, UNSUPPORTED_PLATFORM | UNSUPPORTED_CAPABILITY      |
  * | "not supported on this device" under any code                | UNSUPPORTED_CAPABILITY       |
  * | a stale-ref refusal, by `details.reason` (action paths only) | NODE_STALE (retryable)      |
@@ -35,12 +35,6 @@ export declare function translateError(cause: unknown, operation: string, where?
  * must not tolerate this.
  */
 export declare function isRunnerFailure(error: unknown): boolean;
-/**
- * True for a translated settings command agent-device refused because its
- * session is on no app: the one refusal a foreground open of the pinned app
- * answers.
- */
-export declare function isNoSessionApp(error: unknown): boolean;
 /**
  * True for a translated snapshot the iOS runner acquired but could not
  * present. The check is per capture and the capture is a read, so one retry

package/dist/errors.js

@@ -5,7 +5,7 @@
  * | ----------------------------------------------------------- | ---------------------------- |
  * | already an EngineError / runner error                       | passed through untouched     |
  * | AbortError                                                  | CANCELLED                    |
- * | no active session / session not found / requires a session  | INVALID_STATE                |
+ * | SESSION_NOT_FOUND, or a session-or-device-selector refusal  | INVALID_STATE                |
  * | UNSUPPORTED_OPERATION, NOT_IMPLEMENTED, UNSUPPORTED_PLATFORM | UNSUPPORTED_CAPABILITY      |
  * | "not supported on this device" under any code                | UNSUPPORTED_CAPABILITY       |
  * | a stale-ref refusal, by `details.reason` (action paths only) | NODE_STALE (retryable)      |
@@ -58,9 +58,13 @@ function withHint(cause, text) {
 }
 /** agent-device's generic hint (`Check command arguments and run --help`) is CLI advice, and stays out too. */
 const CLI_ADVICE = /--help|command arguments/i;
-const NO_SESSION_PATTERN = /no active (?:app )?session|requires an active session|session\b.*\bnot found|open an app first|no app (?:is )?open/i;
 const UNSUPPORTED_CODES = new Set(['UNSUPPORTED_OPERATION', 'NOT_IMPLEMENTED', 'UNSUPPORTED_PLATFORM']);
 const UNSUPPORTED_PATTERN = /\b(?:is )?not supported\b|\bunsupported\b/i;
+/**
+ * The `details.reason` agent-device refuses a command with when it has no
+ * session and no device selector to fall back on (0.21.21).
+ */
+const NO_SESSION_REASON = 'session_or_device_selector_required';
 /**
  * The `details.reason` values agent-device refuses an `@ref` with: the ref
  * names no node of the session's tree, or belongs to a capture the session
@@ -167,7 +171,7 @@ export function translateError(cause, operation, where) {
     const normalized = normalizeAgentDeviceError(cause);
     const text = `${operation} failed: ${withHint(cause, normalized.message)}`;
     const options = { retryable: false, cause };
-    if (normalized.code === 'SESSION_NOT_FOUND' || NO_SESSION_PATTERN.test(normalized.message)) {
+    if (normalized.code === 'SESSION_NOT_FOUND' || details(cause).reason === NO_SESSION_REASON) {
         return new EngineError('INVALID_STATE', text, options);
     }
     if (UNSUPPORTED_CODES.has(normalized.code) || UNSUPPORTED_PATTERN.test(normalized.message)) {
@@ -190,15 +194,6 @@ export function translateError(cause, operation, where) {
 export function isRunnerFailure(error) {
     return error instanceof Error && runnerState(error.cause) !== undefined;
 }
-const NO_SESSION_APP_PATTERN = /requires an active app in (?:the )?session/i;
-/**
- * True for a translated settings command agent-device refused because its
- * session is on no app: the one refusal a foreground open of the pinned app
- * answers.
- */
-export function isNoSessionApp(error) {
-    return error instanceof Error && NO_SESSION_APP_PATTERN.test(normalizeAgentDeviceError(error.cause).message);
-}
 /**
  * True for a translated snapshot the iOS runner acquired but could not
  * present. The check is per capture and the capture is a read, so one retry

package/dist/locate.d.ts

@@ -6,5 +6,6 @@
  */
 import { type LocatorExpression } from 'e2e/engine';
 import { type ProjectedNode } from './nodes.ts';
-/** Resolves one expression to the nodes it currently matches. */
-export declare function resolveExpression(expression: LocatorExpression, index: readonly ProjectedNode[]): ProjectedNode[];
+import type { MobilePlatform } from './options.ts';
+/** Resolves one expression to the nodes it currently matches; `platform` is the one agent-device selectors match for. */
+export declare function resolveExpression(expression: LocatorExpression, index: readonly ProjectedNode[], platform: MobilePlatform): ProjectedNode[];

package/dist/locate.js

@@ -7,35 +7,35 @@
 import { EngineError, matchesText } from 'e2e/engine';
 import { isWithin } from './nodes.js';
 import { compileSelector } from './selector.js';
-/** Resolves one expression to the nodes it currently matches. */
-export function resolveExpression(expression, index) {
+/** Resolves one expression to the nodes it currently matches; `platform` is the one agent-device selectors match for. */
+export function resolveExpression(expression, index, platform) {
     switch (expression.kind) {
         case 'query': {
-            const candidates = expression.scope === undefined ? index : descendantsOf(resolveExpression(expression.scope, index), index);
+            const candidates = expression.scope === undefined ? index : descendantsOf(resolveExpression(expression.scope, index, platform), index);
             const matches = candidates.filter((entry) => matchesQuery(entry, expression.query));
             return ECHOED_QUERY_KINDS.has(expression.query.kind) ? innermostOnly(matches) : matches;
         }
         case 'filter': {
-            const source = resolveExpression(expression.source, index);
+            const source = resolveExpression(expression.source, index, platform);
             return source.filter((entry) => {
                 if (expression.hasText !== undefined && !subtreeHasText(entry, index, expression.hasText))
                     return false;
                 if (expression.has !== undefined) {
                     const within = descendantsOf([entry], index);
-                    if (resolveExpression(expression.has, within).length === 0)
+                    if (resolveExpression(expression.has, within, platform).length === 0)
                         return false;
                 }
                 return true;
             });
         }
         case 'index': {
-            const source = resolveExpression(expression.source, index);
+            const source = resolveExpression(expression.source, index, platform);
             const position = expression.index === 'first' ? 0 : expression.index === 'last' ? source.length - 1 : expression.index;
             const picked = source[position];
             return picked === undefined ? [] : [picked];
         }
         case 'selector':
-            return compileSelector(expression.selector)(index);
+            return compileSelector(expression.selector, platform)(index);
         case 'frame':
             throw new EngineError('FRAME_NOT_FOUND', 'a device surface has no nested documents to scope a query into', {
                 retryable: false,

package/dist/nodes.d.ts

@@ -32,15 +32,16 @@ export interface ProjectedSnapshot {
     readonly index: readonly ProjectedNode[];
     readonly viewport: ViewportSize | undefined;
 }
-/** One element-type spelling for `NavigationBar`, `navigation-bar`, and `android.widget.NavigationBar` alike. */
-export declare function normalizeKind(type: string): string;
 /**
  * Projects one snapshot. `mintId` is called once per node in document order,
- * so the surface's id space stays unique across observations. Android's
- * system bars are left out with their children, see `isSystemBar`.
+ * so the surface's id space stays unique across observations. `viewport` is
+ * the one agent-device published with the snapshot; a producer that measured
+ * none leaves it to `viewportOf`. Android's system bars are left out with
+ * their children, see `isSystemBar`.
  */
 export declare function projectSnapshot(raw: readonly RawNode[], options: {
     readonly mintId: () => string;
+    readonly viewport?: ViewportSize | undefined;
 }): ProjectedSnapshot;
 /**
  * The screen's logical size, read off the application or window node when

package/dist/nodes.js

@@ -199,7 +199,7 @@ function isAndroidClass(type) {
     return type !== undefined && type.includes('.');
 }
 /** One element-type spelling for `NavigationBar`, `navigation-bar`, and `android.widget.NavigationBar` alike. */
-export function normalizeKind(type) {
+function normalizeKind(type) {
     const simple = type.slice(type.lastIndexOf('.') + 1);
     return simple
         .replaceAll(/([a-z0-9])([A-Z])/g, '$1-$2')
@@ -339,11 +339,13 @@ function isSystemBar(node, screen, displayOnly) {
 }
 /**
  * Projects one snapshot. `mintId` is called once per node in document order,
- * so the surface's id space stays unique across observations. Android's
- * system bars are left out with their children, see `isSystemBar`.
+ * so the surface's id space stays unique across observations. `viewport` is
+ * the one agent-device published with the snapshot; a producer that measured
+ * none leaves it to `viewportOf`. Android's system bars are left out with
+ * their children, see `isSystemBar`.
  */
 export function projectSnapshot(raw, options) {
-    const viewport = viewportOf(raw);
+    const viewport = options.viewport ?? viewportOf(raw);
     const parents = parentPositions(raw);
     const children = new Map();
     const roots = [];

package/dist/pool.d.ts

@@ -64,9 +64,8 @@ export declare class DevicePool {
     /**
      * Binds a device to every worker slot the run will use and warms each,
      * once per run and outside every launch budget, so `init` finds a booted
-     * device. The bindings, each naming the app its session is on, are
-     * reported back as the target's worker cap and left in the environment
-     * for the workers. A target nothing runs on binds
+     * device. The bindings are reported back as the target's worker cap and
+     * left in the environment for the workers. A target nothing runs on binds
      * nothing: a hosted session is billed from the moment it starts.
      */
     prepare(info: EnginePrepareInfo): Promise<EnginePrepareResult>;
@@ -83,9 +82,8 @@ export declare class DevicePool {
     finish(info: EngineFinishInfo): Promise<void>;
     /**
      * Boots every bound device, starts the iOS automation runner on it, and
-     * opens the pinned app on it once, so the slot's session is on the app,
-     * which the returned binding records for the worker: a permission it
-     * presets there needs no open first. A plain foreground open, with none of the engine's
+     * opens the pinned app on it once, so a test that starts without
+     * `app.open()` finds it on screen. A plain foreground open, with none of the engine's
      * launch options: an app still running from an earlier run keeps its
      * process either way, and a test's `app.open()` relaunches it with them.
      * One slot after another, on purpose: workers
@@ -98,8 +96,7 @@ export declare class DevicePool {
      * its first observation with the app blamed, and the message names the
      * recovery, which a wait of up to the runner's recycle window would only
      * hide. A runner that did not start leaves the slot unopened: the open
-     * would start it again under a shorter budget, and its timeout resets the
-     * daemon every earlier slot is on. A build `appPath` installs in `init` is
+     * would start it again under a shorter budget. A build `appPath` installs in `init` is
      * not on the device yet, so that slot boots and starts the runner only,
      * unless a lease says the build is already there.
      */

package/dist/pool.js

@@ -151,15 +151,15 @@ export class DevicePool {
     /**
      * Binds a device to every worker slot the run will use and warms each,
      * once per run and outside every launch budget, so `init` finds a booted
-     * device. The bindings, each naming the app its session is on, are
-     * reported back as the target's worker cap and left in the environment
-     * for the workers. A target nothing runs on binds
+     * device. The bindings are reported back as the target's worker cap and
+     * left in the environment for the workers. A target nothing runs on binds
      * nothing: a hosted session is billed from the moment it starts.
      */
     async prepare(info) {
         if (info.slots === 0)
             return {};
-        const bindings = await this.warm(await this.source.bind(info), info);
+        const bindings = await this.source.bind(info);
+        await this.warm(bindings, info);
         this.bound.set(info.targetName, bindings);
         return { workers: bindings.length, env: { [bindingsVariable(info.targetName)]: encodeBindings(bindings) } };
     }
@@ -181,9 +181,8 @@ export class DevicePool {
     }
     /**
      * Boots every bound device, starts the iOS automation runner on it, and
-     * opens the pinned app on it once, so the slot's session is on the app,
-     * which the returned binding records for the worker: a permission it
-     * presets there needs no open first. A plain foreground open, with none of the engine's
+     * opens the pinned app on it once, so a test that starts without
+     * `app.open()` finds it on screen. A plain foreground open, with none of the engine's
      * launch options: an app still running from an earlier run keeps its
      * process either way, and a test's `app.open()` relaunches it with them.
      * One slot after another, on purpose: workers
@@ -196,13 +195,11 @@ export class DevicePool {
      * its first observation with the app blamed, and the message names the
      * recovery, which a wait of up to the runner's recycle window would only
      * hide. A runner that did not start leaves the slot unopened: the open
-     * would start it again under a shorter budget, and its timeout resets the
-     * daemon every earlier slot is on. A build `appPath` installs in `init` is
+     * would start it again under a shorter budget. A build `appPath` installs in `init` is
      * not on the device yet, so that slot boots and starts the runner only,
      * unless a lease says the build is already there.
      */
     async warm(bindings, info) {
-        const warmed = [];
         for (const [slot, binding] of bindings.entries()) {
             const label = deviceLabel(binding) ?? `a booted ${this.options.platform} device`;
             const where = deviceSelection(this.options.platform, binding);
@@ -214,29 +211,23 @@ export class DevicePool {
             await runCommand('boot', () => client.devices.boot(where), info.signal, at);
             const runnerUp = this.options.platform !== 'ios' || (await prepareRunner(client, where, info, at));
             const app = pinnedApp(info.app, binding.installedApp);
-            if (app === undefined || !runnerUp) {
-                warmed.push(binding);
+            if (app === undefined || !runnerUp)
                 continue;
-            }
             // A build the suite installs itself is not on the device yet, so there
             // is nothing to open: the first attempt installs it.
             if (info.app.appPath !== undefined && binding.installedApp === undefined) {
                 info.log(`${label}: ${app} awaits the suite's device.installApp()`);
-                warmed.push(binding);
                 continue;
             }
             try {
                 await runCommand(`open ${app}`, () => client.apps.open({ app, ...where }), info.signal, at);
-                warmed.push({ ...binding, sessionApp: app });
             }
             catch (cause) {
                 if (info.signal.aborted || isRunnerFailure(cause))
                     throw cause;
                 info.log(`${label}: ${app} did not open (${message(cause)}); the first attempt opens it`);
-                warmed.push(binding);
             }
         }
-        return warmed;
     }
     /** Holds a warm-up client for `finish`, before its first command: a boot that fails still opened the session. */
     retain(targetName, client) {
@@ -249,8 +240,7 @@ export class DevicePool {
  * Starts the slot's iOS automation runner under `prepare ios-runner`, whose
  * startup budget covers a cold simulator. Left to the first `open`, the
  * start runs inside that request's 90 s envelope, which a cold runner on a
- * loaded CI Mac outlasts; a timed-out `open` resets the daemon, ending every
- * other slot's session with it. A runner that is busy or wedged ends the run
+ * loaded CI Mac outlasts. A runner that is busy or wedged ends the run
  * here, like a warm-up open that meets one; any other failure is logged and
  * left to the first attempt. True when the runner is up.
  */

package/dist/selector.d.ts

@@ -1,16 +1,17 @@
 /**
  * agent-device selector support for the `selector` locator expression:
  * `screen.locator('id=save role=button')` and the structural hint on every
- * observed node. The grammar is agent-device's own (`parseSelectorChain`), so a
- * selector that works on the agent-device CLI works here unchanged; matching
- * runs against the projected snapshot, one immediate pass, every match returned.
+ * observed node. Parsing and term rules are agent-device's own
+ * (`parseSelectorChain`, `listSelectorChainMatches`); matching runs against
+ * the projected snapshot, one immediate pass, every match returned, and
+ * strictness stays with the runner.
  */
-import { type ProjectedNode } from './nodes.ts';
+import type { ProjectedNode } from './nodes.ts';
+import type { MobilePlatform } from './options.ts';
 export type CompiledSelector = (entries: readonly ProjectedNode[]) => ProjectedNode[];
 /**
- * Compiles one selector string. Alternatives (agent-device's fallback chain)
- * are tried in order and the first that matches anything wins, mirroring how
- * agent-device itself resolves a chain; a term's text compares exactly after
- * whitespace collapsing, like every other text rule in the runner.
+ * Compiles one selector string for a platform. Alternatives (agent-device's
+ * fallback chain) are tried in order and the first that matches anything
+ * wins, with every node it matches returned in snapshot order.
  */
-export declare function compileSelector(raw: string): CompiledSelector;
+export declare function compileSelector(raw: string, platform: MobilePlatform): CompiledSelector;

package/dist/selector.js

@@ -1,21 +1,20 @@
 /**
  * agent-device selector support for the `selector` locator expression:
  * `screen.locator('id=save role=button')` and the structural hint on every
- * observed node. The grammar is agent-device's own (`parseSelectorChain`), so a
- * selector that works on the agent-device CLI works here unchanged; matching
- * runs against the projected snapshot, one immediate pass, every match returned.
+ * observed node. Parsing and term rules are agent-device's own
+ * (`parseSelectorChain`, `listSelectorChainMatches`); matching runs against
+ * the projected snapshot, one immediate pass, every match returned, and
+ * strictness stays with the runner.
  */
-import { parseSelectorChain } from 'agent-device/selectors';
+import { listSelectorChainMatches, parseSelectorChain } from 'agent-device/selectors';
 import { EngineError } from 'e2e/engine';
-import { normalizeKind } from './nodes.js';
 import { message } from './errors.js';
 /**
- * Compiles one selector string. Alternatives (agent-device's fallback chain)
- * are tried in order and the first that matches anything wins, mirroring how
- * agent-device itself resolves a chain; a term's text compares exactly after
- * whitespace collapsing, like every other text rule in the runner.
+ * Compiles one selector string for a platform. Alternatives (agent-device's
+ * fallback chain) are tried in order and the first that matches anything
+ * wins, with every node it matches returned in snapshot order.
  */
-export function compileSelector(raw) {
+export function compileSelector(raw, platform) {
     let chain;
     try {
         chain = parseSelectorChain(raw);
@@ -27,57 +26,10 @@ export function compileSelector(raw) {
         });
     }
     return (entries) => {
-        for (const alternative of chain.selectors) {
-            const matches = entries.filter((entry) => alternative.terms.every((term) => matchesTerm(entry, term)));
-            if (matches.length > 0)
-                return matches;
-        }
-        return [];
+        const byNode = new Map(entries.map((entry) => [entry.raw, entry]));
+        // The projection types agent-device's nodes as partial for fixtures that omit fields; the term rules read only optional ones.
+        const nodes = entries.map((entry) => entry.raw);
+        const matched = listSelectorChainMatches(nodes, chain, { platform })?.matchedNodes ?? [];
+        return matched.flatMap((node) => byNode.get(node) ?? []);
     };
 }
-function normalize(text) {
-    return text.replaceAll(/\s+/g, ' ').trim();
-}
-function textEquals(actual, expected) {
-    return actual !== undefined && normalize(actual) === normalize(String(expected));
-}
-function flag(value) {
-    return value === true || String(value).toLowerCase() === 'true';
-}
-function matchesTerm(entry, term) {
-    const states = entry.node.states ?? {};
-    switch (term.key) {
-        case 'id':
-            return textEquals(entry.raw.identifier, term.value);
-        case 'role': {
-            const wanted = normalizeKind(String(term.value));
-            return entry.kind === wanted || entry.node.role === wanted;
-        }
-        case 'text':
-            return textEquals(entry.raw.label, term.value) || textEquals(entry.raw.value, term.value);
-        case 'label':
-            return textEquals(entry.raw.label, term.value);
-        case 'value':
-            return textEquals(entry.raw.value, term.value);
-        case 'appname':
-            return textEquals(entry.raw.appName, term.value);
-        case 'windowtitle':
-            return textEquals(entry.raw.windowTitle, term.value);
-        case 'visible':
-            return (states.hidden !== true) === flag(term.value);
-        case 'hidden':
-            return (states.hidden === true) === flag(term.value);
-        case 'editable':
-            return (entry.node.role === 'textbox') === flag(term.value);
-        case 'selected':
-            return (states.selected === true) === flag(term.value);
-        case 'focused':
-            return (states.focused === true) === flag(term.value);
-        case 'enabled':
-            return (states.disabled !== true) === flag(term.value);
-        case 'hittable':
-            return (entry.raw.hittable !== false) === flag(term.value);
-        default:
-            return false;
-    }
-}

package/dist/surface.d.ts

@@ -76,14 +76,6 @@ export declare class AgentDeviceSurface {
     private readonly located;
     private idCounter;
     private appIdentity;
-    /**
-     * The app this worker's agent-device session is on, and so the app a
-     * permission command there acts on: what the warm-up in `prepare` opened
-     * under the session this worker resumed, while that session is still open,
-     * then whatever this surface last opened. Undefined while nothing has been opened in the session, and once
-     * `closeApp` ended it.
-     */
-    private sessionApp;
     /** The app the build `appPath` installed, once `init` has, itself or through a lease. */
     private installedApp;
     /** The target's app, as `init` received it. */
@@ -157,15 +149,6 @@ export declare class AgentDeviceSurface {
     /** The device selection this worker's commands take. */
     private selection;
     init(info: EngineInitInfo): Promise<void>;
-    /**
-     * The app the warm-up left the slot's session on, while agent-device still
-     * holds that session. Only the slot's first worker finds it: a worker
-     * retired after a failing test closed it in `dispose`, and a permission
-     * command on a closed session reaches no device. A session not listed, or
-     * a list that fails, leaves the app unknown, and the first permission
-     * change opens it again.
-     */
-    private resumedSessionApp;
     startAttempt(context: EngineAttemptContext): Promise<void>;
     endAttempt(context: EngineCleanupContext): Promise<void>;
     /**
@@ -205,25 +188,15 @@ export declare class AgentDeviceSurface {
     /** One `open` of an app, remembered as the session's app and as the screen's replacement. */
     private open;
     /**
-     * Puts an app's permissions in place before it launches. agent-device sets
-     * a permission on the app its session is on, so a session on another app,
-     * or on none yet, is first brought onto this one with a foreground open;
-     * the warm-up in `prepare` did that for the pinned app under the session
-     * this worker resumed, so its first launch needs none. Before the launch,
-     * never after: iOS terminates a running app whose
-     * permission changed, and Android one whose permission was revoked, so a
-     * change after the launch would leave the test on no screen.
+     * Puts an app's permissions in place before it launches, never after: iOS
+     * terminates a running app whose permission changed, and Android one whose
+     * permission was revoked, so a change after the launch would leave the
+     * test on no screen.
      */
     private presetPermissions;
-    /**
-     * One permission change for `device.setPermission`: on the app the session
-     * is on, which is what agent-device acts on. With none known here (nothing
-     * opened yet, `closeApp`, a worker resumed on a bare session) the pinned
-     * app is brought to the foreground first. agent-device's own refusal, met
-     * when its session lost the app since (a failed attempt left it on none),
-     * gets the same foreground open and the command once more.
-     */
+    /** One permission change for `device.setPermission`: on the pinned app, else on the app agent-device's session is on. */
     setPermission(permission: DevicePermission, state: PermissionState, signal: AbortSignal): Promise<void>;
+    /** One permission change on `app`, which needs no running app and no open in the session. */
     private permission;
     /**
      * Opens a link on the device, into `app` (the pinned app when none is
@@ -410,9 +383,11 @@ export declare class AgentDeviceSurface {
     /** Clears the pinned app's persisted state and relaunches it: the device equivalent of a fresh context. */
     reset(operation: OperationContext): Promise<void>;
     /**
-     * Sends a foldable iOS simulator's hinge to a pose; agent-device confirms
-     * the angle through CoreDevice before it answers. The pose moves the app to
-     * another panel, so it counts as an action like a rotation.
+     * Sends a foldable simulator's or emulator's hinge to a pose; agent-device
+     * confirms it before it answers: the hinge angle through CoreDevice on iOS,
+     * the device state the guest commits on Android. The pose moves the app to
+     * another panel, so it counts as an action like a rotation. A device
+     * without a hinge comes back from agent-device as `UNSUPPORTED_OPERATION`.
      */
     fold(pose: FoldPose, signal: AbortSignal): Promise<void>;
     /**

package/dist/surface.js

@@ -15,7 +15,7 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, w
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { EngineError, KEY_NAMES, parseKey, raceAbort, rejectUnknownKeys, stopProviderRecording, withinCleanupBudget, ConfigurationError, TestError, } from 'e2e/engine';
-import { isNoSessionApp, isSnapshotPresentationFailure, runCommand, staleOr } from './errors.js';
+import { isSnapshotPresentationFailure, runCommand, staleOr } from './errors.js';
 import { pointerInteraction, DEFAULT_LONG_PRESS_MS } from './actions.js';
 import { resolveExpression } from './locate.js';
 import { isWithin, projectSnapshot, ROOT_ID, screenRoot, screenTitle, } from './nodes.js';
@@ -187,14 +187,6 @@ export class AgentDeviceSurface {
     located = new Map();
     idCounter = 0;
     appIdentity;
-    /**
-     * The app this worker's agent-device session is on, and so the app a
-     * permission command there acts on: what the warm-up in `prepare` opened
-     * under the session this worker resumed, while that session is still open,
-     * then whatever this surface last opened. Undefined while nothing has been opened in the session, and once
-     * `closeApp` ended it.
-     */
-    sessionApp;
     /** The app the build `appPath` installed, once `init` has, itself or through a lease. */
     installedApp;
     /** The target's app, as `init` received it. */
@@ -320,31 +312,11 @@ export class AgentDeviceSurface {
                 ? undefined
                 : { provider, lease, runId: info.runId, targetName: info.targetName, env: info.env };
         await this.command('boot', (client) => client.devices.boot(this.selection()), info.signal);
-        this.sessionApp = binding?.sessionApp === undefined ? undefined : await this.resumedSessionApp(session, binding.sessionApp, info.signal);
         // Nothing is installed here: a device provider that installed the build
         // from `appPath` says so on the binding, and otherwise the suite installs
         // it where it wants to, with `device.installApp()`.
         this.installedApp = binding?.installedApp;
     }
-    /**
-     * The app the warm-up left the slot's session on, while agent-device still
-     * holds that session. Only the slot's first worker finds it: a worker
-     * retired after a failing test closed it in `dispose`, and a permission
-     * command on a closed session reaches no device. A session not listed, or
-     * a list that fails, leaves the app unknown, and the first permission
-     * change opens it again.
-     */
-    async resumedSessionApp(session, app, signal) {
-        const sessions = await this.command('sessions', (client) => client.sessions.list(), signal).catch((cause) => {
-            if (signal.aborted)
-                throw cause;
-            return undefined;
-        });
-        if (!Array.isArray(sessions))
-            return undefined;
-        const open = sessions.some((entry) => (entry.address ?? entry.name) === session);
-        return open ? app : undefined;
-    }
     async startAttempt(context) {
         if (this.attempt !== undefined) {
             throw invalidState('an attempt is already running on this agent-device engine');
@@ -453,7 +425,6 @@ export class AgentDeviceSurface {
     async stopScreenRecording(signal) {
         const result = await this.command('stop video recording', (client) => client.recording.record({ action: 'stop' }), signal);
         if (result.recordOnlySession === true) {
-            this.sessionApp = undefined;
             this.screenReplaced();
         }
         return result;
@@ -490,7 +461,6 @@ export class AgentDeviceSurface {
         this.generation = new Map();
         this.located.clear();
         this.appIdentity = undefined;
-        this.sessionApp = undefined;
         this.installedApp = undefined;
         this.knownViewport = undefined;
         if (client === undefined)
@@ -526,52 +496,26 @@ export class AgentDeviceSurface {
             ...(relaunch ? { relaunch: true } : {}),
             ...(launchArguments === undefined || launchArguments.length === 0 ? {} : { launchArgs: [...launchArguments] }),
         }), signal);
-        this.sessionApp = app;
         this.launched(result.appBundleId ?? result.appName ?? app);
     }
     /**
-     * Puts an app's permissions in place before it launches. agent-device sets
-     * a permission on the app its session is on, so a session on another app,
-     * or on none yet, is first brought onto this one with a foreground open;
-     * the warm-up in `prepare` did that for the pinned app under the session
-     * this worker resumed, so its first launch needs none. Before the launch,
-     * never after: iOS terminates a running app whose
-     * permission changed, and Android one whose permission was revoked, so a
-     * change after the launch would leave the test on no screen.
+     * Puts an app's permissions in place before it launches, never after: iOS
+     * terminates a running app whose permission changed, and Android one whose
+     * permission was revoked, so a change after the launch would leave the
+     * test on no screen.
      */
     async presetPermissions(app, permissions, signal) {
         const entries = Object.entries(permissions).filter((entry) => entry[1] !== undefined);
-        if (entries.length === 0)
-            return;
-        if (this.sessionApp !== app)
-            await this.open(app, false, undefined, signal);
         for (const [permission, state] of entries)
-            await this.permission(permission, state, signal);
+            await this.permission(permission, state, app, signal);
     }
-    /**
-     * One permission change for `device.setPermission`: on the app the session
-     * is on, which is what agent-device acts on. With none known here (nothing
-     * opened yet, `closeApp`, a worker resumed on a bare session) the pinned
-     * app is brought to the foreground first. agent-device's own refusal, met
-     * when its session lost the app since (a failed attempt left it on none),
-     * gets the same foreground open and the command once more.
-     */
+    /** One permission change for `device.setPermission`: on the pinned app, else on the app agent-device's session is on. */
     async setPermission(permission, state, signal) {
-        const app = this.pinnedApp;
-        if (this.sessionApp === undefined && app !== undefined)
-            await this.open(app, false, undefined, signal);
-        try {
-            await this.permission(permission, state, signal);
-        }
-        catch (cause) {
-            if (signal.aborted || app === undefined || !isNoSessionApp(cause))
-                throw cause;
-            await this.open(app, false, undefined, signal);
-            await this.permission(permission, state, signal);
-        }
+        await this.permission(permission, state, this.pinnedApp, signal);
     }
-    async permission(permission, state, signal) {
-        await this.command(`permission ${permission} ${state}`, (client) => client.settings.update({ setting: 'permission', permission, state }), signal);
+    /** One permission change on `app`, which needs no running app and no open in the session. */
+    async permission(permission, state, app, signal) {
+        await this.command(`permission ${permission} ${state}`, (client) => client.settings.update({ setting: 'permission', permission, state, ...this.selection(), ...(app === undefined ? {} : { app }) }), signal);
     }
     /**
      * Opens a link on the device, into `app` (the pinned app when none is
@@ -595,7 +539,6 @@ export class AgentDeviceSurface {
             ...this.selection(),
             ...(target === undefined ? { app: url.href } : { app: target, url: url.href }),
         }), signal);
-        this.sessionApp = target;
         this.launched(result.appBundleId ?? (target === undefined ? undefined : (result.appName ?? target)));
     }
     /**
@@ -630,7 +573,6 @@ export class AgentDeviceSurface {
     async closeApp(signal) {
         const app = this.appIdentity ?? this.pinnedApp;
         await this.command('device.closeApp', (client) => client.apps.close(app === undefined ? {} : { app }), signal);
-        this.sessionApp = undefined;
         this.screenReplaced();
     }
     /**
@@ -717,6 +659,7 @@ export class AgentDeviceSurface {
                 this.idCounter += 1;
                 return `n${this.idCounter}`;
             },
+            viewport: raw.viewport,
         });
         this.latestIndex = projected.index;
         if (projected.viewport !== undefined)
@@ -766,7 +709,7 @@ export class AgentDeviceSurface {
         const raw = await this.snapshotOrEmpty(operation, false);
         const projected = this.project(raw);
         this.traceScreen(raw, projected);
-        const matches = resolveExpression(expression, projected.index);
+        const matches = resolveExpression(expression, projected.index, this.options.platform);
         for (const entry of matches)
             this.located.set(entry.id, this.bind(entry, projected.index));
         for (const oldest of this.located.keys()) {
@@ -1129,7 +1072,7 @@ export class AgentDeviceSurface {
         let raw = await this.dismissKeyboardTip(await this.snapshot(signal, false), signal);
         if (!keyboardShowing(raw))
             return;
-        const projected = projectSnapshot(raw.nodes ?? [], { mintId: () => 'keyboard' });
+        const projected = projectSnapshot(raw.nodes ?? [], { mintId: () => 'keyboard', viewport: raw.viewport });
         const viewport = await this.viewportFor(projected, signal);
         const centre = { x: viewport.width / 2, y: viewport.height / 2 };
         const drags = [
@@ -1183,14 +1126,13 @@ export class AgentDeviceSurface {
         await this.openApp(app, { relaunch: true }, operation.signal);
     }
     /**
-     * Sends a foldable iOS simulator's hinge to a pose; agent-device confirms
-     * the angle through CoreDevice before it answers. The pose moves the app to
-     * another panel, so it counts as an action like a rotation.
+     * Sends a foldable simulator's or emulator's hinge to a pose; agent-device
+     * confirms it before it answers: the hinge angle through CoreDevice on iOS,
+     * the device state the guest commits on Android. The pose moves the app to
+     * another panel, so it counts as an action like a rotation. A device
+     * without a hinge comes back from agent-device as `UNSUPPORTED_OPERATION`.
      */
     async fold(pose, signal) {
-        if (this.options.platform !== 'ios') {
-            throw unsupported('device.fold drives a foldable iOS simulator (iPhone Duo) through agent-device; it has no Android driver');
-        }
         await this.screenCommand('device.fold', (client) => client.command.fold({ pose }), signal);
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e2e-dev/mobile",
-  "version": "0.11.1-nightly-20261012095456",
+  "version": "0.12.0",
   "description": "Mobile engine (iOS and Android) for e2e agentic end-to-end testing, built on agent-device",
   "keywords": [
     "e2e",
@@ -51,13 +51,13 @@
     "NOTICE"
   ],
   "dependencies": {
-    "agent-device": "0.21.22",
+    "agent-device": "0.21.25",
     "pngjs": "7.0.0",
     "zod": "4.6.1"
   },
   "peerDependencies": {
     "ai": "^7.0.0",
-    "e2e": "0.19.1-nightly-20261012095456"
+    "e2e": ">=0.15.0 <1"
   },
   "peerDependenciesMeta": {
     "ai": {
@@ -68,7 +68,7 @@
     "@types/node": "26.6.2",
     "@types/pngjs": "6.0.5",
     "ai": "7.0.107",
-    "e2e": "0.19.1-nightly-20261012095456",
+    "e2e": "0.20.0",
     "typescript": "7.0.2",
     "vitest": "5.0.1"
   },