Store Listing Carousel

Store Listing Carousel

Maintains the two Apk Analyzer Play Store screenshot carousels — docs/store/graphics/carousel_template.html (light) and carousel_template_dark.html (dark) — each a single self-contained HTML file with 8 phone-frame "slides." Every frame shows a real app screenshot behind a styled device frame, with a themed background, a headline, and a shared "skyline" motif (rounded-arch + antenna dots, derived from the app icon) that ties all frames into one visual system.

This skill covers two independent workflows that share the same templates but don't depend on each other — run either one without the other:

• Editing: swap new device screenshots into the templates (crop → verify color → embed → QA). It never touches phone-screenshots/.
• Exporting: render whatever the templates currently show into individual PNGs at docs/store/graphics/phone-screenshots/{day,night}/, ready for Play Store upload. It's read-only against the templates — it never edits them, and doesn't require having just run the edit workflow first.

Both files render at CSS scale (.frame is 360×640) — that's a review resolution, not the upload resolution produced by the export workflow.

Before touching anything

Read the template(s) being updated and confirm the current frame count and order:

grep -n '<!-- FRAME' docs/store/graphics/carousel_template.html

The <!-- FRAME N — Name --> HTML comments are the only order marker in the file (there are no on-canvas debug labels — those were stripped from the shipped version and shouldn't be reintroduced unless the user explicitly asks for them). Keep the comments sequential and accurate whenever you add, remove, or reorder a frame — a previous edit left them out of order (1,2,3,4,4, 6,4,5), which silently broke the invariant this skill relies on; that's now fixed, so don't reintroduce the drift.

Do not restructure the shared CSS system (.frame, .device, .screen, .skyline, .headtext, theme classes) unless asked. The job is almost always: swap screenshots in, keep everything else.

The 8-frame map

Current locked structure for both templates. Preserve this order and theme unless the user asks to change it — Play Store allows up to 8 screenshots, and this set is already at that cap.

Each frame's screenshot is embedded via:

<img class="real-shot" src="data:image/png;base64,<...>" alt="<descriptive alt text>">

Target a specific frame for replacement by matching on alt, not on position in the file — edits can reorder frames, and alt is the stable identifier.

Workflow A: Editing — swap in a new batch of screenshots

Do the light and dark templates as two separate passes. They take different source screenshots (light-mode vs. dark-mode device captures) and a different .screen background (#f7f7f7 vs. #000000) — don't reuse a light-mode crop in the dark file or vice versa.

This environment has no Python/PIL and no ImageMagick (convert on PATH resolves to the Windows disk-conversion utility, not ImageMagick) — every step below uses PowerShell's built-in System.Drawing, which needs no install.

1. Collect and sanity-check the screenshots

Confirm you have one screenshot per frame you're updating (up to 8), and check resolution consistency:

Add-Type -AssemblyName System.Drawing
Get-ChildItem new_*.png | ForEach-Object {
    $img = [System.Drawing.Image]::FromFile($_.FullName)
    "$($_.Name): $($img.Width)x$($img.Height)"
    $img.Dispose()
}

If resolutions differ from the previous batch, the crop height (next step) must be re-verified — don't reuse a prior crop value blindly.

2. Determine the status-bar crop height

Status bar height varies by device skin, font size, and OS version — never assume a fixed pixel value from a prior session. Read one raw screenshot directly with the Read tool to eyeball it, or cut a top strip first if you need a closer look:

Add-Type -AssemblyName System.Drawing
$src = [System.Drawing.Image]::FromFile("new_frame1.png")
$strip = New-Object System.Drawing.Bitmap($src.Width, 220)
$g = [System.Drawing.Graphics]::FromImage($strip)
$rect = New-Object System.Drawing.Rectangle(0, 0, $src.Width, 220)
$g.DrawImage($src, $rect, $rect, [System.Drawing.GraphicsUnit]::Pixel)
$strip.Save("_status_bar_check.png")
$g.Dispose(); $strip.Dispose(); $src.Dispose()

Then Read _status_bar_check.png and read off where the status bar icons end and real content (back arrow, title, etc.) begins. Re-verify per batch — don't assume a value from a previous session still holds for a different device skin or OS version.

3. Crop every screenshot and sample the background color

Add-Type -AssemblyName System.Drawing
$cropTop = 140  # <- set from step 2

Get-ChildItem new_*.png | ForEach-Object {
    $src = [System.Drawing.Image]::FromFile($_.FullName)
    $h = $src.Height - $cropTop
    $bmp = New-Object System.Drawing.Bitmap($src.Width, $h)
    $g = [System.Drawing.Graphics]::FromImage($bmp)
    $srcRect = New-Object System.Drawing.Rectangle(0, $cropTop, $src.Width, $h)
    $dstRect = New-Object System.Drawing.Rectangle(0, 0, $src.Width, $h)
    $g.DrawImage($src, $dstRect, $srcRect, [System.Drawing.GraphicsUnit]::Pixel)
    $bmp.Save("cropped_$($_.Name)")
    $halfWidth = $src.Width / 2
    $px = $bmp.GetPixel([int]$halfWidth, 5)
    "{0} -> {1}x{2}  #{3:X2}{4:X2}{5:X2}" -f $_.Name, $src.Width, $h, $px.R, $px.G, $px.B
    $g.Dispose(); $bmp.Dispose(); $src.Dispose()
}

Check that every sampled color matches (they should all be identical — either the light #f7f7f7 background token or the dark #000000 token, per ApkAnalyzerColorPalette in Color.kt). If one screenshot samples differently, that screen likely has a non-standard top background (e.g. a colored app bar) — flag it to the user rather than silently forcing a mismatched gap color.

4. Update the notch-gap and screen background to match

.screen sets the base background and .real-shot is absolutely positioned with a fixed top:30px gap so the device notch never overlaps real content:

.screen{ background:#f7f7f7; /* or #000000 for dark */ ... }
.real-shot{
  position:absolute; top:30px; left:0;
  width:100%; height:calc(100% - 30px);
  object-fit:cover; object-position:top center;
}

If switching between light/dark or onto a new palette, update .screen's background to the sampled color from step 3 — do not leave it mismatched, even by a shade, or the notch gap will show a visible seam.

5. Base64-encode and embed by alt-text match

Keep referencing images by relative file path out of the templates — a self-contained HTML file stays reviewable in a browser or an Artifact without carrying sibling image files alongside it in the repo, and it's how the two templates already ship. Always inline as base64:

$templatePath = "docs/store/graphics/carousel_template.html"  # or carousel_template_dark.html
$html = Get-Content -Raw $templatePath

$altToFile = @{
    'App report overview'                  = 'cropped_new_frame1.png'
    'Search and filter apps'               = 'cropped_new_frame2.png'
    'Permissions audit'                    = 'cropped_new_frame3.png'
    'Browse by attribute'                  = 'cropped_new_frame4.png'
    'Certificate details and fingerprints' = 'cropped_new_frame5.png'
    'Raw AndroidManifest.xml'              = 'cropped_new_frame6.png'
    'On-device AI summary'                 = 'cropped_new_frame7.png'
    'Export and share actions'             = 'cropped_new_frame8.png'
}

$pattern = '(?s)(<img class="real-shot" src="data:image/png;base64,)([^"]+)(" alt="([^"]+)">)'
$evaluator = {
    param($m)
    $alt = $m.Groups[4].Value
    if ($altToFile.ContainsKey($alt)) {
        $bytes = [IO.File]::ReadAllBytes($altToFile[$alt])
        $b64 = [Convert]::ToBase64String($bytes)
        return $m.Groups[1].Value + $b64 + $m.Groups[3].Value
    }
    return $m.Value
}
$html = [regex]::Replace($html, $pattern, $evaluator)

[IO.File]::WriteAllText($templatePath, $html, (New-Object System.Text.UTF8Encoding($false)))

Only frames present in $altToFile get touched — everything else in the template (headlines, themes, untouched frames) is preserved exactly. Write with a BOM-less UTF8Encoding explicitly — Set-Content/Out-File in Windows PowerShell 5.1 don't reliably round-trip the file's emoji and unicode punctuation otherwise.

6. Reconcile theme colors against the new screenshots (if content changed)

If a screenshot's own accent color changed (e.g. a redesigned AI-summary card, a new brand color), update the surrounding frame theme to match it rather than leave it clashing. Re-read Color.kt for the current tokens rather than trusting a cached value — this table was correct as of the last verification, but the source file is canonical:

Light: primary #006766 · primaryContainer #B2EBEA · secondary #607C7B · tertiary #894C2D / #FFDBC9 · aiAccent #7C4DFF / #EDE7FE

Dark: primary #86D4D2 · primaryContainer #1A3F3E · secondary #607C7B · aiAccent #B39DFF / #2E2251

The AI Summary frame (theme-violet) in particular must use the dark aiAccent tokens when showing a dark-mode screenshot — using the light-mode violet next to a dark-mode purple card reads as two different, clashing purples.

7. QA before calling it done

Open the updated HTML in a browser and check, per frame:

• No visible seam between the notch gap and the screenshot's real background
• Headline text (max 2 lines) doesn't overlap the device frame
• Cropped screenshot didn't lose the specific content the frame is meant to prove (e.g. don't let a top-anchored crop cut off the one stat that sells the frame — check object-position isn't hiding it)
• Exactly 8 frames total (or fewer, never more — Play Store's hard cap)
• Status bar clocks/times are gone from every frame (cropped in step 3)
• <!-- FRAME N --> comments are still sequential 1–8 after any reorder

The finished files are already in their real location (docs/store/graphics/) — there's no separate delivery step. Tell the user which frames changed and in which of the two templates.

Workflow B: Exporting — render frames to upload-ready PNGs

Purely reads the templates and writes PNGs — never edits carousel_template.html or carousel_template_dark.html. Output goes to docs/store/graphics/phone-screenshots/day/ (from the light template) and .../phone-screenshots/night/ (from the dark template), one file per frame, named from the 8-frame map's slug: 01-app-report.png, 02-search-filter.png, 03-permissions.png, 04-browse-attribute.png, 05-certificates.png, 06-manifest.png, 07-ai-summary.png, 08-export-share.png.

Target format (Play Store phone screenshot requirements): PNG, ≤8 MB, 9:16 or 16:9 aspect ratio, each side between 320 px and 3,840 px. The frames are natively 9:16 (360×640 at CSS scale), so this falls out automatically as long as you scale both dimensions together — never crop to force the ratio.

This environment has no headless HTML-to-PNG renderer (no Puppeteer/Playwright, no ImageMagick — convert on PATH resolves to the Windows disk-conversion utility, not ImageMagick) and no Python/PIL. Rendering goes through the claude-in-chrome browser tools plus PowerShell's built-in System.Drawing for the pixel work — load the chrome tools once via ToolSearch("select:mcp__claude-in-chrome__tabs_context_mcp,mcp__claude-in-chrome__navigate,mcp__claude-in-chrome__computer,mcp__claude-in-chrome__javascript_tool,mcp__claude-in-chrome__browser_batch,mcp__claude-in-chrome__tabs_create_mcp,mcp__claude-in-chrome__tabs_close_mcp") before starting.