@e2e-dev/mobile 0.10.0 → 0.11.0-nightly-20261009094406

package/dist/.build.json

@@ -1 +1 @@
-{"version":"0.10.0"}
+{"version":"0.11.0-nightly-20261009094406"}

package/dist/surface.d.ts

@@ -68,6 +68,8 @@ export declare class AgentDeviceSurface {
     private readonly createClient;
     private client;
     private attempt;
+    /** The attempt's `EngineAttemptContext.screen`, which locate captures feed; undefined between attempts. */
+    private screenSink;
     /** The device this worker drives, the pool's binding for its slot; undefined leaves the choice to agent-device. */
     private device;
     private generation;
@@ -293,6 +295,12 @@ export declare class AgentDeviceSurface {
     observe(operation: OperationContext, options?: EngineObserveOptions): Promise<EngineSnapshot>;
     /** Retains only action bindings for matches, independently of the observation generation. */
     locate(expression: LocatorExpression, operation: OperationContext): Promise<readonly SemanticNode[]>;
+    /**
+     * Hands the harness the capture a locate matched against, for the trace:
+     * the screen the step acted on, at no cost of another snapshot. A screen
+     * whose viewport is not known yet is skipped rather than probed.
+     */
+    private traceScreen;
     private resolveRef;
     private actionTarget;
     /**

package/dist/surface.js

@@ -165,11 +165,22 @@ function settleOptions(settle) {
     }
     return { settle: true, settleQuietMs: quietMs };
 }
+/** Calls one of the harness's trace hooks; a hook that throws, or one an older harness lacks, never fails the device's work. */
+function tellHarness(call) {
+    try {
+        call();
+    }
+    catch {
+        // The trace is a reader of the attempt, never a reason it fails.
+    }
+}
 export class AgentDeviceSurface {
     options;
     createClient;
     client;
     attempt;
+    /** The attempt's `EngineAttemptContext.screen`, which locate captures feed; undefined between attempts. */
+    screenSink;
     /** The device this worker drives, the pool's binding for its slot; undefined leaves the choice to agent-device. */
     device;
     generation = new Map();
@@ -346,11 +357,15 @@ export class AgentDeviceSurface {
         this.attempt = { attemptId: context.attemptId, artifactsDir: context.artifactsDir, screenshots: 0, video: undefined };
         this.generation = new Map();
         this.located.clear();
+        this.screenSink = context.screen;
+        const device = deviceLabel(this.device);
+        tellHarness(() => context.environment?.({ platform: this.options.platform, ...(device === undefined ? {} : { device }) }));
     }
     async endAttempt(context) {
         const attempt = this.attempt;
         const dangling = attempt?.video;
         this.attempt = undefined;
+        this.screenSink = undefined;
         this.generation = new Map();
         this.located.clear();
         // The harness stops the video before it ends the attempt; a recording still
@@ -737,7 +752,7 @@ export class AgentDeviceSurface {
         this.generation = new Map(projected.index.map((entry) => [entry.id, this.bind(entry, projected.index)]));
         const viewport = await this.viewportFor(projected, operation.signal);
         const location = screenLocation(raw.appBundleId ?? raw.appName ?? this.appIdentity, screenTitle(projected));
-        const capture = options?.pixels === true ? await this.capturePixels(operation, projected, viewport) : undefined;
+        const capture = options?.pixels === true ? await this.capturePixels(operation, projected, viewport, { normalizeStatusBar: options.comparable === true }) : undefined;
         return {
             root: screenRoot(projected.roots, viewport),
             viewport,
@@ -750,6 +765,7 @@ export class AgentDeviceSurface {
     async locate(expression, operation) {
         const raw = await this.snapshotOrEmpty(operation, false);
         const projected = this.project(raw);
+        this.traceScreen(raw, projected);
         const matches = resolveExpression(expression, projected.index);
         for (const entry of matches)
             this.located.set(entry.id, this.bind(entry, projected.index));
@@ -760,6 +776,24 @@ export class AgentDeviceSurface {
         }
         return matches.map((entry) => entry.node);
     }
+    /**
+     * Hands the harness the capture a locate matched against, for the trace:
+     * the screen the step acted on, at no cost of another snapshot. A screen
+     * whose viewport is not known yet is skipped rather than probed.
+     */
+    traceScreen(raw, projected) {
+        const sink = this.screenSink;
+        const viewport = projected.viewport ?? this.knownViewport;
+        if (sink === undefined || viewport === undefined)
+            return;
+        const location = screenLocation(raw.appBundleId ?? raw.appName ?? this.appIdentity, screenTitle(projected));
+        tellHarness(() => sink({
+            root: screenRoot(projected.roots, viewport),
+            viewport,
+            ...(isTruncated(raw) ? { truncated: true } : {}),
+            ...(location === undefined ? {} : { location }),
+        }));
+    }
     resolveRef(ref) {
         const entry = this.located.get(ref.id) ?? this.generation.get(ref.id);
         if (entry === undefined) {
@@ -1190,20 +1224,20 @@ export class AgentDeviceSurface {
         return relative;
     }
     /** Raw device pixels; cleanup follows the capture even when its caller abandons it. */
-    rawScreenshot(signal) {
-        return this.captureScreenshot(signal, async (shot, file) => new Uint8Array(readFileSync(shot.path ?? file)));
+    rawScreenshot(signal, capture = {}) {
+        return this.captureScreenshot(signal, async (shot, file) => new Uint8Array(readFileSync(shot.path ?? file)), capture);
     }
     /**
      * One screenshot into a temp directory that is removed once `read` has
      * taken what it needs from the response or the file, even when the caller
      * abandons the capture.
      */
-    captureScreenshot(signal, read) {
+    captureScreenshot(signal, read, capture = {}) {
         return this.command('screenshot', async (client) => {
             const directory = mkdtempSync(path.join(tmpdir(), 'e2e-agent-device-'));
             const file = path.join(directory, 'screenshot.png');
             try {
-                return await read(await client.capture.screenshot({ path: file }), file);
+                return await read(await client.capture.screenshot({ path: file, ...(capture.normalizeStatusBar === true ? { normalizeStatusBar: true } : {}) }), file);
             }
             finally {
                 rmSync(directory, { recursive: true, force: true });
@@ -1238,10 +1272,10 @@ export class AgentDeviceSurface {
      * Viewport pixels for an observation. Best-effort: a screenshot that cannot
      * be produced or redacted costs the observation its image, not the step.
      */
-    async capturePixels(operation, projected, viewport) {
+    async capturePixels(operation, projected, viewport, capture) {
         let raw;
         try {
-            raw = await this.rawScreenshot(operation.signal);
+            raw = await this.rawScreenshot(operation.signal, capture);
         }
         catch {
             return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e2e-dev/mobile",
-  "version": "0.10.0",
+  "version": "0.11.0-nightly-20261009094406",
   "description": "Mobile engine (iOS and Android) for e2e agentic end-to-end testing, built on agent-device",
   "keywords": [
     "e2e",
@@ -57,7 +57,7 @@
   },
   "peerDependencies": {
     "ai": "^7.0.0",
-    "e2e": ">=0.15.0 <1"
+    "e2e": "0.19.0-nightly-20261009094406"
   },
   "peerDependenciesMeta": {
     "ai": {
@@ -68,7 +68,7 @@
     "@types/node": "26.6.2",
     "@types/pngjs": "6.0.5",
     "ai": "7.0.107",
-    "e2e": "0.18.0",
+    "e2e": "0.19.0-nightly-20261009094406",
     "typescript": "7.0.2",
     "vitest": "5.0.1"
   },