@brandon_m_behring/book-scaffold-astro 4.9.0 → 4.11.0

package/CLAUDE.md

@@ -166,9 +166,16 @@ See `recipes/09-validation.md` to extend.
 
 ### Add a figure
 
-1. Drop PDF in `figures/<topic>/<name>.pdf` (or set `BOOK_FIGURES_PATH`).
+1. Drop a PDF in `figures/<topic>/<name>.pdf`, or a TikZ standalone `.tex` (auto-compiled), or set `BOOK_FIGURES_PATH`.
 2. `npm run build:figures` produces `public/figures/<topic>/<name>.svg`.
-3. Reference: `<Figure src="/figures/<topic>/<name>.svg" caption="..." id="..." />`.
+3. Reference: `<Figure src="/figures/<topic>/<name>.svg" caption="..." alt="..." id="..." />`.
+
+**Accessibility + dark mode (v4.11.0, #84).** `build:figures` rewrites every generated SVG so one file serves both themes: it adds `role="img"` and remaps the *neutral* fills/strokes to `var(--diagram-ink|paper|grid, <original>)` (saturated accent colors are left as authored). `<Figure>` **inlines** a local `.svg` (vs `<img>`), so the page's `--diagram-*` tokens cascade in and the figure tracks the in-page dark-mode toggle; `caption`/`alt`/`desc` become the SVG's `<title>`/`<desc>`. Notes:
+
+- `alt` is the short accessible name (defaults to `caption`); `desc` is an optional longer description.
+- Non-SVG (`.png` fallback), remote, or unreadable `src` keep the `<img>` render.
+- Opt a figure out of theming with a `%! no-theme` line in its source `.tex`.
+- After upgrading, re-run `npm run build:figures` to theme pre-existing figures (the rewrite is idempotent).
 
 ### Add a new component
 

package/bin/book-scaffold.mjs

@@ -27,8 +27,9 @@ const HELP = `Usage: book-scaffold <sub-command> [args...]
 Sub-commands:
   validate           Pre-flight content validator (XRef ids, Cite keys, Figure srcs).
   build-labels       Emit src/data/labels.json for cross-references (Phase C).
-  build-bib          BibTeX -> CSL JSON for the <Cite> component.
+  build-bib          BibTeX -> references.json (+ sources/manifest.yaml -> sources.json).
   build-figures      PDF -> SVG via pdftocairo / pdftoppm fallback (+ TikZ in v4.2.0).
+                     Each SVG gets role="img" + dark-mode var(--diagram-*) fills (v4.11.0).
   build-tips         Scan chapters for <Tip> instances; emit src/data/tips.json (v4.3.0).
   build-exercises    Scan chapters for <Exercise> instances; emit src/data/exercises.json (v4.4.0).
   render-notebooks   ipynb -> HTML via Jupyter nbconvert.

package/components/Figure.astro

@@ -4,13 +4,22 @@
  * `\label{...}` pattern with a single component.
  *
  * Source assets are emitted under public/figures/weekNN/ by
- * scripts/build-figures.sh (Phase 2.4); src paths are absolute from
- * site root.
+ * scripts/build-figures.mjs; src paths are absolute from site root.
+ *
+ * v4.11.0 (#84): a local pipeline `.svg` is **inlined** (read from public/ +
+ * `set:html`) rather than referenced via `<img>`. Inlining puts the SVG in the
+ * host DOM, so the page's tokens.css `--diagram-*` cascade in — the figure
+ * tracks the in-page dark-mode toggle (an `<img>`-loaded SVG is CSS-isolated
+ * and could only follow the OS preference). Inlining also lets a11y
+ * `<title>`/`<desc>` come from this component's props (assembleSvg). Non-SVG
+ * (the pdftoppm `.png` fallback), remote, or unreadable `src` gracefully keep
+ * the `<img>` render — a figure must never crash a build.
  *
  * Usage:
  *   <Figure
  *     src="/figures/week04/ex2_hippo_eigenvalues.svg"
  *     caption="HiPPO-LegS eigenvalue structure for N = 16 and N = 64."
+ *     alt="Two overlaid eigenvalue spectra forming nested arcs."
  *     width="100%"
  *     id="w4-fig-hippo-eigenvalues"
  *   />
@@ -18,18 +27,41 @@
  * The id prop registers the figure with the cross-reference label map
  * (consumed by `<XRef>`).
  */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { shouldInline, assembleSvg } from '../src/lib/figure.mjs';
+
 interface Props {
   src: string;
   caption?: string;
   width?: string;
   id?: string;
   alt?: string;
+  /** Long-form description → SVG <desc> (alt stays the short accessible name). */
+  desc?: string;
 }
 
-const { src, caption, width = '100%', id, alt } = Astro.props;
+const { src, caption, width = '100%', id, alt, desc } = Astro.props;
 const altText = alt ?? caption ?? '';
+
+// Inline a local pipeline SVG so host CSS variables theme it + a11y nodes come
+// from props. Any read failure falls back to <img> below (never throws).
+let inlineSvg: string | null = null;
+if (shouldInline(src)) {
+  try {
+    const raw = readFileSync(join(process.cwd(), 'public', src), 'utf8');
+    const idBase = id ?? `fig-${src.replace(/^\/+/, '').replace(/\.[^.]+$/, '')}`;
+    inlineSvg = assembleSvg(raw, { caption, alt, desc, width, idBase });
+  } catch {
+    inlineSvg = null;
+  }
+}
 ---
 <figure class="figure" id={id}>
-  <img src={src} alt={altText} style={`width: ${width}; max-width: 100%;`} />
+  {inlineSvg ? (
+    <Fragment set:html={inlineSvg} />
+  ) : (
+    <img src={src} alt={altText} style={`width: ${width}; max-width: 100%;`} />
+  )}
   {caption && <figcaption>{caption}</figcaption>}
 </figure>

package/components/SourceArchive.astro

@@ -3,14 +3,14 @@
  * SourceArchive — renders every entry in sources/manifest.yaml grouped
  * by tier in descending authority (T1 → T4).
  *
- * Used from Appendix D (`d-source-archive-index.mdx`) to replace the
- * static hand-maintained listing with an auto-generated view that
- * always reflects the manifest.
+ * Used by the auto-injected /references page (v4.10.0, #85) and by
+ * author-placed source-archive appendices, replacing a static hand-
+ * maintained listing with an auto-generated view that always reflects
+ * the manifest.
  *
  * Empty-tier behavior: renders an honest placeholder ("No sources at
- * this tier yet.") rather than hiding the section. This matches the
- * pedagogy of Appendix D — the archive is intentionally sparse in the
- * early book, and the gap is visible by design.
+ * this tier yet.") rather than hiding the section, so the tier taxonomy
+ * stays visible even before a tier has entries.
  */
 import { sourceTiers } from '@brandon_m_behring/book-scaffold-astro';
 import {
@@ -53,7 +53,7 @@ function year(d: Date | undefined): string | null {
 
         {empty ? (
           <p class="source-archive-empty">
-            No sources at this tier yet. Appendix D is intentionally sparse in the early book; this slot fills as chapters leave draft.
+            No sources at this tier yet.
           </p>
         ) : (
           <ol

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brandon_m_behring/book-scaffold-astro",
   "description": "Astro 6 + MDX toolkit for long-form technical books. Profile-aware (academic / tools / minimal); ships Tufte typography, KaTeX, BibTeX citations, Pagefind, Cloudflare Workers deploy. See PACKAGE_DESIGN.md for the API contract.",
-  "version": "4.9.0",
+  "version": "4.11.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -142,15 +142,21 @@
     "test": "node --test tests/*.test.mjs"
   },
   "peerDependencies": {
-    "astro": "^6.1.7",
     "@astrojs/mdx": "^5.0.3",
     "@astrojs/preact": "^5.1.1",
+    "astro": "^6.1.7",
     "preact": "^10.29.1"
   },
   "peerDependenciesMeta": {
-    "katex": { "optional": true },
-    "rehype-katex": { "optional": true },
-    "remark-math": { "optional": true }
+    "katex": {
+      "optional": true
+    },
+    "rehype-katex": {
+      "optional": true
+    },
+    "remark-math": {
+      "optional": true
+    }
   },
   "dependencies": {
     "@astrojs/sitemap": "^3.6.1",
@@ -158,7 +164,8 @@
     "@citation-js/plugin-bibtex": "^0.7.21",
     "@fontsource-variable/roboto": "^5.2.10",
     "@fontsource-variable/source-code-pro": "^5.2.7",
-    "pagefind": "^1.5.2"
+    "pagefind": "^1.5.2",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",

package/pages/references.astro

@@ -1,16 +1,22 @@
 ---
 /**
- * /references — the book's bibliography page.
+ * /references — the book's bibliography + cited-sources page.
  *
- * Renders every entry in src/data/references.json (produced by
- * scripts/build-bib.mjs from guides/shared/references.bib). Each
- * entry gets an anchor ID matching its bibkey, so `<Cite key="gu2024mamba" />`
- * elsewhere on the site links to /references#gu2024mamba.
+ * Auto-injected on every profile (integration route table). Reads two
+ * independent inputs, each via a defensive `import.meta.glob` (missing file →
+ * empty, never a crash — same pattern <XRef> uses for labels.json):
  *
- * Sorted alphabetically by first-author surname, then by year.
- * arXiv-style notes are surfaced as direct links when present.
+ *   - src/data/references.json — BibTeX entries (academic), from build-bib.
+ *     Each entry's anchor matches its bibkey, so `<Cite key="…" />` links to
+ *     /references#<bibkey>.
+ *   - src/data/sources.json — sources/manifest.yaml entries (tools profile),
+ *     also from build-bib (v4.10.0, #85). Its presence is a profile-safe GATE
+ *     for the <SourceArchive> render: a falsy `&&` never instantiates the
+ *     component, so academic/minimal books (which have no `sources` content
+ *     collection) never call getCollection('sources').
  */
 import Base from '../layouts/Base.astro';
+import SourceArchive from '../components/SourceArchive.astro';
 
 type CslAuthor = { family?: string; given?: string; literal?: string };
 type CslEntry = {
@@ -29,8 +35,7 @@ type CslEntry = {
   note?: string;
 };
 
-// Resolve references.json from consumer's project root. Missing file -> empty
-// list (page renders an "empty bibliography" notice rather than crashing).
+// --- Bibliography: BibTeX → references.json (academic profile). ---
 const refsModules = import.meta.glob<{ default: Record<string, CslEntry> }>(
   '/src/data/references.json',
   { eager: true },
@@ -39,6 +44,18 @@ const refsModule = refsModules['/src/data/references.json'];
 const map = (refsModule?.default ?? {}) as Record<string, CslEntry>;
 const entries = Object.values(map);
 
+// --- Cited sources: sources/manifest.yaml → sources.json (tools profile).
+// Presence-only gate; the actual render reads the live `sources` collection
+// via <SourceArchive>, which only runs when this gate is true (so it is never
+// reached on profiles without a `sources` collection). ---
+const srcModules = import.meta.glob<{ default: unknown[] }>(
+  '/src/data/sources.json',
+  { eager: true },
+);
+const sourcesData = (srcModules['/src/data/sources.json']?.default ?? []) as unknown[];
+const hasSources = Array.isArray(sourcesData) && sourcesData.length > 0;
+const hasBib = entries.length > 0;
+
 const surname = (a: CslAuthor): string =>
   (a.family ?? a.literal ?? '').toLowerCase();
 
@@ -73,61 +90,95 @@ function arxivUrl(note?: string): string | null {
   const m = note.match(/arXiv:\s*(\S+)/i);
   return m ? `https://arxiv.org/abs/${m[1]}` : null;
 }
+
+const lede =
+  hasBib && hasSources
+    ? 'Every work cited in this book — the bibliography below, then the external sources grouped by tier.'
+    : hasBib
+      ? 'Every paper, book, and software citation in this book, sorted alphabetically by first-author surname. Click an entry’s anchor to share a deep link, or follow the arXiv / DOI / URL for the source.'
+      : hasSources
+        ? 'Every external source cited in this book, grouped by tier in descending authority.'
+        : 'This book has no references yet.';
 ---
-<Base
-  title="References — Post-Transformers"
-  description="Bibliography for the post_transformers guide, generated from guides/shared/references.bib."
->
+<Base title="References" description="Bibliography and cited sources for this book.">
   <article class="prose">
     <header>
       <h1>References</h1>
-      <p class="lede">
-        Every paper, book, and software citation in this guide, sorted
-        alphabetically by first-author surname. Click an entry's
-        anchor to share a deep link, or follow the arXiv / DOI / URL
-        for the source.
-      </p>
-      <p>
-        <small>
-          {entries.length} entries. Generated from
-          <code>guides/shared/references.bib</code> at build time via
-          <code>scripts/build-bib.mjs</code>.
-        </small>
-      </p>
+      <p class="lede">{lede}</p>
     </header>
 
-    <ol class="references-list">
-      {entries.map((e) => {
-        const y = year(e);
-        const arxiv = arxivUrl(e.note);
-        const primaryUrl = arxiv ?? e.URL ?? (e.DOI ? `https://doi.org/${e.DOI}` : null);
-        return (
-          <li id={e.id} class="reference-entry">
-            <span class="reference-key" aria-label="bibkey">[{e.id}]</span>
-            <span class="reference-text">
-              {formatAuthors(e.author)}
-              {y > 0 && <> ({y})</>}.
-              {' '}
-              <em>{e.title}</em>.
-              {e['container-title'] && <> {e['container-title']}.</>}
-              {e.publisher && !e['container-title'] && <> {e.publisher}.</>}
-              {e.volume && <> Vol. {e.volume}{e.issue && <>, no. {e.issue}</>}.</>}
-              {e.page && <> pp. {e.page}.</>}
-              {primaryUrl && (
-                <>
+    {!hasBib && !hasSources && (
+      <p class="references-empty">
+        No references yet. Add a <code>bibliography.bib</code> (academic) or
+        populate <code>sources/manifest.yaml</code> (tools), then run
+        <code>npm run build:bib</code>.
+      </p>
+    )}
+
+    {hasBib && (
+      <section class="references-bibliography">
+        {hasSources && <h2>Bibliography</h2>}
+        <ol class="references-list">
+          {entries.map((e) => {
+            const y = year(e);
+            const arxiv = arxivUrl(e.note);
+            const primaryUrl = arxiv ?? e.URL ?? (e.DOI ? `https://doi.org/${e.DOI}` : null);
+            return (
+              <li id={e.id} class="reference-entry">
+                <span class="reference-key" aria-label="bibkey">[{e.id}]</span>
+                <span class="reference-text">
+                  {formatAuthors(e.author)}
+                  {y > 0 && <> ({y})</>}.
                   {' '}
-                  <a href={primaryUrl} rel="external noopener">link</a>.
-                </>
-              )}
-            </span>
-          </li>
-        );
-      })}
-    </ol>
+                  <em>{e.title}</em>.
+                  {e['container-title'] && <> {e['container-title']}.</>}
+                  {e.publisher && !e['container-title'] && <> {e.publisher}.</>}
+                  {e.volume && <> Vol. {e.volume}{e.issue && <>, no. {e.issue}</>}.</>}
+                  {e.page && <> pp. {e.page}.</>}
+                  {primaryUrl && (
+                    <>
+                      {' '}
+                      <a href={primaryUrl} rel="external noopener">link</a>.
+                    </>
+                  )}
+                </span>
+              </li>
+            );
+          })}
+        </ol>
+      </section>
+    )}
+
+    {hasSources && (
+      <section class="references-sources">
+        <h2>Cited sources</h2>
+        <p class="references-sources-lede">
+          External sources cited inline via <code>&lt;Citation&gt;</code>, grouped
+          by tier in descending authority.
+        </p>
+        <SourceArchive />
+      </section>
+    )}
   </article>
 </Base>
 
 <style>
+  .references-empty {
+    color: var(--color-text-muted);
+    font-style: italic;
+    padding: var(--space-3);
+    background: var(--color-bg-subtle);
+    border-radius: var(--radius-sm);
+    text-indent: 0;
+  }
+  .references-sources {
+    margin-top: var(--space-6);
+  }
+  .references-sources-lede {
+    color: var(--color-text-muted);
+    font-size: var(--text-sm);
+    text-indent: 0;
+  }
   .references-list {
     list-style: none;
     padding: 0;

package/recipes/04-component-library.md

@@ -64,7 +64,7 @@ Supported `type` values: `theorem`, `proposition`, `lemma`, `corollary`, `defini
 |---|---|---|
 | `Cite` | Inline citation linked to `/references` | `<Cite key="gu2024mamba" page="3" />` |
 | `XRef` | Cross-reference to a labeled element | `<XRef id="thm:zoh-stability" />` |
-| `Figure` | Image + caption + id | `<Figure src="/figures/week04/eigenvalues.svg" caption="…" id="fig-eig" />` |
+| `Figure` | Image/SVG + caption + id; local SVGs inline for a11y + dark mode (`alt`, `desc`) | `<Figure src="/figures/week04/eigenvalues.svg" caption="…" alt="…" id="fig-eig" />` |
 | `MarginNote` | Right-margin annotation (Tufte-style) | `<MarginNote>side comment</MarginNote>` |
 | `Sidenote` | Auto-numbered marginalia | `<Sidenote>numbered note</Sidenote>` |
 | `WeekRef` | Jump-link to a week chapter | `<WeekRef week={4} />` |

package/scripts/build-bib.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * scripts/build-bib.mjs — Bibliography pipeline (academic profile).
+ * scripts/build-bib.mjs — Bibliography + source-manifest pipeline.
  *
  * Reads bibliography.bib at scaffold root (BibTeX), parses via @citation-js,
  * emits src/data/references.json keyed by bibkey. The .bib path is
@@ -8,6 +8,12 @@
  * elsewhere (e.g. a shared `guides/shared/references.bib` outside the
  * Astro project — the post_transformers pattern).
  *
+ * v4.10.0 (#85): ALSO reads sources/manifest.yaml (tools-profile sources,
+ * cited inline via <Citation src>) and emits src/data/sources.json so the
+ * auto-injected /references page can surface them. The two steps are
+ * independent — a tools book with a manifest and no .bib still gets a
+ * populated /references.
+ *
  * Run on `prebuild` so every Astro build sees fresh bibliography data.
  * Idempotent: re-running with no .bib change produces a byte-identical
  * output (modulo timestamp, which we omit).
@@ -37,8 +43,10 @@ import { fileURLToPath } from 'node:url';
 // --help / -h: non-mutating (closes #14).
 const USAGE = `Usage: book-scaffold build-bib
 
-Bibliography pipeline (academic profile). Reads bibliography.bib (or
-BOOK_BIB_PATH if set), parses via @citation-js, emits src/data/references.json.
+Bibliography + source-manifest pipeline. Reads bibliography.bib (or
+BOOK_BIB_PATH if set) -> src/data/references.json (BibTeX via @citation-js),
+AND sources/manifest.yaml -> src/data/sources.json (tools-profile sources for
+the /references page). Either input may be absent.
 
 Env:
   BOOK_BIB_PATH      Override path to .bib file (default: ./bibliography.bib).
@@ -63,8 +71,10 @@ const BIB_PATH = process.env.BOOK_BIB_PATH
   ? resolve(process.cwd(), process.env.BOOK_BIB_PATH)
   : resolve(PROJECT_ROOT, 'bibliography.bib');
 const OUT_PATH = resolve(PROJECT_ROOT, 'src/data/references.json');
+const SOURCES_PATH = resolve(PROJECT_ROOT, 'sources/manifest.yaml');
+const SOURCES_OUT = resolve(PROJECT_ROOT, 'src/data/sources.json');
 
-async function main() {
+async function buildReferences() {
   // Graceful skip when the .bib file is absent (minimal/tools profile, or
   // an academic book that hasn't authored citations yet). Emits an empty
   // references.json so consumers can still `import refs from '...'`.
@@ -125,6 +135,45 @@ async function main() {
   );
 }
 
+// v4.10.0 (closes #85): tools-profile books keep their sources in
+// sources/manifest.yaml (cited inline via <Citation src="id" />); the BibTeX
+// path above never sees them, so the auto-injected /references page rendered
+// blank. Emit those sources to src/data/sources.json so references.astro can
+// surface them via the same defensive import.meta.glob it uses for
+// references.json. Absent manifest -> no file written (academic/minimal books
+// degrade to empty, exactly like a missing .bib). YAML is lazy-imported so the
+// --help / no-manifest paths stay dependency-free.
+async function buildSources() {
+  let yamlText;
+  try {
+    yamlText = await readFile(SOURCES_PATH, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return; // no manifest — nothing to emit
+    throw err;
+  }
+
+  const { parse } = await import('yaml');
+  const parsed = parse(yamlText);
+  // The manifest is a YAML array of source objects. Keep only well-formed
+  // entries (a string `id` is the citation key + the /references anchor target).
+  // A blank or comments-only manifest parses to null/undefined/[].
+  const sources = Array.isArray(parsed)
+    ? parsed.filter((s) => s && typeof s.id === 'string')
+    : [];
+
+  await mkdir(dirname(SOURCES_OUT), { recursive: true });
+  await writeFile(SOURCES_OUT, JSON.stringify(sources, null, 2) + '\n', 'utf8');
+  console.log(
+    `build-bib: ${sources.length} source${sources.length === 1 ? '' : 's'} -> ` +
+      `${SOURCES_OUT.replace(PROJECT_ROOT + '/', '')}`,
+  );
+}
+
+async function main() {
+  await buildReferences();
+  await buildSources();
+}
+
 main().catch((err) => {
   console.error(`build-bib: failed`);
   console.error(err);

package/scripts/build-figures.mjs

@@ -23,7 +23,17 @@
  * Falls back to pdftoppm (PNG @ 200 DPI) if pdftocairo produces an
  * unreasonably small (likely malformed) SVG.
  *
- * Idempotent: skips when the target SVG is newer than the source PDF.
+ * v4.11.0 (closes #84): each generated SVG gets a post-export rewrite
+ * (recolorSvg) that injects role="img" + a CSS-variable theming layer so one
+ * SVG serves light + dark. Neutral fills/strokes are remapped to
+ * var(--diagram-ink|paper|grid, <original>) via injected attribute-selector
+ * rules (the original attribute stays as the fallback); saturated accent colors
+ * are left untouched. A `%! no-theme` line in the source .tex opts a figure out.
+ * <Figure> inlines local SVGs so they track the in-page [data-theme] toggle.
+ *
+ * Idempotent: skips when the target SVG is newer than the source PDF (and the
+ * recolor itself is a no-op on an already-themed SVG, so re-runs after an
+ * upgrade safely theme pre-existing figures).
  * Run on `prebuild` so Astro always sees fresh figures.
  *
  * Graceful skip: when pdftocairo / pdftoppm aren't on PATH (e.g. Cloudflare
@@ -32,10 +42,11 @@
  * from PDFs on every `npm run dev`.
  */
 import { readdir, stat, mkdir } from 'node:fs/promises';
-import { existsSync, statSync } from 'node:fs';
+import { existsSync, statSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, resolve, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
+import { recolorSvg } from '../src/lib/figure.mjs';
 
 // --help / -h: non-mutating (closes #14).
 const USAGE = `Usage: book-scaffold build-figures
@@ -44,6 +55,10 @@ Figure pipeline. PDF -> SVG via pdftocairo (PNG fallback via pdftoppm at
 200dpi). Walks figures/ (or BOOK_FIGURES_PATH), emits to public/figures/.
 Graceful-skip if pdftocairo / pdftoppm not on PATH.
 
+Each SVG is rewritten to be accessible + dark-mode-aware: role="img" plus
+var(--diagram-ink|paper|grid, orig) fills (a "%! no-theme" line in the
+source .tex opts out). <Figure> inlines local SVGs so they track the theme.
+
 Env:
   BOOK_FIGURES_PATH   Override figures source (default: figures/).
 
@@ -179,6 +194,25 @@ function convertToSvg(srcPath, dstPath) {
   return size >= MIN_SVG_BYTES;
 }
 
+// v4.11.0 (#84): a `%! no-theme` line (anywhere in the source .tex) opts a
+// figure out of the dark-mode/a11y rewrite. Matches `%!` then `no-theme`,
+// tolerant of surrounding whitespace — distinct from BibTeX `%`-line comments.
+const NO_THEME_RE = /^\s*%!\s*no-theme\b/m;
+
+/**
+ * v4.11.0 (#84): apply the theming rewrite to a generated SVG in place.
+ * No-op (returns false) if the file is absent or recolorSvg leaves it unchanged
+ * (already themed / nothing neutral to remap). Idempotent.
+ */
+function themeIfSvg(svgPath, optOut) {
+  if (!existsSync(svgPath)) return false;
+  const original = readFileSync(svgPath, 'utf8');
+  const themed = recolorSvg(original, { optOut });
+  if (themed === original) return false;
+  writeFileSync(svgPath, themed, 'utf8');
+  return true;
+}
+
 function convertToPng(srcPath, pngStem) {
   // pdftoppm: -r 200 (DPI), -png, single page (first only).
   const r = spawnSync(
@@ -251,6 +285,7 @@ async function main() {
   let converted = 0;
   let skipped = 0;
   let pngFallback = 0;
+  let themed = 0;
 
   for (const { relPath } of pdfs) {
     total++;
@@ -259,7 +294,20 @@ async function main() {
     const svgPath = resolve(FIGURES_DST, `${stem}.svg`);
     const pngPath = resolve(FIGURES_DST, `${stem}.png`);
 
-    if (isUpToDate(srcPath, svgPath) || isUpToDate(srcPath, pngPath)) {
+    // Opt-out via `%! no-theme` in the source .tex (TikZ figures only).
+    const texSibling = resolve(FIGURES_SRC, `${stem}.tex`);
+    const optOut =
+      existsSync(texSibling) && NO_THEME_RE.test(readFileSync(texSibling, 'utf8'));
+
+    // Cached SVG: still run the (idempotent) rewrite so an upgrade themes
+    // pre-existing figures without forcing a source touch. PNG fallbacks are
+    // raster — nothing to theme.
+    if (isUpToDate(srcPath, svgPath)) {
+      if (themeIfSvg(svgPath, optOut)) themed++;
+      skipped++;
+      continue;
+    }
+    if (isUpToDate(srcPath, pngPath)) {
       skipped++;
       continue;
     }
@@ -269,14 +317,17 @@ async function main() {
     if (!svgOK) {
       convertToPng(srcPath, svgPath.replace(/\.svg$/, ''));
       pngFallback++;
+    } else if (themeIfSvg(svgPath, optOut)) {
+      themed++;
     }
     converted++;
   }
 
   const tikzNote = tikzCompiled > 0 ? `, ${tikzCompiled} tikz→pdf` : '';
+  const themedNote = themed > 0 ? `, ${themed} themed` : '';
   console.log(
     `build-figures: ${total} total, ${converted} converted ` +
-      `(${pngFallback} png fallback), ${skipped} cached${tikzNote}`,
+      `(${pngFallback} png fallback), ${skipped} cached${themedNote}${tikzNote}`,
   );
 }
 

package/src/lib/figure.mjs

@@ -0,0 +1,245 @@
+/**
+ * src/lib/figure.mjs — pure SVG transforms for the figure pipeline (v4.11.0, #84).
+ *
+ * Two concerns, one module so the `data-diagram-*` sentinels stay DRY:
+ *
+ *   • BUILD side — `recolorSvg()` rewrites a pdftocairo SVG to be theme-aware
+ *     (called by scripts/build-figures.mjs after each PDF→SVG conversion).
+ *   • RENDER side — `shouldInline()` + `assembleSvg()` let Figure.astro inline a
+ *     local pipeline SVG with a11y <title>/<desc> from the <Figure> props.
+ *
+ * Why a stylesheet, not presentation attributes: `var()` inside a presentation
+ * attribute (`fill="var(--x, …)"`) has unreliable browser support, whereas
+ * `var()` in a real <style> rule is universal. So `recolorSvg` injects an
+ * attribute-selector rule per distinct neutral color and never mutates a
+ * drawing element — the untouched `fill=""`/`stroke=""` attribute is the
+ * automatic fallback where `var()` is unsupported.
+ *
+ * Why inline (vs <img>): an SVG loaded via <img> is CSS-isolated, so a host
+ * page's `var(--diagram-*)` cannot reach it — it could only follow the OS
+ * prefers-color-scheme via the embedded <style data-diagram-theme>. Inlining
+ * puts the SVG in the host DOM, so the host's tokens.css (which tracks the
+ * in-page [data-theme] toggle) themes it. `assembleSvg` therefore STRIPS the
+ * embedded theme block so the host is the sole source of --diagram-*.
+ *
+ * Pure string ops only — no `node:` imports — so the module bundles for any
+ * consumer (Figure.astro imports it; fs lives in the .astro/.mjs callers).
+ */
+
+// Standalone self-theming defaults: used only when the SVG is NOT inlined
+// (direct file open / <img>). Hex literals because host CSS vars don't exist
+// there. Mirrors styles/tokens.css light + dark neutral values.
+export const DIAGRAM_THEME_CSS =
+  ':root{--diagram-ink:#1A1A19;--diagram-paper:#FDFCF9;--diagram-grid:#B5B3AA}' +
+  '@media (prefers-color-scheme:dark){:root{' +
+  '--diagram-ink:#E8E5DD;--diagram-paper:#1A1816;--diagram-grid:#3A3632}}';
+
+const DIAGRAM_VAR = {
+  ink: '--diagram-ink',
+  paper: '--diagram-paper',
+  grid: '--diagram-grid',
+};
+
+/**
+ * Parse a solid SVG paint into {r,g,b} in [0,1], or null when it is not a
+ * concrete color we should remap (none / url(...) / currentColor / inherit).
+ * Handles pdftocairo's `rgb(R%, G%, B%)` plus `rgb(r,g,b)` and #hex for safety.
+ */
+export function parseColor(value) {
+  if (typeof value !== 'string') return null;
+  const v = value.trim();
+  let m;
+  if ((m = v.match(/^rgb\(\s*([\d.]+)%\s*,\s*([\d.]+)%\s*,\s*([\d.]+)%\s*\)$/i))) {
+    return { r: +m[1] / 100, g: +m[2] / 100, b: +m[3] / 100 };
+  }
+  if ((m = v.match(/^rgb\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*\)$/i))) {
+    return { r: +m[1] / 255, g: +m[2] / 255, b: +m[3] / 255 };
+  }
+  if ((m = v.match(/^#([0-9a-f]{3})$/i))) {
+    const [a, b, c] = m[1];
+    return { r: parseInt(a + a, 16) / 255, g: parseInt(b + b, 16) / 255, b: parseInt(c + c, 16) / 255 };
+  }
+  if ((m = v.match(/^#([0-9a-f]{6})$/i))) {
+    return {
+      r: parseInt(m[1].slice(0, 2), 16) / 255,
+      g: parseInt(m[1].slice(2, 4), 16) / 255,
+      b: parseInt(m[1].slice(4, 6), 16) / 255,
+    };
+  }
+  return null;
+}
+
+/**
+ * Classify a color as 'ink' | 'paper' | 'grid', or null to leave it untouched.
+ * Saturated colors (chroma over threshold) are intentional accents and keep
+ * their hue across themes; only near-neutral colors are remapped, split by
+ * relative luminance into dark ink / light paper / mid gridlines.
+ */
+export function classifyColor(value) {
+  const c = parseColor(value);
+  if (!c) return null;
+  const chroma = Math.max(c.r, c.g, c.b) - Math.min(c.r, c.g, c.b);
+  if (chroma > 0.12) return null; // saturated accent — preserve as authored
+  const lum = 0.2126 * c.r + 0.7152 * c.g + 0.0722 * c.b;
+  if (lum < 0.3) return 'ink';
+  if (lum > 0.9) return 'paper';
+  return 'grid';
+}
+
+// Escape a value for use inside a CSS [attr="…"] selector string.
+function cssAttrEscape(s) {
+  return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+/**
+ * Rewrite a pdftocairo SVG to be theme-aware + carry role="img". Pure and
+ * idempotent (a second pass is a no-op). `opts.optOut` short-circuits, returning
+ * the input unchanged (the `%! no-theme` authoring escape hatch).
+ *
+ * Injects, right after the opening <svg> tag:
+ *   <style data-diagram-theme> — standalone var defaults + @media(dark).
+ *   <style data-diagram-map>   — `[fill="C"]{fill:var(--diagram-X, C)}` … per
+ *                                 distinct neutral color C. Elements are NOT
+ *                                 modified; the attribute stays as fallback.
+ */
+export function recolorSvg(svg, { optOut = false } = {}) {
+  if (typeof svg !== 'string') return svg;
+  if (optOut || svg.includes('data-diagram-map')) return svg;
+
+  const openMatch = svg.match(/<svg\b[^>]*>/i);
+  if (!openMatch) return svg;
+
+  // Distinct concrete colors used as fill="" / stroke="" attributes.
+  const found = new Map(); // original string → class
+  const attrRe = /\b(?:fill|stroke)="([^"]+)"/g;
+  let am;
+  while ((am = attrRe.exec(svg)) !== null) {
+    if (found.has(am[1])) continue;
+    const cls = classifyColor(am[1]);
+    if (cls) found.set(am[1], cls);
+  }
+
+  let openTag = openMatch[0];
+  if (!/\srole=/i.test(openTag)) openTag = openTag.replace(/<svg\b/i, '<svg role="img"');
+
+  // Nothing neutral to remap — still surface role="img" for a11y, no <style>.
+  if (found.size === 0) {
+    return openTag === openMatch[0]
+      ? svg
+      : svg.slice(0, openMatch.index) + openTag + svg.slice(openMatch.index + openMatch[0].length);
+  }
+
+  let mapCss = '';
+  for (const [orig, cls] of found) {
+    const v = DIAGRAM_VAR[cls];
+    const sel = cssAttrEscape(orig);
+    mapCss +=
+      `[fill="${sel}"]{fill:var(${v}, ${orig})}` +
+      `[stroke="${sel}"]{stroke:var(${v}, ${orig})}`;
+  }
+
+  const styleBlocks =
+    `<style data-diagram-theme>${DIAGRAM_THEME_CSS}</style>` +
+    `<style data-diagram-map>${mapCss}</style>`;
+
+  return (
+    svg.slice(0, openMatch.index) +
+    openTag +
+    styleBlocks +
+    svg.slice(openMatch.index + openMatch[0].length)
+  );
+}
+
+// ── Render side ────────────────────────────────────────────────────────────
+
+/** Should <Figure> inline `src` (local pipeline .svg) vs render <img>? */
+export function shouldInline(src) {
+  return (
+    typeof src === 'string' &&
+    src.startsWith('/') &&
+    !src.startsWith('//') && // protocol-relative = remote host
+    /\.svg$/i.test(src)
+  );
+}
+
+const THEME_BLOCK_RE = /<style\b[^>]*\bdata-diagram-theme\b[^>]*>[\s\S]*?<\/style>/gi;
+
+/** Remove the standalone self-theming block so the host tokens.css is the sole
+ *  source of --diagram-* once the SVG is inlined into the page. */
+export function stripThemeBlock(svg) {
+  return typeof svg === 'string' ? svg.replace(THEME_BLOCK_RE, '') : svg;
+}
+
+function escapeXml(s) {
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function ensureSvgAttr(openTag, name, value) {
+  const re = new RegExp(`\\s${name}=`, 'i');
+  if (re.test(openTag)) return openTag;
+  return openTag.replace(/<svg\b/i, `<svg ${name}="${value}"`);
+}
+
+function setSvgAttr(openTag, name, value) {
+  const re = new RegExp(`\\s${name}="[^"]*"`, 'i');
+  if (re.test(openTag)) return openTag.replace(re, ` ${name}="${value}"`);
+  return openTag.replace(/<svg\b/i, `<svg ${name}="${value}"`);
+}
+
+function mergeSvgStyle(openTag, css) {
+  const re = /\sstyle="([^"]*)"/i;
+  const m = openTag.match(re);
+  if (m) {
+    const existing = m[1].trim().replace(/;\s*$/, '');
+    return openTag.replace(re, ` style="${existing ? existing + ';' : ''}${css}"`);
+  }
+  return openTag.replace(/<svg\b/i, `<svg style="${css}"`);
+}
+
+/**
+ * Prepare a raw pipeline SVG for inline embedding in <Figure>:
+ *   - strip the standalone <style data-diagram-theme> (host tokens.css themes it);
+ *   - replace any pre-existing <title>/<desc> with ones from the call-site props
+ *     (caption → <title>, desc ?? alt → <desc>) and wire aria-labelledby;
+ *   - ensure role="img" and a responsive width on the root <svg>.
+ * Pure string transform; output is a trusted local build artifact (set:html).
+ */
+export function assembleSvg(raw, opts = {}) {
+  const { caption, alt, desc, width = '100%', idBase = 'figure' } = opts;
+  if (typeof raw !== 'string') return '';
+
+  let svg = stripThemeBlock(raw);
+  const openMatch = svg.match(/<svg\b[^>]*>/i);
+  if (!openMatch) return svg;
+
+  let openTag = openMatch[0];
+  let body = svg
+    .slice(openMatch.index + openTag.length)
+    .replace(/<title\b[^>]*>[\s\S]*?<\/title>/gi, '')
+    .replace(/<desc\b[^>]*>[\s\S]*?<\/desc>/gi, '');
+
+  const titleText = caption ?? alt ?? '';
+  const descText = desc ?? (alt && alt !== titleText ? alt : '');
+  const id = String(idBase).replace(/[^a-zA-Z0-9_-]/g, '-');
+
+  const a11y = [];
+  const labelledby = [];
+  if (titleText) {
+    a11y.push(`<title id="${id}-title">${escapeXml(titleText)}</title>`);
+    labelledby.push(`${id}-title`);
+  }
+  if (descText) {
+    a11y.push(`<desc id="${id}-desc">${escapeXml(descText)}</desc>`);
+    labelledby.push(`${id}-desc`);
+  }
+
+  openTag = ensureSvgAttr(openTag, 'role', 'img');
+  if (labelledby.length) openTag = setSvgAttr(openTag, 'aria-labelledby', labelledby.join(' '));
+  openTag = mergeSvgStyle(openTag, `width:${width};max-width:100%;height:auto`);
+
+  return `${svg.slice(0, openMatch.index)}${openTag}${a11y.join('')}${body}`;
+}

package/styles/tokens.css

@@ -51,6 +51,15 @@
   --callout-worked:   var(--warm-plum);
   --callout-learn:    var(--warm-gold);
 
+  /* Diagram semantic roles (v4.11.0, #84): theme-aware TikZ→SVG figures.
+   * build-figures remaps an SVG's neutral fills/strokes to these via
+   * var(--diagram-*, <original>); <Figure> inlines the SVG so this cascade
+   * reaches it. They point at existing roles, so they auto-flip in dark mode
+   * (no dark-block edits) — ink↔text, paper↔page bg, grid↔border. */
+  --diagram-ink:      var(--color-text);
+  --diagram-paper:    var(--color-bg);
+  --diagram-grid:     var(--color-border);
+
   /* ===== Typography scale ===== */
   --font-body: 'Roboto Variable', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
   --font-code: 'Source Code Pro Variable', ui-monospace, SFMono-Regular, 'SF Mono', Menlo, monospace;