@e2e-dev/mobile 0.8.0-canary-20260928184528

package/dist/provider.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 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 DeviceClientConfig, 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 `app.open()` launches, 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.
+     * A lease names a daemon, `client` configuration, or both.
+     */
+    readonly daemon?: DeviceDaemon | undefined;
+    /**
+     * agent-device client configuration the worker's client is created with:
+     * how a daemon that runs agent-device's own device-cloud runtimes tells the
+     * leased device apart, as its `leases.allocate` returned it (`tenant`,
+     * `runId`, `leaseId`, `leaseBackend`, `leaseProvider`), or the `stateDir` of
+     * a daemon the provider started. JSON data only; `session`, `daemonBaseUrl`,
+     * and `daemonAuthToken` are refused, the engine and `daemon` own those.
+     */
+    readonly client?: DeviceClientConfig | undefined;
+    /** Device to select inside that daemon by name, when it hosts more than one. */
+    readonly device?: string | undefined;
+    /** Device to select inside that daemon by the id agent-device lists it under: a simulator UDID or an Android serial. */
+    readonly deviceId?: 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, `app.open()` launches this app. 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; a lease the engine then rejects is among them. */
+    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,112 @@
+/**
+ * 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';
+import { isLink } from './links.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;
+}
+/** An object with a lease id: something the provider granted and `release` is owed, whatever the field check makes of it. */
+function isGrantedLease(value) {
+    return typeof value === 'object' && value !== null && typeof value.id === 'string';
+}
+/** A granted lease checked field by field: the engine trusts nothing it did not write. */
+function isDeviceLease(lease) {
+    return isSlotBinding(lease) && (lease.daemon !== undefined || lease.client !== undefined);
+}
+const REJECTED_LEASE = 'returned a lease without an id and a daemon baseUrl or JSON client configuration (no `session` or daemon keys)';
+/** 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; a lease the engine then rejects is among them. */
+    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 (!isGrantedLease(lease))
+                throw new Error(REJECTED_LEASE);
+            // Held before it is checked: the provider bills for what it granted,
+            // and `release` is owed this same object however the check goes.
+            held.push(lease);
+            if (!isDeviceLease(lease))
+                throw new Error(REJECTED_LEASE);
+            if (lease.installedApp !== undefined && appPath === undefined) {
+                throw new Error('reported an installed app for a request without `appPath`');
+            }
+            // The pool opens this on the device in `prepare`; agent-device would open a link as a URL.
+            if (lease.installedApp !== undefined && isLink(lease.installedApp)) {
+                throw new Error('reported an installed app that is a link, not a bundle id or package');
+            }
+            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, deviceId: lease.deviceId, daemon: lease.daemon, client: lease.client, 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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"}

package/dist/support.d.ts

@@ -0,0 +1,63 @@
+/** Shared helpers for the agent-device engine: error constructors, filenames, PNG headers, gestures, the screen location and size. */
+import { EngineError, type Momentum, type ScrollDirection, type ViewportSize } from 'e2e/engine';
+export interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+export interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+export declare function cancelled(text: string): EngineError;
+export declare function invalidState(text: string): EngineError;
+export declare function notActionable(text: string): EngineError;
+export declare function unsupported(text: string): EngineError;
+/** Constrains a caller-supplied artifact label to a safe filename. */
+export declare function sanitizeFilename(name: string): string;
+/** Reads the dimensions out of a PNG's IHDR chunk; undefined for anything else. */
+export declare function readPngSize(data: Uint8Array): {
+    width: number;
+    height: number;
+} | undefined;
+/**
+ * The finger gesture that scrolls one rect's content in `direction`. Scrolling
+ * down reveals what is below, so the finger travels up; the travel is a share
+ * of the rect's extent scaled by momentum, and never leaves the rect. The
+ * root scroll sends no share (agent-device's default, see `perform`); these
+ * are for a gesture inside one control, and deterministic tests step through
+ * a list with `slow`, a quarter of the box, shorter than any row, so every
+ * row lands fully on screen at some stop. At three quarters the mobile
+ * benchmark's scenario list dragged rows past.
+ */
+export declare function swipeWithin(rect: Rect, direction: ScrollDirection, momentum: Momentum | undefined): {
+    from: Point;
+    to: Point;
+};
+/**
+ * The location a device surface reports in a snapshot: the foreground app
+ * and the screen shown, `<app> / <screen title>`. A simulator has no address
+ * bar, so this is an opaque address the harness shows to the model and the
+ * report and anchors trace replay on; it changes exactly when the app or its
+ * screen changes. It is deliberately not a URL: no scheme, no colon, so the
+ * harness never mistakes it for one and applies an origin policy to it.
+ * Undefined when neither the app nor a title is known.
+ */
+export declare function screenLocation(app: string | undefined, title: string | undefined): string | undefined;
+/** The screenshot fields a viewport probe reads off agent-device's response. */
+export interface RawScreenshotResult {
+    readonly path?: string;
+    readonly width?: number;
+    readonly height?: number;
+    readonly logicalWidth?: number;
+    readonly logicalHeight?: number;
+    readonly pixelDensity?: number;
+}
+/**
+ * The device's logical screen size as its screenshot reports it, in points:
+ * the logical dimensions when given, else the pixel dimensions over the
+ * density. Undefined when the response carries neither.
+ */
+export declare function logicalScreenSize(result: RawScreenshotResult): ViewportSize | undefined;
+//# sourceMappingURL=support.d.ts.map

package/dist/support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"support.d.ts","sourceRoot":"","sources":["../src/support.ts"],"names":[],"mappings":"AAAA,sIAAsI;AAEtI,OAAO,EAAE,WAAW,EAAE,KAAK,QAAQ,EAAE,KAAK,eAAe,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAEjG,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAEnD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAEtD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAEvD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAErD;AAED,sEAAsE;AACtE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAID,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAO3F;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,eAAe,EAC1B,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAC7B;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,EAAE,EAAE,KAAK,CAAA;CAAE,CAe5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAKrG;AAED,gFAAgF;AAChF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,mBAAmB,GAC1B,YAAY,GAAG,SAAS,CAS1B"}

package/dist/support.js

@@ -0,0 +1,87 @@
+/** Shared helpers for the agent-device engine: error constructors, filenames, PNG headers, gestures, the screen location and size. */
+import { EngineError } from 'e2e/engine';
+export function cancelled(text) {
+    return new EngineError('CANCELLED', text, { retryable: false });
+}
+export function invalidState(text) {
+    return new EngineError('INVALID_STATE', text, { retryable: false });
+}
+export function notActionable(text) {
+    return new EngineError('NOT_ACTIONABLE', text, { retryable: false });
+}
+export function unsupported(text) {
+    return new EngineError('UNSUPPORTED_CAPABILITY', text, { retryable: false });
+}
+/** Constrains a caller-supplied artifact label to a safe filename. */
+export function sanitizeFilename(name) {
+    return name.replaceAll(/[^A-Za-z0-9._-]/g, '_').slice(0, 64) || 'artifact';
+}
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+/** Reads the dimensions out of a PNG's IHDR chunk; undefined for anything else. */
+export function readPngSize(data) {
+    if (data.byteLength < 24)
+        return undefined;
+    for (const [offset, byte] of PNG_SIGNATURE.entries()) {
+        if (data[offset] !== byte)
+            return undefined;
+    }
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    return { width: view.getUint32(16), height: view.getUint32(20) };
+}
+/**
+ * The finger gesture that scrolls one rect's content in `direction`. Scrolling
+ * down reveals what is below, so the finger travels up; the travel is a share
+ * of the rect's extent scaled by momentum, and never leaves the rect. The
+ * root scroll sends no share (agent-device's default, see `perform`); these
+ * are for a gesture inside one control, and deterministic tests step through
+ * a list with `slow`, a quarter of the box, shorter than any row, so every
+ * row lands fully on screen at some stop. At three quarters the mobile
+ * benchmark's scenario list dragged rows past.
+ */
+export function swipeWithin(rect, direction, momentum) {
+    const ratio = momentum === 'fast' ? 0.8 : momentum === 'slow' ? 0.25 : 0.5;
+    const centre = { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+    const dx = (rect.width * ratio) / 2;
+    const dy = (rect.height * ratio) / 2;
+    switch (direction) {
+        case 'down':
+            return { from: { x: centre.x, y: centre.y + dy }, to: { x: centre.x, y: centre.y - dy } };
+        case 'up':
+            return { from: { x: centre.x, y: centre.y - dy }, to: { x: centre.x, y: centre.y + dy } };
+        case 'right':
+            return { from: { x: centre.x + dx, y: centre.y }, to: { x: centre.x - dx, y: centre.y } };
+        case 'left':
+            return { from: { x: centre.x - dx, y: centre.y }, to: { x: centre.x + dx, y: centre.y } };
+    }
+}
+/**
+ * The location a device surface reports in a snapshot: the foreground app
+ * and the screen shown, `<app> / <screen title>`. A simulator has no address
+ * bar, so this is an opaque address the harness shows to the model and the
+ * report and anchors trace replay on; it changes exactly when the app or its
+ * screen changes. It is deliberately not a URL: no scheme, no colon, so the
+ * harness never mistakes it for one and applies an origin policy to it.
+ * Undefined when neither the app nor a title is known.
+ */
+export function screenLocation(app, title) {
+    const parts = [app, title]
+        .map((part) => (part === undefined ? '' : part.replaceAll(/\s+/g, ' ').trim()))
+        .filter((part) => part !== '');
+    return parts.length === 0 ? undefined : parts.join(' / ');
+}
+/**
+ * The device's logical screen size as its screenshot reports it, in points:
+ * the logical dimensions when given, else the pixel dimensions over the
+ * density. Undefined when the response carries neither.
+ */
+export function logicalScreenSize(result) {
+    const logical = result.logicalWidth !== undefined && result.logicalHeight !== undefined
+        ? { width: result.logicalWidth, height: result.logicalHeight }
+        : result.width !== undefined && result.height !== undefined && result.pixelDensity !== undefined && result.pixelDensity > 0
+            ? { width: result.width / result.pixelDensity, height: result.height / result.pixelDensity }
+            : undefined;
+    if (logical === undefined || logical.width <= 0 || logical.height <= 0)
+        return undefined;
+    return logical;
+}
+//# sourceMappingURL=support.js.map

package/dist/support.js.map

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