From 12637f3dbd0a344e5129308c058e225de9e04621 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Sun, 10 May 2026 18:25:37 +0200 Subject: [PATCH] docs(voyage): write playground/README.md with v4.3 architecture + URL-parameter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Step 32 of v4.3 plan — Wave 8 docs: - v4.3 dashboard-sentrisk arkitektur (fleet-grid + drill-down) - Bruksveier: webkitdirectory-velger, drag-drop, URL-parameter ?project= - Discoverability for .claude/projects/ (open/xdg-open/explorer) - Annotation-flow + window.__voyage hooks - Begrensninger (FF150-Win, no FSA, design/ out-of-scope, baseline'd WCAG) - Bundle-strrelse breakdown - Test-suite oversikt (Groups A-D) NEW file (eksisterte ikke i v4.2 per plan-critic finding 13). --- plugins/voyage/playground/README.md | 136 ++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 plugins/voyage/playground/README.md diff --git a/plugins/voyage/playground/README.md b/plugins/voyage/playground/README.md new file mode 100644 index 0000000..2087fd4 --- /dev/null +++ b/plugins/voyage/playground/README.md @@ -0,0 +1,136 @@ +# voyage playground (v4.3) + +`voyage-playground.html` er en single-file, statisk, file://-loaded eksplorer +for voyage-pipeline-artifakter (brief / plan / research / review). Du peker +den mot en `.claude/projects/-/`-mappe og får en dashboard-sentrisk +oversikt over alle artifakter med drill-down og annotation-redigering. + +## Arkitektur (v4.3) + +Dashboard-sentrisk layout med to hovedoverflater: + +1. **Dashboard (default)** — `fleet-grid` med én `fleet-tile` per artifact-type + (brief, plan, research-briefer, review). Status-badges viser tilstand + (foreligger / mangler / partial). +2. **Drill-down** — klikk på en tile åpner detail-visningen med rendered + markdown, anchor-overlay, og annotation-sidebar. + +Theme-system: dark er default (``); IIFE-bootstrap +respekterer `localStorage('voyage-theme')`, deretter `prefers-color-scheme`. +Theme-toggle i topbar persisterer valg. + +Anchor-rendering: `` +kommentarer i rå-markdown blir til klikkbare gutters med yellow-tint highlight +i rendered markdown. Block-boundary-fallback håndterer code-fences, tables, og +list-items per Prettier #18066-workaround. + +## Bruk + +### Webkitdirectory-velger (anbefalt) + +Klikk **"Velg prosjekt-mappe"**-knappen og velg din `.claude/projects//` +i nettleserens directory-picker. Krever Chromium-baserte nettlesere +(Chrome / Edge / Brave / Arc) — Firefox støtter `webkitdirectory` siden v150 +men har en kjent Windows-bug (se Begrensninger). + +### Drag-drop + +Dra hele prosjekt-mappen direkte fra Finder/Explorer over playground-vinduet. +Drop-zone aktiveres ved `dragenter`. Bruker `webkitGetAsEntry()` for rekursiv +mappe-walk. + +### URL-parameter `?project=` + +Som ergonomisk shortcut kan du seede URL-en med en absolutt sti: + +``` +file:///path/to/playground/voyage-playground.html?project=/abs/path/to/project +``` + +URL-parameteren skriver til localStorage som default-prosjekt. Trenger fortsatt +en webkitdirectory-velger eller drag-drop første gang for å gi nettleseren +fil-tilgang (file:// + JS sandbox kan ikke åpne arbitrære lokale stier uten +brukergeste). + +## Discoverability av `.claude/`-mappen + +`.claude/projects/` er hidden by default på macOS / Linux. For å åpne den i +Finder: + +```bash +# macOS +open .claude/projects/ + +# Linux +xdg-open .claude/projects/ + +# Windows (PowerShell) +explorer .claude/projects/ +``` + +I directory-picker kan du også taste `.` for å vise hidden folders. + +## Annotation-flow + +1. **Rediger:** klikk på en gutter-badge eller bruk `J`/`K` for å navigere mellom + anchors. `Esc` lukker sidebar. +2. **Lagre:** annotations persisteres til `localStorage` med key + `voyage_ann_`. +3. **Eksporter:** klikk **"Eksporter annotert markdown"** for å laste ned + `annotated-{target}.md` (target = brief|plan|review|artifact basert på + frontmatter). Filen kan deretter mates til `/trekrevise --project ` + for å folde annotasjonene tilbake i source-artifaktet. + +## Hooks for screenshot-automatisering + +`window.__voyage` (Wave 5 Step 23) eksponerer tre metoder for Playwright + +manuell screenshot-prosedyre: + +- `window.__voyage.navigate(target)` — prog-navigerer til artifact-detail +- `window.__voyage.scheduleRender({ a11yViolations })` — populerer A11Y-panel +- `window.__voyage.getProjectArtifacts()` — returnerer aktiv ProjectArtifacts + +Se `docs/screenshots/README.md` for fullstendig manuell og automatisert +screenshot-prosedyre. + +## Begrensninger + +- **Firefox 150 Windows drag-drop bug:** UA-detect-guard viser fallback-melding + som ber bruker bruke `webkitdirectory`-velgeren istedenfor. +- **Ingen File System Access (FSA):** voyage skriver ikke direkte til disk. + Annotations lagres i `localStorage`; eksport går via `Blob` + nedlasting. +- **`design/`-mappen out-of-scope:** voyage utforsker ikke `/design/`-mapper + i v4.3. +- **Kjente WCAG-violations:** v4.3 har baseline'd WCAG-violations + (`aria-hidden-focus`, `color-contrast` på `.key-stat--critical__label`) + defer til v4.4. Se `tests/e2e/snapshots/a11y-baseline.json`. + +## Bundle-størrelse + +Total vendored bundle: ~388 KB (under 460 KB HALT-gate). Inkluderer: + +- `markdown-it` ~115 KB +- `gray-matter` (front-matter) ~36 KB +- `highlight.js` minimal subset ~120 KB +- `DOMPurify` 3.2.6 ~22 KB (Wave 5 Step 24) +- `playground-design-system` ~95 KB + +Alle vendored under `playground/lib/` + `playground/vendor/playground-design-system/` — +ingen CDN-kall (SC7 verifisert via Playwright network-intercept i +`tests/e2e/voyage-playground-network.spec.mjs`). + +## Tester + +- `tests/playground/voyage-playground.test.mjs` — Group A static-HTML + assertions (SC1 10-element + SC3 + SC6 + SC7) +- `tests/playground/voyage-playground-structure.test.mjs` — Group B DS-token + + theme-toggle + sidebar-tab + keyboard-pattern +- `tests/integration/annotation-export-schema.test.mjs` — Group C export-bundle + schema + annotation_digest validity +- `tests/e2e/voyage-playground-a11y.spec.mjs` — Group D Playwright a11y + delta-baseline + pixel-diff +- `tests/e2e/voyage-playground-network.spec.mjs` — Group D SC7 zero-external- + requests authoritative gate + +`npm test` kjører Groups A/B/C (Node-test, raskt). `npm run test:e2e` kjører +Group D (Playwright + Chromium).