@e2edev/mobile 0.8.0-canary-20260921180210

package/dist/pool.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The devices one target drives: one simulator or emulator per worker slot,
+ * each under its own agent-device session. A named `device` is a pool of one
+ * and a list a pool of many; with no `device` the pool is every booted device
+ * of the platform, discovered in `prepare`; a `DeviceProvider` leases one
+ * hosted device per slot instead. Each is a `DeviceSource`; `prepare` binds
+ * one `SlotBinding` per slot from it, warms each once per run before any
+ * worker exists, and hands the bindings to the workers through the run's
+ * environment. The worker that owns a slot then resumes its session in
+ * `init`, and `finish` releases what the source acquired.
+ */
+import { type EngineFinishInfo, type EnginePrepareInfo, type EnginePrepareResult } from 'e2e/engine';
+import { type SlotBinding } from './bindings.ts';
+import type { MobileOptions, MobilePlatform, ClientFactory } from './options.ts';
+/**
+ * The device selection agent-device commands take: the platform, and the
+ * device when one is named, as `udid` for a simulator UDID and `device` for a
+ * name, the two fields agent-device resolves them by.
+ */
+export declare function deviceSelection(platform: MobilePlatform, device: string | undefined): {
+    platform: MobilePlatform;
+    device?: string;
+    udid?: string;
+};
+export declare class DevicePool {
+    private readonly options;
+    private readonly createClient;
+    private readonly source;
+    /** What this process's `prepare` bound, per target: a handle may serve several targets and runs. */
+    private readonly bound;
+    constructor(options: MobileOptions, createClient: ClientFactory);
+    /**
+     * Workers the engine serves per target, one per device: known up front for
+     * a configured pool, and `undefined` for a discovered or leased one until
+     * `prepare` reports it, which lets the run plan with its own cap meanwhile.
+     */
+    get size(): number | undefined;
+    /** The agent-device session a worker slot drives its device under: the `session` option or `e2e-<target>`, then `-<slot>`. */
+    session(targetName: string, slot: number): string;
+    /**
+     * What a worker slot drives, for a worker's `init`: what this process's
+     * `prepare` bound for the target (an in-process run), else what `prepare`
+     * left in the environment (a child worker), else the source's fallback
+     * for a run without `prepare`. With none, the choice stays with the local
+     * daemon, which picks a booted device. A slot beyond the pool is a broken
+     * invariant: the runner caps the target at the workers this engine
+     * declared or reported.
+     */
+    binding(targetName: string, slot: number, env: Readonly<Record<string, string | undefined>>): SlotBinding | undefined;
+    /**
+     * 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 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>;
+    /** Releases what the source acquired for the target; a local pool has nothing to release. */
+    finish(info: EngineFinishInfo): Promise<void>;
+    /**
+     * Boots every bound device and opens the pinned app on it once, so its
+     * automation runner is up. One slot after another, on purpose: workers
+     * booting at once in `init` contend for the host and the daemon, and one
+     * cold boot pushes the others past `launchTimeout`. Each slot warms under
+     * the session its worker resumes. A device that cannot boot ends the run
+     * here; an app that does not open is logged and left to the first attempt.
+     * A build `appPath` installs in `init` is not on the device yet, so that
+     * slot boots only, unless a lease says the build is already there.
+     */
+    private warm;
+}
+//# sourceMappingURL=pool.d.ts.map

package/dist/pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAwC,KAAK,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,KAAK,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAC3I,OAAO,EAAkF,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjI,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAMjF;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB;IAAE,QAAQ,EAAE,cAAc,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAG9D;AA8ED,qBAAa,UAAU;IAMnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAN/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,oGAAoG;IACpG,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6C;IAEnE,YACmB,OAAO,EAAE,aAAa,EACtB,YAAY,EAAE,aAAa,EAG7C;IAED;;;;OAIG;IACH,IAAI,IAAI,IAAI,MAAM,GAAG,SAAS,CAE7B;IAED,8HAA8H;IAC9H,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;IAED;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GAAG,WAAW,GAAG,SAAS,CAYpH;IAED;;;;;;OAMG;IACG,OAAO,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAMnE;IAED,6FAA6F;IACvF,MAAM,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAElD;IAED;;;;;;;;;OASG;YACW,IAAI;CAiBnB"}

package/dist/pool.js

@@ -0,0 +1,185 @@
+/**
+ * The devices one target drives: one simulator or emulator per worker slot,
+ * each under its own agent-device session. A named `device` is a pool of one
+ * and a list a pool of many; with no `device` the pool is every booted device
+ * of the platform, discovered in `prepare`; a `DeviceProvider` leases one
+ * hosted device per slot instead. Each is a `DeviceSource`; `prepare` binds
+ * one `SlotBinding` per slot from it, warms each once per run before any
+ * worker exists, and hands the bindings to the workers through the run's
+ * environment. The worker that owns a slot then resumes its session in
+ * `init`, and `finish` releases what the source acquired.
+ */
+import { ConfigurationError, EngineError, obj } from 'e2e/engine';
+import { bindingsVariable, decodeBindings, encodeBindings, pinnedApp } from './bindings.js';
+import { message, runCommand } from './errors.js';
+import { asDeviceProvider, LeasedDevices } from './provider.js';
+/** An Apple simulator UDID; anything else names a device. */
+const UDID = /^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$/i;
+/**
+ * The device selection agent-device commands take: the platform, and the
+ * device when one is named, as `udid` for a simulator UDID and `device` for a
+ * name, the two fields agent-device resolves them by.
+ */
+export function deviceSelection(platform, device) {
+    if (device !== undefined && UDID.test(device))
+        return { platform, udid: device };
+    return obj({ platform, device });
+}
+function isDeviceList(device) {
+    return Array.isArray(device);
+}
+/** The source the `device` option names: a configured pool, the booted devices, or a provider's leases. */
+function sourceFor(options, createClient, session) {
+    const { device } = options;
+    if (device === undefined)
+        return new BootedDevices(options.platform, createClient, session);
+    if (typeof device === 'string')
+        return new ConfiguredDevices([device]);
+    if (isDeviceList(device)) {
+        if (device.length === 0) {
+            throw new ConfigurationError('INVALID_CONFIG', 'mobile: `device` is an empty pool; name at least one simulator or emulator, or omit it to use every booted one');
+        }
+        return new ConfiguredDevices(device);
+    }
+    return new LeasedDevices(asDeviceProvider(device), options);
+}
+/** The devices named in the config, bound in order, as many as the run has slots. */
+class ConfiguredDevices {
+    size;
+    fallback;
+    constructor(devices) {
+        this.size = devices.length;
+        this.fallback = devices.map((device) => ({ device }));
+    }
+    async bind(info) {
+        return this.fallback.slice(0, Math.min(info.slots, this.size));
+    }
+}
+/** Every booted device of the platform, as many as the run has slots; with none booted, one slot the daemon fills. */
+class BootedDevices {
+    platform;
+    createClient;
+    session;
+    constructor(platform, createClient, session) {
+        this.platform = platform;
+        this.createClient = createClient;
+        this.session = session;
+    }
+    async bind(info) {
+        const booted = await this.inventory(info.targetName, info.signal);
+        const chosen = booted.slice(0, info.slots);
+        if (chosen.length === 0) {
+            info.log(`no booted ${this.platform} device; agent-device boots one`);
+            return [{}];
+        }
+        info.log(`${booted.length} booted ${this.platform} device(s); driving ${chosen.length}: ${chosen.map((device) => device.name).join(', ')}`);
+        return chosen.map((device) => ({ device: device.id }));
+    }
+    /** Every booted device of the platform, by stable id and name, in agent-device's inventory order. */
+    async inventory(targetName, signal) {
+        const client = this.createClient(this.session(targetName, 0));
+        const inventory = await runCommand('devices', () => client.devices.list({ platform: this.platform }), signal);
+        if (!Array.isArray(inventory))
+            return [];
+        return inventory
+            .filter((device) => typeof device === 'object' &&
+            device !== null &&
+            device.booted === true &&
+            device.platform === this.platform &&
+            typeof device.id === 'string')
+            .map((device) => ({ id: device.id, name: typeof device.name === 'string' ? device.name : device.id }));
+    }
+}
+export class DevicePool {
+    options;
+    createClient;
+    source;
+    /** What this process's `prepare` bound, per target: a handle may serve several targets and runs. */
+    bound = new Map();
+    constructor(options, createClient) {
+        this.options = options;
+        this.createClient = createClient;
+        this.source = sourceFor(options, createClient, (targetName, slot) => this.session(targetName, slot));
+    }
+    /**
+     * Workers the engine serves per target, one per device: known up front for
+     * a configured pool, and `undefined` for a discovered or leased one until
+     * `prepare` reports it, which lets the run plan with its own cap meanwhile.
+     */
+    get size() {
+        return this.source.size;
+    }
+    /** The agent-device session a worker slot drives its device under: the `session` option or `e2e-<target>`, then `-<slot>`. */
+    session(targetName, slot) {
+        return `${this.options.session ?? `e2e-${targetName}`}-${slot}`;
+    }
+    /**
+     * What a worker slot drives, for a worker's `init`: what this process's
+     * `prepare` bound for the target (an in-process run), else what `prepare`
+     * left in the environment (a child worker), else the source's fallback
+     * for a run without `prepare`. With none, the choice stays with the local
+     * daemon, which picks a booted device. A slot beyond the pool is a broken
+     * invariant: the runner caps the target at the workers this engine
+     * declared or reported.
+     */
+    binding(targetName, slot, env) {
+        const bindings = this.bound.get(targetName) ?? decodeBindings(env[bindingsVariable(targetName)]) ?? this.source.fallback;
+        if (bindings === undefined)
+            return undefined;
+        const binding = bindings[slot];
+        if (binding === undefined) {
+            throw new EngineError('ENGINE_FAILURE', `worker slot ${slot} is outside a device pool of ${bindings.length}; the runner must cap the target at the engine's declared workers`, { retryable: false });
+        }
+        return binding;
+    }
+    /**
+     * 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 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.source.bind(info);
+        this.bound.set(info.targetName, bindings);
+        await this.warm(bindings, info);
+        return { workers: bindings.length, env: { [bindingsVariable(info.targetName)]: encodeBindings(bindings) } };
+    }
+    /** Releases what the source acquired for the target; a local pool has nothing to release. */
+    async finish(info) {
+        await this.source.finish?.(info);
+    }
+    /**
+     * Boots every bound device and opens the pinned app on it once, so its
+     * automation runner is up. One slot after another, on purpose: workers
+     * booting at once in `init` contend for the host and the daemon, and one
+     * cold boot pushes the others past `launchTimeout`. Each slot warms under
+     * the session its worker resumes. A device that cannot boot ends the run
+     * here; an app that does not open is logged and left to the first attempt.
+     * A build `appPath` installs in `init` is not on the device yet, so that
+     * slot boots only, unless a lease says the build is already there.
+     */
+    async warm(bindings, info) {
+        for (const [slot, binding] of bindings.entries()) {
+            const label = binding.device ?? `a booted ${this.options.platform} device`;
+            const where = deviceSelection(this.options.platform, binding.device);
+            const client = this.createClient(this.session(info.targetName, slot), binding.daemon);
+            info.log(`booting ${label} (${slot + 1} of ${bindings.length})`);
+            await runCommand('boot', () => client.devices.boot(where), info.signal);
+            const app = pinnedApp(this.options, binding.installedApp);
+            if (app === undefined)
+                continue;
+            try {
+                await runCommand(`open ${app}`, () => client.apps.open({ app, ...where }), info.signal);
+            }
+            catch (cause) {
+                if (info.signal.aborted)
+                    throw cause;
+                info.log(`${label}: automation runner not warmed up (${message(cause)}); the first attempt starts it`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=pool.js.map

package/dist/pool.js.map

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

package/dist/provider.d.ts

@@ -0,0 +1,105 @@
+/**
+ * The seam a hosted device service plugs into: a `DeviceProvider` leases one
+ * device per worker slot for the run and hands back the agent-device daemon
+ * that drives it. The engine acquires in `prepare`, drives each lease from
+ * its worker, and releases in `finish`, on every exit path. Nothing here
+ * knows any vendor: a hosted simulator service, a device farm, or a daemon on
+ * a machine down the hall are each one small provider in user code.
+ */
+import { type EngineFinishInfo, type EnginePrepareInfo } from 'e2e/engine';
+import { type DeviceDaemon, type DeviceSource, type SlotBinding } from './bindings.ts';
+import type { MobileOptions, MobilePlatform } from './options.ts';
+/** What the engine asks a provider for: one device for one worker slot of a run. */
+export interface DeviceRequest {
+    /** Platform the target's device must run. */
+    readonly platform: MobilePlatform;
+    /** The run id, for naming the session at the provider. */
+    readonly runId: string;
+    /** The target the device serves. */
+    readonly targetName: string;
+    /** Worker slot the device serves, `0` to `slots - 1`; `slots` leases are acquired at once. */
+    readonly slot: number;
+    /** Devices the run acquires for this target, in all. */
+    readonly slots: number;
+    /** The `app` option: the bundle id or package the engine opens fresh per attempt, when the config names one. */
+    readonly app?: string | undefined;
+    /**
+     * The build the engine would install, resolved to an absolute path, when
+     * the config names one. A provider that installs it itself (uploading it,
+     * or naming a build it already hosts) reports `installedApp` on the lease
+     * and the engine skips its own install.
+     */
+    readonly appPath?: string | undefined;
+    /** The run's environment: where a provider reads its token from, never `process.env`. */
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /** Aborts on interrupt only; acquiring has no budget of its own. */
+    readonly signal: AbortSignal;
+    /** Reports one line of progress to the run's reporter (a session URL to watch). */
+    readonly log: (line: string) => void;
+}
+/**
+ * One leased device, as `acquire` returns it and `release` gets it back.
+ * JSON data only: a lease travels from the runner process to the worker that
+ * drives it through the environment.
+ */
+export interface DeviceLease extends SlotBinding {
+    /**
+     * The provider's handle on the lease (a session id); named in progress
+     * lines and handed back to `release`. A provider may keep further fields on
+     * the object it returns: `release` gets that same object, while only the
+     * fields declared here travel to the worker.
+     */
+    readonly id: string;
+    /** The agent-device daemon the worker connects to instead of its local one. */
+    readonly daemon: DeviceDaemon;
+    /** Device to select inside that daemon, by name or UDID, when it hosts more than one. */
+    readonly device?: string | undefined;
+    /**
+     * Bundle id or package of the app the provider installed from the
+     * request's `appPath`, and only then: with it the engine installs nothing
+     * and, without an `app` option, opens this app fresh per attempt. A lease
+     * reporting one for a request without `appPath` fails the run.
+     */
+    readonly installedApp?: string | undefined;
+}
+/** Handed to `release`, once per lease at the end of the run. */
+export interface DeviceReleaseContext {
+    readonly runId: string;
+    readonly targetName: string;
+    /** The run's environment, the same `acquire` saw. */
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /** Aborts when the cleanup budget is spent. */
+    readonly signal: AbortSignal;
+    readonly log: (line: string) => void;
+}
+/**
+ * A source of hosted devices. `acquire` is called once per worker slot, for
+ * every slot at once; `release` once per lease acquired, at the end of the
+ * run, also after an `acquire` of another slot failed. Both run in the
+ * runner process, so a provider may keep state between them.
+ */
+export interface DeviceProvider {
+    /** Label in progress lines and error messages. */
+    readonly name: string;
+    acquire(request: DeviceRequest): Promise<DeviceLease>;
+    release(lease: DeviceLease, context: DeviceReleaseContext): Promise<void>;
+}
+/** Narrows an intended provider, or names what it is missing. */
+export declare function asDeviceProvider(device: object): DeviceProvider;
+/**
+ * Devices a provider leases, one per slot, all at once: hosted sessions start
+ * in parallel and are billed from the moment they do, so nothing waits on a
+ * sibling. Every lease granted is held for `finish` before the outcome is
+ * known, so a slot that fails to lease fails the run and the others are
+ * still released, each one whatever happened to the rest.
+ */
+export declare class LeasedDevices implements DeviceSource {
+    private readonly provider;
+    private readonly options;
+    /** Leases granted so far, per target, filled as each `acquire` settles. */
+    private readonly held;
+    constructor(provider: DeviceProvider, options: Pick<MobileOptions, 'platform' | 'app' | 'appPath'>);
+    bind(info: EnginePrepareInfo): Promise<readonly SlotBinding[]>;
+    finish(info: EngineFinishInfo): Promise<void>;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

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

package/dist/provider.js

@@ -0,0 +1,98 @@
+/**
+ * The seam a hosted device service plugs into: a `DeviceProvider` leases one
+ * device per worker slot for the run and hands back the agent-device daemon
+ * that drives it. The engine acquires in `prepare`, drives each lease from
+ * its worker, and releases in `finish`, on every exit path. Nothing here
+ * knows any vendor: a hosted simulator service, a device farm, or a daemon on
+ * a machine down the hall are each one small provider in user code.
+ */
+import path from 'node:path';
+import { ConfigurationError, EngineError, obj } from 'e2e/engine';
+import { isSlotBinding } from './bindings.js';
+import { message } from './errors.js';
+/** Narrows an intended provider, or names what it is missing. */
+export function asDeviceProvider(device) {
+    const candidate = device;
+    if (typeof candidate.name !== 'string' || candidate.name.trim() === '') {
+        throw new ConfigurationError('INVALID_CONFIG', 'mobile: a `device` provider needs a non-empty `name`');
+    }
+    for (const member of ['acquire', 'release']) {
+        if (typeof candidate[member] !== 'function') {
+            throw new ConfigurationError('INVALID_CONFIG', `mobile: device provider "${candidate.name}" must implement ${member}()`);
+        }
+    }
+    return device;
+}
+/** A lease as a provider returned it, checked field by field: the engine trusts nothing it did not write. */
+function isDeviceLease(value) {
+    return isSlotBinding(value) && typeof value.id === 'string' && value.daemon !== undefined;
+}
+/** Runs every task, then reports the first failure: nothing is skipped because a sibling failed. */
+async function allOrFirstFailure(tasks, describe) {
+    // `async` so a task that throws before its first await is a rejection like any other, not an escape.
+    const settled = await Promise.allSettled(tasks.map(async (task) => task()));
+    const failed = settled.find((result) => result.status === 'rejected');
+    if (failed !== undefined) {
+        throw new EngineError('ENGINE_FAILURE', `${describe}: ${message(failed.reason)}`, { retryable: false, cause: failed.reason });
+    }
+    return settled.flatMap((result) => (result.status === 'fulfilled' ? [result.value] : []));
+}
+/**
+ * Devices a provider leases, one per slot, all at once: hosted sessions start
+ * in parallel and are billed from the moment they do, so nothing waits on a
+ * sibling. Every lease granted is held for `finish` before the outcome is
+ * known, so a slot that fails to lease fails the run and the others are
+ * still released, each one whatever happened to the rest.
+ */
+export class LeasedDevices {
+    provider;
+    options;
+    /** Leases granted so far, per target, filled as each `acquire` settles. */
+    held = new Map();
+    constructor(provider, options) {
+        this.provider = provider;
+        this.options = options;
+    }
+    async bind(info) {
+        const { provider } = this;
+        const { platform, app } = this.options;
+        const appPath = this.options.appPath === undefined ? undefined : path.resolve(info.projectRoot, this.options.appPath);
+        const held = [];
+        this.held.set(info.targetName, held);
+        info.log(`leasing ${info.slots} ${platform} device(s) from ${provider.name}`);
+        const leases = await allOrFirstFailure(Array.from({ length: info.slots }, (_, slot) => async () => {
+            const lease = await provider.acquire({
+                platform,
+                runId: info.runId,
+                targetName: info.targetName,
+                slot,
+                slots: info.slots,
+                app,
+                appPath,
+                env: info.env,
+                signal: info.signal,
+                log: (line) => info.log(`${provider.name} (${slot + 1} of ${info.slots}): ${line}`),
+            });
+            if (!isDeviceLease(lease))
+                throw new Error('returned a lease without an id and a daemon baseUrl');
+            held.push(lease);
+            if (lease.installedApp !== undefined && appPath === undefined) {
+                throw new Error('reported an installed app for a request without `appPath`');
+            }
+            info.log(`${provider.name}: leased ${lease.id}${lease.device === undefined ? '' : ` (${lease.device})`}`);
+            return lease;
+        }), `device provider "${provider.name}" could not lease a device`);
+        return leases.map((lease) => obj({ device: lease.device, daemon: lease.daemon, installedApp: lease.installedApp }));
+    }
+    async finish(info) {
+        const { provider } = this;
+        const leases = this.held.get(info.targetName);
+        this.held.delete(info.targetName);
+        if (leases === undefined || leases.length === 0)
+            return;
+        const context = { runId: info.runId, targetName: info.targetName, env: info.env, signal: info.signal, log: (line) => info.log(`${provider.name}: ${line}`) };
+        await allOrFirstFailure(leases.map((lease) => () => provider.release(lease, context)), `device provider "${provider.name}" could not release a device`);
+        info.log(`${provider.name}: released ${leases.length} device(s)`);
+    }
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

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

package/dist/selector.d.ts

@@ -0,0 +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.
+ */
+import { type ProjectedNode } from './nodes.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.
+ */
+export declare function compileSelector(raw: string): CompiledSelector;
+//# sourceMappingURL=selector.d.ts.map

package/dist/selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector.d.ts","sourceRoot":"","sources":["../src/selector.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAQ/D,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,KAAK,aAAa,EAAE,CAAC;AAEtF;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAiB7D"}

package/dist/selector.js

@@ -0,0 +1,84 @@
+/**
+ * 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.
+ */
+import { 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.
+ */
+export function compileSelector(raw) {
+    let chain;
+    try {
+        chain = parseSelectorChain(raw);
+    }
+    catch (cause) {
+        throw new EngineError('ENGINE_FAILURE', `invalid agent-device selector ${JSON.stringify(raw)}: ${message(cause)}`, {
+            retryable: false,
+            cause,
+        });
+    }
+    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 [];
+    };
+}
+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;
+    }
+}
+//# sourceMappingURL=selector.js.map

package/dist/selector.js.map

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