open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions
ktg-plugin-marketplace/plugins/voyage/playground
History
Kjell Tore Guttormsen 8ae51cda30 fix(voyage): remove dead console.log else-branches + announce drag-drop fallback (809a225e)
2026-05-10 21:26:24 +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 fix(voyage): remove dead console.log else-branches + announce drag-drop fallback (809a225e) 2026-05-10 21:26:24 +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:

  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:

# 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).