appstore-screenshot-pipeline

name

appstore-screenshot-pipeline

description

Sync App Store screenshot PREVIEWS from committed snapshot-test baselines via `mise run store:screenshots` (list / sync / clean). Symlinks selected baseline PNGs into docs/app-store/screenshots/<app>/<device>/<locale>/NN-screen.png so re-recording snapshots auto-refreshes previews. PREVIEW-ONLY — baselines carry an alpha channel and wrong dimensions, so they are NOT ASC submission-spec; a separate marketing-frame/upscale pass is still required before any real upload. Invoke when wiring or refreshing store-preview screenshots, running/debugging `store:screenshots`, eyeballing the storefront storyline, or when asked "can I upload these snapshot PNGs to App Store Connect" (answer: not directly).

App Store Screenshot Pipeline

When to invoke

• Wiring or refreshing the store-preview screenshot tree.
• Running or debugging mise run store:screenshots.
• Eyeballing the App Store storefront storyline from a single source.
• Someone proposes uploading the snapshot PNGs straight to ASC.

What it is

mise-tasks/store/screenshots (task store:screenshots) maps selected snapshot-test baseline PNGs into a staging tree using relative symlinks:

docs/app-store/screenshots/<app>/<device>/<locale>/NN-screen.png
  → Packages/.../__Snapshots__/<...>.png

This keeps the snapshot baseline the single source of truth: re-recording the snapshots (swift test --record) auto-updates the store preview with no copy step. Git stores the symlinks as links, not PNG copies. Mirrors the scriptable-ops precedent of mise-tasks/ck/schema and the ASCRegister CLI.

Invocation

mise run store:screenshots list                              # print mapping + gaps
mise run store:screenshots sync  [--app sudoku|minesweeper|all]
mise run store:screenshots clean [--app sudoku|minesweeper|all]

• list — prints every wired slot with an [ok] / [MISSING-BASELINE] mark, plus the standing reminders (preview-only; no iPad baselines).
• sync — creates/refreshes the symlinks; skips slots whose baseline is missing.
• clean — removes only the symlinks (-L checked) and prunes empty dirs.

The mapping table lives inline in the task (one row per store slot that has a baseline today). --app filters to one app.

What is wired today

Light-mode, en/default-locale slots that have a baseline (per the inline MAP):

• Sudoku — iPhone: Home / Daily / Board / Completion / Settings; Mac: Home / Board / Settings.
• Minesweeper — iPhone: Home / Daily / Board / Completion; Mac: Home / Daily.

Run mise run store:screenshots list for the authoritative live mapping. Only light-mode renders are wired (ASC v1 storyline is light-mode per docs/app-store/screenshot-strategy.md §Capture conventions).

PREVIEW-ONLY — these are NOT submission-ready

The baselines are raw NSHostingView renders at snapshot layout sizes with an alpha channel. ASC's screenshot spec is exact-dimension, zero-tolerance, no alpha — so ASC rejects them at the dimension/alpha check before review:

Source	Baseline pixels	ASC requirement	Verdict
iPhone snapshot	786 × 1704, RGBA	6.9": 1290×2796 / 1320×2868, no alpha	✗ size + alpha
Mac snapshot	1800 × 1200, RGBA	≥ 1280×800, no alpha	✗ alpha
iPad	1032×1376 baselines exist (#506)	13": 2048×2732 / 2064×2752	✗ size + alpha (use build-ascspec)

The symlinked tree is for eyeballing the storyline from one source — it is not an upload path.

The marketing-frame pass NOW EXISTS — and is the real upload path (#311 / #506)

The "separate pass" below is no longer hypothetical. mise run store:screenshots build-ascspec (→ scripts/build-ascspec-screenshots.py) composites the baselines into ASC-exact 1290×2796 (iPhone 6.9") + 2064×2752 (iPad 13") RGB, no-alpha PNGs with on-brand frames + the strategy-doc caption copy, written to their OWN tree:

docs/app-store/screenshots-ascspec/<app>/<device>/<locale>/NN-screen.png

This path is separate from the preview symlinks (so it never clobbers them) AND matches the uploader contract <app>/<device>/<locale> exactly. Key facts:

• Per-locale fonts: CJK locales (zh-Hant/zh-Hans/ja/ko) load Hiragino/PingFang — SFNS has zero CJK glyphs and renders Chinese as tofu (the #504 regression).
• iPad baselines now exist (#506 added iPad-13 snapshot configs + the generator's ipad-13 arm) — the "unwired" row above is historical.
• Upload (Leader-orderable, gated): ASCRegister metadata screenshots --app <app> --app-id <id> --platform ios --locale <repo-code> --screenshots-dir docs/app-store/screenshots-ascspec --i-am-sure (run per locale; device auto-detected from the dir; iPhone+iPad both picked up, already-present slots skipped). Other locales fall back to en in ASC.
• EYEBALL the output per locale (esp. CJK) before upload — the dimension/mode check passed even while every zh-Hant caption was tofu (#504). See [[interactive-sim-ux-audit]] discipline: verify content, not just dims.

Known footguns

• Do not upload the symlinked PNGs to App Store Connect. They fail the dimension + alpha pre-check. The sync output and list both reprint this.
• The gap to submission-ready is now CLOSED by build-ascspec (see the section above). Do not upload the preview symlinks; do upload the screenshots-ascspec/ tree. #311 delivered the marketing-frame pass + CJK-font fix + uploader-contract path; #506 added the iPad-13 arm. Both apps' iPhone 6.9" + iPad 13" (en + zh-Hant) are uploaded to ASC as of 2026-06-15.
• Missing baseline ≠ error. sync skips a slot whose source PNG is absent and reports it; that's expected when a snapshot hasn't been recorded yet.
• Re-record refreshes automatically. Because the previews are symlinks, you never re-run anything after swift test --record — the preview follows.

See also

• docs/app-store/screenshot-strategy.md — the full storyline (5 shots × device classes × 7 locales), overlay copy, capture conventions, and the §"Snapshot-sourced pipeline" / §gap that this task implements.
• [[asc-ops-handoff]] — uploading App Metadata (incl. screenshots) to ASC is a user-owned / future-ASCRegister-mode op; this task only stages previews.
• [[apple-dev-skills:swift-testing-baseline]] — the snapshot baselines that are the source of truth.
• [[mise-task-operations]] — the ops-task index this task belongs to.