@brandon_m_behring/book-scaffold-astro 4.23.0 → 4.25.0

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.23.0",
+  "version": "4.25.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -59,13 +59,17 @@
     "./components/Diagnostic.astro": "./components/Diagnostic.astro",
     "./components/Divergence.astro": "./components/Divergence.astro",
     "./components/DynConnect.astro": "./components/DynConnect.astro",
+    "./components/Epigraph.astro": "./components/Epigraph.astro",
+    "./components/EvidenceTag.astro": "./components/EvidenceTag.astro",
     "./components/ExampleBox.astro": "./components/ExampleBox.astro",
     "./components/Exercise.astro": "./components/Exercise.astro",
     "./components/ExerciseSolutions.astro": "./components/ExerciseSolutions.astro",
     "./components/Figure.astro": "./components/Figure.astro",
     "./components/InsightBox.astro": "./components/InsightBox.astro",
     "./components/KeyIdea.astro": "./components/KeyIdea.astro",
+    "./components/MarginFigure.astro": "./components/MarginFigure.astro",
     "./components/MarginNote.astro": "./components/MarginNote.astro",
+    "./components/Newthought.astro": "./components/Newthought.astro",
     "./components/NoteBox.astro": "./components/NoteBox.astro",
     "./components/ObjectiveMap.astro": "./components/ObjectiveMap.astro",
     "./components/OpenQuestion.astro": "./components/OpenQuestion.astro",
@@ -82,6 +86,7 @@
     "./components/Rationale.astro": "./components/Rationale.astro",
     "./components/Recovery.astro": "./components/Recovery.astro",
     "./components/ResultBox.astro": "./components/ResultBox.astro",
+    "./components/SectionMap.astro": "./components/SectionMap.astro",
     "./components/Sidebar.astro": "./components/Sidebar.astro",
     "./components/Sidenote.astro": "./components/Sidenote.astro",
     "./components/SkillBox.astro": "./components/SkillBox.astro",
@@ -111,6 +116,10 @@
       "types": "./dist/components/Flashcards.d.ts",
       "import": "./dist/components/Flashcards.mjs"
     },
+    "./components/SectionMap": {
+      "types": "./dist/components/SectionMap.d.ts",
+      "import": "./dist/components/SectionMap.mjs"
+    },
     "./components/WarnBox.astro": "./components/WarnBox.astro",
     "./components/WeekRef.astro": "./components/WeekRef.astro",
     "./components/WorkedExample.astro": "./components/WorkedExample.astro",
@@ -127,6 +136,7 @@
     "./styles/tool-filter.css": "./styles/tool-filter.css",
     "./styles/exam-runner.css": "./styles/exam-runner.css",
     "./styles/flashcards.css": "./styles/flashcards.css",
+    "./styles/section-map.css": "./styles/section-map.css",
     "./layouts/Base.astro": "./layouts/Base.astro",
     "./layouts/Chapter.astro": "./layouts/Chapter.astro",
     "./lib": {

package/recipes/04-component-library.md

@@ -65,8 +65,12 @@ 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/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>` |
+| `MarginFigure` | A `Figure` that **floats into the right gutter** (Tufte margin figure; ≥64rem, inline on mobile). Same props as `Figure`; rendering delegated to it. For full-bleed use `<Figure class="wide">` | `<MarginFigure src="/figures/week04/eig.svg" caption="…" alt="…" id="fig-eig-m" />` |
+| `MarginNote` | **Inline** colored callout in the text column (does **not** float to the margin, despite the name) — load-bearing aside the reader must see | `<MarginNote>side comment</MarginNote>` |
+| `Sidenote` | Auto-numbered Tufte marginalia that **floats into the right gutter** on desktop (inline on mobile) | `<Sidenote>numbered note</Sidenote>` |
+| `EvidenceTag` | Inline claim-confidence pill after a claim (`verified`/`inference`/`audit-corrected`) | `<EvidenceTag kind="verified" /> … <EvidenceTag kind="inference" />` |
+| `Newthought` | Tufte run-in small-caps section opener | `<p><Newthought>In practice</Newthought>, …</p>` |
+| `Epigraph` | Chapter-opening italic quotation with right-aligned attribution | `<Epigraph>…<Fragment slot="attribution">Hamming</Fragment></Epigraph>` |
 | `WeekRef` | Jump-link to a week chapter | `<WeekRef week={4} />` |
 | `CodeRef` | GitHub-deep-link to file:line | `<CodeRef path="experiments/jax/foo.py" line={42} />` |
 | `CodeBlock` | Embed code-file range with syntax highlight | `<CodeBlock src="…" lines="10-30" />` |

package/recipes/16-tikz-figures.md

@@ -95,6 +95,45 @@ Common failures:
 
 If you hit friction with the TikZ pipeline (a TikZ feature that doesn't compile, an obscure error message, a workflow pattern that doesn't fit), file an issue at https://github.com/brandon-behring/book-scaffold-astro/issues with the `consumer:<your-workspace>` label. v4.x is the iteration window.
 
+## Margin & full-width figure placement (1d)
+
+Once a figure exists, three placements are available — all reuse the existing Tufte float + gutter technique (the same one `Sidenote`/SectionMap use); none introduce a grid.
+
+**In the running text (default).** Plain `<Figure>` constrained to the main measure:
+
+```mdx
+<Figure src="/figures/topic/diagram.svg" caption="…" alt="…" id="fig-x" />
+```
+
+**In the right margin** — `<MarginFigure>` floats into the gutter at ≥64rem and reflows inline below on mobile. Same props as `<Figure>` (rendering is delegated to it); `width` defaults to `100%` of the ~28ch gutter column, and the caption shrinks:
+
+```mdx
+import MarginFigure from '@brandon_m_behring/book-scaffold-astro/components/MarginFigure.astro';
+
+<MarginFigure src="/figures/topic/diagram.svg" caption="A small aside figure." alt="…" id="fig-x-margin" />
+```
+
+**Full-bleed** — a wide figure/table/code block that spans the gutter column too. Use the canonical `.wide` escape (or its alias `.column-page`):
+
+```mdx
+<Figure src="/figures/topic/wide-plot.svg" caption="…" alt="…" id="fig-wide" class="wide" />
+```
+
+**Generic gutter block** — to float a non-figure block (a small note, a key figure number) into the margin, add `class="column-margin"` to any element. It uses the identical gutter float.
+
+### Per-page width knob: `layout: wide`
+
+For a chapter that's figure- or table-heavy, widen the **main text measure** via an optional frontmatter field (closed enum `default` | `wide`, accepted by every profile):
+
+```yaml
+---
+title: "Architecture Atlas"
+layout: wide      # widens --measure-main to 80ch; omit (or 'default') for the standard 65ch
+---
+```
+
+`Chapter.astro` threads this as `data-layout="wide"` on `<article class="prose">`, and `layout.css` maps `.prose[data-layout="wide"] { --measure-main: 80ch }`. Omitting the field (or setting `layout: default`) emits no attribute and applies no rule — existing chapters render unchanged. A value outside the enum fails the build at content load.
+
 ## See also
 
 - `recipes/06-figures.md` — overall figure pipeline + matplotlib/svg sources

package/src/lib/section-map.ts

@@ -0,0 +1,88 @@
+/**
+ * section-map.ts — PURE heading-selection + scrollspy logic for the right-gutter
+ * "On this page" section map (#section-map).
+ *
+ * No DOM, no Preact: this is the testable core under both ChapterTOC.astro (the
+ * collapsed mobile fallback) and the SectionMap island (the sticky gutter nav).
+ * Two pure, total functions:
+ *
+ *   - tocHeadings:  the ONE filter (h2+h3) that both the fallback TOC and the
+ *                   gutter map share — a single source of truth so the two
+ *                   never disagree about which headings are "on this page".
+ *   - pickActive:   given the headings currently intersecting the viewport (slug
+ *                   + viewport-relative top), choose which one is "active". The
+ *                   island feeds it IntersectionObserver state; node:test feeds
+ *                   it plain arrays. Browser geometry stays OUT of this file.
+ *
+ * Both are unit-tested in tests/section-map.test.mjs (node:test, no browser),
+ * mirroring exam-engine.ts.
+ */
+
+import type { MarkdownHeading } from 'astro';
+
+/**
+ * Filter a chapter's headings to the TOC set: depth 2–3 only. h1 is the chapter
+ * title (rendered by ChapterHeader, not the body) and h4+ is noise in an anchor
+ * list. This is the shared contract — ChapterTOC.astro and SectionMap.astro both
+ * call it so the fallback and the gutter map carry IDENTICAL entries. Pure: it
+ * copies (filter) rather than mutating the input.
+ */
+export function tocHeadings(headings: MarkdownHeading[]): MarkdownHeading[] {
+  return headings.filter((h) => h.depth >= 2 && h.depth <= 3);
+}
+
+/**
+ * One visible heading, as the island measures it: its slug and its
+ * viewport-relative top (CSS pixels — `getBoundingClientRect().top`). A negative
+ * `top` means the heading has scrolled above the top of the viewport.
+ */
+export interface VisibleHeading {
+  slug: string;
+  /** Viewport-relative top in px (negative = scrolled above the fold). */
+  top: number;
+}
+
+/**
+ * Choose the active section slug from the headings currently intersecting the
+ * viewport.
+ *
+ * Rule (a stable, total scrollspy):
+ *   1. Prefer the topmost heading at or below the top of the viewport — the
+ *      visible heading with the SMALLEST non-negative `top`. That's the section
+ *      the reader has just scrolled to / is reading into.
+ *   2. If every visible heading is above the fold (all `top` negative — e.g. a
+ *      heading STRADDLING the top edge: its top is slightly negative but its box
+ *      still overlaps the top zone, so it's intersecting yet has no non-negative
+ *      sibling below it), fall back to the one nearest the fold from above: the
+ *      GREATEST `top` (closest to 0 from the negative side). That keeps the
+ *      enclosing section lit instead of going dark mid-section. (A heading whose
+ *      box FULLY scrolled above the top has left `inView` entirely — it isn't in
+ *      `visible` at all, and is handled by the empty-set → `prev` branch below.)
+ *   3. If NOTHING is visible (the observer reports an empty set — between two
+ *      sparse intersections, or scrolled past the last heading), retain `prev`
+ *      so the highlight is sticky rather than flickering off.
+ *
+ * Pure + total: no DOM, no throw, deterministic. Ties (equal `top`) resolve to
+ * the first in iteration order, which the island passes in document order.
+ */
+export function pickActive(
+  visible: ReadonlyArray<VisibleHeading>,
+  prev: string | null,
+): string | null {
+  if (visible.length === 0) return prev;
+
+  let bestNonNeg: VisibleHeading | null = null; // smallest top >= 0
+  let bestAbove: VisibleHeading | null = null; // greatest top < 0
+  for (const h of visible) {
+    if (h.top >= 0) {
+      if (bestNonNeg === null || h.top < bestNonNeg.top) bestNonNeg = h;
+    } else {
+      if (bestAbove === null || h.top > bestAbove.top) bestAbove = h;
+    }
+  }
+
+  if (bestNonNeg !== null) return bestNonNeg.slug;
+  // All above the fold: the one just above the top edge keeps its section lit.
+  if (bestAbove !== null) return bestAbove.slug;
+  return prev;
+}

package/src/profiles/academic.ts

@@ -31,7 +31,7 @@ export const academicProfile = defineProfile({
     flashcards: false, // v4.22.0 #116: opt-in per book; requires src/content/glossary/
     landing: true,          // v4.5.0: auto-inject minimal root landing; consumers override via src/pages/index.astro
   },
-  styles: ['tokens.css', 'layout.css', 'callouts.css', 'chapter.css', 'typography.css', 'print.css'],
+  styles: ['tokens.css', 'layout.css', 'callouts.css', 'chapter.css', 'typography.css', 'print.css', 'section-map.css'],
   katex: true,
   chaptersRenderer: academicChaptersRenderer,   // v3.7.0 (#35) — owns /chapters semantics if consumer opts in via routes.chapters
   // v4.6.0 (#76 Secondary): exclude /print/ from sitemap — print-friendly

package/src/profiles/course-notes.ts

@@ -33,7 +33,7 @@ export const courseNotesProfile = defineProfile({
     flashcards: false, // v4.22.0 #116: opt-in per book; requires src/content/glossary/
     landing: true,          // v4.5.0: auto-inject minimal root landing
   },
-  styles: ['tokens.css', 'layout.css', 'callouts.css', 'chapter.css', 'typography.css', 'print.css'],
+  styles: ['tokens.css', 'layout.css', 'callouts.css', 'chapter.css', 'typography.css', 'print.css', 'section-map.css'],
   // v3.7.0 (#35): course-notes schema has tools-style fields (chapter, volatility, sources) — fallback renderer dispatches via tools renderer
   chaptersRenderer: fallbackChaptersRenderer,
   // v4.6.0 (#76 Secondary): exclude /print/ from sitemap — print-friendly

package/src/profiles/minimal.ts

@@ -28,7 +28,7 @@ export const minimalProfile = defineProfile({
     flashcards: false, // v4.22.0 #116: opt-in per book; requires src/content/glossary/
     landing: true,          // v4.5.0: auto-inject minimal root landing
   },
-  styles: ['tokens.css', 'layout.css', 'callouts.css', 'chapter.css', 'typography.css', 'print.css'],
+  styles: ['tokens.css', 'layout.css', 'callouts.css', 'chapter.css', 'typography.css', 'print.css', 'section-map.css'],
   // v3.7.0 (#35): minimal aliases tools schema; fallback renderer field-dispatches if a consumer opts into routes.chapters
   chaptersRenderer: fallbackChaptersRenderer,
 });

package/src/profiles/research-portfolio.ts

@@ -44,7 +44,7 @@ export const researchPortfolioProfile = defineProfile({
     flashcards: false, // v4.22.0 #116: opt-in per book; requires src/content/glossary/
     landing: true,               // v4.5.0: auto-inject minimal root landing
   },
-  styles: ['tokens.css', 'layout.css', 'callouts.css', 'chapter.css', 'typography.css', 'print.css'],
+  styles: ['tokens.css', 'layout.css', 'callouts.css', 'chapter.css', 'typography.css', 'print.css', 'section-map.css'],
   katex: true,                   // math is common in research content
   // v3.7.0 (#35): portfolio schema is a union of academic + tools shapes — fallback renderer dispatches per chapter via field presence
   chaptersRenderer: fallbackChaptersRenderer,

package/src/profiles/tools.ts

@@ -31,6 +31,7 @@ export const toolsProfile = defineProfile({
   styles: [
     'tokens.css', 'layout.css', 'callouts.css', 'chapter.css',
     'typography.css', 'print.css', 'convergence.css', 'tool-filter.css',
+    'section-map.css',
   ],
   chaptersRenderer: toolsChaptersRenderer,   // v3.7.0 (#35) — owns /chapters semantics for tools shape
 });

package/src/schemas.ts

@@ -70,6 +70,17 @@ export const chapterStatus = [
   'planned',
 ] as const;
 
+// ===== Per-page width knob (1d) — any profile =====
+//
+// Optional `layout:` on EVERY chapter schema below. A CLOSED enum (a typo'd
+// value fails loud at content load — that IS the validation, no assertEnumProp
+// needed). Threaded by Chapter.astro as `data-layout` on <article class="prose">;
+// layout.css maps `[data-layout="wide"]` → a wider --measure-main. ADDITIVE:
+// 'default' (or an omitted field) applies no rule, so existing chapters render
+// byte-identically. 'wide' widens the main text measure (e.g. 80ch) for
+// figure-heavy or table-heavy chapters.
+export const layoutModes = ['default', 'wide'] as const;
+
 // ===== Provenance (v4.8.0) — process-as-artifact audit trail =====
 //
 // Optional per-chapter block attached to EVERY profile schema below.
@@ -117,6 +128,7 @@ export const academicChapterSchema = z.object({
   part: z.enum(academicParts),
   title: z.string().min(1),
   slug: z.string().optional(),                 // v4.9.0: explicit URL slug override (else filename → entry.id)
+  layout: z.enum(layoutModes).optional(),      // 1d: per-page width knob (default measure | 'wide'); threaded as data-layout
   status: z.enum(chapterStatus),
   roadmap_lines: z.tuple([z.number().int(), z.number().int()]).optional(),
   code_path: z.string().optional(),
@@ -138,6 +150,7 @@ export const academicChapterSchema = z.object({
 export const toolsChapterSchema = z.object({
   title: z.string().min(1),
   slug: z.string().optional(),                 // v4.9.0: explicit URL slug override (else filename → entry.id)
+  layout: z.enum(layoutModes).optional(),      // 1d: per-page width knob (default measure | 'wide'); threaded as data-layout
   part: z.number().int().min(0).max(10),
   chapter: z.number().int().min(0).max(99),
   volatility: z.enum(volatilityLevels),
@@ -181,6 +194,7 @@ export const courseNotesChapterSchema = z.object({
   // Identity
   title: z.string().min(1),
   slug: z.string().optional(),                 // v4.9.0: explicit URL slug override (else filename → entry.id)
+  layout: z.enum(layoutModes).optional(),      // 1d: per-page width knob (default measure | 'wide'); threaded as data-layout
   chapter: z.number().int().min(0).max(99),
   part: z.number().int().min(0).max(20).default(1),
   description: z.string().optional(),
@@ -244,6 +258,7 @@ export const researchPortfolioChapterSchema = z.object({
   // Identity
   title: z.string().min(1),
   slug: z.string().optional(),                 // explicit slug override (otherwise filename)
+  layout: z.enum(layoutModes).optional(),      // 1d: per-page width knob (default measure | 'wide'); threaded as data-layout
   description: z.string().optional(),
 
   // Hierarchy — accept either academic-style or tools-style; all optional.

package/styles/layout.css

@@ -154,3 +154,67 @@
   max-width: none !important;
   width: 100%;
 }
+
+/* ===== 1d: additive figure/content placement + per-page width knob =====
+ *
+ * STRICTLY ADDITIVE. Nothing here changes `.prose`'s block layout or the
+ * `.sidenote` float — the gutter placements below REUSE the same Tufte
+ * float + negative-margin-right technique `.sidenote` and SectionMap use
+ * (the full float→grid migration is deferred). All values are tokens.
+ *
+ * .column-margin   — generic "float a block into the right gutter" utility
+ *                    (the un-figure version of MarginFigure's placement).
+ * .margin-figure   — MarginFigure's wrapper: the same gutter float, tuned for
+ *                    a figure (small caption, no italic).
+ * .column-page     — full-width breakout; an ALIAS of `.wide` (which already
+ *                    does the max-width override). Use either.
+ * .prose[data-layout="wide"] — the per-page width knob: widen the main text
+ *                    measure. Only applies when Chapter.astro emits
+ *                    data-layout="wide" from frontmatter `layout: wide`.
+ */
+
+/* Float a block into the right gutter — same mechanism as .sidenote: the
+ * negative margin-right pulls the box into the --measure-side column so it
+ * sits BESIDE the running text instead of pushing the measure. Shown only at
+ * >= 64rem (the gutter breakpoint, matching SectionMap); below that it reflows
+ * inline in document flow (the rule simply doesn't apply). */
+@media (min-width: 64rem) {
+  .column-margin,
+  .margin-figure {
+    float: right;
+    clear: right;
+    width: var(--measure-side);
+    margin-right: calc(-1 * (var(--measure-side) + var(--space-6)));
+    margin-top: 0.3rem;
+    margin-bottom: var(--space-3);
+  }
+}
+
+/* MarginFigure: a Figure wrapped for the gutter. The wrapped <figure> fills
+ * the column; the caption stays small (margin context = less room) without
+ * touching the global .figure/figcaption rules. */
+.margin-figure > .figure {
+  margin: 0;
+  max-width: none;
+}
+.margin-figure figcaption {
+  font-size: var(--text-xs);
+  line-height: var(--leading-normal);
+}
+
+/* Full-width breakout: an alias of `.wide` (figures, wide tables, code that
+ * need the whole container including the gutter column). `.wide` is the
+ * canonical escape; `.column-page` reads better next to `.column-margin`. */
+.column-page {
+  max-width: none !important;
+  width: 100%;
+}
+
+/* Per-page width knob (frontmatter `layout: wide`). Widen ONLY the main text
+ * measure; the container + gutter math in `.prose` already references
+ * --measure-main, so this one override flows through. Additive: absent
+ * data-layout (or "default") matches nothing, so existing chapters are
+ * unaffected. 80ch matches the wide-desktop tier's main measure (tokens.css). */
+.prose[data-layout="wide"] {
+  --measure-main: 80ch;
+}

package/styles/section-map.css

@@ -0,0 +1,130 @@
+/* section-map.css — right-gutter sticky "On this page" scrollspy (#section-map).
+ *
+ * The SectionMap island is framework-component-driven markup outside Astro's
+ * style scoping, so its nav ships as a plain stylesheet (like exam-runner.css /
+ * flashcards.css). Colors via design tokens only — recolors with [data-theme]
+ * automatically.
+ *
+ * Layout: the nav lives in the .prose RIGHT gutter — the same ~28ch column the
+ * sidenotes float into (layout.css). It uses the identical float + negative
+ * margin-right technique so it sits beside the running text rather than pushing
+ * it, and is `position: sticky` so it tracks the reader down the page.
+ *
+ * Visibility handshake with ChapterTOC (chapter.css): the gutter map shows ONLY
+ * at >= 64rem (the sidebar/gutter breakpoint, where there's room for a margin
+ * column); the collapsed top ChapterTOC is the < 64rem fallback. Each is hidden
+ * in the other's range so they never double-show. At >= 64rem the handshake is
+ * ALSO sidenote-aware: the gutter is a single column the sidenotes already float
+ * into (layout.css), so a chapter with <Sidenote>s yields it back to them — the
+ * map hides and ChapterTOC stays as the nav (see the @media block below, #151).
+ */
+
+/* Default (< 64rem): the gutter has no room — the collapsed ChapterTOC is the
+ * fallback. Hidden until the breakpoint opens it below. */
+.section-map {
+  display: none;
+}
+
+/* The island's mount node is a zero-footprint anchor; never shown. */
+.section-map-mount {
+  display: none !important;
+}
+
+@media (min-width: 64rem) {
+  /* Sidenote-aware handshake (#151). The gutter map and <Sidenote>s float into
+   * the SAME ~28ch right column (layout.css), so they cannot coexist there:
+   *   - A chapter WITH sidenotes → the gutter belongs to the sidenotes; suppress
+   *     the map (else its sticky float overlaps the notes on scroll) and keep the
+   *     collapsed ChapterTOC visible as the nav.
+   *   - A chapter with NO sidenotes → the gutter map IS the nav; hide the
+   *     collapsed top ChapterTOC so the two don't double-show (the original
+   *     handshake).
+   * The suppressed .section-map stays in the DOM (display:none) — its island
+   * still runs but only toggles hidden links, which is harmless. (:has() is
+   * within the scaffold's CSS baseline — tokens.css already uses it.) */
+  .prose:has(.sidenote) .section-map {
+    display: none;
+  }
+
+  .prose:not(:has(.sidenote)) .chapter-toc {
+    display: none;
+  }
+
+  .section-map {
+    display: block;
+    /* Float into the right margin — same technique as .sidenote: the negative
+     * margin-right pulls it into the gutter column so it sits beside the text
+     * instead of pushing the measure. */
+    float: right;
+    clear: right;
+    width: var(--measure-side);
+    margin-right: calc(-1 * (var(--measure-side) + var(--space-6)));
+    margin-top: 0.3rem;
+    margin-bottom: var(--space-3);
+    padding-left: var(--space-3);
+    border-left: var(--border-bar) solid var(--color-border);
+    /* Sticky: stay in view as the reader scrolls; cap height + scroll its own
+     * overflow so a long TOC never runs off-screen. */
+    position: sticky;
+    top: var(--space-8);
+    max-height: calc(100vh - 2 * var(--space-8));
+    overflow: auto;
+    font-size: var(--text-sm);
+    line-height: var(--leading-normal);
+  }
+
+  .section-map-label {
+    margin: 0 0 var(--space-1);
+    font-size: var(--text-xs);
+    color: var(--color-text-muted);
+    font-style: italic;
+  }
+
+  .section-map-title {
+    margin: 0 0 var(--space-2);
+    font-size: var(--text-xs);
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    color: var(--color-text-muted);
+    font-weight: 600;
+  }
+
+  .section-map-list {
+    list-style: none;
+    padding-left: 0;
+    margin: 0;
+  }
+
+  .section-map-list li {
+    margin: var(--space-1) 0;
+  }
+
+  .section-map-list a {
+    display: block;
+    text-decoration: none;
+    color: var(--color-text-muted);
+    /* The active link gains a left border (border-bar); reserve its width on
+     * every link so lighting one doesn't shift the others horizontally. */
+    border-left: var(--border-bar) solid transparent;
+    padding-left: var(--space-2);
+    margin-left: calc(-1 * var(--space-2));
+    transition: color 120ms ease;
+  }
+
+  /* h3 links indent under their h2. */
+  .section-map-list a.toc-h3 {
+    padding-left: var(--space-5);
+  }
+
+  .section-map-list a:hover {
+    color: var(--color-link);
+  }
+
+  /* Active section (scrollspy): the island sets aria-current="page" + .active. */
+  .section-map-list a.active,
+  .section-map-list a[aria-current='page'] {
+    color: var(--color-link);
+    border-left-color: var(--color-link);
+    font-weight: 500;
+  }
+}

package/styles/typography.css

@@ -145,3 +145,54 @@ th {
   font-weight: 600;
   color: var(--color-heading);
 }
+
+/* ===== Tufte typographic openers (v4.25.0) =====
+ * Ported from the LaTeX book (interview-preamble-tufte.sty): the run-in
+ * <Newthought> section opener and the chapter-opening <Epigraph>. Markup is in
+ * the matching .astro components; styling stays here so it's always loaded.
+ * Token-only colors — recolor with [data-theme] automatically. */
+
+/* <Newthought>: run-in small-caps opener. TRUE small-caps via the smcp OpenType
+ * feature (the Roboto variable face ships it) — font-variant: small-caps would
+ * synthesize faux small-caps by scaling capitals. Slightly heavier + tracked
+ * out for the Tufte look. */
+.newthought {
+  font-feature-settings: "smcp";
+  font-weight: 600;
+  letter-spacing: 0.05em;
+}
+
+/* <Epigraph>: italic chapter-opening quotation with a right-aligned
+ * attribution. Inherits the running measure from .prose / --measure-main rather
+ * than forcing a width that would fight the Tufte measure. */
+.epigraph {
+  margin: 0 0 var(--space-8) 0;
+}
+.epigraph blockquote {
+  /* Override the global blockquote left-bar: an epigraph reads as an opener,
+   * not a pull-quote. Keep it italic + muted. */
+  border-left: 0;
+  padding: 0;
+  margin: 0;
+  font-style: italic;
+  color: var(--color-text-muted);
+}
+.epigraph .epigraph-attribution {
+  margin-top: var(--space-2);
+  text-align: right;
+  font-style: normal;
+  font-size: var(--text-sm);
+  color: var(--color-text-muted);
+}
+/* The em-dash lead-in is conventional for an attribution; authors may also
+ * write it themselves, so it is not auto-inserted. */
+
+/* .heading-accent — OPT-IN colored-italic heading utility (warm-blue italic).
+ * The global h1–h6 are already blue-italic (above); this class is for a heading
+ * an author wants to force into the accent style outside that cascade (e.g. a
+ * heading inside a card whose local styles reset it). Deliberately NOT applied
+ * to the global headings — restyling those would churn every page + baseline. */
+.heading-accent {
+  color: var(--warm-blue);
+  font-style: italic;
+}