@e2e-dev/mobile 0.8.0-canary-20260928184528

package/dist/bindings.js

@@ -0,0 +1,112 @@
+/**
+ * What one worker slot drives, and how it travels from the runner's `prepare`
+ * to the worker's `init`. Every way a pool comes by devices (a configured
+ * list, the booted devices it discovered, the leases a provider granted) is
+ * one `DeviceSource` that ends in one `SlotBinding` per slot, so the worker
+ * reads one shape through one environment variable, whatever produced it.
+ */
+import { createHash } from 'node:crypto';
+import { EngineError, obj } from 'e2e/engine';
+/** What a binding calls its device in progress and error lines: the name, else the id, else nothing. */
+export function deviceLabel(binding) {
+    return binding?.device ?? binding?.deviceId;
+}
+/**
+ * The app a slot's `app.open()` launches, and its warm-up opens once: the
+ * `app` option, else the app the build `appPath` installed, once the suite's
+ * `device.installApp()` (or a device provider) has. `undefined` with a build
+ * nobody has installed and no `app`.
+ */
+export function pinnedApp(options, installedApp) {
+    return options.app ?? installedApp;
+}
+/**
+ * The most the serialized bindings of one target may occupy in a worker's
+ * environment: a lease comes from third-party code, and an oversized
+ * environment fails the worker spawn with an opaque error.
+ */
+const MAX_BINDINGS_ENV_BYTES = 16 * 1024;
+/**
+ * The environment variable a target's bindings travel to the workers in: the
+ * name made environment-safe for reading, plus a digest of the exact name so
+ * `ios-a` and `ios.a` never share a key.
+ */
+export function bindingsVariable(targetName) {
+    const readable = targetName.replace(/[^A-Za-z0-9]/g, '_').toUpperCase();
+    const digest = createHash('sha256').update(targetName).digest('hex').slice(0, 8).toUpperCase();
+    return `E2E_AGENT_DEVICE_POOL_${readable}_${digest}`;
+}
+/** Serializes the bindings for the environment: declared fields only, bounded. */
+export function encodeBindings(bindings) {
+    const encoded = JSON.stringify(bindings.map((binding) => obj({
+        device: binding.device,
+        deviceId: binding.deviceId,
+        daemon: binding.daemon === undefined ? undefined : obj({ baseUrl: binding.daemon.baseUrl, authToken: binding.daemon.authToken }),
+        client: binding.client,
+        installedApp: binding.installedApp,
+        sessionApp: binding.sessionApp,
+    })));
+    const bytes = Buffer.byteLength(encoded);
+    if (bytes > MAX_BINDINGS_ENV_BYTES) {
+        throw new EngineError('ENGINE_FAILURE', `the device bindings take ${bytes} bytes; the worker environment carries at most ${MAX_BINDINGS_ENV_BYTES}`, { retryable: false });
+    }
+    return encoded;
+}
+/** The bindings a `prepare` left in the environment, or `undefined` when there are none it can read. */
+export function decodeBindings(raw) {
+    if (raw === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed) && parsed.every(isSlotBinding))
+            return parsed;
+    }
+    catch {
+        // Not ours to read.
+    }
+    return undefined;
+}
+function isOptionalString(value) {
+    return value === undefined || typeof value === 'string';
+}
+/** A binding as JSON parses it back, or as a provider returned it: nothing the engine did not write is trusted. */
+export function isSlotBinding(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const { device, deviceId, daemon, client, installedApp, sessionApp } = value;
+    return (isOptionalString(device) &&
+        isOptionalString(deviceId) &&
+        isOptionalString(installedApp) &&
+        isOptionalString(sessionApp) &&
+        (daemon === undefined || isDaemon(daemon)) &&
+        (client === undefined || isClientConfig(client)));
+}
+/**
+ * Reserved for the engine and the `daemon` field, where a provider's value would be
+ * silently overruled; the transport is how the worker reaches the daemon, not a device fact.
+ */
+const RESERVED_CLIENT_KEYS = new Set(['session', 'daemonBaseUrl', 'daemonAuthToken', 'daemonTransport']);
+/** Plain JSON data with none of the reserved keys: what survives the environment and what the engine will not override. */
+function isClientConfig(value) {
+    return isJsonObject(value) && Object.keys(value).every((key) => !RESERVED_CLIENT_KEYS.has(key));
+}
+function isJsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) && Object.values(value).every(isJsonValue);
+}
+/** What survives `JSON.stringify` unchanged: a non-finite number would reach the worker as `null`. */
+function isJsonValue(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJsonValue);
+    return isJsonObject(value);
+}
+function isDaemon(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const { baseUrl, authToken } = value;
+    return typeof baseUrl === 'string' && isOptionalString(authToken);
+}
+//# sourceMappingURL=bindings.js.map

package/dist/bindings.js.map

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

package/dist/device.d.ts

@@ -0,0 +1,117 @@
+/**
+ * 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 { DevicePermission, PermissionState } from './options.ts';
+import type { AgentDeviceSurface, InstallAppOptions, InstalledApp, OpenAppOptions } from './surface.ts';
+/** 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 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.
+     */
+    setPermission(permission: DevicePermission, state: PermissionState): Promise<void>;
+    /** Sets the simulated location, switching location services on first on Android. */
+    setLocation(coordinates: {
+        latitude: number;
+        longitude: number;
+    }): Promise<void>;
+    /** Turns simulated location off; on Android that is location services off, until the next `setLocation`. */
+    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; without a path, the engine's
+     * `appPath`. The engine installs nothing on its own, so a suite that runs
+     * against a build calls this once per device, in a fixture or a test.
+     * `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, which becomes the app `app.open()` launches
+     * when the engine's build is installed and no `app` is pinned.
+     */
+    installApp(appPath?: string, options?: InstallAppOptions): Promise<InstalledApp>;
+    /**
+     * Brings an app to the foreground; `relaunch` restarts it fresh.
+     * `launchArguments` and `permissions` apply to this launch alone; the
+     * engine's configured ones apply to a `relaunch` of the pinned app, and
+     * to no foreground-only open.
+     */
+    openApp(app: string, options?: OpenAppOptions): Promise<void>;
+    /**
+     * Opens a deep link (`myapp://orders/42`) or a web link (`https://...`)
+     * into `app` (default: the pinned app), which the session observes
+     * afterwards. iOS launches the app for a web link and then opens the URL;
+     * a web link the app does not claim goes to Safari, and the next
+     * observation brings the app back. Android starts the link on that
+     * package. Without an app, Android lets the OS route the link; iOS needs
+     * one (`INVALID_ARGUMENT` without). `file:`, `data:`, and `javascript:`
+     * links are `POLICY_DENIED`.
+     */
+    openLink(url: string, options?: {
+        app?: string;
+    }): Promise<void>;
+    /**
+     * Terminates the session's app and ends the session, so the next
+     * `openApp` launches it fresh. Until then the screen is unobservable and
+     * `foregroundApp` is `APP_NOT_OPEN`.
+     */
+    closeApp(): Promise<void>;
+    /**
+     * Resets the simulator's keychain, every app's, since simctl has no
+     * per-app reset: what `app.clearState()` leaves behind (a session token, a
+     * Firebase sign-in). iOS simulator only; Android is
+     * `UNSUPPORTED_CAPABILITY`. Launch the app afterwards to see it signed out.
+     */
+    clearKeychain(): Promise<void>;
+    /**
+     * The app the session is on. iOS answers from the session, not the
+     * device, so it names the app the session opened even after `home()`;
+     * Android reads the device's foreground activity. `APP_NOT_OPEN` once
+     * `closeApp` ended 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,116 @@
+/**
+ * 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 { linkLabel, linkTarget } from './links.js';
+/** 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.setPermission(permission, state, context.signal);
+        },
+        async setLocation({ latitude, longitude }) {
+            // Android reads a fix only while location services are on, and
+            // `clearLocation` switched them off for good on the emulator (the
+            // setting outlives the app); iOS has no such switch.
+            if (surface.options.platform === 'android') {
+                await surface.command('device.setLocation', (client) => client.settings.update({ setting: 'location', state: 'on' }), context.signal);
+            }
+            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.screenCommand('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 ?? {}, context.signal);
+        },
+        async openLink(url, options) {
+            await surface.openLink(linkTarget(url), options?.app, context.signal);
+        },
+        async closeApp() {
+            await surface.closeApp(context.signal);
+        },
+        async clearKeychain() {
+            await surface.clearKeychain(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.screenCommand('device.home', (client) => client.command.home({}), context.signal);
+        },
+        async back() {
+            await surface.screenCommand('device.back', (client) => client.command.back({ ...surface.settleOptions }), context.signal);
+        },
+        async alert(action) {
+            await surface.screenCommand('device.alert', (client) => client.command.alert({ action }), context.signal);
+        },
+        async dismissKeyboard() {
+            await surface.dismissKeyboard(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 ?? surface.options.appPath ?? 'appPath' },
+        openApp: { ...action, label: (app) => linkLabel(app) },
+        openLink: { ...action, label: (url) => linkLabel(url) },
+        closeApp: action,
+        clearKeychain: 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":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AA4GnD,iDAAiD;AACjD,MAAM,UAAU,mBAAmB,CAAC,OAA2B,EAAE,OAA6B;IAC5F,MAAM,MAAM,GAAW;QACrB,OAAO,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC;QACtE,KAAK,CAAC,UAAU,CAAC,KAAK;YACpB,MAAM,OAAO,CAAC,OAAO,CACnB,mBAAmB,EACnB,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,EAClG,OAAO,CAAC,MAAM,CACf,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,eAAe,CAAC,OAAO;YAC3B,MAAM,OAAO,CAAC,OAAO,CACnB,wBAAwB,EACxB,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,EAC1F,OAAO,CAAC,MAAM,CACf,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,aAAa,CAAC,UAAU,EAAE,KAAK;YACnC,MAAM,OAAO,CAAC,aAAa,CAAC,UAAU,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QACjE,CAAC;QACD,KAAK,CAAC,WAAW,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE;YACvC,+DAA+D;YAC/D,kEAAkE;YAClE,qDAAqD;YACrD,IAAI,OAAO,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3C,MAAM,OAAO,CAAC,OAAO,CACnB,oBAAoB,EACpB,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,EACxE,OAAO,CAAC,MAAM,CACf,CAAC;YACJ,CAAC;YACD,MAAM,OAAO,CAAC,OAAO,CACnB,oBAAoB,EACpB,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAC9F,OAAO,CAAC,MAAM,CACf,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,aAAa;YACjB,MAAM,OAAO,CAAC,OAAO,CACnB,sBAAsB,EACtB,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EACzE,OAAO,CAAC,MAAM,CACf,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,aAAa,CAAC,IAAI;YACtB,MAAM,OAAO,CAAC,OAAO,CACnB,sBAAsB,EACtB,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,EAC1E,OAAO,CAAC,MAAM,CACf,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,cAAc,CAAC,WAAW;YAC9B,MAAM,OAAO,CAAC,aAAa,CAAC,uBAAuB,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QAChI,CAAC;QACD,KAAK,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM;YAChC,MAAM,OAAO,CAAC,OAAO,CACnB,sBAAsB,EACtB,CAAC,MAAM,EAAE,EAAE,CACT,MAAM,KAAK,aAAa;gBACtB,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;gBACnE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,EAChE,OAAO,CAAC,MAAM,CACf,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,gBAAgB,CAAC,MAAM,EAAE,QAAQ;YACrC,MAAM,OAAO,CAAC,OAAO,CACnB,yBAAyB,EACzB,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,EAChG,OAAO,CAAC,MAAM,CACf,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO;YAC/B,OAAO,OAAO,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QACpE,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO;YACxB,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,IAAI,EAAE,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QAC5D,CAAC;QACD,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,OAAO;YACzB,MAAM,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QACxE,CAAC;QACD,KAAK,CAAC,QAAQ;YACZ,MAAM,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACzC,CAAC;QACD,KAAK,CAAC,aAAa;YACjB,MAAM,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC9C,CAAC;QACD,KAAK,CAAC,aAAa;YACjB,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,sBAAsB,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;YACrH,IAAI,SAAS,IAAI,KAAK;gBAAE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;YAChF,OAAO;gBACL,IAAI,EAAE,KAAK,CAAC,OAAO;gBACnB,GAAG,CAAC,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC;aAC5E,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,IAAI;YACR,MAAM,OAAO,CAAC,aAAa,CAAC,aAAa,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QAClG,CAAC;QACD,KAAK,CAAC,IAAI;YACR,MAAM,OAAO,CAAC,aAAa,CAAC,aAAa,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QAC5H,CAAC;QACD,KAAK,CAAC,KAAK,CAAC,MAAM;YAChB,MAAM,OAAO,CAAC,aAAa,CAAC,cAAc,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QAC5G,CAAC;QACD,KAAK,CAAC,eAAe;YACnB,MAAM,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAChD,CAAC;QACD,KAAK,CAAC,SAAS;YACb,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAClC,kBAAkB,EAClB,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EACxD,OAAO,CAAC,MAAM,CACf,CAAC;YACF,OAAO,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,CAAC;QACD,KAAK,CAAC,YAAY,CAAC,IAAI;YACrB,MAAM,OAAO,CAAC,OAAO,CAAC,qBAAqB,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QAChI,CAAC;KACF,CAAC;IACF,MAAM,MAAM,GAAG,EAAE,IAAI,EAAE,UAAU,EAAW,CAAC;IAC7C,OAAO,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE;QACvC,UAAU,EAAE,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE;QAClD,eAAe,EAAE,MAAM;QACvB,aAAa,EAAE,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,EAAE;QAC/D,WAAW,EAAE,MAAM;QACnB,aAAa,EAAE,MAAM;QACrB,aAAa,EAAE,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE;QACnD,cAAc,EAAE,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,EAAE;QAClE,aAAa,EAAE,MAAM;QACrB,gBAAgB,EAAE,MAAM;QACxB,UAAU,EAAE,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,OAAO,IAAI,SAAS,EAAE;QAC9F,OAAO,EAAE,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE;QACtD,QAAQ,EAAE,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE;QACvD,QAAQ,EAAE,MAAM;QAChB,aAAa,EAAE,MAAM;QACrB,aAAa,EAAE,MAAM;QACrB,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,MAAM;QACZ,KAAK,EAAE,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE;QAC7C,eAAe,EAAE,MAAM;QACvB,SAAS,EAAE,MAAM;QACjB,YAAY,EAAE,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,QAAQ,EAAE;KACrE,CAAC,CAAC;AACL,CAAC"}

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; a test launches the pinned app with `app.open()`. */
+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,CAgDrE;AAED,wHAAwH;AACxH,wBAAgB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,YAAY,CAW3D;AAaD,wFAAwF;AACxF,wBAAgB,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,kBAAkB,GAAG,SAAS,CAE9E"}

package/dist/engine.js

@@ -0,0 +1,98 @@
+/**
+ * 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.signal),
+        },
+        app: declaredApp(surface.options),
+        // No `open`: a device app has no URL to open, so the runner serves
+        // `app.open()` with `restart`, the fresh launch of the pinned app, which
+        // is also the device's "recreate the context"; 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; a test launches the pinned app with `app.open()`. */
+export function mobile(options) {
+    const factory = (session, connection) => createAgentDeviceClient(obj({
+        ...connection?.client,
+        session,
+        daemonBaseUrl: connection?.daemon?.baseUrl,
+        daemonAuthToken: connection?.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,61 @@
+/**
+ * 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 / requires a session  | 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)       |
+ * | the iOS runner busy, wedged, or past its watchdog           | ENGINE_FAILURE, naming the   |
+ * | a snapshot the iOS runner acquired but could not present    |   runner and the recovery    |
+ * | anything else, agent-device's own timeouts included         | ENGINE_FAILURE with the text |
+ *
+ * `OPERATION_TIMEOUT` is never produced here. In the contract it means the
+ * harness budget expired, which `raceAbort` already reports, and core
+ * replaces its message with a bare `operation timed out`. A timeout
+ * agent-device itself reports (a simulator boot, the runner connecting, an
+ * app launch) is a device-side fault whose text is the diagnosis, so it
+ * stays `ENGINE_FAILURE` and keeps its message and hint.
+ */
+/** 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.
+ * `where` names the session and device the command ran under, for the
+ * messages whose recovery is per device.
+ */
+export declare function translateError(cause: unknown, operation: string, where?: string): Error;
+/**
+ * True for a translated failure of the iOS automation runner itself: busy,
+ * wedged, or past its watchdog. The runner, not the app, is what needs
+ * attention, so a caller that tolerates an app that did not open (warm-up)
+ * 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
+ * is safe and usually enough.
+ */
+export declare function isSnapshotPresentationFailure(error: unknown): boolean;
+/**
+ * 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, where?: string): 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, where?: 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;;;;;;;;;;;;;;;;;;;;;GAqBG;AAiBH,6DAA6D;AAC7D,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE9C;AAwHD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAkBvF;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEvD;AAID;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAErE;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAM1H;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAOhF"}