Site D: arc42 architecture docs on the site (client-side Mermaid)

.github/workflows/a11y-check.yml

@@ -32,7 +32,7 @@ jobs:
 
       - name: Diagram pipeline unit tests
         working-directory: site
-        run: node --test test/diagram.test.mjs test/replace-plantuml.test.mjs test/schema-versions.test.mjs test/build-sports.test.mjs
+        run: node --test test/diagram.test.mjs test/replace-plantuml.test.mjs test/schema-versions.test.mjs test/build-sports.test.mjs test/mermaid-marked.test.mjs
 
       - name: Build site
         working-directory: site
@@ -70,6 +70,7 @@ jobs:
             http://localhost:4321/learn/ \
             http://localhost:4321/use/ \
             http://localhost:4321/build/ \
+            http://localhost:4321/build/architecture/ \
             http://localhost:4321/docs/ \
             http://localhost:4321/docs/spec/ \
             http://localhost:4321/docs/schema/ \

docs/superpowers/specs/2026-08-28-site-redesign-design.md

@@ -85,23 +85,31 @@ One document, one editor, switchable outputs:
   `/schema/versions.json`, the validator loaded at `@latest`, and the
   error/warning list with error codes.
 
-### Diagram rendering pipeline (build-time SVG, two renderers)
-
-A build-time module renders diagram sources to **SVG**, embedded statically into
-the page (no client JS). **Verified fact (2026-08-28):** the two doc sets use
-disjoint diagram languages, and the public `kroki.io` renders PlantUML but
-returns HTTP 500 for Mermaid (its Mermaid companion is unavailable). So the
-pipeline uses two renderers, one per language:
-
-- **PlantUML → Kroki** (`https://kroki.io`, POST). Serves the spec `.adoc`'s
-  4 PlantUML blocks. Endpoint is a **config constant** (self-hostable later).
-- **Mermaid → local `@mermaid-js/mermaid-cli` (`mmdc`)**. Serves the arc42's
-  5 Mermaid blocks. No network dependency; runs headless in CI.
-
-Both go through one façade module (`renderDiagram(type, source) -> svg`) that
-dispatches by type. If a renderer fails, the build **fails loudly** rather than
-silently dropping diagrams. (A single self-hosted Kroki instance could later
-serve both and collapse this back to one renderer — noted in Open Points.)
+### Diagram rendering pipeline (PlantUML build-time, Mermaid client-side)
+
+**Verified facts (2026-08-28):** the two doc sets use disjoint diagram
+languages (spec `.adoc` → PlantUML only; arc42 → Mermaid only). Public
+`kroki.io` renders PlantUML fine but returns HTTP 500 for Mermaid. And
+`@mermaid-js/mermaid-cli` (`mmdc`) is a **fragile, heavyweight build dependency**:
+its install downloads a headless Chromium and failed outright in this
+environment (`node install.mjs` errored), and the deploy workflow has no browser
+set up. So the two languages render by different, each-verified means:
+
+- **PlantUML → Kroki, build-time SVG** (`https://kroki.io`, POST). Serves the
+  spec `.adoc` blocks. Embedded statically, no client JS. Endpoint is a config
+  constant (self-hostable later). *(Already shipped in Plan A.)*
+- **Mermaid → client-side** via `mermaid@11` ESM from jsDelivr (verified: 200,
+  CORS `*`). The arc42 pages emit `<pre class="mermaid">…</pre>` blocks and a
+  small module script calls `mermaid.run()` in the browser. No build-time
+  Chromium, no fragile post-install. This is a deliberate, fact-driven revision
+  of the original "no client JS" goal: mmdc's unreliability makes client-side the
+  robust choice for Mermaid specifically. PlantUML stays build-time SVG.
+
+The PlantUML path stays behind the Plan A façade (`renderDiagram`); the Mermaid
+path is a thin arc42-only concern. If the PlantUML renderer fails, the build
+**fails loudly** rather than silently dropping diagrams. (A single self-hosted
+Kroki instance with a working Mermaid companion could later move Mermaid
+build-time too and collapse this back to one build-time path — noted in Open Points.)
 
 ### arc42 integration
 
@@ -126,9 +134,11 @@ Kroki, and publishes it under **Build → Architecture**.
 
 ## Components (site build)
 
-- `site/src/lib/diagram.mjs` — façade `renderDiagram(type, source) -> svg`:
-  dispatches `plantuml` → Kroki (fetch), `mermaid` → local `mmdc`. Endpoint/CLI
-  are constants; any renderer error throws (build-fails-loud).
+- `site/src/lib/diagram.mjs` — façade `renderDiagram(type, source) -> svg` for
+  the **build-time** path: `plantuml` → Kroki (fetch); errors throw
+  (build-fails-loud). Mermaid is **not** in this façade — it renders client-side
+  (see the pipeline section), so arc42 pages emit `<pre class="mermaid">` + a
+  `mermaid@11` module script instead.
 - `site/scripts/build-adoc.mjs` — extended to route `[plantuml]`/`[mermaid]`
   blocks through `kroki.mjs`.
 - `site/scripts/build-arc42.mjs` — new: fetch arc42 markdown at the pinned
@@ -172,9 +182,12 @@ here is shared across all four.
 
 - **PlantUML needs network (Kroki) at build time.** Public `kroki.io` is the
   default; a CI without egress would fail the PlantUML step. Mitigation (not built
-  now): self-host Kroki. Mermaid (via local `mmdc`) has no such dependency.
-- **`mmdc` runs headless Chromium.** The Mermaid CLI downloads/uses a headless
-  browser; Plan D must ensure the CI runner has it (puppeteer's bundled Chromium
-  or a system install) — verified during Plan D.
+  now): self-host Kroki.
+- **Mermaid renders client-side.** The arc42 pages load `mermaid@11` from
+  jsDelivr in the visitor's browser (verified: 200, CORS `*`), so there is no
+  build-time Chromium dependency. Trade-off: the diagrams need JS to appear, and
+  the axe a11y check runs only the mermaid-free overview page (section pages are
+  excluded to avoid flaky client-render timing).
 - **Future consolidation.** A self-hosted Kroki with a working Mermaid companion
-  could render both languages, collapsing the two renderers back into one.
+  could render Mermaid build-time too, moving arc42 diagrams to static SVG and
+  removing the client-side dependency.