safety.viz documentation site

Design document for Requirement #21 · obot.roadmap · supersedes the examples-site deferral in the #1 design · interim artifact for #15

Context

Requirement #21 (filed 2026-07-08) makes documentation the delivery bar for the renderer migration: a GitHub Pages site for safety.viz with three pillars per renderer — a live example-gallery demo, a test-evidence page (requirements → tests → screenshots), and an API reference — plus the process rule that a renderer is not done, and its migration requirement not Released, until all three are published.

Inputs already in place: the merged library scaffold (safety.viz PR #3), the histogram module extraction (PR #4) with its requirement-keyed test suite (32 Vitest + 15 Playwright), the coverage table docs/histogram-coverage.md, the JSON data contract src/data/schema/histogram.json, and the fixture demo page the Playwright harness already uses.

Four scoping decisions were made with @jwildfire on 2026-07-08 and are treated as settled inputs to this design:

Architecture overview

src/ (JSDoc)          docs/<module>-coverage.md      docs/evidence/<module>/   site/ (templates,
  │ jsdoc -X                    │                      (committed json + png)     config, css)
  ▼                             ▼                              ▼                     ▼
  └────────────────────► scripts/site.mjs ◄──────────────────────────────────────────┘
                        (plain Node, no framework)
                                │ emits relative-URL static pages
                                ▼
                             _site/  ──►  gh-pages branch  ──►  https://jwildfire.github.io/safety.viz/
                                             ├── /          (deployed from main — releases)
                                             ├── /dev/      (deployed from dev — integration)
                                             └── /pr/{N}/   (deployed per open PR, removed on close)

Repo layout additions (safety.viz)

safety.viz/
├── site/
│   ├── shell.html              # shared page shell: header, nav, footer, styles
│   ├── config.json             # per-renderer metadata: title, blurb, status
│   │                           #   (available / in-migration / planned), hero evidence ID
│   └── site.css                # one stylesheet for the whole site
├── scripts/
│   ├── site.mjs                # assembles _site/ from templates + generated data
│   └── evidence.mjs            # runs the suites with JSON reporters + screenshot
│                               #   capture and (re)writes docs/evidence/<module>/
├── docs/evidence/<module>/     # committed: evidence.json + <REQ-ID>[_slug].png
├── _site/                      # build output — gitignored, never committed
└── .github/workflows/pages.yml # build → verify → publish (main + PR previews)

The site pages per renderer: index.html (gallery), <module>/index.html (live demo), <module>/evidence.html, <module>/api.html. All internal links and asset paths are relative, so the same build works at the site root and under /pr/{N}/.

Pillar 1 — Example gallery

• Homepage = gallery. One card per renderer — all nine listed from site/config.json with status badges (available / in-migration / planned), so the gallery doubles as the migration scoreboard. Card thumbnail is the renderer's designated hero screenshot from its committed evidence set.
• Demo pages are live. Each available renderer's page mounts the module from the committed versioned dist/ bundle (the same IIFE asset gsm.safety vendors) against the committed fixture data (e.g. adbds.csv), with the full control panel active. The existing Playwright harness page is the seed; harness pages stay test-only, demo pages get the site shell plus a short "what you're looking at" intro and links to the evidence + API pages.

Pillar 2 — Test evidence

Evidence pipeline (npm run evidence)

• scripts/evidence.mjs runs Vitest and Playwright with JSON reporters and normalizes the results to docs/evidence/<module>/evidence.json: one record per test — test name, parsed requirement IDs, issue refs ((#N)), suite (unit/browser), pass/fail, screenshot filenames.
• Playwright specs capture named screenshots at assertion points as visual-regression assertions: await expect(page).toHaveScreenshot('SH-FUNC-004C_pulse-hides-control.png'), with snapshotPathTemplate pointing baselines at docs/evidence/<module>/. One committed PNG is therefore evidence artifact, regression baseline, and site image at once — and site images can never go stale, because a rendering change fails CI until baselines are deliberately refreshed. Capture runs under fixed conditions: 1280×800 viewport, device scale 1, animations disabled, committed fixture data only, with per-assertion maxDiffPixelRatio thresholds to absorb antialiasing noise.
• Evidence is committed (decision above): PR reviews see the screenshots and status changes in the diff, and the site build is a pure function of the repo tree — no test execution needed to build or preview the site.

Canonical rendering environment

Pixel comparison is only stable within one rendering stack (fonts and canvas antialiasing differ across OSes), so baselines are canonical to the Playwright Linux container CI already uses. npm run evidence:update regenerates baselines inside that container (locally via Docker, or as a manually-triggered workflow that commits the refresh); a plain local npm run evidence still runs the suites and captures screenshots for eyeballing, but never writes canonical baselines. Playwright browser bumps that shift pixels are absorbed the same way — one deliberate refresh, which updates the site images in the same commit.

Freshness guard (CI)

Two layers, both in the regular CI workflow: (1) the browser suite's toHaveScreenshot assertions enforce the pixel baselines natively; (2) a step compares test IDs and pass/fail statuses against the committed evidence.json — a mismatch fails the build with "evidence stale — run npm run evidence:update and commit".

Evidence page

Generated per renderer by joining the coverage table (docs/<module>-coverage.md) with evidence.json: requirement ID → source matrix rows (linked to the safety.agent matrix) → evidencing test(s) → status chip → screenshot(s). Unrouted/manual matrix rows render in the same routing-status sections the coverage table already carries, so the page tells the whole story — covered, superseded, deferred, and pending rows alike.

Pillar 3 — API reference

• JSDoc annotations in source for each module's public surface: the factory + lifecycle methods (init, setData, setSettings, render, resize, destroy) and every DEFAULT_SETTINGS key (type, default, behavior).
• Generation: jsdoc -X (the only new dev-dependency) emits doclet JSON; site.mjs renders it into the per-renderer API page — no JSDoc HTML templates or themes.
• Data contract straight from the schema: the API page's data section renders src/data/schema/<module>.json directly (field, type, required, description), keeping one source of truth for the contract.

Branch and release model

safety.viz adopts the gsm-style two-branch model (added in review, 2026-07-08 — already applied to the repo):

• dev is the integration branch — feature-branch PRs target dev (histogram PR #4 retargeted accordingly).
• Releases are PRs from dev → main; the site root republishes on merge, so the public site always reflects the latest release.
• main is protected: PR required (no direct pushes), the "Build, format, and test" check must pass, force pushes and deletion blocked; required approvals set to 0 so @jwildfire can merge his own release PRs (the never-merge-without-Jeremy gate stays a process rule).
• CI runs on PRs and on pushes to main and dev.

Publishing model

The single-artifact deploy-pages flow replaces the whole site on every deploy, which cannot host persistent PR previews — so Pages serves from a gh-pages branch written incrementally by pages.yml, with three tiers:

The site build also runs as a check in the regular CI workflow (build must succeed, internal links and referenced screenshots must resolve), alongside the evidence freshness guard. Repo settings change: Pages source = gh-pages branch (one-time manual step).

Done-gate mechanics

• A renderer is done when its site entry is complete: gallery card + live demo page, evidence page green for all matrix-routed rows, and API reference published.
• Encoded in safety.viz CONTRIBUTING.md as the renderer definition-of-done checklist, and in each renderer requirement's acceptance criteria from here on.
• On the hub board, a renderer migration requirement moves to Released only after its site entry is deployed — the histogram requirement (#2) stays in Development until the histogram pages ship, even though its code merged.

Relationship to existing requirements

Candidate decomposition

Sub-issues to be filed via requirement-tasks after sign-off (all in safety.viz unless noted):

1. Evidence pipeline — evidence.mjs, toHaveScreenshot baselines in docs/evidence/, canonical-container evidence:update flow, JSON reporters, committed histogram evidence set, CI freshness guard.
2. API reference — JSDoc annotations on the histogram module + jsdoc -X → page generation in site.mjs.
3. Site build — site.mjs, shell/templates/config, gallery + histogram demo + evidence page assembly, link/asset validation, CONTRIBUTING done-gate checklist.
4. Publishing — pages.yml (main root + /dev/ tier + PR previews + close cleanup), Pages settings, preview-link bot comment.

Open questions

• None blocking. Two small calls left to implementation: the exact sticky-comment mechanism for preview links, and per-renderer hero-screenshot choices in site/config.json.