Resolution Agent

Standalone Android screenshot capture agent for quick responsiveness galleries.

It captures the same app screen in these fixed variants:

• with gesture bar
• with 3-button bar
• without navigation bar
• wider screen
• taller screen
• shorter screen
• narrower screen
• bigger font
• smaller font

It then generates a local static gallery website with all screenshots.

For live debugging, you can also apply a single preset without taking a full capture matrix, keep the app open, and reset back afterward.

Requirements

• adb on PATH
• one connected Android device or emulator
• an installed app package to capture

Capture

npx resolution-agent capture --package com.example.app

If --package is omitted, the CLI tries to use the current foreground package.

Useful variants:

npx resolution-agent capture --package com.example.app --serve
npx resolution-agent capture --package com.example.app --relaunch --serve
npx resolution-agent capture --package com.example.app --relaunch --maestro-file ./flow.yaml
npx resolution-agent capture --package com.example.app --deeplink "myapp://settings" --relaunch --serve --port 37901
npx resolution-agent capture --package com.example.app --activity com.example.app/.MainActivity --out-dir ./artifacts/settings

By default the CLI preserves the current foreground screen and only changes the logical display config between screenshots. Use --relaunch if you want the old deterministic behavior that restarts the app before each capture.

Serve Existing Report

npx resolution-agent serve --dir ./artifacts/settings --port 37901

Live Resize

Apply one preset and keep it active while you inspect or fix the app:

npx resolution-agent apply --scenario narrower_screen
npx resolution-agent apply --scenario shorter_screen
npx resolution-agent apply --scenario bigger_font

When you are done, restore the original display state:

npx resolution-agent reset

If you want to force the device back to physical resolution plus fullscreen gesture navigation, use:

npx resolution-agent reset-resolution

Maestro Navigation

If you want deterministic relaunches to a deeper screen, pass a Maestro flow:

npx resolution-agent capture --package com.example.app --relaunch --maestro-file ./flow.yaml

The flow runs after each relaunch and before the screenshot. These environment variables are exposed to Maestro for each scenario:

• RESOLUTION_AGENT_SCENARIO
• RESOLUTION_AGENT_WIDTH
• RESOLUTION_AGENT_HEIGHT
• RESOLUTION_AGENT_FONT_SCALE
• RESOLUTION_AGENT_NAV_MODE
• RESOLUTION_AGENT_PACKAGE
• RESOLUTION_AGENT_SERIAL

Important Flags

• --device SERIAL: target a specific adb device
• --package APP_ID: app package to relaunch before each screenshot
• --activity PKG/.Activity: launch a specific activity instead of the launcher
• --deeplink URI: launch a deep link before each screenshot
• --wait-ms 1800: settle time after launch before screenshot
• --size-delta-pct 0.2: how much wider/taller/narrower/shorter variants differ from the baseline
• --font-bigger 1.25: multiplier for the bigger font scenario
• --font-smaller 0.85: multiplier for the smaller font scenario
• --relaunch: force-stop and relaunch the app before each screenshot
• --no-relaunch: explicit alias for the default behavior
• --maestro-file FLOW.yaml: run a Maestro flow after each relaunch and before capture
• apply --scenario SLUG: apply one preset without capturing screenshots
• reset: restore the display state saved by apply
• reset-resolution: reset wm size and wm density, then force fullscreen gesture navigation
• --serve: keep a local gallery server running after capture
• --keep-display-config: do not restore display overrides afterward

Output

The capture output directory contains:

• index.html: gallery page
• report.json: machine-readable metadata
• screenshots/*.png: scenario screenshots

Notes

• The CLI uses adb shell wm size, adb shell wm density, font_scale, and policy_control.
• By default capture remembers the initial display/navbar state and restores that exact state at the end, unless --keep-display-config is set.
• reset is for restoring the baseline saved by apply; reset-resolution is the quick recovery command if you want the device back in full-resolution fullscreen mode regardless of the starting state.
• wider and taller are logical-display overrides, not real hardware changes. Use them as comparison probes, not as physical-device truth.