feat: add screenshot no-stabilize flag (#553)

thymikee · web-flow · commit 60f36eff66f8 · 2026-05-15T19:21:06.000+02:00
diff --git a/src/__tests__/cli-client-commands.test.ts b/src/__tests__/cli-client-commands.test.ts
@@ -384,6 +384,7 @@ test('screenshot forwards --overlay-refs to the client capture API', async () =>
         path?: string;
         overlayRefs?: boolean;
         maxSize?: number;
+        stabilize?: boolean;
       }
     | undefined;
   const client = createStubClient({
@@ -408,6 +409,7 @@ test('screenshot forwards --overlay-refs to the client capture API', async () =>
       version: false,
       overlayRefs: true,
       screenshotMaxSize: 1024,
+      screenshotNoStabilize: true,
     },
     client,
   });
@@ -417,6 +419,7 @@ test('screenshot forwards --overlay-refs to the client capture API', async () =>
     path: '/tmp/screenshot.png',
     overlayRefs: true,
     maxSize: 1024,
+    stabilize: false,
   });
 });
 
diff --git a/src/backend.ts b/src/backend.ts
@@ -69,6 +69,7 @@ export type BackendFindTextResult = {
 export type BackendScreenshotOptions = {
   fullscreen?: boolean;
   overlayRefs?: boolean;
+  stabilize?: boolean;
   surface?: 'app' | 'frontmost-app' | 'desktop' | 'menubar';
 };
 
diff --git a/src/cli/commands/screenshot.ts b/src/cli/commands/screenshot.ts
@@ -14,6 +14,7 @@ export const screenshotCommand: ClientCommandHandler = async ({ positionals, fla
     path: positionals[0] ?? flags.out,
     overlayRefs: flags.overlayRefs,
     maxSize: flags.screenshotMaxSize,
+    ...(flags.screenshotNoStabilize ? { stabilize: false } : {}),
     ...(flags.screenshotFullscreen !== undefined ? { fullscreen: flags.screenshotFullscreen } : {}),
   });
   const data = {
@@ -97,6 +98,7 @@ function createClientScreenshotBackend(
         session: context.session,
         overlayRefs: options?.overlayRefs,
         fullscreen: options?.fullscreen,
+        stabilize: options?.stabilize,
         surface: options?.surface,
       });
       return {
diff --git a/src/client-normalizers.ts b/src/client-normalizers.ts
@@ -270,6 +270,7 @@ export function buildFlags(options: InternalRequestOptions): CommandFlags {
     snapshotRaw: options.raw,
     screenshotFullscreen: options.screenshotFullscreen,
     screenshotMaxSize: options.screenshotMaxSize,
+    screenshotNoStabilize: options.screenshotNoStabilize,
     overlayRefs: options.overlayRefs,
     appsFilter: options.appsFilter,
     out: options.out,
diff --git a/src/client-types.ts b/src/client-types.ts
@@ -331,6 +331,7 @@ export type CaptureScreenshotOptions = AgentDeviceRequestOverrides & {
   overlayRefs?: boolean;
   fullscreen?: boolean;
   maxSize?: number;
+  stabilize?: boolean;
   surface?: 'app' | 'frontmost-app' | 'desktop' | 'menubar';
 };
 
@@ -753,6 +754,7 @@ type CommandExecutionOptions = {
   raw?: boolean;
   screenshotFullscreen?: boolean;
   screenshotMaxSize?: number;
+  screenshotNoStabilize?: boolean;
   count?: number;
   fps?: number;
   quality?: RecordingQuality;
diff --git a/src/client.ts b/src/client.ts
@@ -333,6 +333,7 @@ export function createAgentDeviceClient(
           ...options,
           screenshotFullscreen: options.fullscreen,
           screenshotMaxSize: options.maxSize,
+          screenshotNoStabilize: options.stabilize === false ? true : undefined,
         });
         return {
           path: readRequiredString(data, 'path'),
diff --git a/src/commands/capture-definition.ts b/src/commands/capture-definition.ts
@@ -42,9 +42,15 @@ const screenshotCommandDefinition = defineCommand({
   name: PUBLIC_COMMANDS.screenshot,
   schema: {
     helpDescription:
-      'Capture screenshot (macOS app sessions default to the app window; use --fullscreen for full desktop, --max-size to downscale, or --overlay-refs to annotate the image with current refs)',
+      'Capture screenshot (macOS app sessions default to the app window; use --fullscreen for full desktop, --max-size to downscale, --overlay-refs to annotate current refs, or --no-stabilize for low-latency Android capture loops)',
     positionalArgs: ['path?'],
-    allowedFlags: ['out', 'overlayRefs', 'screenshotFullscreen', 'screenshotMaxSize'],
+    allowedFlags: [
+      'out',
+      'overlayRefs',
+      'screenshotFullscreen',
+      'screenshotMaxSize',
+      'screenshotNoStabilize',
+    ],
   },
   capability: ALL_DEVICE_COMMAND_CAPABILITY,
 });
diff --git a/src/commands/capture-screenshot.ts b/src/commands/capture-screenshot.ts
@@ -39,6 +39,7 @@ export const screenshotCommand: RuntimeCommand<
       {
         fullscreen: options.fullscreen,
         overlayRefs: options.overlayRefs,
+        stabilize: options.stabilize,
         surface: options.surface,
       },
     );
diff --git a/src/commands/runtime-types.ts b/src/commands/runtime-types.ts
@@ -17,6 +17,7 @@ export type ScreenshotCommandOptions = CommandContext & {
   fullscreen?: boolean;
   overlayRefs?: boolean;
   maxSize?: number;
+  stabilize?: boolean;
   appId?: string;
   appBundleId?: string;
   surface?: 'app' | 'frontmost-app' | 'desktop' | 'menubar';
diff --git a/src/core/dispatch-context.ts b/src/core/dispatch-context.ts
@@ -26,6 +26,7 @@ export type DispatchContext = {
   snapshotScope?: string;
   snapshotRaw?: boolean;
   screenshotFullscreen?: boolean;
+  screenshotNoStabilize?: boolean;
   count?: number;
   intervalMs?: number;
   delayMs?: number;
diff --git a/src/core/dispatch.ts b/src/core/dispatch.ts
@@ -106,6 +106,7 @@ export async function dispatchCommand(
           await interactor.screenshot(screenshotPath, {
             appBundleId: context?.appBundleId,
             fullscreen: context?.screenshotFullscreen,
+            stabilize: context?.screenshotNoStabilize ? false : undefined,
             surface: context?.surface,
           });
           return { path: screenshotPath, ...successText(`Saved screenshot: ${screenshotPath}`) };
diff --git a/src/core/interactor-types.ts b/src/core/interactor-types.ts
@@ -22,6 +22,7 @@ export type BackMode = 'in-app' | 'system';
 export type ScreenshotOptions = {
   appBundleId?: string;
   fullscreen?: boolean;
+  stabilize?: boolean;
   surface?: SessionSurface;
 };
 
diff --git a/src/core/interactors/android.ts b/src/core/interactors/android.ts
@@ -39,7 +39,7 @@ export function createAndroidInteractor(device: DeviceInfo): Interactor {
     type: (text, delayMs) => typeAndroid(device, text, delayMs),
     fill: (x, y, text, delayMs) => fillAndroid(device, x, y, text, delayMs),
     scroll: (direction, options) => scrollAndroid(device, direction, options),
-    screenshot: (outPath) => screenshotAndroid(device, outPath),
+    screenshot: (outPath, options) => screenshotAndroid(device, outPath, options),
     snapshot: async (options) => {
       const result = await withDiagnosticTimer(
         'snapshot_capture',
diff --git a/src/daemon/__tests__/context.test.ts b/src/daemon/__tests__/context.test.ts
@@ -14,9 +14,14 @@ test('contextFromFlags forwards scroll pixels from CLI flags', () => {
   assert.equal(context.pixels, 240);
 });
 
-test('contextFromFlags forwards screenshot fullscreen from CLI flags', () => {
-  const flags: CommandFlags = { screenshotFullscreen: true, screenshotMaxSize: 1024 };
+test('contextFromFlags forwards screenshot flags from CLI flags', () => {
+  const flags: CommandFlags = {
+    screenshotFullscreen: true,
+    screenshotMaxSize: 1024,
+    screenshotNoStabilize: true,
+  };
   const context = contextFromFlags('/tmp/agent-device.log', flags);
   assert.equal(context.screenshotFullscreen, true);
   assert.equal(context.screenshotMaxSize, 1024);
+  assert.equal(context.screenshotNoStabilize, true);
 });
diff --git a/src/daemon/context.ts b/src/daemon/context.ts
@@ -27,6 +27,7 @@ export function contextFromFlags(
     snapshotScope: flags?.snapshotScope,
     snapshotRaw: flags?.snapshotRaw,
     screenshotFullscreen: flags?.screenshotFullscreen,
+    screenshotNoStabilize: flags?.screenshotNoStabilize,
     screenshotMaxSize: flags?.screenshotMaxSize,
     count: flags?.count,
     intervalMs: flags?.intervalMs,
diff --git a/src/daemon/handlers/__tests__/session-replay-script.test.ts b/src/daemon/handlers/__tests__/session-replay-script.test.ts
@@ -84,18 +84,19 @@ test('screenshot replay script round-trips screenshot flags', () => {
       ts: Date.now(),
       command: 'screenshot',
       positionals: ['./page.png'],
-      flags: { screenshotFullscreen: true, screenshotMaxSize: 1024 },
+      flags: { screenshotFullscreen: true, screenshotMaxSize: 1024, screenshotNoStabilize: true },
     },
   ];
 
   writeReplayScript(replayPath, actions, makeSession());
   const script = fs.readFileSync(replayPath, 'utf8');
-  assert.match(script, /screenshot "\.\/page\.png" --fullscreen --max-size 1024/);
+  assert.match(script, /screenshot "\.\/page\.png" --fullscreen --max-size 1024 --no-stabilize/);
 
   const parsed = parseReplayScript(script);
   assert.deepEqual(parsed[0]?.positionals, ['./page.png']);
   assert.equal(parsed[0]?.flags.screenshotFullscreen, true);
   assert.equal(parsed[0]?.flags.screenshotMaxSize, 1024);
+  assert.equal(parsed[0]?.flags.screenshotNoStabilize, true);
 });
 
 test('type and fill replay scripts round-trip typing delay flags', () => {
diff --git a/src/daemon/handlers/session-replay-script.ts b/src/daemon/handlers/session-replay-script.ts
@@ -348,6 +348,10 @@ function parseReplayScriptLine(line: string): SessionAction | null {
         action.flags.screenshotFullscreen = true;
         continue;
       }
+      if (token === '--no-stabilize') {
+        action.flags.screenshotNoStabilize = true;
+        continue;
+      }
       if (token === '--max-size') {
         const value = args[index + 1];
         const maxSize = value === undefined ? NaN : Number(value);
diff --git a/src/daemon/screenshot-runtime.ts b/src/daemon/screenshot-runtime.ts
@@ -38,6 +38,7 @@ export async function dispatchScreenshotViaRuntime(params: {
     appBundleId: session.appBundleId,
     fullscreen: dispatchContext.screenshotFullscreen,
     maxSize: dispatchContext.screenshotMaxSize,
+    stabilize: dispatchContext.screenshotNoStabilize ? false : undefined,
     surface: session.surface,
     ...(outPath ? { out: { kind: 'path', path: outPath } } : {}),
   });
@@ -56,6 +57,7 @@ function createDispatchScreenshotBackend(params: {
         ...dispatchContext,
         screenshotFullscreen: options?.fullscreen,
         overlayRefs: options?.overlayRefs,
+        screenshotNoStabilize: options?.stabilize === false ? true : undefined,
         surface: options?.surface,
       };
       if (outputPlacement === 'out') {
diff --git a/src/daemon/script-utils.ts b/src/daemon/script-utils.ts
@@ -158,6 +158,7 @@ export function appendScreenshotActionScriptArgs(parts: string[], action: Sessio
   if (typeof action.flags?.screenshotMaxSize === 'number') {
     parts.push('--max-size', String(action.flags.screenshotMaxSize));
   }
+  if (action.flags?.screenshotNoStabilize) parts.push('--no-stabilize');
 }
 
 export function appendRuntimeActionScriptArgs(
diff --git a/src/daemon/session-action-recorder.ts b/src/daemon/session-action-recorder.ts
@@ -55,6 +55,7 @@ const SANITIZED_FLAG_KEYS = [
   'snapshotRaw',
   'screenshotFullscreen',
   'screenshotMaxSize',
+  'screenshotNoStabilize',
   'relaunch',
   'saveScript',
   'noRecord',
diff --git a/src/platforms/android/__tests__/snapshot.test.ts b/src/platforms/android/__tests__/snapshot.test.ts
@@ -98,6 +98,28 @@ test('screenshotAndroid waits for transient UI to settle before capture', async
   assert.deepEqual(relevantEvents, ['enable', 'settle:1000', 'capture', 'disable']);
 });
 
+test('screenshotAndroid skips stabilization when requested', async () => {
+  const events: string[] = [];
+  const outPath = path.join(os.tmpdir(), `agent-device-android-screenshot-${Date.now()}.png`);
+
+  mockRunCmd.mockImplementation(async (_cmd, args) => {
+    if (args.includes('exec-out')) {
+      events.push('capture');
+      return { exitCode: 0, stdout: '', stderr: '', stdoutBuffer: VALID_PNG };
+    }
+    events.push(args.some((arg) => arg.includes('exit')) ? 'disable' : 'enable');
+    return { exitCode: 0, stdout: '', stderr: '' };
+  });
+  mockSleep.mockImplementation(async (ms) => {
+    events.push(`settle:${ms}`);
+  });
+
+  await screenshotAndroid(device, outPath, { stabilize: false });
+
+  assert.deepEqual(events, ['capture']);
+  assert.equal(mockSleep.mock.calls.length, 0);
+});
+
 test('screenshotAndroid writes a valid PNG when output is clean', async () => {
   await withTempScreenshot('screenshot-clean-', async (outPath) => {
     await screenshotAndroid(device, outPath);
diff --git a/src/platforms/android/screenshot.ts b/src/platforms/android/screenshot.ts
@@ -7,7 +7,20 @@ import { runAndroidAdb, sleep } from './adb.ts';
 const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 const ANDROID_SCREENSHOT_SETTLE_DELAY_MS = 1_000;
 
-export async function screenshotAndroid(device: DeviceInfo, outPath: string): Promise<void> {
+export type AndroidScreenshotOptions = {
+  stabilize?: boolean;
+};
+
+export async function screenshotAndroid(
+  device: DeviceInfo,
+  outPath: string,
+  options: AndroidScreenshotOptions = {},
+): Promise<void> {
+  if (options.stabilize === false) {
+    await captureAndroidScreenshot(device, outPath);
+    return;
+  }
+
   await enableAndroidDemoMode(device);
   try {
     // Allow transient UI affordances like scrollbars to fade before capture.
diff --git a/src/utils/__tests__/args.test.ts b/src/utils/__tests__/args.test.ts
@@ -644,14 +644,25 @@ test('parseArgs recognizes record --hide-touches flag', () => {
   assert.equal(parsed.flags.hideTouches, true);
 });
 
-test('parseArgs recognizes screenshot --fullscreen flag', () => {
-  const parsed = parseArgs(['screenshot', 'page.png', '--fullscreen', '--max-size', '1024'], {
-    strictFlags: true,
-  });
+test('parseArgs recognizes screenshot flags', () => {
+  const parsed = parseArgs(
+    ['screenshot', 'page.png', '--fullscreen', '--max-size', '1024', '--no-stabilize'],
+    {
+      strictFlags: true,
+    },
+  );
   assert.equal(parsed.command, 'screenshot');
   assert.deepEqual(parsed.positionals, ['page.png']);
   assert.equal(parsed.flags.screenshotFullscreen, true);
   assert.equal(parsed.flags.screenshotMaxSize, 1024);
+  assert.equal(parsed.flags.screenshotNoStabilize, true);
+});
+
+test('usageForCommand documents screenshot stabilization tradeoff', () => {
+  const help = usageForCommand('screenshot');
+  if (help === null) throw new Error('Expected screenshot help text');
+  assert.match(help, /--no-stabilize/);
+  assert.match(help, /low-latency Android capture loops/);
 });
 
 test('parseArgs rejects invalid record --fps range', () => {
diff --git a/src/utils/command-schema.ts b/src/utils/command-schema.ts
@@ -56,6 +56,7 @@ export type CliFlags = RemoteConfigMetroOptions & {
   overlayRefs?: boolean;
   screenshotFullscreen?: boolean;
   screenshotMaxSize?: number;
+  screenshotNoStabilize?: boolean;
   baseline?: string;
   threshold?: string;
   appsFilter?: 'user-installed' | 'all';
@@ -1413,6 +1414,14 @@ const FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     usageLabel: '--max-size <px>',
     usageDescription: 'Screenshot: downscale so the longest edge is at most <px>',
   },
+  {
+    key: 'screenshotNoStabilize',
+    names: ['--no-stabilize'],
+    type: 'boolean',
+    usageLabel: '--no-stabilize',
+    usageDescription:
+      'Screenshot: skip Android demo-mode/status-bar stabilization and settle delay for low-latency capture loops',
+  },
   {
     key: 'baseline',
     names: ['--baseline', '-b'],

Original file line number	Diff line number	Diff line change
`@@ -39,6 +39,7 @@ export const screenshotCommand: RuntimeCommand<`
`39`	`39`	`{`
`40`	`40`	`fullscreen: options.fullscreen,`
`41`	`41`	`overlayRefs: options.overlayRefs,`
	`42`	`+ stabilize: options.stabilize,`
`42`	`43`	`surface: options.surface,`
`43`	`44`	`},`
`44`	`45`	`);`