# 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`: `![Alt text](~/assets/screenshots/whp/<id>.png)`.
