@e2edev/mobile 0.8.0-canary-20260921180210

package/dist/device.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The `device` fixture: deterministic device management this engine
+ * contributes. Not an agent tool; a test calls these directly to arrange or
+ * assert device state, and the harness records each call as a
+ * `device.<method>` step bounded by the action timeout.
+ */
+import type { EngineFixtureContext, Locator } from 'e2e/engine';
+import type { AgentDeviceSurface, InstallAppOptions, InstalledApp } from './surface.ts';
+/** Permissions agent-device can grant, deny, or reset on an open app. */
+export type DevicePermission = 'camera' | 'microphone' | 'photos' | 'contacts' | 'notifications' | 'calendar' | 'location' | 'reminders' | 'motion' | 'siri' | 'media-library';
+/** Orientations `setOrientation` accepts. */
+export type DeviceOrientation = 'portrait' | 'portrait-upside-down' | 'landscape-left' | 'landscape-right';
+export type BiometricSensor = 'faceid' | 'touchid' | 'fingerprint';
+export interface ForegroundApp {
+    readonly name: string;
+    readonly bundleId?: string;
+}
+/** Deterministic device management exposed to tests as `device`. */
+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
+     * vocabulary cannot name. Same polling and strictness as any locator.
+     */
+    locator(selector: string): Locator;
+    /** Toggles the device's Wi-Fi. */
+    setNetwork(state: 'online' | 'offline'): Promise<void>;
+    /** Toggles airplane mode. */
+    setAirplaneMode(enabled: boolean): Promise<void>;
+    /** Grants, denies, or resets one permission for the open app. */
+    setPermission(permission: DevicePermission, state: 'grant' | 'deny' | 'reset'): Promise<void>;
+    /** Sets the simulated location. */
+    setLocation(coordinates: {
+        latitude: number;
+        longitude: number;
+    }): Promise<void>;
+    /** Turns simulated location off. */
+    clearLocation(): Promise<void>;
+    /** Sets the system appearance. */
+    setAppearance(mode: 'light' | 'dark'): Promise<void>;
+    /** Rotates the device. */
+    setOrientation(orientation: DeviceOrientation): Promise<void>;
+    /** Simulates one biometric attempt on the open app. */
+    setBiometrics(sensor: BiometricSensor, result: 'match' | 'nonmatch'): Promise<void>;
+    /** Enrolls or unenrolls the simulator's Face ID or Touch ID. */
+    enrollBiometrics(sensor: 'faceid' | 'touchid', enrolled: boolean): Promise<void>;
+    /**
+     * Installs a build (an iOS `.app` bundle or an Android `.apk`, resolved
+     * against the project root) on the device. `reinstall: true` removes
+     * the app first so it starts with no data; a plain install replaces the
+     * binary and keeps its data. Resolves to the identity to `openApp` it by.
+     */
+    installApp(appPath: string, options?: InstallAppOptions): Promise<InstalledApp>;
+    /** Brings an app to the foreground; `relaunch` restarts it fresh. */
+    openApp(app: string, options?: {
+        relaunch?: boolean;
+    }): Promise<void>;
+    /** Closes the session's current app. */
+    closeApp(): Promise<void>;
+    /** The app currently in the foreground of the session. */
+    foregroundApp(): Promise<ForegroundApp>;
+    /** Sends the device to its home screen. */
+    home(): Promise<void>;
+    /** Navigates back once (in-app back). */
+    back(): Promise<void>;
+    /** Accepts or dismisses the visible system alert. */
+    alert(action: 'accept' | 'dismiss'): Promise<void>;
+    /** Dismisses the soft keyboard. */
+    dismissKeyboard(): Promise<void>;
+    /** Reads the clipboard. */
+    clipboard(): Promise<string>;
+    /** Writes the clipboard. */
+    setClipboard(text: string): Promise<void>;
+}
+/** Builds the device fixture for one attempt. */
+export declare function createDeviceFixture(surface: AgentDeviceSurface, context: EngineFixtureContext): Device;
+//# sourceMappingURL=device.d.ts.map

package/dist/device.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.d.ts","sourceRoot":"","sources":["../src/device.ts"],"names":[],"mappings":"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"}

package/dist/device.js

@@ -0,0 +1,101 @@
+/**
+ * The `device` fixture: deterministic device management this engine
+ * contributes. Not an agent tool; a test calls these directly to arrange or
+ * assert device state, and the harness records each call as a
+ * `device.<method>` step bounded by the action timeout.
+ */
+/** Builds the device fixture for one attempt. */
+export function createDeviceFixture(surface, context) {
+    const device = {
+        locator: (selector) => context.locator({ kind: 'selector', selector }),
+        async setNetwork(state) {
+            await surface.command('device.setNetwork', (client) => client.settings.update({ setting: 'wifi', state: state === 'offline' ? 'off' : 'on' }), context.signal);
+        },
+        async setAirplaneMode(enabled) {
+            await surface.command('device.setAirplaneMode', (client) => client.settings.update({ setting: 'airplane', state: enabled ? 'on' : 'off' }), context.signal);
+        },
+        async setPermission(permission, state) {
+            await surface.command('device.setPermission', (client) => client.settings.update({ setting: 'permission', permission, state }), context.signal);
+        },
+        async setLocation({ latitude, longitude }) {
+            await surface.command('device.setLocation', (client) => client.settings.update({ setting: 'location', state: 'set', latitude, longitude }), context.signal);
+        },
+        async clearLocation() {
+            await surface.command('device.clearLocation', (client) => client.settings.update({ setting: 'location', state: 'off' }), context.signal);
+        },
+        async setAppearance(mode) {
+            await surface.command('device.setAppearance', (client) => client.settings.update({ setting: 'appearance', state: mode }), context.signal);
+        },
+        async setOrientation(orientation) {
+            await surface.command('device.setOrientation', (client) => client.command.orientation({ orientation }), context.signal);
+        },
+        async setBiometrics(sensor, result) {
+            await surface.command('device.setBiometrics', (client) => sensor === 'fingerprint'
+                ? client.settings.update({ setting: 'fingerprint', state: result })
+                : client.settings.update({ setting: sensor, state: result }), context.signal);
+        },
+        async enrollBiometrics(sensor, enrolled) {
+            await surface.command('device.enrollBiometrics', (client) => client.settings.update({ setting: sensor, state: enrolled ? 'enroll' : 'unenroll' }), context.signal);
+        },
+        async installApp(appPath, options) {
+            return surface.installApp(appPath, options ?? {}, context.signal);
+        },
+        async openApp(app, options) {
+            await surface.openApp(app, options?.relaunch === true, context.signal);
+        },
+        async closeApp() {
+            await surface.command('device.closeApp', (client) => client.apps.close({}), context.signal);
+        },
+        async foregroundApp() {
+            const state = await surface.command('device.foregroundApp', (client) => client.command.appState({}), context.signal);
+            if ('package' in state)
+                return { name: state.package, bundleId: state.package };
+            return {
+                name: state.appName,
+                ...(state.appBundleId === undefined ? {} : { bundleId: state.appBundleId }),
+            };
+        },
+        async home() {
+            await surface.command('device.home', (client) => client.command.home({}), context.signal);
+        },
+        async back() {
+            await surface.command('device.back', (client) => client.command.back({ ...surface.settleOptions }), context.signal);
+        },
+        async alert(action) {
+            await surface.command('device.alert', (client) => client.command.alert({ action }), context.signal);
+        },
+        async dismissKeyboard() {
+            await surface.command('device.dismissKeyboard', (client) => client.command.keyboard({ action: 'dismiss' }), context.signal);
+        },
+        async clipboard() {
+            const result = await surface.command('device.clipboard', (client) => client.command.clipboard({ action: 'read' }), context.signal);
+            return result.action === 'read' ? result.text : '';
+        },
+        async setClipboard(text) {
+            await surface.command('device.setClipboard', (client) => client.command.clipboard({ action: 'write', text }), context.signal);
+        },
+    };
+    const action = { kind: 'resource' };
+    return context.fixture('device', device, {
+        setNetwork: { ...action, label: (state) => state },
+        setAirplaneMode: action,
+        setPermission: { ...action, label: (permission) => permission },
+        setLocation: action,
+        clearLocation: action,
+        setAppearance: { ...action, label: (mode) => mode },
+        setOrientation: { ...action, label: (orientation) => orientation },
+        setBiometrics: action,
+        enrollBiometrics: action,
+        installApp: { ...action, label: (appPath) => appPath },
+        openApp: { ...action, label: (app) => app },
+        closeApp: action,
+        foregroundApp: action,
+        home: action,
+        back: action,
+        alert: { ...action, label: (value) => value },
+        dismissKeyboard: action,
+        clipboard: action,
+        setClipboard: { ...action, label: (text) => `${text.length} chars` },
+    });
+}
+//# sourceMappingURL=device.js.map

package/dist/device.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.js","sourceRoot":"","sources":["../src/device.ts"],"names":[],"mappings":"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"}

package/dist/engine.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The agent-device engine for e2e: a mobile body built with the
+ * public `defineEngine`, validated by the same rules and graded by the same
+ * capabilities as any other engine. Core imports nothing from here; this
+ * package imports the contract from `e2e/engine` and contributes the
+ * `device` fixture the way the browser engine contributes `web`.
+ */
+import { type EngineHandle } from 'e2e/engine';
+import type { MobileOptions } from './options.ts';
+import { AgentDeviceSurface } from './surface.ts';
+/** Assembles the manifest for one surface. Exported for tests that script the client. */
+export declare function buildEngine(surface: AgentDeviceSurface): EngineHandle;
+/** Creates one agent-device engine: one device session per worker, one fresh app launch per attempt. */
+export declare function mobile(options: MobileOptions): EngineHandle;
+/** The surface behind a handle this package created; undefined for any other engine. */
+export declare function surfaceOf(engine: EngineHandle): AgentDeviceSurface | undefined;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAgD,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAE7F,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,cAAc,CAAC;AAEjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAIlD,yFAAyF;AACzF,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,YAAY,CA+CrE;AAED,wGAAwG;AACxG,wBAAgB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,YAAY,CAM3D;AAaD,wFAAwF;AACxF,wBAAgB,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,kBAAkB,GAAG,SAAS,CAE9E"}

package/dist/engine.js

@@ -0,0 +1,92 @@
+/**
+ * The agent-device engine for e2e: a mobile body built with the
+ * public `defineEngine`, validated by the same rules and graded by the same
+ * capabilities as any other engine. Core imports nothing from here; this
+ * package imports the contract from `e2e/engine` and contributes the
+ * `device` fixture the way the browser engine contributes `web`.
+ */
+import { createRequire } from 'node:module';
+import { createAgentDeviceClient } from 'agent-device';
+import { defineEngine, obj } from 'e2e/engine';
+import { createDeviceFixture } from './device.js';
+import { DEVICE_ACTIONS, DEVICE_POINTER_ACTIONS } from './actions.js';
+import { AgentDeviceSurface } from './surface.js';
+const surfaces = new WeakMap();
+/** Assembles the manifest for one surface. Exported for tests that script the client. */
+export function buildEngine(surface) {
+    const handle = defineEngine({
+        name: 'mobile',
+        version: ownVersion(),
+        spiVersion: 1,
+        platform: surface.options.platform,
+        ...(surface.pool.size === undefined ? {} : { workers: surface.pool.size }),
+        prepare: (info) => surface.pool.prepare(info),
+        finish: (info) => surface.pool.finish(info),
+        init: (info) => surface.init(info),
+        startAttempt: (context) => surface.startAttempt(context),
+        endAttempt: (context) => surface.endAttempt(context),
+        dispose: (context) => surface.dispose(context),
+        observe: (operation, options) => surface.observe(operation, options),
+        locate: (expression, operation) => surface.locate(expression, operation),
+        perform: (ref, action, operation) => surface.perform(ref, action, operation),
+        actions: DEVICE_ACTIONS,
+        performAt: (point, action, operation) => surface.performAt(point, action, operation),
+        pointerActions: DEVICE_POINTER_ACTIONS,
+        keyboard: {
+            type: (text, keyboardOptions, operation) => surface.typeText(text, keyboardOptions, operation),
+            press: (key, operation) => surface.pressFocusedKey(key, operation),
+            dismiss: (operation) => surface.dismissKeyboard(operation),
+        },
+        app: declaredApp(surface.options),
+        // No `open`: a device app has no URL to open. Relaunching the pinned app
+        // is the device's "recreate the context", so restart and reset need one.
+        session: {
+            back: (operation) => surface.back(operation),
+            ...(surface.managesApp
+                ? {
+                    restart: (operation) => surface.restart(operation),
+                    reset: (operation) => surface.reset(operation),
+                }
+                : {}),
+        },
+        artifacts: {
+            screenshot: (label, operation) => surface.screenshot(label, operation),
+            startVideo: (operation) => surface.startVideo(operation),
+            stopVideo: (operation) => surface.stopVideo(operation),
+        },
+        fixtures: {
+            device: (context) => createDeviceFixture(surface, context),
+        },
+    });
+    surfaces.set(handle, surface);
+    return handle;
+}
+/** Creates one agent-device engine: one device session per worker, one fresh app launch per attempt. */
+export function mobile(options) {
+    const factory = (session, daemon) => createAgentDeviceClient(daemon === undefined ? { session } : obj({ session, daemonBaseUrl: daemon.baseUrl, daemonAuthToken: daemon.authToken }));
+    return buildEngine(new AgentDeviceSurface(options, factory));
+}
+/**
+ * What the device engine declares about its app: the pinned app (else the
+ * build it installs) is the identity cache and session entries key on.
+ */
+function declaredApp(options) {
+    return obj({
+        identity: options.identity ?? options.app ?? options.appPath,
+        environment: options.environment,
+    });
+}
+/** The surface behind a handle this package created; undefined for any other engine. */
+export function surfaceOf(engine) {
+    return surfaces.get(engine);
+}
+/** This package's published version, read through require resolution. */
+function ownVersion() {
+    try {
+        return createRequire(import.meta.url)('../package.json').version;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Translation of agent-device failures onto the engine error contract.
+ *
+ * | agent-device failure                                        | Code                         |
+ * | ----------------------------------------------------------- | ---------------------------- |
+ * | already an EngineError / runner error                       | passed through untouched     |
+ * | AbortError                                                  | CANCELLED                    |
+ * | no active session / session not found                       | INVALID_STATE                |
+ * | UNSUPPORTED_OPERATION, NOT_IMPLEMENTED, UNSUPPORTED_PLATFORM | UNSUPPORTED_CAPABILITY      |
+ * | "not supported on this device" under any code                | UNSUPPORTED_CAPABILITY       |
+ * | a ref the daemon no longer knows (action paths only)        | NODE_STALE (retryable)       |
+ * | timed out                                                   | OPERATION_TIMEOUT            |
+ * | anything else                                               | ENGINE_FAILURE              |
+ */
+/** A failure's message in agent-device's normalized form. */
+export declare function message(cause: unknown): string;
+/** Translates an unexpected agent-device error at the contract boundary. */
+export declare function translateError(cause: unknown, operation: string): Error;
+/**
+ * Runs one agent-device command under an abort signal and translates its
+ * failure onto the engine taxonomy: the one boundary every command crosses.
+ */
+export declare function runCommand<T>(label: string, work: () => Promise<T>, signal: AbortSignal): Promise<T>;
+/**
+ * Like translateError, but a ref the daemon no longer binds becomes retryable
+ * `NODE_STALE`: nothing was dispatched, so the harness may re-observe and
+ * re-resolve the node instead of failing the action.
+ */
+export declare function staleOr(cause: unknown, operation: string): Error;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAiBH,6DAA6D;AAC7D,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE9C;AAqBD,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,KAAK,CAcvE;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAM1G;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,KAAK,CAOhE"}

package/dist/errors.js

@@ -0,0 +1,95 @@
+/**
+ * Translation of agent-device failures onto the engine error contract.
+ *
+ * | agent-device failure                                        | Code                         |
+ * | ----------------------------------------------------------- | ---------------------------- |
+ * | already an EngineError / runner error                       | passed through untouched     |
+ * | AbortError                                                  | CANCELLED                    |
+ * | no active session / session not found                       | INVALID_STATE                |
+ * | UNSUPPORTED_OPERATION, NOT_IMPLEMENTED, UNSUPPORTED_PLATFORM | UNSUPPORTED_CAPABILITY      |
+ * | "not supported on this device" under any code                | UNSUPPORTED_CAPABILITY       |
+ * | a ref the daemon no longer knows (action paths only)        | NODE_STALE (retryable)       |
+ * | timed out                                                   | OPERATION_TIMEOUT            |
+ * | anything else                                               | ENGINE_FAILURE              |
+ */
+import { isAgentDeviceError, normalizeAgentDeviceError } from 'agent-device';
+import { EngineError, ConfigurationError, InfrastructureError, TestError, raceAbort } from 'e2e/engine';
+import { cancelled } from './support.js';
+/**
+ * True for an error that already carries its classification: an `EngineError`
+ * from any module copy, or a runner error. Those cross the boundary untouched;
+ * re-wrapping one would turn a `POLICY_DENIED` into an infrastructure failure.
+ */
+function isClassified(cause) {
+    if (cause instanceof EngineError || cause instanceof TestError)
+        return true;
+    if (cause instanceof ConfigurationError || cause instanceof InfrastructureError)
+        return true;
+    return cause instanceof Error && cause.name === 'EngineError';
+}
+/** A failure's message in agent-device's normalized form. */
+export function message(cause) {
+    return normalizeAgentDeviceError(cause).message;
+}
+/**
+ * The normalized message followed by the hint the failure itself declared.
+ * That hint is the recovery path (press return, tap the app's own Done
+ * control) and the model only ever sees the error text, so dropping it leaves
+ * the agent retrying the same refused action. The per-code default hint the
+ * normalizer would add is CLI advice and stays out.
+ */
+function withHint(cause, text) {
+    const hint = isAgentDeviceError(cause) ? cause.details?.hint?.trim() : undefined;
+    return hint ? `${text} Hint: ${hint}` : text;
+}
+const NO_SESSION_PATTERN = /no active (?:app )?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;
+const TIMEOUT_PATTERN = /\btimed?\s?out\b/i;
+const STALE_PATTERN = /\bref\b.*\b(?:not found|unknown|stale|no longer|expired|invalid|missing)|\b(?:not found|unknown|stale|no longer|expired|invalid|missing)\b.*\bref\b|refs?generation/i;
+/** Translates an unexpected agent-device error at the contract boundary. */
+export function translateError(cause, operation) {
+    if (isClassified(cause))
+        return cause;
+    if (cause instanceof Error && cause.name === 'AbortError')
+        return cancelled(`${operation} cancelled`);
+    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)) {
+        return new EngineError('INVALID_STATE', text, options);
+    }
+    if (UNSUPPORTED_CODES.has(normalized.code) || UNSUPPORTED_PATTERN.test(normalized.message)) {
+        return new EngineError('UNSUPPORTED_CAPABILITY', text, options);
+    }
+    if (TIMEOUT_PATTERN.test(normalized.message))
+        return new EngineError('OPERATION_TIMEOUT', text, options);
+    return new EngineError('ENGINE_FAILURE', text, options);
+}
+/**
+ * Runs one agent-device command under an abort signal and translates its
+ * failure onto the engine taxonomy: the one boundary every command crosses.
+ */
+export async function runCommand(label, work, signal) {
+    try {
+        return await raceAbort(work, signal, label);
+    }
+    catch (cause) {
+        throw translateError(cause, label);
+    }
+}
+/**
+ * Like translateError, but a ref the daemon no longer binds becomes retryable
+ * `NODE_STALE`: nothing was dispatched, so the harness may re-observe and
+ * re-resolve the node instead of failing the action.
+ */
+export function staleOr(cause, operation) {
+    if (isClassified(cause))
+        return cause;
+    const normalized = normalizeAgentDeviceError(cause);
+    if (STALE_PATTERN.test(normalized.message)) {
+        return new EngineError('NODE_STALE', `${operation}: ${normalized.message}`, { retryable: true, cause });
+    }
+    return translateError(cause, operation);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `@e2edev/mobile` public surface: the `mobile()` engine factory,
+ * the `device` fixture types, and a `test` typed with that fixture. `expect`
+ * and `credentials` still come from `e2e`; the agent-side tool pack lives on
+ * the `@e2edev/mobile/tools` subpath so this entry never loads the AI SDK.
+ */
+import type { Device } from './device.ts';
+export { mobile } from './engine.ts';
+export type { MobileOptions, MobilePlatform } from './options.ts';
+export type { DeviceDaemon } from './bindings.ts';
+export type { DeviceLease, DeviceProvider, DeviceReleaseContext, DeviceRequest } from './provider.ts';
+export type { InstallAppOptions, InstalledApp } from './surface.ts';
+export type { BiometricSensor, Device, DeviceOrientation, DevicePermission, ForegroundApp } from './device.ts';
+/**
+ * `test` typed with this engine's contributed `device` fixture. The same
+ * runtime `test` as `e2e`'s; only the fixture types differ.
+ */
+export declare const test: import("e2e").TestAPI<import("e2e").TestFixtures & {
+    device: Device;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAClE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACtG,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACpE,YAAY,EAAE,eAAe,EAAE,MAAM,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE/G;;;GAGG;AACH,eAAO,MAAM,IAAI;YAAyB,MAAM;EAAK,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * `@e2edev/mobile` public surface: the `mobile()` engine factory,
+ * the `device` fixture types, and a `test` typed with that fixture. `expect`
+ * and `credentials` still come from `e2e`; the agent-side tool pack lives on
+ * the `@e2edev/mobile/tools` subpath so this entry never loads the AI SDK.
+ */
+import { test as base } from 'e2e';
+export { mobile } from './engine.js';
+/**
+ * `test` typed with this engine's contributed `device` fixture. The same
+ * runtime `test` as `e2e`'s; only the fixture types differ.
+ */
+export const test = base.extend();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,IAAI,IAAI,IAAI,EAAE,MAAM,KAAK,CAAC;AAGnC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAOrC;;;GAGG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,EAAsB,CAAC"}

package/dist/locate.d.ts

@@ -0,0 +1,11 @@
+/**
+ * LocatorExpression evaluation over one projected snapshot: the location
+ * capability's query language answered against the accessibility tree the
+ * device just reported. One immediate pass, every match in document order;
+ * polling, strictness, and staleness stay with the runner.
+ */
+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[];
+//# sourceMappingURL=locate.d.ts.map

package/dist/locate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locate.d.ts","sourceRoot":"","sources":["../src/locate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAA4B,KAAK,iBAAiB,EAAsB,MAAM,YAAY,CAAC;AAClG,OAAO,EAAY,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAG1D,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,iBAAiB,EAAE,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,aAAa,EAAE,CAiCjH"}

package/dist/locate.js

@@ -0,0 +1,115 @@
+/**
+ * LocatorExpression evaluation over one projected snapshot: the location
+ * capability's query language answered against the accessibility tree the
+ * device just reported. One immediate pass, every match in document order;
+ * polling, strictness, and staleness stay with the runner.
+ */
+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) {
+    switch (expression.kind) {
+        case 'query': {
+            const candidates = expression.scope === undefined ? index : descendantsOf(resolveExpression(expression.scope, index), index);
+            const matches = candidates.filter((entry) => matchesQuery(entry, expression.query));
+            return expression.query.kind === 'text' ? innermostOnly(matches) : matches;
+        }
+        case 'filter': {
+            const source = resolveExpression(expression.source, index);
+            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)
+                        return false;
+                }
+                return true;
+            });
+        }
+        case 'index': {
+            const source = resolveExpression(expression.source, index);
+            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);
+        case 'frame':
+            throw new EngineError('FRAME_NOT_FOUND', 'a device surface has no nested documents to scope a query into', {
+                retryable: false,
+            });
+    }
+}
+/**
+ * Drops every match that contains another match, the way a browser's text
+ * selector answers with the innermost element. A device tree echoes text
+ * upwards: iOS reports a React Native Text host view and its StaticText child
+ * with the same label, and a container view inherits its descendants' labels,
+ * so without this rule every `getByText` on such a screen is ambiguous.
+ */
+function innermostOnly(matches) {
+    return matches.filter((entry) => !matches.some((other) => other !== entry && isWithin(other, entry)));
+}
+/** Strict descendants of any node in `ancestors`, in document order. */
+function descendantsOf(ancestors, index) {
+    if (ancestors.length === 0)
+        return [];
+    return index.filter((entry) => ancestors.some((ancestor) => isWithin(entry, ancestor)));
+}
+function subtreeHasText(entry, index, pattern) {
+    const ownTexts = [entry.node.name, entry.node.text, entry.node.value];
+    if (ownTexts.some((text) => text !== undefined && matchesText(text, pattern)))
+        return true;
+    return descendantsOf([entry], index).some((child) => [child.node.name, child.node.text, child.node.value].some((text) => text !== undefined && matchesText(text, pattern)));
+}
+const STATE_KEYS = ['checked', 'disabled', 'selected', 'expanded', 'pressed'];
+/**
+ * One node against one semantic query. Role queries skip hidden nodes, as a
+ * browser's role query does; the other kinds
+ * answer with every node and leave visibility to the action or assertion,
+ * unless the query says `visible`, which drops hidden nodes for every kind.
+ */
+function matchesQuery(entry, query) {
+    const node = entry.node;
+    if (query.visible === true && node.states?.hidden === true)
+        return false;
+    switch (query.kind) {
+        case 'role': {
+            if (query.value.kind !== 'string') {
+                throw new EngineError('ENGINE_FAILURE', 'role query value must be a string', { retryable: false });
+            }
+            if ((node.role ?? '') !== query.value.value)
+                return false;
+            if (query.name !== undefined && !matchesText(node.name ?? '', query.name))
+                return false;
+            if (node.states?.hidden === true)
+                return false;
+            const wanted = query.states ?? {};
+            for (const key of STATE_KEYS) {
+                const expected = wanted[key];
+                if (expected !== undefined && (node.states?.[key] ?? false) !== expected)
+                    return false;
+            }
+            // A device tree reports no heading levels, so a level query matches nothing rather than everything.
+            if (query.level !== undefined && node.level !== query.level)
+                return false;
+            return true;
+        }
+        case 'label':
+            return node.name !== undefined && matchesText(node.name, query.value);
+        case 'placeholder': {
+            const placeholder = node.attributes?.['placeholder'];
+            return placeholder !== undefined && matchesText(placeholder, query.value);
+        }
+        case 'text':
+            return ((node.name !== undefined && matchesText(node.name, query.value)) ||
+                (node.text !== undefined && matchesText(node.text, query.value)));
+        case 'displayValue':
+            return node.value !== undefined && matchesText(node.value, query.value);
+        case 'testId':
+            return node.testId !== undefined && matchesText(node.testId, query.value);
+    }
+}
+//# sourceMappingURL=locate.js.map