perf(scripts): add a device-free PNG crop benchmark

`pnpm bench:png-crop` runs the whole-image pipeline and the shipped region crop
over the same bytes in one process, so the comparison holds the capture content,
the deflate stream, and the machine fixed. The corpus is generated, which keeps a
run at seconds with no device; real captures join the same table via `--file`, and
each corpus entry prints its compressed size so an unrealistic corpus is visible.

The README records what the measurements said, including the case the encoder
policy loses: `None` on every scanline is faster everywhere but writes about 1.7x
more bytes than a filtered encoding on smooth low-frequency content.

Author: thymikee

package.json

@@ -124,6 +124,7 @@
     "bench:ios-snapshot": "node --experimental-strip-types scripts/ios-snapshot-benchmark/run.ts",
     "bench:ios-snapshot:deep-button": "node --experimental-strip-types scripts/ios-snapshot-benchmark/deep-button.ts",
     "bench:ios-snapshot:evidence": "node --experimental-strip-types scripts/ios-snapshot-benchmark/evidence.ts",
+    "bench:png-crop": "node --experimental-strip-types scripts/png-crop-benchmark/run.ts",
     "bench:ios-ax-bridge:targeted": "node --experimental-strip-types scripts/ios-ax-bridge-spike/targeted-run.ts",
     "mutation:run": "node --experimental-strip-types scripts/mutation/run.ts",
     "mutation:check": "node --experimental-strip-types scripts/mutation/run.ts --no-run",

scripts/png-crop-benchmark/README.md

@@ -0,0 +1,51 @@
+# PNG crop benchmark
+
+```sh
+pnpm bench:png-crop -- --rounds 5
+pnpm bench:png-crop -- --rounds 5 --file /path/to/real-capture.png
+```
+
+Compares the two ways this repository can crop a screenshot. Both run over the same bytes as PNG
+worker jobs in one process, so what differs is the algorithm and not the thread it happens to land
+on, or a file write on one side only:
+
+- `whole-image` — the previous crop: one job decodes the whole capture to RGBA, the box rows are
+  copied out of that bitmap, and a second job encodes the box.
+- `region` — the shipped crop: one job reads the box's rows and encodes them, as RGB rather than
+  RGBA whenever the cropped pixels are all opaque.
+
+The corpus is generated, so a full run costs seconds and needs no device. Generated captures are
+written to `.tmp/png-crop-benchmark/` and each one's compressed size is printed under the table:
+a corpus that stops resembling a real capture becomes visible there instead of flattering the
+result. Pass real captures with `--file` (repeatable) to put their numbers in the same table; the
+real captures decide the verdict, since generated content cannot match a device's deflate stream.
+
+## What is actually saved
+
+Neither pipeline reads less of the file: a deflate stream has to be inflated to its end, so both
+inflate the whole compressed image and reconstruct the rows above the box. What the region path
+saves is the pixel work — reconstructing only down to the box's last row, allocating and copying
+only the box's pixels instead of a full RGBA bitmap — plus one worker round trip, and the RGBA
+re-encode of the answer.
+
+## What the measurements have said
+
+Measured at that matched boundary over 7 rounds, on captures taken from an iOS Simulator and an
+Android Emulator: the iOS captures go 2.5x to 5.6x faster and their crops come out 1.04x to 2.16x
+smaller, mostly because an opaque crop is written as RGB instead of RGBA. A flat UI capture gains
+the most, because the previous pipeline still expands the whole capture to an RGBA bitmap whatever
+the filters look like, while the region path skips the pixels above the box.
+
+The noisiest capture in that set — a full-screen Android `screencap`, 1.4 MB compressed — is a wash
+on time (1.0x to 1.6x) and its crop comes out up to 1.13x *larger*. Inflating and reconstructing
+that much entropy dominates both pipelines, and the region writer's `None` filter cannot beat the
+general writer's filter search on content that noisy. Check your own captures with `--file` before
+reading a win or a loss into any number here.
+
+The encoder keeps the `None` filter on every scanline. Scoring the five PNG filters per row is
+1.4x to 2.6x slower and produces a *larger* file on UI captures, where the smallest-sum-of-absolute-
+differences heuristic prefers Sub or Up on text rows that deflate smaller unfiltered. On synthetic
+low-frequency content — the `photo` captures here, which are smooth 8px blocks — `None` is still
+faster but writes about 1.7x more bytes than a filtered encoding would. Real photo-filled captures
+still come out smaller with `None` than with the general writer's own filter search, so the corpus
+here overstates that case; check your own captures with `--file` before treating it as a limit.

scripts/png-crop-benchmark/args.test.ts

@@ -0,0 +1,41 @@
+import { test } from 'vitest';
+import assert from 'node:assert/strict';
+import { parseBenchmarkArgs } from './args.ts';
+
+test('an empty command line keeps the default round count', () => {
+  assert.deepEqual(parseBenchmarkArgs([]), {
+    rounds: 5,
+    jsonPath: undefined,
+    captureFiles: [],
+  });
+});
+
+test('rounds, json path, and every capture file are read from their flags', () => {
+  assert.deepEqual(
+    parseBenchmarkArgs([
+      '--rounds',
+      '9',
+      '--json',
+      'out/bench.json',
+      '--file',
+      'a.png',
+      '--file',
+      'b.png',
+    ]),
+    { rounds: 9, jsonPath: 'out/bench.json', captureFiles: ['a.png', 'b.png'] },
+  );
+});
+
+test('a round count that is not a positive number falls back to the default', () => {
+  assert.equal(parseBenchmarkArgs(['--rounds', '0']).rounds, 5);
+  assert.equal(parseBenchmarkArgs(['--rounds', 'many']).rounds, 5);
+  assert.equal(parseBenchmarkArgs(['--rounds', '2.4']).rounds, 2);
+});
+
+test('a flag with no value after it is ignored', () => {
+  assert.deepEqual(parseBenchmarkArgs(['--json']), {
+    rounds: 5,
+    jsonPath: undefined,
+    captureFiles: [],
+  });
+});

scripts/png-crop-benchmark/args.ts

@@ -0,0 +1,36 @@
+/** The command line `pnpm bench:png-crop` accepts. */
+
+export type BenchmarkOptions = Readonly<{
+  rounds: number;
+  jsonPath: string | undefined;
+  captureFiles: readonly string[];
+}>;
+
+const DEFAULT_ROUNDS = 5;
+
+export function parseBenchmarkArgs(argv: readonly string[]): BenchmarkOptions {
+  return {
+    rounds: readNumber(argv, '--rounds') ?? DEFAULT_ROUNDS,
+    jsonPath: readString(argv, '--json'),
+    captureFiles: readAll(argv, '--file'),
+  };
+}
+
+function readNumber(argv: readonly string[], flag: string): number | undefined {
+  const value = readString(argv, flag);
+  const parsed = value === undefined ? Number.NaN : Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.round(parsed) : undefined;
+}
+
+function readString(argv: readonly string[], flag: string): string | undefined {
+  const index = argv.indexOf(flag);
+  return index >= 0 ? argv[index + 1] : undefined;
+}
+
+function readAll(argv: readonly string[], flag: string): string[] {
+  const values: string[] = [];
+  argv.forEach((entry, index) => {
+    if (entry === flag && argv[index + 1] !== undefined) values.push(argv[index + 1]!);
+  });
+  return values;
+}

scripts/png-crop-benchmark/corpus.test.ts

@@ -0,0 +1,68 @@
+import { test } from 'vitest';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { PNG } from '@agent-device/capture-kit/png';
+import { buildCorpus, cropBoxOf, CROP_SCENARIOS } from './corpus.ts';
+
+const SCENARIO_BY_NAME = new Map(CROP_SCENARIOS.map((scenario) => [scenario.name, scenario]));
+const CAPTURE = {
+  name: 'phone',
+  label: 'phone',
+  width: 1200,
+  height: 2400,
+  bytes: Buffer.alloc(0),
+};
+const SMALL = [{ name: 'tiny', label: 'tiny', width: 24, height: 40 }];
+
+test('a card crop keeps the framed fraction of the capture', () => {
+  const box = cropBoxOf(CAPTURE, SCENARIO_BY_NAME.get('card')!);
+
+  assert.deepEqual(box, { x: 96, y: 600, width: 960, height: 480 });
+});
+
+test('a full-bleed header is clamped to the image, never one pixel past it', () => {
+  const box = cropBoxOf(CAPTURE, SCENARIO_BY_NAME.get('header')!);
+
+  assert.equal(box.x, 0);
+  assert.equal(box.width, CAPTURE.width);
+  assert.equal(box.y + box.height, 288);
+});
+
+test('the same generated capture comes out byte for byte every run', () => {
+  const directory = mkdtempSync(path.join(os.tmpdir(), 'png-crop-corpus-'));
+  try {
+    const first = buildCorpus(path.join(directory, 'first'), SMALL);
+    const second = buildCorpus(path.join(directory, 'second'), SMALL);
+
+    assert.equal(first.length, 2);
+    assert.deepEqual(
+      first.map((capture) => capture.bytes),
+      second.map((capture) => capture.bytes),
+    );
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+test('interface and photo captures differ, and both decode at their declared size', () => {
+  const directory = mkdtempSync(path.join(os.tmpdir(), 'png-crop-corpus-'));
+  try {
+    const [interfaceCapture, photoCapture] = buildCorpus(directory, SMALL);
+
+    const decoded = [interfaceCapture, photoCapture].map((capture) =>
+      PNG.sync.read(capture!.bytes),
+    );
+    assert.deepEqual(
+      decoded.map((png) => [png.width, png.height]),
+      [
+        [24, 40],
+        [24, 40],
+      ],
+    );
+    assert.notDeepEqual(decoded[0]!.data, decoded[1]!.data);
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});

scripts/png-crop-benchmark/corpus.ts

@@ -0,0 +1,155 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { PNG } from '@agent-device/capture-kit/png';
+
+/**
+ * The captures and crop boxes this benchmark measures. They are generated rather than recorded,
+ * so a run costs seconds and needs no device; each one reports its own compressed size, which is
+ * how a corpus that stopped resembling a real capture becomes visible instead of flattering.
+ * Pass real captures with `--file` to put their numbers in the same table.
+ */
+
+export type CaptureResolution = Readonly<{
+  name: string;
+  label: string;
+  width: number;
+  height: number;
+}>;
+
+const RESOLUTIONS: readonly CaptureResolution[] = [
+  { name: 'ios-phone', label: 'iPhone-class 1206x2622', width: 1206, height: 2622 },
+  { name: 'android-phone', label: 'Android-class 1080x2400', width: 1080, height: 2400 },
+  { name: 'ios-pad', label: 'iPad-class 2048x2732', width: 2048, height: 2732 },
+];
+
+export type Capture = Readonly<{
+  name: string;
+  label: string;
+  width: number;
+  height: number;
+  bytes: Buffer;
+}>;
+
+export type CropScenario = Readonly<{
+  name: string;
+  /** Fractions of the capture, so one scenario reads well at every resolution. */
+  fraction: Readonly<{ x: number; y: number; width: number; height: number }>;
+}>;
+
+/** The box shapes `--crop-on` resolves: a card, a full-bleed header, and a small control. */
+export const CROP_SCENARIOS: readonly CropScenario[] = [
+  { name: 'card', fraction: { x: 0.08, y: 0.25, width: 0.8, height: 0.2 } },
+  { name: 'header', fraction: { x: 0, y: 0, width: 1, height: 0.12 } },
+  { name: 'control', fraction: { x: 0.3, y: 0.6, width: 0.3, height: 0.04 } },
+];
+
+export function buildCorpus(
+  outDir: string,
+  resolutions: readonly CaptureResolution[] = RESOLUTIONS,
+): Capture[] {
+  mkdirSync(outDir, { recursive: true });
+  return resolutions.flatMap(({ name, label, width, height }) =>
+    (['interface', 'photo'] as const).map((kind) => {
+      const bytes = PNG.sync.write(encodeCapture(width, height, kind));
+      writeFileSync(path.join(outDir, `${name}-${kind}.png`), bytes);
+      return { name: `${name}-${kind}`, label: `${label} ${kind}`, width, height, bytes };
+    }),
+  );
+}
+
+export function readCaptureFile(filePath: string, index: number): Capture {
+  const bytes = readFileSync(filePath);
+  const png = PNG.sync.read(bytes);
+  return {
+    name: `capture-${index}`,
+    label: path.basename(filePath),
+    width: png.width,
+    height: png.height,
+    bytes,
+  };
+}
+
+type Content = 'interface' | 'photo';
+
+/**
+ * A capture a device could have produced. `interface` is flat panels with high-frequency text
+ * where the copy is drawn, which is what a settings or list screen looks like. `photo` is
+ * low-frequency detail in 8px blocks plus a gradient, which is what a photo, artwork, or a blurred
+ * background does to the deflate stream.
+ */
+function encodeCapture(width: number, height: number, content: Content): PNG {
+  const png = new PNG({ width, height });
+  const tones = content === 'photo' ? photoToneField(width, height) : null;
+  for (let y = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1) {
+      const offset = (y * width + x) * 4;
+      const [red, green, blue] = tones ? photoPixel(tones, x, y) : interfacePixel(x, y);
+      png.data[offset] = red;
+      png.data[offset + 1] = green;
+      png.data[offset + 2] = blue;
+      png.data[offset + 3] = 255;
+    }
+  }
+  return png;
+}
+
+/** Flat panels with high-frequency text where the copy is drawn. */
+function interfacePixel(x: number, y: number): readonly [number, number, number] {
+  const ink = x % 320 < 2 || y % 96 < 2 || (y % 24 > 6 && y % 24 < 18 && x % 7 < 3);
+  if (ink) return [24, 26, 30];
+  const band = Math.floor(y / 96);
+  return [(band * 11) % 240, (band * 17) % 244, (band * 23) % 248];
+}
+
+/** The 8px-block detail and soft gradient of a photo, scaled by the pixel position. */
+function photoPixel(
+  tones: readonly (readonly number[])[],
+  x: number,
+  y: number,
+): readonly [number, number, number] {
+  const tone = tones[y >> 3]?.[x >> 3] ?? 0;
+  return [
+    clampByte(tone + y / 6),
+    clampByte(tone * 0.8 + x / 9),
+    clampByte(tone * 0.6 + (x + y) / 24),
+  ];
+}
+
+/** Smooth 8px-block luminance in [40, 215], so a photo corpus compresses like a real photo. */
+function photoToneField(width: number, height: number): number[][] {
+  let state = 0x9e3779b9;
+  const next = () => {
+    state = (state * 1664525 + 1013904223) >>> 0;
+    return state / 0x100000000;
+  };
+  return Array.from({ length: Math.ceil(height / 8) }, (_row, blockRow) =>
+    Array.from({ length: Math.ceil(width / 8) }, (_column, blockColumn) => {
+      const drift = Math.sin(blockRow / 26) * 45 + Math.cos(blockColumn / 19) * 45;
+      return clampByte(128 + drift + (next() - 0.5) * 70);
+    }),
+  );
+}
+
+function clampByte(value: number): number {
+  return Math.max(0, Math.min(255, Math.round(value)));
+}
+
+export function cropBoxOf(
+  capture: Capture,
+  scenario: CropScenario,
+): {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+} {
+  const { fraction } = scenario;
+  const x = Math.round(capture.width * fraction.x);
+  const y = Math.round(capture.height * fraction.y);
+  return {
+    x,
+    y,
+    width: Math.max(1, Math.min(capture.width - x, Math.round(capture.width * fraction.width))),
+    height: Math.max(1, Math.min(capture.height - y, Math.round(capture.height * fraction.height))),
+  };
+}