History

Kjell Tore Guttormsen 12637f3dbd 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).		2026-05-10 18:25:37 +02:00
..
lib	feat(voyage): vendor DOMPurify >=3.1.1 + sanitize annotation-content	2026-05-10 18:01:30 +02:00
vendor/playground-design-system	feat(ds): add voyage scope tokens + badge--scope-voyage (B-DS-4); resync vendor	2026-05-10 10:17:50 +02:00
README.md	docs(voyage): write playground/README.md with v4.3 architecture + URL-parameter	2026-05-10 18:25:37 +02:00
voyage-playground.html	feat(voyage): implement path-traversal + symlink/dotfile filter on loaded files	2026-05-10 18:05:35 +02:00

README.md

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:

Dashboard (default) — fleet-grid med én fleet-tile per artifact-type (brief, plan, research-briefer, review). Status-badges viser tilstand (foreligger / mangler / partial).
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:  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:

# 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

Rediger: klikk på en gutter-badge eller bruk J/K for å navigere mellom anchors. Esc lukker sidebar.
Lagre: annotations persisteres til localStorage med key voyage_ann_<storage-key>.
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).