capod/.claude/rules/screenshots.md

Play Store Screenshot Pipeline

Overview

Localized screenshots are generated using Compose Preview Screenshot Testing (alpha), rendered offline (no device needed), and sorted into fastlane metadata directories for Play Store upload.

Pipeline

ScreenshotContent.kt (mock data + composables)
    → PlayStoreScreenshots.kt (@PreviewTest entry points)
    → PlayStoreLocales.kt (multi-preview locale annotations, auto-generated per batch)
    → generate_screenshots.sh (batched Gradle runs to avoid OOM)
    → copy_screenshots.sh (sort PNGs into fastlane locale dirs)
    → fastlane/metadata/android/{locale}/images/phoneScreenshots/

Key Files

File	Purpose
app/src/debug/java/.../screenshots/ScreenshotContent.kt	Mock data composables for each screen (7 screens)
app/src/screenshotTest/kotlin/.../screenshots/PlayStoreScreenshots.kt	@PreviewTest functions (currently: DashboardLight, DashboardDark, CasePopUp, DeviceProfiles, AddProfile, DeviceSettingsReactions, WidgetConfiguration)
app/src/screenshotTest/kotlin/.../screenshots/PlayStoreLocales.kt	Multi-preview annotations (auto-generated by batch script)
fastlane/generate_screenshots.sh	Batched generation; locale list (ALL_LOCALES) and BATCH_SIZE are defined inside the script
fastlane/copy_screenshots.sh	Copies rendered PNGs into fastlane structure

Commit policy

Only the 6 smoke locales (en-US, de-DE, ja-JP, ar, zh-CN, pt-BR) have phoneScreenshots/*.png checked into the repo. Non-smoke locales are excluded by .gitignore. This mirrors permission-pilot and keeps repo size small (~7 MB vs ~67 MB for the full 68 locales).

Play Store's supply only uploads what's present in fastlane/metadata/android/<locale>/images/phoneScreenshots/. For locales not in the upload, Play Store retains whatever was last pushed. So full localization on Play Store is maintained by an occasional manual full regen + :screenshots_only upload — not by every PR.

Commands

# Default — smoke set (6 locales × 7 screens, ~42 PNGs, single batch).
# Use this for local iteration and PRs that touch screenshot content.
./fastlane/generate_screenshots.sh --smoke

# Full run — all 68 locales. Use only when intending to upload to Play Store
# (the non-smoke output is .gitignored and should not be committed).
./fastlane/generate_screenshots.sh

# Copy into fastlane directories (run after generate)
./fastlane/copy_screenshots.sh

# Clean copy (removes old screenshots first) — REQUIRED when screens are removed or renamed
./fastlane/copy_screenshots.sh --clean

Adding a New Screenshot

1. Add a composable content function in ScreenshotContent.kt (e.g. NewScreenContent())
2. Add a @PreviewTest function in PlayStoreScreenshots.kt that calls it
3. Add the function name → filename mapping in copy_screenshots.sh SCREEN_MAP
4. Update the expected count in generate_screenshots.sh (composables per locale)
5. Run the smoke pipeline: generate_screenshots.sh --smoke then copy_screenshots.sh --clean

Removing or Renaming a Screenshot

1. Remove the @PreviewTest entry and its SCREEN_MAP mapping
2. Run generate_screenshots.sh --smoke
3. Run copy_screenshots.sh --clean — --clean is required here; without it, old files (e.g. a renamed 8_reaction_settings.png) stay in fastlane/metadata/android/<smoke locale>/images/phoneScreenshots/ and get uploaded to Play Store

After UI Changes

When modifying a screen that appears in screenshots (check ScreenshotContent.kt), regenerate the smoke set:

./fastlane/generate_screenshots.sh --smoke
./fastlane/copy_screenshots.sh --clean

Refreshing all locales on Play Store

Periodic, manual operation — not per-PR:

./fastlane/generate_screenshots.sh           # full, ~30 min, 477 PNGs
./fastlane/copy_screenshots.sh --clean
bundle exec fastlane screenshots_only        # uploads all 68 locales to Play Store
git checkout -- fastlane/metadata/android/   # discard non-smoke changes (gitignored anyway)

The .gitignore rule keeps non-smoke output unstaged automatically, so only the smoke locales' refreshed PNGs would show up as modifications and can be committed.

Technical Notes

• Batch size defaults to 2 locales; renders per batch = BATCH_SIZE × screen count (currently 2 × 7 = 14). Small batches avoid layoutlib memory leaks (~10MB/image)
• Gradle daemon is stopped between batches to release memory
• PlayStoreLocales.kt is temporarily rewritten per batch and restored via trap
• Device spec: 1080x2400px @ 428 DPI (Pixel-class phone)
• Uses com.android.compose.screenshot plugin v0.0.1-alpha13
• Output: app/src/screenshotTestGplayDebug/reference/