# Theme screenshots

Screenshots of a block theme's templates at 1440, 782 and 480px, for reviewing new themes. The Theme Screenshots workflow runs this on any PR that adds a new block theme and publishes the result to https://theme-screenshots.space.fast/<slug>/, which the `/theme-review` reviewer checklist links to.

- `capture.sh <slug> <out-dir>` starts WordPress Playground with the theme and the content in `fixture/`, then runs `capture.cjs` (Playwright). Each screenshot is saved as WebP (a page taller than 16,383px, WebP's limit, stays a PNG) and labelled with the template that rendered it. The gallery lists the theme's templates that no screenshot shows.
- `publish.sh <slug> <out-dir> [note]` builds the gallery page (`gallery.cjs`) and publishes it to the Theme Screenshots space on Spacefast. The space keeps the 11 most recently updated themes (about 4 to 7 MB each, so roughly 75 MB; the free plan has 500 MB). With the text cell that makes four full rows of three on the front page. Each publish replaces the whole site with the new gallery plus copies of the 10 newest other galleries, so older ones are removed. The front page is a grid of the themes, each shown with its own `screenshot.png` or `.jpg`. With `PR_NUMBER` set, the gallery links to the workflow's Run workflow page: enter the PR number there to take new screenshots without a push, or, for a theme already merged, leave it empty and enter the theme folder name to capture it from trunk (PRs from forks are refused, since the job holds the Spacefast key). Only one screenshot run works at a time, across all PRs: the next one waits, so two publishes never overlap. If a third run arrives while one is waiting, it replaces the waiting one, and that PR needs a push or Regenerate. CI uses the `SPACEFAST_TOKEN` secret, a "CI publish" key of the Theme Review CI team, which holds only this space.

To run it locally, from the repo root:

```bash
PLAYWRIGHT_PATH=$PWD/node_modules/playwright SHARP_PATH=/path/to/node_modules/sharp bash .theme-utils/screenshots/capture.sh <slug> /tmp/shots/<slug>
```

Set `CHROME_PATH` when Playwright's own browser download doesn't match the installed version. `SHARP_PATH` points to the `sharp` package, which the repo doesn't install (`npm install --prefix /tmp/pw sharp`).

## Fixture

`fixture/setup.php` creates 11 posts (edge cases such as a long title, no title and a long word, then the block tests), a page, and one page per custom template in `theme.json`. The single post and the pages use `content/alignments.html`: default, wide and full images, and left and right floats.

The Reading setting depends on the theme. A theme with `front-page.html` shows it on the homepage whatever the setting is, so the site uses a static homepage and a Blog page at `/blog/`, and `home.html` or `index.html` shows there. Any other theme gets "Your latest posts", as a new site does, so `home.html` or `index.html` shows on the homepage.

A theme with WooCommerce templates also gets WooCommerce, its sample products (`sample-data/sample_products.csv` in the plugin, with images from WooCommerce's demo site) and one order (`fixture/store.php`). The shots then add the shop, a product category, product search, each product type, the cart (empty and with a product), checkout, the order confirmation, My account and Coming soon.

`fixture/mu-plugins/theme-screenshots.php` tells `capture.cjs` how the site is set up (`/?shot-info`) and which template rendered each page (the `X-Shot-Template` header).

Image credits: the photos are from Unsplash (Unsplash License) by Oleg Laptev, Lea L, Sarah Dorweiler, Jakub Dziubak and Sumner Mahaffey. `default-scaled.jpg`, `wide-scaled.jpg` and `full-scaled.jpg` are plain grey placeholders with a text label.
