shadowdao
8f42adc799
Completes the section-capture docs after merging main — capture-email.ts (Email page "Mail Client Setup") now appears alongside the other scripts. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
74 lines
3.7 KiB
Markdown
74 lines
3.7 KiB
Markdown
# Screenshot pipeline
|
||
|
||
Captures real WHP screenshots into `src/assets/screenshots/whp/`.
|
||
|
||
**Local-only. Never runs in CI.** CI builds the static site; it never opens a browser or hits WHP.
|
||
|
||
## Prerequisites
|
||
|
||
1. A demo WHP account (prod recommended for accuracy; staging works internally).
|
||
2. Network access to that WHP host.
|
||
3. Node 20+ and Playwright Chromium installed: `npx playwright install chromium`.
|
||
|
||
## Configure
|
||
|
||
Create `tools/screenshots/.env` (gitignored):
|
||
|
||
```
|
||
WHP_BASE=https://whp01.cloud-hosting.io:8443
|
||
WHP_USER=demo-kb
|
||
WHP_PASS=…
|
||
```
|
||
|
||
The script reads these via `process.env`; pass them in your shell or use a `.env` loader like `dotenv-cli`.
|
||
|
||
## Run
|
||
|
||
```bash
|
||
# Load .env into your shell (one option):
|
||
set -a; source tools/screenshots/.env; set +a
|
||
npm run screenshots
|
||
```
|
||
|
||
Outputs one PNG per entry in `shots.config.ts` to `src/assets/screenshots/whp/<id>.png`. Existing files are overwritten.
|
||
|
||
## Capture rules
|
||
|
||
- **Viewport: 1440×900.** Locked. No `fullPage`. Playwright's viewport screenshots never include browser chrome — no address bar, no tab strip.
|
||
- **Mask list:** defaults (account ID, server hostname, user IP, billing column) plus per-shot additions.
|
||
- **No address bar in any image.** Multi-server fleet — we don't want a specific host in any screenshot.
|
||
- Use `selector` to clip to a region (e.g., just the sidebar) when the full viewport is noisier than useful.
|
||
|
||
## Refresh workflow
|
||
|
||
UI changed? → run the capture (see below) locally → review the diffs (`git diff --stat` shows changed PNGs) → **open each changed PNG and eyeball it for accidental leakage** (server hostname, IP, account ID, customer domains/usernames) → commit → push.
|
||
|
||
- **A page covered by `shots.config.ts`** (a plain navigate-and-shoot page): `npm run screenshots`.
|
||
- **A page that needs interaction** — opening a modal, ticking checkboxes, switching tabs — lives in a **section capture script** (see below). Re-run that script instead.
|
||
|
||
When a section is *reworked* (not just restyled), also: re-walk the new UI to find every state worth a screenshot, update the section script's steps, add/rename the `whp-<section>-*` ids, then refresh the `.mdx` references and run `npm run build` to confirm links and images resolve.
|
||
|
||
## Section capture scripts
|
||
|
||
`shots.config.ts` + `run.ts` only do navigate → redact → screenshot. Anything that needs **interaction or per-section redaction** gets its own `capture-<section>.ts`, run directly with `tsx`:
|
||
|
||
```bash
|
||
set -a; source tools/screenshots/.env; set +a
|
||
npx tsx tools/screenshots/capture-dns.ts
|
||
```
|
||
|
||
| Script | Covers | Auth |
|
||
| --- | --- | --- |
|
||
| `capture-admin.ts` | Server Settings tabs, admin pages | `WHP_ADMIN_USER` |
|
||
| `capture-site-builder.ts` | Site Builder editor states | `WHP_USER` |
|
||
| `capture-dns.ts` | Domains & DNS list, Add Domain modal, records editor, bulk toolbar | `WHP_USER` |
|
||
| `capture-email.ts` | Email page "Mail Client Setup" section (autodiscovery DNS records) | `WHP_USER` |
|
||
|
||
Each script carries its own `redact()` (text-node + input-value swaps) so fleet hostnames, IPs, and customer data become neutral placeholders while brand/demo domains stay visible. Copy the closest existing script when adding a new section — match its viewport (1440×900), `deviceScaleFactor: 2`, and **read-only** discipline (open modals and tick boxes for the shot, but never save/delete/submit).
|
||
|
||
## Adding a new shot
|
||
|
||
1. **Static page?** Add an entry to `shots.config.ts` with a stable `id`, then `npm run screenshots`.
|
||
2. **Interactive state?** Add the step to the relevant `capture-<section>.ts` (or copy one for a new section), then `npx tsx tools/screenshots/capture-<section>.ts`.
|
||
3. Reference the new file in your `.mdx`: ``.
|