From e6eb0d818f7b39fda42878b6236162d8e13d7a60 Mon Sep 17 00:00:00 2001
From: darken <darken@darken.eu>
Date: Thu, 26 Feb 2026 00:49:46 +0100
Subject: [PATCH] docs: Add screenshot pipeline documentation

---
 .claude/CLAUDE.md            |  3 ++
 .claude/rules/screenshots.md | 68 ++++++++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+)
 create mode 100644 .claude/rules/screenshots.md

diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
index aae19f52..689e317f 100644
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -25,6 +25,8 @@ Quick build check: `./gradlew assembleFossDebug`
 | `app/src/main/res/` | Layouts, drawables, strings |
 | `app-common/src/test/` | Unit tests |
 | `app/build.gradle.kts` | App build config, dependencies, flavors |
+| `app/src/debug/java/.../screenshots/` | Play Store screenshot content composables |
+| `fastlane/` | Screenshot generation scripts, Play Store metadata |
 
 ## Development Tips
 
@@ -43,3 +45,4 @@ Detailed guidelines are in `.claude/rules/`:
 - `localization.md` — String resource naming conventions
 - `commit-guidelines.md` — Commit message format and prefixes
 - `agent-instructions.md` — Sub-agent delegation and critical thinking
+- `screenshots.md` — Play Store screenshot pipeline, commands, adding new screens
diff --git a/.claude/rules/screenshots.md b/.claude/rules/screenshots.md
new file mode 100644
index 00000000..ef3a531f
--- /dev/null
+++ b/.claude/rules/screenshots.md
@@ -0,0 +1,68 @@
+# 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 (8 screens) |
+| `app/src/screenshotTest/kotlin/.../screenshots/PlayStoreScreenshots.kt` | `@PreviewTest` functions that wire content to locale annotations |
+| `app/src/screenshotTest/kotlin/.../screenshots/PlayStoreLocales.kt` | Multi-preview annotations (auto-generated by batch script) |
+| `fastlane/generate_screenshots.sh` | Batched generation across 68 locales |
+| `fastlane/copy_screenshots.sh` | Copies rendered PNGs into fastlane structure |
+
+## Commands
+
+```bash
+# Full run — all 68 locales, ~12 batches, ~7 minutes
+./fastlane/generate_screenshots.sh
+
+# Smoke test — 6 locales (en, de, ja, ar, zh-CN, pt-BR), single batch
+./fastlane/generate_screenshots.sh --smoke
+
+# Copy into fastlane directories (run after generate)
+./fastlane/copy_screenshots.sh
+
+# Clean copy (removes old screenshots first)
+./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 full pipeline: `generate_screenshots.sh` then `copy_screenshots.sh`
+
+## After UI Changes
+
+When modifying a screen that appears in screenshots (check `ScreenshotContent.kt`), regenerate:
+
+```bash
+./fastlane/generate_screenshots.sh
+./fastlane/copy_screenshots.sh --clean
+```
+
+## Technical Notes
+
+- Batch size defaults to 2 locales (16 renders) to avoid layoutlib memory leak (~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/`