/store-assets: Store Screenshots from Code

Generates store-ready stills from a project's own app screens and a project-local config (.store-assets/store-assets.json). Pattern follows screens/: this SKILL.md orchestrates, bin/*.mjs is deterministic, references/*.md holds specs and schema, templates/ holds the rendering surface. No brand values live in this skill; everything (fonts, colors, background, logo, headlines, pills) comes from the target project's config. Device bezels and status-bar overlays are real assets (references/store-specs.md "Devices"), cached once per machine, not downloaded or generated by the skill itself.

Ablauf

1. Config lesen. Read <project>/.store-assets/store-assets.json. Missing file: report and stop (nothing to render). Schema: references/config-schema.md.
2. Headlines-Gate. Every scene's headline/subline per locale needs reviewed: true with a reviewed_hash (SHA-256 of headline + subline, bin/lib.mjs's reviewedHash()) matching the current text. render.mjs's pre-flight reports which scenes are unreviewed (an INFO line, not a failure: Muster-Gate below still renders unreviewed text for preview); only validate.mjs blocks on it (Gate 1 in the store-assets plan).
3. Muster-Gate. Before a full render across every scene/locale/format, render one representative sample (--scene <id> --format <id> --locale <code>) and show it next to the project's previous store images for a look-and-feel approval (Gate 2).
4. Vollrender. bin/render.mjs --project <path> (no filters) renders every scene x locale x format into <project>/native/store-assets/generated/<format>/<locale>/<id>.jpg (play-feature renders once per locale from the config's first/hero scene, see references/config-schema.md), plus a static contact-sheet generated/index.html (a grid grouped by format/locale).
5. Validator. bin/validate.mjs --project <path> checks exact pixel dimensions, no alpha channel, sRGB profile, file size, per-format image counts, and that every rendered scene is reviewed: true with a matching hash. Exit 0 only when every check passes.
6. Video (Meilenstein B, not built). templates/preview.html and bin/render-video.mjs do not exist yet (docs/plans/2026-09-27-store-assets-skill.md Step 10). Stills are the whole deliverable for now.

Before any full render, check references/store-specs.md's Stand date: if it is older than 6 months, re-verify the sizes against the source URLs there before trusting them.

Runtime

Playwright: the target project's own playwright/@playwright/test devDependency always wins (any installed version, no pin comparison). Only when the project has neither, fall back to npx -y playwright@<pinned version, see references/store-specs.md> plus npx playwright install chromium with PLAYWRIGHT_BROWSERS_PATH=~/.cache/store-assets/browsers (only when that cache does not already have the browser -- never re-download it, and never install a Chromium copy under this skill's own directory or the project's node_modules). ImageMagick's magick (used to sample a source screenshot's own top pixel color, references/store-specs.md "Devices") is assumed already installed, not managed by the skill.

Layout

Every portrait format (ios-6.9, ios-ipad-13, play-phone) renders the same fixed three-band grid, no panorama, no per-format layout branch:

• Text zone, 0-30% of the canvas height. The headline/subline/pills block itself centers inside the inner 7-30% (7% top breathing room). Headline ceiling 0.12 * canvas width, subline ceiling 0.048 * canvas width; both shrink in 4px steps (down to a 40px floor) if the block overflows that inner box vertically, or if a single line overflows horizontally (a hyphenated word's no-wrap span can force this even when the box still fits otherwise).
• Gap, 30-40%. Empty.
• Image zone, 40-100%. A layout: "single" scene's device sits with its top edge at exactly 40% of the height and runs off the bottom edge, same as a plain screenshot mockup. A layout: "combo" scene (two phones, the hero so far) instead binary-searches the largest scale -- measured live via getBoundingClientRect, not derived analytically, so it adapts to any device kind/canvas aspect -- that keeps both phones' left/right edges within a side margin (>=5% of the width) and the back phone's own visible height (clipped by the canvas edge) at >=35% of its rendered width; the pair may run off the canvas bottom like a single-device scene, and is centered horizontally in the margin zone. Device choice follows the store format, not the scene: ios-6.9 -> iPhone bezel, play-phone -> Android/Pixel bezel (bin/render.mjs's DEVICE_BY_FORMAT). iPhone bezel color follows the scene's own background hex (IPHONE_COLOR_BY_BG: navy #04081f -> Silver, light #f7f7f7 -> Black, brand-red #e0452f -> Glacier); a combo scene's own ios_color per phone overrides that. Android has no bezel color variants.
• ios-ipad-13 (2064x2752) uses the same grid but a frameless device: the iPad screenshot as a rounded rectangle with a shadow, no bezel/status bar (ipad in references/store-specs.md "Devices"). Sources come from the scene's source_ipad; a combo scene renders only its front part's source_ipad as a single device (references/config-schema.md). Device width and top edge default to 80% / 40% and can be set per project (format_options) or per scene (ipad_width_pct, ipad_top_pct), see references/store-specs.md "iPad overrides".
• ios-ipad-13-landscape (2752x2064, optional) is the same frameless iPad in a landscape canvas (defaults 62% / 34%, whole screenshot visible). It renders only for scenes whose formats list includes it; an iPad-only scene ("formats": ["ios-ipad-13-landscape"]) needs source_ipad but no iPhone source. Add the format to the config's formats first.
• play-feature (landscape, 1024x500) is not part of this grid: logo + headline only (no subline, no device) in the left ~55-70% column, and optionally one device on the right (the hero's own front phone, Pixel-framed, sized off canvas height) when the hero scene is combo.

Device frames are real bezel PNGs + real status-bar capture overlays (references/store-specs.md "Devices"), sourced from a project's own screenshots via crop_top_px (hides that source screenshot's own page header/status bar, backfilled with its own sampled top color) -- not CSS-drawn approximations.

Edge Cases

• Source PNG missing for a locale/theme, or a bezel/status-bar/mask asset missing from the cache: pre-flight in render.mjs fails before any render, lists every missing path.
• A font fails to load (document.fonts.check): abort, no silent fallback font in the output.
• Headline (or a single line of it) too long for its box: shrinks in 4px steps to a 40px floor; below that, still renders (no hard error), since a floor that low is already a copy problem to fix, not a render-time one.
• Headline or subline text changed after Gate 1 approval: reviewed_hash no longer matches -> reviewed is treated as false -> validator fails.
• The ASCII apostrophe (') renders as a detached mark with a gap in some display fonts (Holdstone): both headline and subline text are normalized to the typographic ' (U+2019) first; if the headline font itself lacks that glyph (checked live via document.fonts.check, never assumed), only that character renders in the subline font instead, inside its own span.
• Chromium not cached and no network: stop with the exact install command (npx playwright install chromium), do not attempt a partial render.

References

• references/config-schema.md — every store-assets.json field, including layout: combo's front/back parts and the CLI flags (--background, --out).
• references/store-specs.md — exact store sizes, formats, limits, source URLs, the device bezel and status-bar asset spec (paths, screen rects, provenance), HyperFrames version, Playwright pin.
• CLAUDE.md (this skill's own, next to this file) — commands, cache-rebuild pointer, gotchas.