Skip to content
ArchTect Docs

Regenerating Doc Screenshots

Every screenshot in this documentation site is generated by a Playwright script, not captured by hand. This keeps them reproducible and lets them be regenerated whenever the UI changes.

Running it

Section titled “Running it”
Terminal window
cd frontend
npm run docs:screenshots

This starts the Vite dev server itself, runs every scenario in the manifest against it, writes PNGs into docs/images/screenshots/<section>/, and shuts the server down when done. No dev server needs to be running beforehand — if one already is, stop it first (the script binds its own on port 5173).

To run a subset:

Terminal window
npm run docs:screenshots -- --scenario=landscape-overview
npm run docs:screenshots -- --scenario=landscape-overview,dsl-editor

How it works

Section titled “How it works”

The script (frontend/scripts/docs-screenshots.ts) drives headless Chromium through a small, reusable action vocabulary — openDslTab, pasteDsl, save, clickTab, selectElement, openLeftPanel, openViewFromPanel, screenshot, screenshotElement, screenshotClip, and a few others. Each documentation scenario is a named list of these actions plus an output path.

Two things about the app’s behavior matter for writing new scenarios:

  • Pasting DSL doesn’t render until you save. The sequence is: open the DSL tab, select-all and replace its content, then press Ctrl+S — that’s what actually triggers a parse and re-render, not the paste itself.
  • DSL-authored views don’t automatically become the open tab. A systemContext/container/etc. block in your views { } section shows up in the Views panel (tagged DSL, alongside AUTO auto-generated views of the same scope) — you have to open it from there.

Fixtures

Section titled “Fixtures”

Most scenarios reuse frontend/tests/fixtures/smart-city-iot.dsl, a rich reference model, so screenshots show a realistic, populated workspace rather than an empty canvas. A few scenarios use small, purpose-built fixtures under frontend/tests/fixtures/docs/ when a simpler or more specific model reads better for a given page (e.g. the Getting Started tutorial’s exact DSL, or a minimal AWS-theme example).

Adding a new screenshot

Section titled “Adding a new screenshot”
  1. Add a fixture under frontend/tests/fixtures/docs/ if the existing ones don’t fit.
  2. Add a scenario to the scenarios array in frontend/scripts/docs-screenshots.ts, giving it a unique name and an out path under docs/images/screenshots/.
  3. Run it in isolation (--scenario=your-name) and inspect the output before wiring it into a page.
  4. Reference it in the relevant .md file with a normal Markdown image link.

See also

Section titled “See also”