fix(docs): frontmatter disclosure, sidenav directory tree, themed syntax highlighting

docs/plans/2026-08-31-docs-reader-design-surface.md

@@ -0,0 +1,56 @@
+---
+status: in-flight
+branch: fix/docs-frontmatter-and-tree
+next: design-iterate the docs reader (tree density, frontmatter treatment, code-block fit) — read this stub, open `forgectl docs serve`, compare against the Artificer live-spec
+---
+
+# The docs reader as a design surface
+
+## Continuation
+
+Design-iterate the docs reader: tree density, frontmatter treatment, code-block fit. Open `forgectl docs serve` on real docs and judge against the Artificer live-spec.
+
+Branch: fix/docs-frontmatter-and-tree
+PR: #430 (this branch); #429 (Artificer 0.19.0 -> 0.25.0 re-vendor + docs slate, ready)
+
+### What the surface is
+
+`forgectl docs serve` is a pure-Go, server-rendered markdown reader on loopback HTTP. The shell is an Artificer surface-tool layout: appbar + split-pane + sidenav on the left, `surface-document` main pane. Assets are vendored Artificer (0.25.0 once #429 merges), embedded via `internal/docs/assets.go` — only `artificer.css`, `artificer-theme.js`, and `artificer-tree.js` from the vendored set are served. Two hard constraints shape every design change:
+
+- CSP sends `script-src 'self'` — no inline scripts ever; any behavior must be a served asset (see `assets/sidenav-filter.js` for the precedent).
+- `style-src` allows inline styles, so template-level `<style>` blocks and `style=` attributes are legitimate.
+
+### What shipped 2026-08-31
+
+- Frontmatter renders as a collapsed `Front matter · N keys` disclosure — accordion wrapper + `.kv` grid. Treatment "A" (collapsed) chosen by Cameron over open-card "B" and meta-strip "C".
+- The sidenav renders each root as a `.tree--static` (nested details/summary): per-directory counts, path to the current doc pre-expanded, filter-aware via `assets/sidenav-filter.js`. Recent stays a flat list.
+- Syntax highlighting maps chroma's classes onto Artificer syntax roles in `assets/chroma.css` (replaced hardcoded monokai; follows light/dark).
+
+### Design levers still open
+
+- `.sidenav a` min-height makes tree leaf rows taller than the 28px `.tree__row` intent — flagged in review, deliberately unchanged; needs a design-fit judgment.
+- Duplicate `aria-current` — the current doc is marked in both the Recent list and the tree.
+- The tree--static backing CSS (twisty rotation, count styling) lives as an inline `<style>` block in `templates/shell.html.tmpl` — candidate to upstream into Artificer proper.
+- The chroma role mapping is a first pass: four roles use `var()` fallbacks pending upstream token minting (successBright, attentionAlt, cyan, urgentBright — noted in `artificer.css` around line 868).
+- Mermaid diagrams + SVG pan/zoom exist and were untouched this round.
+- The static prototype that drove the treatment choice was `/tmp/docs-reader-proto/index.html` (ephemeral); the shipped code on this branch is now the reference.
+
+### Key files
+
+- `internal/docs/templates/shell.html.tmpl` — shell, recursive `treeNodes` template, tree CSS backing.
+- `internal/docs/render.go` — goldmark -> bluemonday pipeline; `frontmatterHTML` builds the disclosure post-sanitizer from escaped fragments only.
+- `internal/docs/assets/chroma.css` — the Artificer token mapping for syntax highlighting.
+- `internal/docs/assets/sidenav-filter.js` — filter box; hides empty branches, auto-expands matches.
+- `internal/docs/server.go` — `buildTree` / `buildGroups` shape the sidenav data.
+
+### Artificer references
+
+- Tree and `tree--static` recipes: design-system live-spec `components-extended.html`.
+- `.kv` and accordion recipes: live-spec `data-display.html` and `components.html`.
+- Upstream feedback already filed: artificer-design-system#447 (`vendor --check`), #448 (ledger gaps from the 0.25.0 crossing).
+
+### Open questions
+
+- Upstream the tree--static twisty/count CSS into Artificer, or keep it local to forgectl?
+- Tree leaf row height: 44px touch target vs the 28px density intent — needs Cameron's eye on the live surface.
+- Run the full artificer-design-system sync into claude.ai/design for component-true prototyping? Declined this session in favor of a local static prototype.

go.mod

@@ -16,10 +16,13 @@ require (
 	github.com/microcosm-cc/bluemonday v1.0.27
 	github.com/muesli/termenv v0.16.0
 	github.com/spf13/cobra v1.10.2
+	github.com/spf13/pflag v1.0.9
 	github.com/yuin/goldmark v1.8.4
 	github.com/yuin/goldmark-highlighting/v2 v2.0.0-20230729083705-37449abec8cc
+	go.abhg.dev/goldmark/frontmatter v0.3.0
 	golang.org/x/sys v0.46.0
 	golang.org/x/term v0.44.0
+	gopkg.in/yaml.v3 v3.0.1
 )
 
 require (
@@ -45,6 +48,7 @@ require (
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
+	github.com/kr/text v0.2.0 // indirect
 	github.com/lucasb-eyer/go-colorful v1.4.0 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mattn/go-localereader v0.0.1 // indirect
@@ -57,8 +61,8 @@ require (
 	github.com/muesli/mango-pflag v0.1.0 // indirect
 	github.com/muesli/roff v0.1.0 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
+	github.com/rogpeppe/go-internal v1.16.0 // indirect
 	github.com/sahilm/fuzzy v0.1.1 // indirect
-	github.com/spf13/pflag v1.0.9 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	golang.org/x/net v0.55.0 // indirect
 	golang.org/x/sync v0.20.0 // indirect

go.sum

@@ -63,6 +63,7 @@ github.com/clipperhouse/displaywidth v0.11.0/go.mod h1:bkrFNkf81G8HyVqmKGxsPufD3
 github.com/clipperhouse/uax29/v2 v2.7.0 h1:+gs4oBZ2gPfVrKPthwbMzWZDaAFPGYK72F0NJv2v7Vk=
 github.com/clipperhouse/uax29/v2 v2.7.0/go.mod h1:EFJ2TJMRUaplDxHKj1qAEhCtQPW2tJSwu5BF98AuoVM=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/creack/pty v1.1.24 h1:bJrF4RRfyJnbTJqzRLHzcGaZK1NeM5kTC9jGgovnR1s=
 github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -92,6 +93,10 @@ github.com/jackc/pgx/v5 v5.10.0 h1:VhSvgU2jSli8o3AqIEOTJr7rZwAEUVo4E4XhR94Zfr0=
 github.com/jackc/pgx/v5 v5.10.0/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
 github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
 github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
+github.com/kr/pretty v0.3.0 h1:WgNl7dwNpEZ6jJ9k1snq4pZsg7DOEN8hP9Xw0Tsjwk0=
+github.com/kr/pretty v0.3.0/go.mod h1:640gp4NfQd8pI5XOwp5fnNeVWj67G7CFk/SaSQn7NBk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
 github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
 github.com/lucasb-eyer/go-colorful v1.4.0 h1:UtrWVfLdarDgc44HcS7pYloGHJUjHV/4FwW4TvVgFr4=
@@ -124,6 +129,8 @@ github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZb
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
 github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
+github.com/rogpeppe/go-internal v1.16.0 h1:O9DK+vNMDVGLr2BeZqmpLeMjiMNkuXfcqntWbZV6S5g=
+github.com/rogpeppe/go-internal v1.16.0/go.mod h1:DrUVZyrJU+txYW5/1kwtXQSMFio52ZOxX7yM1VHvnxs=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/sahilm/fuzzy v0.1.1 h1:ceu5RHF8DGgoi+/dR5PsECjCDH1BE3Fnmpo7aVXOdRA=
 github.com/sahilm/fuzzy v0.1.1/go.mod h1:VFvziUEIMCrT6A6tw2RFIXPXXmzXbOsSHF0DOI8ZK9Y=
@@ -143,6 +150,8 @@ github.com/yuin/goldmark v1.8.4 h1:oat/nd3U6NeQqFEL3xpEJq7d7c86NI+DbSNGAs4xnjA=
 github.com/yuin/goldmark v1.8.4/go.mod h1:ip/1k0VRfGynBgxOz0yCqHrbZXhcjxyuS66Brc7iBKg=
 github.com/yuin/goldmark-highlighting/v2 v2.0.0-20230729083705-37449abec8cc h1:+IAOyRda+RLrxa1WC7umKOZRsGq4QrFFMYApOeHzQwQ=
 github.com/yuin/goldmark-highlighting/v2 v2.0.0-20230729083705-37449abec8cc/go.mod h1:ovIvrum6DQJA4QsJSovrkC4saKHQVs7TvcaeO8AIl5I=
+go.abhg.dev/goldmark/frontmatter v0.3.0 h1:ZOrMkeyyYzhlbenFNmOXyGFx1dFE8TgBWAgZfs9D5RA=
+go.abhg.dev/goldmark/frontmatter v0.3.0/go.mod h1:W3KXvVveKKxU1FIFZ7fgFFQrlkcolnDcOVmu19cCO9U=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
 golang.org/x/exp v0.0.0-20231006140011-7918f672742d h1:jtJma62tbqLibJ5sFQz8bKtEM8rJBtfilJ2qTU199MI=
 golang.org/x/exp v0.0.0-20231006140011-7918f672742d/go.mod h1:ldy0pHrwJyGW56pPQzzkH36rKxoZW1tw7ZJpeKx+hdo=
@@ -159,6 +168,8 @@ golang.org/x/term v0.44.0/go.mod h1:7ze4MdzUzLXpSAoFP1H0bOI9aXDqveSvatT5vKcFh2Y=
 golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc=
 golang.org/x/text v0.37.0/go.mod h1:a5sjxXGs9hsn/AJVwuElvCAo9v8QYLzvavO5z2PiM38=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

internal/docs/assets.go

@@ -45,6 +45,14 @@ var reloadJS []byte
 //go:embed assets/sidenav-filter.js
 var sidenavFilterJS []byte
 
+// chromaArtificerCSS maps chroma's class-based token output onto the
+// Artificer syntax roles (the .tok-* map in artificer.css), replacing the
+// generated monokai sheet whose hardcoded palette ignored the theme. Served
+// at /assets/chroma.css via ChromaCSS().
+//
+//go:embed assets/chroma.css
+var chromaArtificerCSS []byte
+
 // mermaidJS is vendored mermaid (version, license, and sha256 recorded in
 // assets/provenance-mermaid.json). Embedded rather than loaded from a CDN: the
 // reader must render a diagram with no network call, because opening a local

internal/docs/assets/chroma.css

@@ -0,0 +1,81 @@
+/* Syntax highlighting for chroma's class-based output, mapped onto the
+   Artificer 12-role syntax map (artificer.css .code-block .tok-* rules) so
+   code blocks read as part of the page and follow the light/dark theme.
+   Replaces the generated monokai sheet, whose hardcoded palette ignored
+   both. Chroma emits <pre class="chroma">; that wrapper takes the same
+   treatment .code-block gives hand-authored blocks. */
+
+.chroma {
+  font-family: var(--font-mono);
+  font-size: var(--t-label-md-size);
+  line-height: 1.6;
+  background: var(--bg-inactive);
+  color: var(--fg);
+  padding: var(--s-md) var(--s-lg);
+  border-radius: var(--radius-md);
+  border: 1px solid var(--border);
+  overflow-x: auto;
+  white-space: pre;
+  margin: 0;
+}
+
+/* Comments and operators recede — tok-comment / tok-operator. */
+.chroma .c, .chroma .c1, .chroma .cm, .chroma .ch, .chroma .cs,
+.chroma .cp, .chroma .cpf { color: var(--fg-muted); font-style: italic; }
+.chroma .o, .chroma .ow, .chroma .p { color: var(--fg-muted); }
+
+/* Keywords — tok-keyword. */
+.chroma .k, .chroma .kd, .chroma .kn, .chroma .kp, .chroma .kr,
+.chroma .kv { color: var(--brand-purple-bright); }
+
+/* Types and classes — tok-type. */
+.chroma .kt, .chroma .nc, .chroma .nb { color: var(--accent-bright); }
+
+/* Strings — tok-string. */
+.chroma .s, .chroma .s1, .chroma .s2, .chroma .sb, .chroma .sc,
+.chroma .sd, .chroma .se, .chroma .sh, .chroma .si, .chroma .sx,
+.chroma .sr, .chroma .ss { color: var(--success-bright, var(--success)); }
+
+/* Numbers and constants — tok-number / tok-constant. */
+.chroma .m, .chroma .mb, .chroma .mf, .chroma .mh, .chroma .mi,
+.chroma .il, .chroma .mo, .chroma .kc, .chroma .no {
+  color: var(--attention-alt, var(--attention));
+}
+
+/* Functions — tok-fn. */
+.chroma .nf, .chroma .fm { color: var(--accent); }
+
+/* Namespaces — tok-namespace. */
+.chroma .nn { color: var(--cyan, var(--steel)); }
+
+/* Tags and attributes — tok-tag / tok-param. */
+.chroma .nt { color: var(--urgent-bright, var(--urgent)); }
+.chroma .na { color: var(--steel); }
+
+/* Variables stay body-colored — tok-variable. */
+.chroma .nv, .chroma .vc, .chroma .vg, .chroma .vi { color: var(--fg); }
+
+/* Errors — tok-invalid. */
+.chroma .err {
+  color: var(--urgent-bright, var(--urgent));
+  text-decoration: wavy underline;
+}
+
+/* Diff lines lean on the status pair. */
+.chroma .gd { color: var(--urgent-bright, var(--urgent)); }
+.chroma .gi { color: var(--success-bright, var(--success)); }
+.chroma .ge { font-style: italic; }
+.chroma .gs { font-weight: 600; }
+
+/* Line numbers and highlights, for chroma's table/line modes. */
+.chroma .lnt, .chroma .ln {
+  color: var(--fg-disabled);
+  -webkit-user-select: none;
+  user-select: none;
+  margin-right: 0.4em;
+  padding: 0 0.4em;
+}
+.chroma .hl { background-color: var(--bg-raised); }
+.chroma .lnlinks { outline: none; text-decoration: none; color: inherit; }
+.chroma .lntd { vertical-align: top; padding: 0; margin: 0; border: 0; }
+.chroma .lntable { border-spacing: 0; padding: 0; margin: 0; border: 0; }

internal/docs/assets/sidenav-filter.js

@@ -1,7 +1,11 @@
 // Sidenav filter box for `forgectl docs serve`.
 //
-// Hides sidenav links whose data-filter-text does not contain the query, then
-// hides any group heading left with no visible links under it.
+// The sidenav holds two shapes: the flat Recent link list, and one
+// .tree--static per root (nested details/summary). Filtering hides
+// non-matching leaves in both, hides any directory left with no visible
+// descendant, auto-expands directories that contain a match while a query is
+// live, and restores each directory's original open state when the box
+// clears. Group headings hide when their whole section is filtered out.
 //
 // This is a file rather than an inline <script> in shell.html.tmpl because the
 // server sends a Content-Security-Policy with script-src 'self', which forbids
@@ -19,19 +23,51 @@
   // it and cannot assume that adjacency.
   if (!input) { return; }
 
-  var links = document.querySelectorAll(".sidenav a");
-  var groups = document.querySelectorAll(".sidenav__group");
+  var links = Array.prototype.slice.call(
+    document.querySelectorAll(".sidenav a[data-filter-text]"));
+  var groups = Array.prototype.slice.call(
+    document.querySelectorAll(".sidenav .sidenav__group"));
+  var dirs = Array.prototype.slice.call(
+    document.querySelectorAll(".sidenav details"));
+
+  // Remember each directory's server-rendered open state (the path to the
+  // current doc) so clearing the filter restores it instead of leaving the
+  // whole tree sprung open.
+  dirs.forEach(function (d) { d.dataset.openAtRest = d.open ? "1" : ""; });
+
+  function matches(a, q) {
+    if (q === "") { return true; }
+    return (a.getAttribute("data-filter-text") || "").indexOf(q) !== -1;
+  }
+
   input.addEventListener("input", function () {
     var q = input.value.trim().toLowerCase();
+
     links.forEach(function (a) {
-      var hay = a.getAttribute("data-filter-text") || "";
-      a.style.display = (q === "" || hay.indexOf(q) !== -1) ? "" : "none";
+      var row = a.closest("li") || a;
+      row.style.display = matches(a, q) ? "" : "none";
     });
+
+    dirs.forEach(function (d) {
+      var anyHit = Array.prototype.some.call(
+        d.querySelectorAll("a[data-filter-text]"),
+        function (a) { return matches(a, q); });
+      var row = d.closest("li") || d;
+      row.style.display = anyHit ? "" : "none";
+      d.open = q === "" ? d.dataset.openAtRest === "1" : anyHit;
+    });
+
     groups.forEach(function (g) {
-      var sib = g.nextElementSibling;
       var anyVisible = false;
+      var sib = g.nextElementSibling;
       while (sib && !sib.classList.contains("sidenav__group")) {
-        if (sib.tagName === "A" && sib.style.display !== "none") { anyVisible = true; }
+        var candidates = sib.matches("a[data-filter-text]")
+          ? [sib]
+          : Array.prototype.slice.call(sib.querySelectorAll("a[data-filter-text]"));
+        if (candidates.some(function (a) { return matches(a, q); })) {
+          anyVisible = true;
+          break;
+        }
         sib = sib.nextElementSibling;
       }
       g.style.display = anyVisible ? "" : "none";