docs(voyage): write playground/README.md with v4.3 architecture + URL-parameter
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).
This commit is contained in:
parent
59cab69bf4
commit
12637f3dbd
1 changed files with 136 additions and 0 deletions
136
plugins/voyage/playground/README.md
Normal file
136
plugins/voyage/playground/README.md
Normal file
|
|
@ -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/<dato>-<slug>/`-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 (`<html data-theme="dark">`); IIFE-bootstrap
|
||||
respekterer `localStorage('voyage-theme')`, deretter `prefers-color-scheme`.
|
||||
Theme-toggle i topbar persisterer valg.
|
||||
|
||||
Anchor-rendering: `<!-- voyage:anchor id="ANN-NNNN" target="<slug>" line="N" -->`
|
||||
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/<slug>/`
|
||||
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_<storage-key>`.
|
||||
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 <dir>`
|
||||
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 `<project>/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).
|
||||
Loading…
Add table
Add a link
Reference in a new issue