# Voyage playground screenshot convention (v4.3)

This directory holds reference screenshots for the Voyage playground
(`playground/voyage-playground.html`). They serve as a visual baseline for
manual review of design changes and as fixtures for the Wave 7 axe-core
Playwright spec (`tests/e2e/voyage-playground-a11y.spec.mjs`).

Screenshots are NOT auto-committed. The `tests/e2e/snapshots/` directory
(produced by Playwright in Wave 7) is the test-baseline; this directory
holds curated illustrative captures for documentation.

## Mappestruktur

```
docs/screenshots/
  README.md                ← this file
  dashboard/               ← project-dashboard fleet-grid views
  artifact-detail/         ← drill-down render of brief/plan/review
  annotation/              ← gutter-badge + sidebar + active highlight states
  dark-mode/               ← screenshots taken with html[data-theme="dark"]
  light-mode/              ← screenshots taken with html[data-theme="light"]
```

Each subfolder contains PNGs named by feature + variant, e.g.
`dashboard/fleet-grid-with-progress-tile.png`,
`annotation/active-anchor-yellow-tint.png`.

## Hooks (window.__voyage)

The playground exposes three automation hooks for headless screenshot
scripts. They are namespaced under `window.__voyage` to avoid global
pollution:

| Method | Purpose |
|--------|---------|
| `window.__voyage.navigate(surface)` | Switch surface. `surface ∈ ['dashboard', 'detail', 'render', 'a11y']` |
| `window.__voyage.scheduleRender(state)` | Pre-populate state. `state.markdown` triggers `mountRender`; `state.artifacts` triggers `renderDashboard` |
| `window.__voyage.getProjectArtifacts()` | Returns the last-loaded `ProjectArtifacts` object (or `null`) |

The hook surface mirrors the pattern used in
`plugins/llm-security/playground/llm-security-playground.html`
(`window.__navigate`, `window.__scheduleRender`).

## Producing screenshots — Playwright headless (Wave 7+)

Wave 7 ships a Playwright spec
(`tests/e2e/voyage-playground-a11y.spec.mjs`). Reuse its setup for
screenshots:

```js
// tests/e2e/snapshot-helper.mjs (NOT committed in v4.3 — illustrative)
import { test } from '@playwright/test';

test('dashboard with all artifacts', async ({ page }) => {
  await page.goto('file://' + process.cwd() + '/playground/voyage-playground.html');
  await page.evaluate(() => {
    window.__voyage.scheduleRender({
      artifacts: {
        basePath: 'demo',
        brief: { path: 'brief.md', content: '...' },
        plan:  { path: 'plan.md',  content: '...' },
        review: null,
        research: [],
        architecture: { overview: null, gaps: null, looseFiles: [] },
        progress: null,
        looseFiles: [],
      }
    });
  });
  await page.screenshot({ path: 'docs/screenshots/dashboard/fleet-grid-demo.png' });
});
```

## Producing screenshots — manuelt

1. Åpne `playground/voyage-playground.html` i Chrome/Firefox.
2. Hvis du trenger et bestemt UI-state, paste relevant artifact-innhold i
   textarea og trykk Render.
3. macOS: `Cmd+Shift+4`, deretter `Space` for vindu-skjermbilde.
4. Lagre med beskrivende filnavn under riktig undermappe ovenfor.

## Konvensjon for nye screenshots

- Bruk PNG, ikke JPG (lossless for tekst-tunge UIer).
- Kjør i konsistent viewport (1280×800 anbefales for desktop-baseline).
- Ta dark- og light-mode-varianter parvis når komponenten har visuelle
  forskjeller mellom temaene.
- Ikke commit screenshots med personidentifiserende info eller hemmelig
  artifact-innhold.