fix: strip pre-PNG garbage from Android screenshots on multi-display devices (#185)

* fix: strip pre-PNG garbage from Android screenshots on multi-display devices

On Android emulators with multiple displays (e.g. Galaxy Z Fold), `adb
exec-out screencap -p` writes a warning to stdout before the PNG data,
producing corrupt files.  Locate the PNG signature in the buffer and
discard everything before it.

https://claude.ai/code/session_01Lfb3WKqXCSqYtCg8dbS8JW

* refactor: simplify PNG stripping and test scripts

- Remove unnecessary ternary; subarray(0) is a no-op
- Replace hex-encoded printf mock scripts with file-based payloads

https://claude.ai/code/session_01Lfb3WKqXCSqYtCg8dbS8JW

* fix: trim Android screenshot output to complete PNG payload

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: thymikee

src/platforms/android/__tests__/snapshot.test.ts

@@ -0,0 +1,103 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { screenshotAndroid } from '../index.ts';
+import type { DeviceInfo } from '../../../utils/device.ts';
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const VALID_PNG = Buffer.from(
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+b9xkAAAAASUVORK5CYII=',
+  'base64',
+);
+
+async function withMockedAdb(
+  tempPrefix: string,
+  script: string,
+  run: (ctx: { device: DeviceInfo; tmpDir: string }) => Promise<void>,
+  payload?: Buffer,
+): Promise<void> {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), tempPrefix));
+  const adbPath = path.join(tmpDir, 'adb');
+  await fs.writeFile(adbPath, script, 'utf8');
+  await fs.chmod(adbPath, 0o755);
+  if (payload) {
+    await fs.writeFile(path.join(tmpDir, 'payload.bin'), payload);
+  }
+
+  const previousPath = process.env.PATH;
+  process.env.PATH = `${tmpDir}${path.delimiter}${previousPath ?? ''}`;
+
+  const device: DeviceInfo = {
+    platform: 'android',
+    id: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator',
+    booted: true,
+  };
+
+  try {
+    await run({ device, tmpDir });
+  } finally {
+    process.env.PATH = previousPath;
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+}
+
+const catPayload = '#!/bin/bash\ncat "$(dirname "$0")/payload.bin"\n';
+
+test('screenshotAndroid writes a valid PNG when output is clean', async () => {
+  await withMockedAdb('screenshot-clean-', catPayload, async ({ device, tmpDir }) => {
+    const outPath = path.join(tmpDir, 'out.png');
+    await screenshotAndroid(device, outPath);
+    const written = await fs.readFile(outPath);
+    assert.deepEqual(written, VALID_PNG);
+  }, VALID_PNG);
+});
+
+test('screenshotAndroid strips warning text before PNG signature', async () => {
+  const warning =
+    '[Warning] Multiple displays were found, but no display id was specified! Defaulting to the first display found.';
+  const payload = Buffer.concat([Buffer.from(warning), VALID_PNG]);
+
+  await withMockedAdb('screenshot-warning-', catPayload, async ({ device, tmpDir }) => {
+    const outPath = path.join(tmpDir, 'out.png');
+    await screenshotAndroid(device, outPath);
+    const written = await fs.readFile(outPath);
+    assert.deepEqual(written, VALID_PNG);
+  }, payload);
+});
+
+test('screenshotAndroid strips trailing garbage after PNG payload', async () => {
+  const payload = Buffer.concat([VALID_PNG, Buffer.from('\ntrailing-warning\n')]);
+
+  await withMockedAdb('screenshot-trailing-', catPayload, async ({ device, tmpDir }) => {
+    const outPath = path.join(tmpDir, 'out.png');
+    await screenshotAndroid(device, outPath);
+    const written = await fs.readFile(outPath);
+    assert.deepEqual(written, VALID_PNG);
+  }, payload);
+});
+
+test('screenshotAndroid throws when output contains no PNG signature', async () => {
+  const script = '#!/bin/bash\necho "not a png"\n';
+
+  await withMockedAdb('screenshot-nopng-', script, async ({ device, tmpDir }) => {
+    const outPath = path.join(tmpDir, 'out.png');
+    await assert.rejects(() => screenshotAndroid(device, outPath), {
+      message: 'Screenshot data does not contain a valid PNG header',
+    });
+  });
+});
+
+test('screenshotAndroid throws when PNG payload is truncated', async () => {
+  const payload = VALID_PNG.subarray(0, VALID_PNG.length - 3);
+
+  await withMockedAdb('screenshot-truncated-', catPayload, async ({ device, tmpDir }) => {
+    const outPath = path.join(tmpDir, 'out.png');
+    await assert.rejects(() => screenshotAndroid(device, outPath), {
+      message: 'Screenshot data does not contain a complete PNG payload',
+    });
+  }, payload);
+});

src/platforms/android/snapshot.ts

@@ -18,14 +18,28 @@ export async function snapshotAndroid(
   return parseUiHierarchy(xml, 800, options);
 }
 
+// PNG file signature: 0x89 P N G \r \n 0x1A \n
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
 export async function screenshotAndroid(device: DeviceInfo, outPath: string): Promise<void> {
   const result = await runCmd('adb', adbArgs(device, ['exec-out', 'screencap', '-p']), {
     binaryStdout: true,
   });
   if (!result.stdoutBuffer) {
     throw new AppError('COMMAND_FAILED', 'Failed to capture screenshot');
   }
-  await fs.writeFile(outPath, result.stdoutBuffer);
+  // On multi-display devices (e.g. Galaxy Z Fold), adb screencap may write a
+  // warning to stdout before the PNG data.  Strip any leading garbage by
+  // locating the PNG signature and discarding everything before it.
+  const pngOffset = result.stdoutBuffer.indexOf(PNG_SIGNATURE);
+  if (pngOffset < 0) {
+    throw new AppError('COMMAND_FAILED', 'Screenshot data does not contain a valid PNG header');
+  }
+  const pngEndOffset = findPngEndOffset(result.stdoutBuffer, pngOffset);
+  if (!pngEndOffset) {
+    throw new AppError('COMMAND_FAILED', 'Screenshot data does not contain a complete PNG payload');
+  }
+  await fs.writeFile(outPath, result.stdoutBuffer.subarray(pngOffset, pngEndOffset));
 }
 
 export async function dumpUiHierarchy(device: DeviceInfo): Promise<string> {
@@ -83,6 +97,20 @@ function extractUiDumpXml(stdout: string, stderr: string): string | null {
   return xml.length > 0 ? xml : null;
 }
 
+function findPngEndOffset(buffer: Buffer, pngStartOffset: number): number | null {
+  let offset = pngStartOffset + PNG_SIGNATURE.length;
+  while (offset + 8 <= buffer.length) {
+    const chunkLength = buffer.readUInt32BE(offset);
+    const chunkTypeOffset = offset + 4;
+    const chunkType = buffer.toString('ascii', chunkTypeOffset, chunkTypeOffset + 4);
+    const chunkEnd = offset + 12 + chunkLength; // len(4) + type(4) + data + crc(4)
+    if (chunkEnd > buffer.length) return null;
+    if (chunkType === 'IEND') return chunkEnd;
+    offset = chunkEnd;
+  }
+  return null;
+}
+
 function isRetryableAdbError(err: unknown): boolean {
   if (!(err instanceof AppError)) return false;
   if (err.code !== 'COMMAND_FAILED') return false;