Android Readme Screenshot Studio

Android README Screenshot Studio

Create repository screenshots from the real Bitchat Android UI, not from a drawn mockup. The result should look intentional enough for the top of the README while remaining reproducible, synthetic, and honest about what a static emulator capture proves.

Resolve the brief

Extract as much as possible from the conversation before asking questions. Confirm or infer:

1. Which surfaces are needed, such as mesh chat and geohash globe.
2. The exact visible state and ordering. Treat phrases like “photo, messages, three voices, thumbs-up” as a chronological contract rather than a loose suggestion.
3. Whether existing README images should be preserved, replaced, or added.
4. The target base. Default repository work to the latest origin/main.
5. Whether GitHub publication and merge are authorized. A request to “open a PR and merge it” authorizes both; otherwise do not merge.

Do not invent the subject of a requested photo. Nicknames, channel names, or previous fixture copy are not sufficient justification for choosing an outdoor, urban, political, or personal scene. Reuse an existing rights-safe asset when the subject should remain stable, or ask for the intended subject. If the user explicitly approves synthetic imagery, disclose it and keep its source capture-only unless they request a committed asset.

Read references/showcase-recipes.md for every run. It contains the concrete mesh-chat and globe recipes, framing guidance, the verified current-pair fast path, and the final acceptance checklist. When the request matches the existing README pair and the production UI has not materially changed, try that fast path first and then validate every visible result. Fall back to tracing the current implementation when an entry point, state model, or composition has changed.

When a populated screen requires a debug fixture, also read ../android-ui-visual-review/references/fixture-recipes.md.

Work in a fresh tree

Protect the user's active checkout:

1. Inspect git status without modifying it.
2. Fetch origin/main.
3. Create a new codex/ branch in a temporary worktree rooted at the current origin/main.
4. Keep screenshots and raw captures in a separate temporary artifact directory so cleanup or checkout operations cannot remove them.

Do not switch the user's original checkout, reuse a dirty branch, or mix an unrelated PR into the screenshot change. If the request continues an existing screenshot PR, reuse its already-isolated worktree only after verifying its head and base.

Establish the capture contract

Before building, write a compact local matrix containing:

• surface and navigation path;
• chronological fixture contents;
• expected visible top and bottom rows;
• emulator profile class, portrait orientation, theme, and locale;
• crop policy and final asset dimensions;
• existing asset path and README reference;
• behaviors the static screenshot does not prove.

Use the current production UI and latest main interaction model. Trace the screen entry point and state source before adding a fixture. A beautiful capture of a stale or fake UI is not acceptable.

Use a high-resolution Android canvas

Prefer the newest stable Android runtime installed locally and a large, high-density portrait emulator profile. Reuse a previously validated capture profile when it remains available, but verify the guest properties and keep the resulting profile facts in the local capture contract rather than the repository or GitHub text.

After boot, record the guest values with an explicit emulator selector:

adb -s "$ANDROID_README_SERIAL" shell getprop ro.build.version.release
adb -s "$ANDROID_README_SERIAL" shell getprop ro.build.version.sdk
adb -s "$ANDROID_README_SERIAL" shell getprop ro.build.version.security_patch
adb -s "$ANDROID_README_SERIAL" shell wm size
adb -s "$ANDROID_README_SERIAL" shell wm density

Never publish emulator selectors, AVD names, local paths, usernames, IP addresses, or other machine identifiers.

Build a deterministic showcase fixture

Launch the Activity before injecting process-local state. Prefer existing debug hooks. If they cannot express the composition, add the smallest temporary command under:

app/src/debug/java/com/bitchat/android/testhook/

The fixture should:

• use synthetic names, peer IDs, message IDs, and copy;
• use the real local mesh peer ID for self-authored messages;
• use a fixed epoch so timestamps and ordering are stable;
• insert records in the exact requested chronology;
• report structured counts through the test-hook result file;
• copy capture-only media into the app's cache or files directory;
• populate only the peers and state needed for the header;
• avoid persistence unless persistence itself is the subject.

For voice notes, route real audio files through the app's waveform extractor. Use short, distinct, locally synthesized speech clips or other rights-safe speech audio. Never draw a decorative waveform and call it speech. Wait for asynchronous decoding before capture, then inspect that pauses and syllable envelopes look plausibly different between notes.

For image attachments, use a rights-safe existing asset or an explicitly approved synthetic source. Keep fixture media outside production source sets and remove every capture-only hook before committing. Compose image rows may remember a decoded bitmap by file path. After replacing the bytes at an unchanged path, relaunch the app or use a new destination path before judging the revised crop.

Capture from the real app

Build and install the ABI-matching debug APK, satisfy onboarding and permissions, inject the fixture, and navigate to the intended surface.

Capture directly:

adb -s "$ANDROID_README_SERIAL" exec-out screencap -p > "$ARTIFACT_PATH"

Inspect the full screenshot immediately. Check message count and order, nickname ownership, peer count, waveform variety, image visibility, globe center, grid precision, clipping, and composer placement.

Inject a complete timeline in one operation and allow at least two seconds of quiet UI time after the fixture reports success. This avoids capturing entry animations, incomplete placement, or media that has not finished decoding.

Crop only Android system chrome. Preserve Bitchat's app header, translucent overlap, content, and composer. Derive the crop from the observed status and navigation insets; do not blindly reuse pixel offsets from a different profile. Because the app renders edge-to-edge, app controls may extend into the reported navigation inset. Place the bottom crop after the final control outline and shadow but before the system gesture affordance; removing the entire inset can clip the app itself. Keep every final README screenshot in a matched portrait size.

Use image inspection after the crop. File dimensions and a successful ADB command do not prove that the desired composition is visible.