@e2e-dev/mobile 0.8.0-canary-20260928184528 → 0.8.0

package/dist/surface.d.ts

@@ -12,7 +12,7 @@
  * scrolls the whole screen.
  */
 import { type EngineAttemptContext, type EngineCleanupContext, type EngineInitInfo, type EngineObserveOptions, type EngineSnapshot, type LocatorAction, type LocatorExpression, type NodeRef, type OperationContext, type PointerAction, type VideoSegment, type SemanticNode, type ViewportPoint } from 'e2e/engine';
-import type { AgentDeviceClient, ClientFactory, DevicePermission, LaunchPermissions, MobileOptions, PermissionState } from './options.ts';
+import { type AgentDeviceClient, type ClientFactory, type DevicePermission, type LaunchPermissions, type MobileOptions, type PermissionState } from './options.ts';
 import { DevicePool } from './pool.ts';
 /** How `installApp` puts a build on the device. */
 export interface InstallAppOptions {
@@ -36,14 +36,14 @@ export interface OpenAppOptions {
     readonly relaunch?: boolean;
     /**
      * Arguments this launch hands the app: its process arguments on iOS,
-     * `am start` arguments on Android. Replaces the engine's `launchArguments`
-     * for a relaunch of the pinned app.
+     * `am start` arguments on Android. Replaces the target's
+     * `app.launchArguments` for a relaunch of the pinned app.
      */
     readonly launchArguments?: readonly string[];
     /**
      * Permissions the app holds before this launch, each granted, denied, or
-     * reset. Replaces the engine's `permissions` for a relaunch of the pinned
-     * app.
+     * reset. Replaces the target's `app.permissions` for a relaunch of the
+     * pinned app.
      */
     readonly permissions?: LaunchPermissions;
 }
@@ -52,6 +52,15 @@ type SettleOptions = {
     readonly settle: true;
     readonly settleQuietMs: number;
 } | Record<never, never>;
+/**
+ * Refuses a permissions map before any device command: anything but a plain
+ * object, a name agent-device
+ * does not set, naming the nearest, or a state other than grant, deny, or
+ * reset. `INVALID_CONFIG` for a target's `app.permissions`, `INVALID_ARGUMENT`
+ * for a test's `device.openApp`. An `undefined` state is skipped, as the preset
+ * skips it.
+ */
+export declare function assertPermissions(label: string, permissions: unknown, code: 'INVALID_CONFIG' | 'INVALID_ARGUMENT'): void;
 export declare class AgentDeviceSurface {
     readonly options: MobileOptions;
     private readonly createClient;
@@ -73,10 +82,14 @@ export declare class AgentDeviceSurface {
     private sessionApp;
     /** The app the build `appPath` installed, once `init` has, itself or through a lease. */
     private installedApp;
+    /** The target's app, as `init` received it. */
+    private app;
     /** Where relative build paths resolve; the run's project root once init has told us. */
     private projectRoot;
     /** The session and device this worker drives, for the error messages whose recovery is per device; set in init. */
     private where;
+    /** How this worker's device records through its provider: set in init when the pool's provider records and the slot rides one of its leases. */
+    private leaseRecorder;
     /**
      * Commands still running on the device. agent-device takes no abort
      * signal, so a cancelled or timed-out call is only abandoned by its
@@ -104,10 +117,12 @@ export declare class AgentDeviceSurface {
      */
     private knownViewport;
     constructor(options: MobileOptions, createClient: ClientFactory);
-    /** Whether the manifest declares app restart and state clearing. */
-    get managesApp(): boolean;
-    /** The app `app.open()` launches: the `app` option, else the build `appPath` installed. */
+    /** Whether the target pins an app for `app.open()`, `app.restart()`, and `app.clearState()` to launch. */
+    private get managesApp();
+    /** The app `app.open()` launches: the target's `bundleId`, else the app its build `appPath` installed. */
     get pinnedApp(): string | undefined;
+    /** The build the target's `app.appPath` names, as declared. */
+    get appPath(): string | undefined;
     /** Whether an attempt is running on this surface right now. */
     get attemptRunning(): boolean;
     /** The live client; INVALID_STATE before init or after dispose. */
@@ -152,11 +167,29 @@ export declare class AgentDeviceSurface {
     /**
      * Asks the device to record its screen into the attempt directory. Taps stay
      * visible in the recording (agent-device's touch indicator), which is the
-     * closest a phone comes to a cursor.
+     * closest a phone comes to a cursor, unless `videoTouches` is `false`. A
+     * device provider that records its devices records the attempt instead,
+     * when the slot rides one of its leases.
      */
     startVideo(operation: OperationContext): Promise<void>;
     /** Stops the recording and returns its one segment, or none when the device wrote nothing. */
     stopVideo(operation: OperationContext): Promise<readonly VideoSegment[]>;
+    /**
+     * Stops the device's screen recording. A device-scope recording started
+     * with no session made one of its own, and stopping it ends that session,
+     * whatever the test opened in it since, so the session is then as
+     * `closeApp` leaves it.
+     */
+    private stopScreenRecording;
+    /**
+     * Starts the device provider's recording of the leased device. Marked
+     * the moment `record` is called, before it settles, as the screen
+     * recording is before its start command: a start that outlives its budget
+     * may still come up, and `endAttempt` then stops it.
+     */
+    private startLeaseRecording;
+    /** Ends the provider's recording as the attempt's one segment, a file in its `video` directory or a link. */
+    private stopLeaseRecording;
     dispose(context: EngineCleanupContext): Promise<void>;
     /**
      * Opens an app in the session, remembering its identity for the path

package/dist/surface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"surface.d.ts","sourceRoot":"","sources":["../src/surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAML,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,OAAO,EAEZ,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,aAAa,EAInB,MAAM,YAAY,CAAC;AAcpB,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAI1I,OAAO,EAAE,UAAU,EAAyC,MAAM,WAAW,CAAC;AAe9E,mDAAmD;AACnD,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAaD,4CAA4C;AAC5C,MAAM,WAAW,cAAc;IAC7B,yGAAyG;IACzG,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,iBAAiB,CAAC;CAC1C;AAiID,gEAAgE;AAChE,KAAK,aAAa,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAuBtG,qBAAa,kBAAkB;IAoD3B,QAAQ,CAAC,OAAO,EAAE,aAAa;IAC/B,OAAO,CAAC,QAAQ,CAAC,YAAY;IApD/B,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,OAAO,CAAsB;IACrC,mHAAmH;IACnH,OAAO,CAAC,MAAM,CAAuD;IACrE,OAAO,CAAC,UAAU,CAAkC;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,WAAW,CAAqB;IACxC;;;;;;OAMG;IACH,OAAO,CAAC,UAAU,CAAqB;IACvC,yFAAyF;IACzF,OAAO,CAAC,YAAY,CAAqB;IACzC,wFAAwF;IACxF,OAAO,CAAC,WAAW,CAAiB;IACpC,mHAAmH;IACnH,OAAO,CAAC,KAAK,CAAqB;IAClC;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA+B;IAExD,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,kHAAkH;IAClH,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,iIAAiI;IACjI,OAAO,CAAC,YAAY,CAAK;IACzB,6HAA6H;IAC7H,OAAO,CAAC,iBAAiB,CAAuC;IAChE,4EAA4E;IAC5E,OAAO,CAAC,WAAW,CAAuC;IAC1D,0GAA0G;IAC1G,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC;;;;;OAKG;IACH,OAAO,CAAC,aAAa,CAA2B;IAEhD,YACW,OAAO,EAAE,aAAa,EACd,YAAY,EAAE,aAAa,EAM7C;IAED,oEAAoE;IACpE,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,2FAA2F;IAC3F,IAAI,SAAS,IAAI,MAAM,GAAG,SAAS,CAElC;IAED,+DAA+D;IAC/D,IAAI,cAAc,IAAI,OAAO,CAE5B;IAED,mEAAmE;IACnE,aAAa,IAAI,iBAAiB,CAGjC;IAED;;;;OAIG;IACG,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAGhH;IAED;;;;;;;OAOG;IACG,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAKrH;IAED,kEAAkE;IAClE,OAAO,CAAC,KAAK;IASb;;;;OAIG;YACW,cAAc;IAM5B,wDAAwD;IACxD,OAAO,CAAC,SAAS;IAIX,IAAI,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAc9C;IAED;;;;;;;OAOG;YACW,iBAAiB;IAUzB,YAAY,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAY/D;IAEK,UAAU,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB7D;IAID;;;;OAIG;IACG,UAAU,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB3D;IAED,8FAA8F;IACxF,SAAS,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAkB7E;IAEK,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAY1D;IAED;;;;;OAKG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAWtF;IAED,6FAA6F;YAC/E,IAAI;IAgBlB;;;;;;;;;OASG;YACW,iBAAiB;IAS/B;;;;;;;OAOG;IACG,aAAa,CAAC,UAAU,EAAE,gBAAgB,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAU5G;YAEa,UAAU;IAQxB;;;;;;;;;;;;OAYG;IACG,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBpF;IAED;;;;OAIG;IACH,OAAO,CAAC,QAAQ;IAKhB;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAMtB;;;;;;;OAOG;IACG,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAKjD;IAED;;;;OAIG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAuBpH;YAEa,QAAQ;IActB;;;;;OAKG;YACW,OAAO;IAWrB;;;;OAIG;YACW,eAAe;IAS7B,OAAO,CAAC,OAAO;IAYf;;;;;;OAMG;YACW,WAAW;IAezB,qGAAqG;YACvF,aAAa;IAKrB,OAAO,CAAC,SAAS,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAclG;IAED,6FAA6F;IACvF,MAAM,CAAC,UAAU,EAAE,iBAAiB,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAUzG;IAED,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,YAAY;IAMpB;;;;;;OAMG;IACH,OAAO,CAAC,SAAS;IAgBjB,+EAA+E;IAC/E,OAAO,CAAC,IAAI;IAMZ;;;OAGG;IACH,OAAO,CAAC,MAAM;IAwBd;;;;;;;;;;;;OAYG;YACW,OAAO;IAkBrB,wGAAwG;YAC1F,SAAS;IAMvB;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAKZ,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8F7F;IAED;;;;;;OAMG;YACW,QAAQ;IAuBtB;;;;OAIG;IACG,SAAS,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvG;IAED;;;;;OAKG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;KAAE,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAO/G;IAED;;;;OAIG;IACG,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB7E;IAED;;;;;;;OAOG;IACG,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CASxD;IAED;;;;;;;;;;;;;;;;;OAiBG;YACW,wBAAwB;IAsBtC;;;;;OAKG;YACW,kBAAkB;IAW1B,IAAI,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKrD;IAEK,OAAO,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIxD;IAED,2GAA2G;IACrG,KAAK,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAStD;IAED;;;;OAIG;IACG,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAStD;IAED;;;;;;OAMG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAUxF;IAED,uFAAuF;IACvF,OAAO,CAAC,aAAa;IAIrB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAezB;;;;;OAKG;YACW,gBAAgB;IAmB9B;;;OAGG;YACW,aAAa;CAqB5B"}
+{"version":3,"file":"surface.d.ts","sourceRoot":"","sources":["../src/surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAQL,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EAEnB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,OAAO,EAEZ,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAElB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,aAAa,EAInB,MAAM,YAAY,CAAC;AAcpB,OAAO,EAAsB,KAAK,iBAAiB,EAAE,KAAK,aAAa,EAAE,KAAK,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,KAAK,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAIvL,OAAO,EAAE,UAAU,EAAyC,MAAM,WAAW,CAAC;AAgB9E,mDAAmD;AACnD,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAaD,4CAA4C;AAC5C,MAAM,WAAW,cAAc;IAC7B,yGAAyG;IACzG,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,iBAAiB,CAAC;CAC1C;AAwJD,gEAAgE;AAChE,KAAK,aAAa,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAkBtG;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,gBAAgB,GAAG,kBAAkB,GAAG,IAAI,CAexH;AAqBD,qBAAa,kBAAkB;IAwD3B,QAAQ,CAAC,OAAO,EAAE,aAAa;IAC/B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAxD/B,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,OAAO,CAAsB;IACrC,mHAAmH;IACnH,OAAO,CAAC,MAAM,CAAuD;IACrE,OAAO,CAAC,UAAU,CAAkC;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,WAAW,CAAqB;IACxC;;;;;;OAMG;IACH,OAAO,CAAC,UAAU,CAAqB;IACvC,yFAAyF;IACzF,OAAO,CAAC,YAAY,CAAqB;IACzC,+CAA+C;IAC/C,OAAO,CAAC,GAAG,CAAqB;IAChC,wFAAwF;IACxF,OAAO,CAAC,WAAW,CAAiB;IACpC,mHAAmH;IACnH,OAAO,CAAC,KAAK,CAAqB;IAClC,gJAAgJ;IAChJ,OAAO,CAAC,aAAa,CAA4B;IACjD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA+B;IAExD,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,kHAAkH;IAClH,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,iIAAiI;IACjI,OAAO,CAAC,YAAY,CAAK;IACzB,6HAA6H;IAC7H,OAAO,CAAC,iBAAiB,CAAuC;IAChE,4EAA4E;IAC5E,OAAO,CAAC,WAAW,CAAuC;IAC1D,0GAA0G;IAC1G,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC;;;;;OAKG;IACH,OAAO,CAAC,aAAa,CAA2B;IAEhD,YACW,OAAO,EAAE,aAAa,EACd,YAAY,EAAE,aAAa,EAM7C;IAED,0GAA0G;IAC1G,OAAO,KAAK,UAAU,GAErB;IAED,0GAA0G;IAC1G,IAAI,SAAS,IAAI,MAAM,GAAG,SAAS,CAElC;IAED,+DAA+D;IAC/D,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;IAED,+DAA+D;IAC/D,IAAI,cAAc,IAAI,OAAO,CAE5B;IAED,mEAAmE;IACnE,aAAa,IAAI,iBAAiB,CAGjC;IAED;;;;OAIG;IACG,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAGhH;IAED;;;;;;;OAOG;IACG,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAKrH;IAED,kEAAkE;IAClE,OAAO,CAAC,KAAK;IASb;;;;OAIG;YACW,cAAc;IAM5B,wDAAwD;IACxD,OAAO,CAAC,SAAS;IAIX,IAAI,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB9C;IAED;;;;;;;OAOG;YACW,iBAAiB;IAUzB,YAAY,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAY/D;IAEK,UAAU,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB7D;IAID;;;;;;OAMG;IACG,UAAU,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8B3D;IAED,8FAA8F;IACxF,SAAS,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAoB7E;IAED;;;;;OAKG;YACW,mBAAmB;IASjC;;;;;OAKG;YACW,mBAAmB;IAOjC,6GAA6G;YAC/F,kBAAkB;IAS1B,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB1D;IAED;;;;;OAKG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAYtF;IAED,6FAA6F;YAC/E,IAAI;IAgBlB;;;;;;;;;OASG;YACW,iBAAiB;IAS/B;;;;;;;OAOG;IACG,aAAa,CAAC,UAAU,EAAE,gBAAgB,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAU5G;YAEa,UAAU;IAQxB;;;;;;;;;;;;OAYG;IACG,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBpF;IAED;;;;OAIG;IACH,OAAO,CAAC,QAAQ;IAKhB;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAMtB;;;;;;;OAOG;IACG,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAKjD;IAED;;;;OAIG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAuBpH;YAEa,QAAQ;IActB;;;;;OAKG;YACW,OAAO;IAWrB;;;;OAIG;YACW,eAAe;IAS7B,OAAO,CAAC,OAAO;IAYf;;;;;;OAMG;YACW,WAAW;IAezB,qGAAqG;YACvF,aAAa;IAKrB,OAAO,CAAC,SAAS,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAclG;IAED,6FAA6F;IACvF,MAAM,CAAC,UAAU,EAAE,iBAAiB,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAUzG;IAED,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,YAAY;IAMpB;;;;;;OAMG;IACH,OAAO,CAAC,SAAS;IAgBjB,+EAA+E;IAC/E,OAAO,CAAC,IAAI;IAMZ;;;OAGG;IACH,OAAO,CAAC,MAAM;IAwBd;;;;;;;;;;;;OAYG;YACW,OAAO;IAkBrB,wGAAwG;YAC1F,SAAS;IAMvB;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAKZ,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8F7F;IAED;;;;;;OAMG;YACW,QAAQ;IAuBtB;;;;OAIG;IACG,SAAS,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvG;IAED;;;;;OAKG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;KAAE,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAO/G;IAED;;;;OAIG;IACG,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB7E;IAED;;;;;;;OAOG;IACG,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CASxD;IAED;;;;;;;;;;;;;;;;;OAiBG;YACW,wBAAwB;IAsBtC;;;;;OAKG;YACW,kBAAkB;IAW1B,IAAI,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKrD;IAEK,OAAO,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIxD;IAED,2GAA2G;IACrG,KAAK,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAStD;IAED;;;;OAIG;IACG,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAStD;IAED;;;;;;OAMG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAUxF;IAED,uFAAuF;IACvF,OAAO,CAAC,aAAa;IAIrB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAezB;;;;;OAKG;YACW,gBAAgB;IAmB9B;;;OAGG;YACW,aAAa;CAqB5B"}

package/dist/surface.js

@@ -14,18 +14,20 @@
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
-import { EngineError, KEY_NAMES, parseKey, raceAbort, withinCleanupBudget, ConfigurationError, TestError, } from 'e2e/engine';
+import { EngineError, KEY_NAMES, parseKey, raceAbort, rejectUnknownKeys, stopProviderRecording, withinCleanupBudget, ConfigurationError, TestError, } from 'e2e/engine';
 import { isNoSessionApp, isSnapshotPresentationFailure, runCommand, staleOr } from './errors.js';
 import { pointerInteraction, DEFAULT_LONG_PRESS_MS } from './actions.js';
 import { resolveExpression } from './locate.js';
 import { isWithin, projectSnapshot, ROOT_ID, screenRoot, screenTitle, } from './nodes.js';
+import { DEVICE_PERMISSIONS } from './options.js';
 import { maskPng } from './png.js';
 import { deviceLabel, pinnedApp } from './bindings.js';
-import { assertAppId, assertConfiguredApp } from './links.js';
+import { assertAppId } from './links.js';
 import { DevicePool, deviceSelection } from './pool.js';
+import { recordLease, travelledLease } from './provider.js';
 import { invalidState, notActionable, logicalScreenSize, readPngSize, sanitizeFilename, screenLocation, swipeWithin, unsupported, } from './support.js';
 /** Why nothing is pinned with `appPath` alone: the install is the suite's. */
-const UNINSTALLED_BUILD = 'the build `appPath` names installed first with `device.installApp()`';
+const UNINSTALLED_BUILD = "the build the target's `app.appPath` names installed first with `device.installApp()`";
 /** Platform element types that are the soft keyboard or one of its keys, as agent-device names them. */
 const KEYBOARD_TYPES = new Set(['keyboard', 'key']);
 /**
@@ -109,6 +111,42 @@ function sleep(ms, signal) {
     });
 }
 const DEFAULT_SETTLE_QUIET_MS = 150;
+/** Every option `mobile()` takes, kept equal to `MobileOptions` by the compiler. */
+const MOBILE_OPTION_KEYS = Object.keys({
+    platform: true,
+    device: true,
+    session: true,
+    snapshot: true,
+    settle: true,
+    transition: true,
+    videoTouches: true,
+});
+/** Every state a permission takes, kept equal to `PermissionState` by the compiler. */
+const PERMISSION_STATES = Object.keys({ grant: true, deny: true, reset: true });
+/**
+ * Refuses a permissions map before any device command: anything but a plain
+ * object, a name agent-device
+ * does not set, naming the nearest, or a state other than grant, deny, or
+ * reset. `INVALID_CONFIG` for a target's `app.permissions`, `INVALID_ARGUMENT`
+ * for a test's `device.openApp`. An `undefined` state is skipped, as the preset
+ * skips it.
+ */
+export function assertPermissions(label, permissions, code) {
+    const fail = (message) => {
+        throw code === 'INVALID_CONFIG' ? new ConfigurationError(code, message) : new TestError(code, message);
+    };
+    // A Map or class instance carries no own keys to check, and the preset would apply none of it.
+    const prototype = typeof permissions === 'object' && permissions !== null ? Object.getPrototypeOf(permissions) : undefined;
+    if (prototype !== Object.prototype && prototype !== null) {
+        fail(`${label} must be a plain object of permission names to ${PERMISSION_STATES.join(', ')}`);
+    }
+    rejectUnknownKeys(label, permissions, DEVICE_PERMISSIONS, code);
+    for (const [name, state] of Object.entries(permissions)) {
+        if (state !== undefined && !PERMISSION_STATES.includes(state)) {
+            fail(`${label}.${name} must be one of ${PERMISSION_STATES.join(', ')}, got ${typeof state === 'string' ? `"${state}"` : String(state)}`);
+        }
+    }
+}
 /** Resolves the `transition` option: the default budget or a custom one. */
 function transitionMs(transition) {
     const budget = transition ?? DEFAULT_TRANSITION_MS;
@@ -148,10 +186,14 @@ export class AgentDeviceSurface {
     sessionApp;
     /** The app the build `appPath` installed, once `init` has, itself or through a lease. */
     installedApp;
+    /** The target's app, as `init` received it. */
+    app = {};
     /** Where relative build paths resolve; the run's project root once init has told us. */
     projectRoot = process.cwd();
     /** The session and device this worker drives, for the error messages whose recovery is per device; set in init. */
     where;
+    /** How this worker's device records through its provider: set in init when the pool's provider records and the slot rides one of its leases. */
+    leaseRecorder;
     /**
      * Commands still running on the device. agent-device takes no abort
      * signal, so a cancelled or timed-out call is only abandoned by its
@@ -181,18 +223,22 @@ export class AgentDeviceSurface {
     constructor(options, createClient) {
         this.options = options;
         this.createClient = createClient;
-        assertConfiguredApp(options.app);
+        rejectUnknownKeys('mobile()', options, MOBILE_OPTION_KEYS);
         this.pool = new DevicePool(options, createClient);
         this.settleOptions = settleOptions(options.settle);
         this.transitionMs = transitionMs(options.transition);
     }
-    /** Whether the manifest declares app restart and state clearing. */
+    /** Whether the target pins an app for `app.open()`, `app.restart()`, and `app.clearState()` to launch. */
     get managesApp() {
-        return this.options.app !== undefined || this.options.appPath !== undefined;
+        return this.app.bundleId !== undefined || this.app.appPath !== undefined;
     }
-    /** The app `app.open()` launches: the `app` option, else the build `appPath` installed. */
+    /** The app `app.open()` launches: the target's `bundleId`, else the app its build `appPath` installed. */
     get pinnedApp() {
-        return pinnedApp(this.options, this.installedApp);
+        return pinnedApp(this.app, this.installedApp);
+    }
+    /** The build the target's `app.appPath` names, as declared. */
+    get appPath() {
+        return this.app.appPath;
     }
     /** Whether an attempt is running on this surface right now. */
     get attemptRunning() {
@@ -249,12 +295,19 @@ export class AgentDeviceSurface {
     }
     async init(info) {
         this.projectRoot = info.projectRoot;
+        this.app = info.app;
         const binding = this.pool.binding(info.targetName, info.workerSlot, info.env);
         this.device = binding;
         const session = this.pool.session(info.targetName, info.workerSlot);
         const label = deviceLabel(binding);
         this.where = `session ${session}${label === undefined ? '' : ` on ${label}`}`;
         this.client ??= this.createClient(session, binding);
+        const provider = this.pool.recorder;
+        const lease = travelledLease(binding);
+        this.leaseRecorder =
+            provider === undefined || lease === undefined
+                ? undefined
+                : { provider, lease, runId: info.runId, targetName: info.targetName, env: info.env };
         await this.command('boot', (client) => client.devices.boot(this.selection()), info.signal);
         this.sessionApp = binding?.sessionApp === undefined ? undefined : await this.resumedSessionApp(session, binding.sessionApp, info.signal);
         // Nothing is installed here: a device provider that installed the build
@@ -290,12 +343,13 @@ export class AgentDeviceSurface {
         // worker's `prepare`, left it, and a test that wants it fresh calls
         // `app.open()`, which is `restart` below. The bindings are forgotten, the
         // screen is not, so a control still in place is acted on at once.
-        this.attempt = { artifactsDir: context.artifactsDir, screenshots: 0, video: undefined };
+        this.attempt = { attemptId: context.attemptId, artifactsDir: context.artifactsDir, screenshots: 0, video: undefined };
         this.generation = new Map();
         this.located.clear();
     }
     async endAttempt(context) {
-        const dangling = this.attempt?.video;
+        const attempt = this.attempt;
+        const dangling = attempt?.video;
         this.attempt = undefined;
         this.generation = new Map();
         this.located.clear();
@@ -304,16 +358,21 @@ export class AgentDeviceSurface {
         // and the device must not keep recording into the next one. A start that
         // outlived its budget may still be landing: it settles first, so the stop
         // cannot overtake it.
-        if (dangling !== undefined) {
+        if (attempt !== undefined && dangling?.kind === 'lease') {
+            await this.stopLeaseRecording(dangling, attempt.artifactsDir, context.signal).catch(() => undefined);
+        }
+        else if (dangling !== undefined) {
             await this.settleInflight(context.signal).catch(() => undefined);
-            await this.command('stop video recording', (client) => client.recording.record({ action: 'stop' }), context.signal).catch(() => undefined);
+            await this.stopScreenRecording(context.signal).catch(() => undefined);
         }
     }
     // --- video ---
     /**
      * Asks the device to record its screen into the attempt directory. Taps stay
      * visible in the recording (agent-device's touch indicator), which is the
-     * closest a phone comes to a cursor.
+     * closest a phone comes to a cursor, unless `videoTouches` is `false`. A
+     * device provider that records its devices records the attempt instead,
+     * when the slot rides one of its leases.
      */
     async startVideo(operation) {
         const attempt = this.attempt;
@@ -321,14 +380,26 @@ export class AgentDeviceSurface {
             throw invalidState('startVideo outside an attempt');
         if (attempt.video !== undefined)
             throw invalidState('a video is already recording');
+        if (this.leaseRecorder !== undefined) {
+            await this.startLeaseRecording(attempt, this.leaseRecorder, operation.signal);
+            return;
+        }
         const relative = path.join('video', 'video.mp4');
         const absolute = path.join(attempt.artifactsDir, relative);
         mkdirSync(path.dirname(absolute), { recursive: true });
         // Marked before the device is asked: a start that outlives its budget
         // still records, and `endAttempt` must be able to stop it.
-        const recording = { relative, absolute, startedAt: new Date().toISOString() };
+        const recording = { kind: 'screen', relative, absolute, startedAt: new Date().toISOString() };
         attempt.video = recording;
-        await this.command('start video recording', (client) => client.recording.record({ action: 'start', path: absolute, quality: 'medium' }), operation.signal);
+        await this.command('start video recording', 
+        // The whole screen: an app scope refuses to start while no app is open, before `app.open()` and after `closeApp()`.
+        (client) => client.recording.record({
+            action: 'start',
+            path: absolute,
+            quality: 'medium',
+            recordingScope: 'device',
+            ...(this.options.videoTouches === false ? { hideTouches: true } : {}),
+        }), operation.signal);
         // The device confirmed: it is recording from about now.
         recording.startedAt = new Date().toISOString();
     }
@@ -340,7 +411,13 @@ export class AgentDeviceSurface {
         const video = attempt.video;
         if (video === undefined)
             return [];
-        const result = await this.command('stop video recording', (client) => client.recording.record({ action: 'stop' }), operation.signal);
+        if (video.kind === 'lease') {
+            const segment = await this.stopLeaseRecording(video, attempt.artifactsDir, operation.signal);
+            // Cleared only now: a stop that failed leaves the recording for `endAttempt`.
+            attempt.video = undefined;
+            return [segment];
+        }
+        const result = await this.stopScreenRecording(operation.signal);
         // Cleared only now: a stop that failed leaves the recording for `endAttempt`.
         attempt.video = undefined;
         // The device may finalize the file under a path of its own choosing; the
@@ -352,8 +429,47 @@ export class AgentDeviceSurface {
             return [];
         return [{ path: video.relative, startedAt: video.startedAt }];
     }
+    /**
+     * Stops the device's screen recording. A device-scope recording started
+     * with no session made one of its own, and stopping it ends that session,
+     * whatever the test opened in it since, so the session is then as
+     * `closeApp` leaves it.
+     */
+    async stopScreenRecording(signal) {
+        const result = await this.command('stop video recording', (client) => client.recording.record({ action: 'stop' }), signal);
+        if (result.recordOnlySession === true) {
+            this.sessionApp = undefined;
+            this.screenReplaced();
+        }
+        return result;
+    }
+    /**
+     * Starts the device provider's recording of the leased device. Marked
+     * the moment `record` is called, before it settles, as the screen
+     * recording is before its start command: a start that outlives its budget
+     * may still come up, and `endAttempt` then stops it.
+     */
+    async startLeaseRecording(attempt, recorder, signal) {
+        const { provider, lease, runId, targetName, env } = recorder;
+        const started = recordLease(provider, lease, { runId, targetName, attemptId: attempt.attemptId, env, signal });
+        attempt.video = { kind: 'lease', recorder, started };
+        await raceAbort(started, signal, 'start video recording');
+    }
+    /** Ends the provider's recording as the attempt's one segment, a file in its `video` directory or a link. */
+    async stopLeaseRecording(video, artifactsDir, signal) {
+        const { provider, lease } = video.recorder;
+        video.stopping ??= (async () => stopProviderRecording(await video.started, { artifactsDir, provider: `device provider "${provider.name}"`, leaseId: lease.id, signal }))().finally(() => {
+            video.stopping = undefined;
+        });
+        return raceAbort(video.stopping, signal, 'stop video recording');
+    }
     async dispose(context) {
         const client = this.client;
+        const attempt = this.attempt;
+        // A worker torn down mid-attempt must not leave the provider recording the device.
+        if (attempt?.video?.kind === 'lease') {
+            await withinCleanupBudget(this.stopLeaseRecording(attempt.video, attempt.artifactsDir, context.signal), context).catch(() => undefined);
+        }
         this.client = undefined;
         this.attempt = undefined;
         this.generation = new Map();
@@ -374,13 +490,15 @@ export class AgentDeviceSurface {
      */
     async openApp(app, options, signal) {
         assertAppId(app);
+        if (options.permissions !== undefined)
+            assertPermissions('device.openApp({ permissions })', options.permissions, 'INVALID_ARGUMENT');
         const relaunch = options.relaunch === true;
         // The engine's own launch options belong to a fresh launch of the pinned
         // app. A foreground-only open of a running app takes no arguments, and a
         // permission change there would terminate the app it means to keep.
         const configured = relaunch && app === this.pinnedApp;
-        const launchArguments = options.launchArguments ?? (configured ? this.options.launchArguments : undefined);
-        const permissions = options.permissions ?? (configured ? this.options.permissions : undefined);
+        const launchArguments = options.launchArguments ?? (configured ? this.app.launchArguments : undefined);
+        const permissions = options.permissions ?? (configured ? this.app.permissions : undefined);
         if (permissions !== undefined)
             await this.presetPermissions(app, permissions, signal);
         await this.open(app, relaunch, launchArguments, signal);
@@ -456,7 +574,7 @@ export class AgentDeviceSurface {
     async openLink(url, app, signal) {
         const target = app ?? this.pinnedApp;
         if (target === undefined && this.options.platform === 'ios') {
-            throw new TestError('INVALID_ARGUMENT', 'openLink needs an app on iOS: pass `app`, or pin one with the engine option `app` or `appPath`; the session observes the app a link is opened into');
+            throw new TestError('INVALID_ARGUMENT', "openLink needs an app on iOS: pass `app`, or pin one with the target's app.bundleId or app.appPath; the session observes the app a link is opened into");
         }
         const result = await this.command('device.openLink', (client) => client.apps.open({
             ...this.selection(),
@@ -506,15 +624,15 @@ export class AgentDeviceSurface {
      * with no data; a plain install replaces the binary and keeps its data.
      */
     async installApp(appPath, options, signal) {
-        const build = appPath ?? this.options.appPath;
+        const build = appPath ?? this.app.appPath;
         if (build === undefined)
-            throw invalidState('installApp needs a build: pass a path, or name one with the engine option `appPath`');
+            throw invalidState("installApp needs a build: pass a path, or name one with the target's app.appPath");
         const resolved = path.resolve(this.projectRoot, build);
         const selection = this.selection();
-        const engineBuild = appPath === undefined || (this.options.appPath !== undefined && resolved === path.resolve(this.projectRoot, this.options.appPath));
-        const app = options.app ?? (engineBuild ? this.options.app : undefined) ?? (options.reinstall === true ? this.pinnedApp : undefined);
+        const engineBuild = appPath === undefined || (this.app.appPath !== undefined && resolved === path.resolve(this.projectRoot, this.app.appPath));
+        const app = options.app ?? (engineBuild ? this.app.bundleId : undefined) ?? (options.reinstall === true ? this.pinnedApp : undefined);
         if (options.reinstall === true && app === undefined) {
-            throw invalidState('reinstall needs an app: pass `app`, or pin one with the engine option `app` or `appPath`');
+            throw invalidState("reinstall needs an app: pass `app`, or pin one with the target's app.bundleId or app.appPath");
         }
         const result = (await this.command(`install ${resolved}`, (client) => options.reinstall === true && app !== undefined
             ? client.apps.reinstall({ ...selection, app, appPath: resolved })
@@ -1015,14 +1133,14 @@ export class AgentDeviceSurface {
     async restart(operation) {
         const app = this.pinnedApp;
         if (app === undefined)
-            throw unsupported(`app.restart needs the engine option \`app\`, or ${UNINSTALLED_BUILD}`);
+            throw unsupported(`app.restart needs the target's \`app.bundleId\`, or ${UNINSTALLED_BUILD}`);
         await this.openApp(app, { relaunch: true }, operation.signal);
     }
     /** Clears the pinned app's persisted state and relaunches it: the device equivalent of a fresh context. */
     async reset(operation) {
         const app = this.pinnedApp;
         if (app === undefined)
-            throw unsupported(`app.clearState needs the engine option \`app\`, or ${UNINSTALLED_BUILD}`);
+            throw unsupported(`app.clearState needs the target's \`app.bundleId\`, or ${UNINSTALLED_BUILD}`);
         await this.command('clear app state', (client) => client.settings.update({ setting: 'clear-app-state', state: 'clear', app }), operation.signal);
         await this.openApp(app, { relaunch: true }, operation.signal);
     }