Store Listing Images

This page covers how the Chrome Web Store images are produced: two scripts turn the real extension, running on made-up data, into upload-ready PNGs. Read it to rebuild the images after a UI change or to add one. The repo docs hold the full detail, and this page links to them instead of repeating them:

• Listing screenshots covers capturing the views, the sample data, and adding a capture.
• Listing image style sets the Web Store rules, colours, type, layouts, copy and the pre-upload checklist.

Pipeline

The images come from two stages, each a package script. Run them in order from the repo root:

pnpm screenshots   # writes out/screenshots/
pnpm showcase      # writes out/showcase/

1. scripts/capture-screenshots.ts builds the extension, loads it into headless Chromium, fills it with sample data and saves 7 views to out/screenshots/ at 1280 × 800 and 2× pixel density.
2. scripts/build-showcase.ts lays crops of those captures into HTML pages in the listing style, renders each page in Chromium, and saves 5 screenshots, a small promo tile and a marquee promo tile to out/showcase/, with alt text in alt-text.txt.

Both scripts use Playwright, which is a dev dependency. On a new machine, the first run can fail with "Executable doesn't exist"; run pnpm exec playwright install chromium once and rerun. out/ is in .gitignore, so the generated images never get committed. CI doesn't run either script.

Capture stage

The capture script calls WXT's build API for the Chrome build, then starts Chromium with .output/chrome-mv3 loaded through --load-extension and opens the extension's own pages (app.html#/… and popup.html). The script tests the real extension rather than a dev server with stubbed extension APIs. Every browser.* call works as it does for a user, and no capture code goes into src/. The scripts only cover Chrome: nothing builds or captures the Firefox add-on, so there are no addons.mozilla.org images.

Before capturing, the script's seed function writes the sample data straight into the extension's IndexedDB and localStorage:

• Screenshots. scripts/listing-samples.ts holds 4 invented web pages as HTML: an analytics dashboard, a docs site, a bakery and a task board. The script renders each at 1440 × 900 and stores the result as a screenshot with the page's title and URL. Every address in the samples uses the .example domain.
• Recordings. The script records an 8-second WebM of a pointer moving over the dashboard and stores it as 5 recordings with different dates and saved states. One has no duration, so Latest videos shows it as interrupted and recovered.
• Settings. The Record page shows Screen + camera and System + mic picked.

seed writes rows in the schema of src/lib/db.ts. It opens the database itself, with its own version number and stores, so those have to match db.ts too. When that schema changes, update seed in the same pull request, or the captures show empty or broken views. The seed writes no thumbnails: Latest videos makes them when it opens, as it does for a user.

Each view is an entry in the SHOTS array: a file name, the page to open, a ready locator to wait for, and optional prepare and element fields. The guide's Adding a screenshot section explains those fields and the workarounds in the editor shot.

Showcase stage

The IMAGES array in the showcase script sets each image's layout, headline, ticks, crops, highlighted element and alt text. Crops are in CSS pixels of the capture, half its pixel size. When a captured view's layout moves, update the crop in IMAGES, or the image shows the wrong part of the UI.

The script stops in two cases:

• A capture an image needs is missing from out/screenshots/. Run pnpm screenshots first.
• An output PNG has an alpha channel. The Web Store rejects those, so the script checks the PNG colour type on every image.

The script loads Inter from rsms.me, so build the images with a network connection. Offline, the headline falls back to the system sans-serif.

The colours, type and layouts appear twice: in the style reference and in the script's CSS. Change both together.

Updating the listing

After a UI change that shows in the listing:

1. Run pnpm screenshots and check the 7 captures in out/screenshots/.
2. If a view's layout moved, adjust its crop and highlight in IMAGES in scripts/build-showcase.ts.
3. Run pnpm showcase.
4. Work through the checklist in the style reference for each image.
5. Upload the PNGs from out/showcase/ with the alt text from alt-text.txt.

Never edit a captured image by hand. If a view needs different data, change the samples or seed and capture again.