feat(voyage): implement screenshots-spor convention (window.__hooks + docs/screenshots/)

plugins/voyage/docs/screenshots/README.md

@@ -0,0 +1,89 @@
+# 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.