Screenshots¶

Every screenshot of the guide is taken from the real application by one script, on a fresh demo world, in a light and a dark variant. Nothing is captured by hand, so the whole set can be retaken in one command when a screen changes, and every image carries the metadata needed to retake it alone.

Where things are¶

A scene is a data record in the script: a name, a caption, the persona signed in, the URL, the viewport, an optional action performed after the page loaded (a click, a keystroke, a typed word) and the phase of the demo world it needs. The manifest is derived from that list at the end of a run and adds the date, the commit and the base URL. To add or change a screenshot, edit the scene in the script, never the manifest.

How a page shows an image¶

A screenshot taken in one palette looks wrong in the other, so a page embeds both variants, each with a fragment naming its palette:

<figure markdown="span">
  ![The courses page](../assets/screenshots/teacher-home-light.png#only-light)
  ![The courses page](../assets/screenshots/teacher-home-dark.png#only-dark)
  <figcaption>The courses page: one card per course.</figcaption>
</figure>

The fragment is not part of the file name: the browser requests teacher-home-light.png and the theme's stylesheet hides the image whose fragment does not match the active palette, so the reader sees exactly one of the two, and switching the palette swaps it in place. Write the same alt text on both lines; only one is ever visible.

Regenerating¶

The script needs an isolated instance of the API, serving the built single-page application on a seed of its own. It must never run against the pnpm dev you work with: the phases below move the demo world forward, and PGlite is single-process. The header comment of the script spells out the procedure; in short:

pnpm --filter @quiz/web build
cd apps/api
export DATABASE_URL=pglite://.data/pglite-docs ASSETS_DIR=.data/assets-docs
export PORT=3100 PUBLIC_URL=http://localhost:3100 AUTH_DEV_LOGIN=1
export STATIC_DIR=$PWD/../web/dist RUNNER_MODE=http RUNNER_URL=http://localhost:3200
export LLM_PROVIDER=stub                               # the essays' AI proposals
pnpm seed                                              # PGlite: before the API
pnpm exec tsx --env-file-if-exists=../../.env src/server.ts &
curl localhost:3100/healthz                            # database up, runner up
cd ../..
pnpm docs:screenshots                                  # everything, both themes

The code runner on port 3200 is optional. Without it, the code, code-to-picture and circuit questions are graded with a proposal marked as runner unavailable, which is what the grading scenes then show. The stub LLM provider is not: without LLM_PROVIDER=stub on BOTH the seed and the instance, the essays of "Test 0" are 0-point placeholders and the grading-essay and grading-batch scenes lose their AI proposals (the instance re-proposes them when a scene reruns the grading pass).

One scene, or one theme, can be retaken alone. The manifest is merged, not rewritten:

pnpm docs:screenshots -- --list
pnpm docs:screenshots -- --only=grading-code
pnpm docs:screenshots -- --only=poll --dark

The phases¶

The script walks the demo world through one-way phases and takes the scenes of each phase before moving on. The light and dark variants of a scene are captured back to back, so they show the same state.

A scene that needs an earlier phase than the instance is in, such as the lobby once the exercise has started, needs a fresh seed: stop the instance, delete apps/api/.data/pglite-docs, seed and start again.

Every scene¶

The table is rewritten from the manifest at the end of each run. Paths contain the identifiers of that run's seed; the script discovers them over the API, so they change from one seed to the next.

Last full run: 2026-10-14, commit 75d362c1, 76 scenes.