@verbb/docs-screenshots

Reusable Craft control panel screenshot automation for plugin docs.

This package provides:

• disposable Craft install bootstrapping
• compose-backed runtime
• preview and capture workflows
• generic target handling such as selector, clip, and anchoredClip
• generic screenshot presets and typed scenario definitions

What Lives Here

The shared package should own:

• the screenshot CLI
• Craft/bootstrap/runtime orchestration
• Docker compose setup
• generic preview and capture handling
• shared target types and typed scenario APIs
• generic presets that are not tied to one plugin

Plugin-specific setup should stay in the plugin repo.

Recommended Plugin Structure

Each plugin should keep its own screenshot implementation details under docs/.screenshots/.

Typical split:

• docs/.screenshots/global.profile.ts
• docs/.screenshots/plugin.bootstrap.ts
• docs/.screenshots/<plugin>/fixtures.ts
• docs/.screenshots/<plugin>/presets.ts
• docs/**/*.screenshot.ts

This keeps the engine reusable while letting each plugin define its own seeded state, UI cleanup, and screenshot composition.

Runtime Model

The screenshot harness is designed around a disposable Craft install and disposable database.

Expected flow:

1. Create or reuse a temporary Craft app.
2. Install the plugin from the local working copy.
3. Seed deterministic CP state for the target scenario.
4. Open the control panel with Playwright.
5. Preview or capture the requested target.

The runtime expects a dedicated database server via CRAFT_SCREENSHOT_DB_* env vars, and Playwright Chromium should be installed once with:

npx playwright install chromium

Workflow

The intended authoring loop is:

1. Prepare a reusable install once.
2. Preview a single screenshot repeatedly while adjusting the scenario.
3. Capture the final image once the framing is correct.

Typical commands from a plugin repo:

npm run docs:screenshots -- prepare
npm run docs:screenshots -- preview --reuse-install last --filter form-builder
npm run docs:screenshots -- capture --reuse-install last --filter form-builder

Useful flags:

• --reuse-install last reuses the most recently prepared Craft install.
• --inspect <id> opens the scenario in Playwright Inspector.
• --headed runs visibly without enabling full debug behavior.
• --save-from-preview saves the currently previewed framing.
• --keep-install preserves the temporary install for manual reuse.

Targets

The engine supports a few capture styles:

• page
• selector
• clip
• anchoredClip

anchoredClip is especially useful when a UI region needs manual pixel framing but still has to stay attached to a moving parent element.

Presets

The shared package should expose only generic presets.

Examples:

• CP focused region
• CP modal
• CP detail view
• full CP viewport

If a plugin needs extra cleanup rules or DOM-specific tweaks, those should be wrapped in plugin-owned presets rather than added to the shared package directly.

Notes

• Scenario files should live beside the docs pages they support.
• Generated screenshots should usually be committed assets, not rebuilt on every docs run.
• If Craft changes global CP structure, fix the shared runtime or generic presets once.
• If a specific plugin changes its own UI structure, fix that plugin’s fixtures or presets locally.