feat(inspect): add --disable-animations flag to fix uiautomator dump on animated screens

packages/driver-mobile-use/src/driver.ts

@@ -3,6 +3,7 @@ import { stat } from 'node:fs/promises';
 import { basename } from 'node:path';
 import createDebug from 'debug';
 import type {
+  AnimationScales,
   AppInfo,
   ConnectionConfig,
   DeviceInfo,
@@ -399,6 +400,18 @@ export class MobileUseDriver implements MobilewrightDriver {
     return result;
   }
 
+  async getAnimationScales(): Promise<AnimationScales> {
+    return this.call<AnimationScales>('device.io.animation-scales.get');
+  }
+
+  async setAnimationScales(scales: AnimationScales): Promise<void> {
+    await this.call('device.io.animation-scales.set', {
+      window: scales.window,
+      transition: scales.transition,
+      animator: scales.animator,
+    });
+  }
+
   // ─── Apps ───────────────────────────────────────────────────
 
   async launchApp(bundleId: string, opts?: LaunchOptions): Promise<void> {

packages/driver-mobilecli/src/driver.ts

@@ -1,6 +1,7 @@
 import createDebug from 'debug';
 import { execFileSync } from 'node:child_process';
 import type {
+  AnimationScales,
   AppInfo,
   ConnectionConfig,
   DeviceInfo,
@@ -337,6 +338,18 @@ export class MobilecliDriver implements MobilewrightDriver {
     await this.call('device.io.orientation.set', { orientation });
   }
 
+  async getAnimationScales(): Promise<AnimationScales> {
+    return this.call<AnimationScales>('device.io.animation-scales.get');
+  }
+
+  async setAnimationScales(scales: AnimationScales): Promise<void> {
+    await this.call('device.io.animation-scales.set', {
+      window: scales.window,
+      transition: scales.transition,
+      animator: scales.animator,
+    });
+  }
+
   // ─── Recording Operations ─────────────────────────────────────
 
   async startRecording(opts: RecordingOptions): Promise<void> {

packages/mobilewright-core/src/device.ts

@@ -1,4 +1,5 @@
 import type {
+  AnimationScales,
   AppInfo,
   ConnectionConfig,
   LaunchOptions,
@@ -132,4 +133,23 @@ export class Device {
   async stopRecording(): Promise<RecordingResult> {
     return this.driver.stopRecording();
   }
+
+  // ─── Android animations ─────────────────────────────────────────
+  // uiautomator dump fails on continuously animated screens (e.g. a
+  // ride-searching page with a SurfaceView/TextureView animation that
+  // never settles). Disabling the three system animation scales before
+  // calling getViewHierarchy() lets the dump succeed.
+  //
+  // disableAnimations() saves and returns the current scales so the
+  // caller can restore the exact originals via enableAnimations(saved).
+
+  async disableAnimations(): Promise<AnimationScales> {
+    const saved = await this.driver.getAnimationScales();
+    await this.driver.setAnimationScales({ window: 0, transition: 0, animator: 0 });
+    return saved;
+  }
+
+  async enableAnimations(scales: AnimationScales = { window: 1, transition: 1, animator: 1 }): Promise<void> {
+    await this.driver.setAnimationScales(scales);
+  }
 }

packages/mobilewright-core/src/expect.test.ts

@@ -84,6 +84,8 @@ function createMockDriver(hierarchy: ViewNode[]): MobilewrightDriver & { _tracke
     openUrl: async (...args: any[]) => { tracker.openUrlCalls.push(args); },
     startRecording: async () => {},
     stopRecording: async () => ({}),
+    getAnimationScales: async () => ({ window: 1, transition: 1, animator: 1 }),
+    setAnimationScales: async () => {},
   };
 }
 

packages/mobilewright-core/src/locator.test.ts

@@ -83,6 +83,8 @@ function createMockDriver(hierarchy: ViewNode[]): MobilewrightDriver & { _tracke
     openUrl: async (...args: any[]) => { tracker.openUrlCalls.push(args); },
     startRecording: async () => {},
     stopRecording: async () => ({}),
+    getAnimationScales: async () => ({ window: 1, transition: 1, animator: 1 }),
+    setAnimationScales: async () => {},
   };
 }
 

packages/mobilewright/src/cli.ts

@@ -13,6 +13,8 @@ import { MobilecliDriver, DEFAULT_URL, resolveMobilecliBinary } from '@mobilewri
 import { ensureMobilecliReachable } from './server.js';
 import { loadConfig } from './config.js';
 import { gatherChecks, renderTerminal, renderJSON } from './commands/doctor.js';
+import { runInspect, type InspectOptions } from './commands/inspect.js';
+import { runInspectUI } from './commands/inspect-ui.js';
 import { brandReport } from './reporter.js';
 import { telemetry } from './telemetry.js';
 
@@ -248,6 +250,23 @@ program
     }
   });
 
+// ── inspect ───────────────────────────────────────────────────────
+program
+  .command('inspect')
+  .description('dump the live accessibility tree of a connected device')
+  .option('-d, --device <id>', 'device ID (run "mobilewright devices" to list)')
+  .option('--url <url>', 'mobilecli server URL', DEFAULT_URL)
+  .option('--json', 'output raw ViewNode[] JSON instead of the terminal tree')
+  .option('--ui', 'open an interactive browser UI with auto-refresh and locator copy')
+  .option('--disable-animations', 'disable Android system animations before dumping (fixes uiautomator failures on animated screens)')
+  .action(async (opts: InspectOptions & { ui?: boolean }) => {
+    if (opts.ui) {
+      await runInspectUI(opts);
+    } else {
+      await runInspect(opts);
+    }
+  });
+
 // ── install ───────────────────────────────────────────────────────
 program
   .command('install')