@brandon_m_behring/book-scaffold-astro 4.24.0 → 4.25.0

package/CLAUDE.md

@@ -100,7 +100,15 @@ Two callout families coexist. Authors import what they need.
 
 **Pedagogy family** (v4.1.0+, any profile, 4 components): `Pitfall` (rose; "common mistake" — distinct from `WarnBox`'s preemptive warning), `WorkedExample` (plum; collapsible `<details>` block with `#worked-example-{id}` anchor for deep links), `YouWillLearn` (gold; chapter-opener with optional `prerequisites` prop), `Diagnostic` (v4.19.0, #110; teal; pre-reading "Do I Know This Already?" DIKTA self-check — a slotted question list + a skip/skim/read routing rubric via `skimTo`, plus an optional collapsible answer key via `slot="answers"`). Slot bullets/code freely; render at any preset.
 
-**Utility components** (`src/components/`, any profile): `Cite`, `XRef`, `Figure`, `MarginNote`, `Sidenote`, `WeekRef`, `CodeRef`, `CodeBlock`, `Tag`, `StatusBadge`, `BookLink` (v4.16.0+; cross-book link — `<BookLink book="design" to="…"/>` resolves `book` against `defineBookConfig({ siblingBooks })` and throws on an unknown book; `<XRef>` is in-book only — #96), `PocLayout` (v4.1.0+; wraps slot in a per-`kind` layout shell — 5 closed-union kinds; see `recipes/15-defining-styles.md`).
+**Utility components** (`src/components/`, any profile): `Cite`, `XRef`, `Figure`, `MarginFigure`, `MarginNote`, `Sidenote`, `EvidenceTag`, `Newthought`, `Epigraph`, `WeekRef`, `CodeRef`, `CodeBlock`, `Tag`, `StatusBadge`, `BookLink` (v4.16.0+; cross-book link — `<BookLink book="design" to="…"/>` resolves `book` against `defineBookConfig({ siblingBooks })` and throws on an unknown book; `<XRef>` is in-book only — #96), `PocLayout` (v4.1.0+; wraps slot in a per-`kind` layout shell — 5 closed-union kinds; see `recipes/15-defining-styles.md`).
+
+**`MarginNote` vs `Sidenote` (don't let the names mislead).** `MarginNote` renders **inline** — a colored callout in the running text column; despite the name it does **not** go in the margin. It's for a load-bearing aside the reader must see. `Sidenote` is the one that **floats into the right gutter** (auto-numbered Tufte marginalia, reflowing inline on mobile). Reach for `Sidenote` for footnote-like asides; `MarginNote` for an inline colored callout.
+
+**`MarginFigure` + figure/content placement (1d).** `MarginFigure` is a `<Figure>` that **floats into the right gutter** (the same Tufte float + negative-margin technique `Sidenote`/SectionMap use — *not* a grid), shown at ≥64rem and reflowing inline below on mobile. Props mirror `<Figure>` (`src`/`caption`/`alt`/`desc`/`id`/`width`); rendering is delegated to `Figure`, and `width` defaults to `100%` (of the ~28ch gutter column). Two additive placement classes back it: **`.column-margin`** floats any block into the gutter (the un-figure version), and **`.column-page`** is a full-width breakout — an alias of the canonical **`.wide`** escape (max-width override, spans the gutter column too). For a full-bleed figure use `<Figure class="wide" …/>`; for the margin use `<MarginFigure …/>`. **Per-page width knob:** an optional `layout: wide` frontmatter field (closed enum `default`|`wide`, every profile) widens the main text measure for figure-/table-heavy chapters — `Chapter.astro` threads it as `data-layout="wide"` on `<article class="prose">` and `layout.css` maps `.prose[data-layout="wide"] { --measure-main: 80ch }`. Omitting it (or `layout: default`) emits no attribute, so existing chapters are byte-identical. All of these live in the always-loaded `layout.css` (token-only; additive — `.prose`'s block layout and `.sidenote`'s float are unchanged).
+
+**`EvidenceTag`** (v4.25.0): inline claim-confidence pill placed right after a claim — `kind` is a closed union `verified | inference | audit-corrected` (fail-loud via `assertEnumProp`; colors green/blue/rose, token-only). Sibling of `Tag` (which flags claim *provenance*); `EvidenceTag` flags how well a claim has been *checked*. An optional `source` prop is reserved (rendered as `data-source`, no behavior yet) for a future fail-loud `validate.mjs` upgrade. Usage: `<EvidenceTag kind="verified" /> … <EvidenceTag kind="inference" />`.
+
+**`Newthought` + `Epigraph`** (v4.25.0): Tufte typographic openers ported from the LaTeX book. `Newthought` is a run-in small-caps section opener (TRUE small-caps via `font-feature-settings: "smcp"`) — `<p><Newthought>In practice</Newthought>, …</p>`. `Epigraph` is a chapter-opening italic quotation with a right-aligned attribution (named `attribution` slot) — `<Epigraph>…<Fragment slot="attribution">Hamming</Fragment></Epigraph>`. Their CSS ships in the always-loaded `typography.css`; an opt-in `.heading-accent` (warm-blue italic) class is available there too (global headings are unchanged).
 
 **Provenance** (v4.8.0, any profile, **auto-injected by the chapter route — not author-imported**): per-chapter "How this was made" audit-trail block, rendered from the optional `provenance` frontmatter (`ai_tools`, `prompts_archive`, `decisions_log`, `audit_history`, `citation_backstop`). **Opt-out**: a chapter with no `provenance` shows a fallback ("Audit history not yet recorded"). Distinct from `AICollaborationDisclosure` (book-level, manual model+role disclosure). Repo-relative path fields render as `<code>`; only `http(s)` values link.
 

package/components/ChapterTOC.astro

@@ -8,15 +8,22 @@
  *
  * If the chapter has fewer than 3 matching headings, the TOC renders
  * nothing — an anchor list for a short chapter is clutter.
+ *
+ * The h2/h3 filter is the shared `tocHeadings` (lib/section-map.ts) — the SAME
+ * one the right-gutter SectionMap island uses, so this collapsed fallback and
+ * the gutter map carry identical entries (#section-map). On desktop (>= 64rem)
+ * this <details> is CSS-hidden and the gutter map takes over; below it, this is
+ * the fallback.
  */
 import type { MarkdownHeading } from 'astro';
+import { tocHeadings } from '../src/lib/section-map';
 
 interface Props {
   headings: MarkdownHeading[];
 }
 const { headings } = Astro.props;
 
-const toc = headings.filter((h) => h.depth >= 2 && h.depth <= 3);
+const toc = tocHeadings(headings);
 const showToc = toc.length >= 3;
 ---
 {showToc && (

package/components/Epigraph.astro

@@ -0,0 +1,28 @@
+---
+/**
+ * Epigraph — a chapter-opening quotation in the Tufte style: an italic block
+ * quote with a right-aligned attribution. Maps the LaTeX `epigraph`-style
+ * opener from interview-preamble-tufte.sty.
+ *
+ * The quote text goes in the default slot; the attribution goes in the named
+ * `attribution` slot (rendered in a <footer>, right-aligned). The measure is
+ * inherited from the running text tokens (--measure-main / .prose) rather than
+ * a fixed % width, so it doesn't fight the Tufte measure. CSS lives in the
+ * shared typography.css (always loaded). The footer renders only when the
+ * attribution slot is filled.
+ *
+ * Usage:
+ *   <Epigraph>
+ *     The purpose of computing is insight, not numbers.
+ *     <Fragment slot="attribution">Richard Hamming</Fragment>
+ *   </Epigraph>
+ */
+---
+<div class="epigraph">
+  <blockquote>
+    <slot />
+    {Astro.slots.has('attribution') && (
+      <footer class="epigraph-attribution"><slot name="attribution" /></footer>
+    )}
+  </blockquote>
+</div>

package/components/EvidenceTag.astro

@@ -0,0 +1,102 @@
+---
+/**
+ * EvidenceTag — inline claim-confidence marker, placed immediately after a
+ * stated claim to calibrate how far the reader should trust it. Ported from
+ * the user's Tufte-LaTeX evidence tags (interview-preamble-tufte.sty).
+ *
+ * Sibling of <Tag> (practice provenance): Tag flags WHERE a claim comes from
+ * (official / practitioner / convergence); EvidenceTag flags HOW WELL it has
+ * been checked. Three closed-union states:
+ *
+ *   verified         Confirmed against a primary source / first-hand check.
+ *   inference        Reasoned conclusion, not directly verified.
+ *   audit-corrected  A prior claim that an audit pass overturned/repaired.
+ *
+ * Colors are token-only so they recolor with [data-theme] automatically:
+ * verified → --warm-green, inference → --warm-blue, audit-corrected →
+ * --warm-rose (tinted background + matching text/border), matching the
+ * scoped-<style> + data-attribute idiom of <Tag>.
+ *
+ * Usage:
+ *   The kernel is diagonal-plus-low-rank <EvidenceTag kind="verified" />.
+ *   This generalizes to higher orders <EvidenceTag kind="inference" />.
+ */
+import { assertEnumProp } from '../src/lib/assert-prop';
+
+const KINDS = ['verified', 'inference', 'audit-corrected'] as const;
+type Kind = (typeof KINDS)[number];
+
+interface Props {
+  kind: Kind;
+  /**
+   * Provenance pointer for the claim (citekey, URL, audit-file path). RESERVED
+   * (#section-map plan NQ3): rendered as a `data-source` attribute today with
+   * no behavior. A future fail-loud upgrade — additive, designed-for here — is
+   * a `validate.mjs` check requiring `source` on kind="verified" (an unverified
+   * "verified" tag is the silent-degradation class assertEnumProp guards). Do
+   * NOT wire that validation now; reserving the prop keeps the upgrade additive.
+   */
+  source?: string;
+}
+
+// #109 sweep: fail loud on an unknown kind rather than rendering a blank pill
+// (LABEL[undefined] -> undefined). A closed union with no valid value is an
+// authoring error that should stop the build.
+const kind = assertEnumProp(Astro.props.kind, KINDS, {
+  component: 'EvidenceTag',
+  prop: 'kind',
+});
+const { source } = Astro.props;
+
+const LABEL: Record<Kind, string> = {
+  verified: '[V] Verified',
+  inference: '[I] Inference',
+  'audit-corrected': 'Audit-corrected',
+};
+
+const TITLE: Record<Kind, string> = {
+  verified: 'Confirmed against a primary source or first-hand check',
+  inference: 'Reasoned conclusion — not directly verified',
+  'audit-corrected': 'A prior claim an audit pass overturned or repaired',
+};
+---
+<span class="evidence-tag" data-kind={kind} data-source={source} title={TITLE[kind]}>
+  {LABEL[kind]}
+</span>
+
+<style>
+  .evidence-tag {
+    display: inline-block;
+    font-family: var(--font-code);
+    font-size: 0.75em;
+    font-weight: 500;
+    padding: 0 0.4em;
+    margin: 0 0.1em;
+    border-radius: var(--radius-sm);
+    border: 1px solid var(--color-border);
+    background: var(--color-bg-subtle);
+    color: var(--color-text-muted);
+    vertical-align: 0.1em;
+    letter-spacing: 0.02em;
+    /* Inline pill: don't let it stretch the line box awkwardly. */
+    line-height: 1.4;
+    white-space: nowrap;
+  }
+  /* Tinted background + matching text/border per kind. Tokens only, so each
+   * recolors in the [data-theme="dark"] scope without a dark-block edit. */
+  .evidence-tag[data-kind="verified"] {
+    border-color: var(--warm-green);
+    color: var(--warm-green);
+    background: var(--warm-green-tint);
+  }
+  .evidence-tag[data-kind="inference"] {
+    border-color: var(--warm-blue);
+    color: var(--warm-blue);
+    background: var(--warm-blue-tint);
+  }
+  .evidence-tag[data-kind="audit-corrected"] {
+    border-color: var(--warm-rose);
+    color: var(--warm-rose);
+    background: var(--warm-rose-tint);
+  }
+</style>

package/components/MarginFigure.astro

@@ -0,0 +1,49 @@
+---
+/**
+ * MarginFigure — a Figure pulled into the RIGHT margin (Tufte margin figure).
+ *
+ * Floats into the .prose right gutter using the SAME float + negative
+ * margin-right technique as `.sidenote` and SectionMap (layout.css,
+ * `.margin-figure`) — NOT a grid. Shown at >= 64rem (the gutter breakpoint);
+ * below that the float rule doesn't apply, so it reflows INLINE in document
+ * flow right where it appears (mobile gets the figure, just full-width).
+ *
+ * Rendering is DELEGATED to <Figure> — this component does not reinvent the
+ * inline-SVG / <img> / caption / a11y logic; it only wraps Figure in the
+ * gutter-floated <aside> and forwards every prop. The wrapper is an <aside>
+ * because a margin figure is supplementary to the running text.
+ *
+ * `width` defaults to "100%" (of the narrow gutter column, ~28ch) rather than
+ * Figure's page-width default — a margin figure should fill its column, not
+ * the page. Caption is shrunk to --text-xs in layout.css (margin context).
+ *
+ * Usage (same props as <Figure>):
+ *   <MarginFigure
+ *     src="/figures/week04/ex2_hippo_eigenvalues.svg"
+ *     caption="HiPPO-LegS eigenvalue structure."
+ *     alt="Two overlaid eigenvalue spectra forming nested arcs."
+ *     id="w4-fig-hippo-eigenvalues"
+ *   />
+ *
+ * For a full-width (not margin) figure, use <Figure> with class="wide" (or
+ * class="column-page"). For a generic non-figure block in the gutter, use a
+ * plain element with class="column-margin".
+ */
+import Figure from './Figure.astro';
+
+interface Props {
+  src: string;
+  caption?: string;
+  /** Defaults to 100% of the gutter column (not Figure's page-width default). */
+  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, desc } = Astro.props;
+---
+<aside class="margin-figure" role="group">
+  <Figure src={src} caption={caption} width={width} id={id} alt={alt} desc={desc} />
+</aside>

package/components/Newthought.astro

@@ -0,0 +1,18 @@
+---
+/**
+ * Newthought — Tufte run-in section opener. Maps LaTeX `\newthought{…}`:
+ * the first few words of a new line of thought set in small-caps, used in
+ * place of (or alongside) a subheading to mark a shift without breaking the
+ * paragraph flow.
+ *
+ * TRUE small-caps via `font-feature-settings: "smcp"` (NOT
+ * `font-variant: small-caps`, which synthesizes faux small-caps by scaling
+ * the capitals) — the Roboto variable face ships the smcp feature. CSS lives
+ * in the shared typography.css (always loaded via every profile's styles
+ * array), so this component is markup-only.
+ *
+ * Usage (inline at the start of a paragraph):
+ *   <p><Newthought>In practice</Newthought>, the kernel is computed once …</p>
+ */
+---
+<span class="newthought"><slot /></span>

package/components/SectionMap.astro

@@ -0,0 +1,56 @@
+---
+/**
+ * SectionMap.astro — the right-gutter sticky "On this page" section map
+ * (#section-map).
+ *
+ * Renders a real anchor list (h2/h3 slug links) into the .prose right gutter and
+ * mounts the SectionMap island (client:idle) as a controller over it. The island
+ * observes the heading elements and lights the active link as the reader scrolls
+ * (scrollspy). The collapsed top ChapterTOC remains the mobile/no-JS fallback —
+ * section-map.css hides THIS nav below 64rem (the gutter breakpoint) and hides
+ * ChapterTOC at/above it, so the two never double-show.
+ *
+ * Gated identically to ChapterTOC: renders nothing below 3 matching headings
+ * (an anchor list for a 1–2 heading chapter is clutter). Uses the shared
+ * `tocHeadings` filter so the gutter map and the fallback carry IDENTICAL
+ * entries. The island is imported via the package exports map (consumers must
+ * not compile raw .tsx out of node_modules — same as practice-exam.astro's
+ * ExamRunner import).
+ *
+ * DOM contract (see SectionMap.tsx): the <nav> is [data-section-map-root]; each
+ * link is a[data-section-id="<slug>"]; the island mounts INSIDE the nav so its
+ * closest() finds the root.
+ */
+import type { MarkdownHeading } from 'astro';
+import { tocHeadings } from '../src/lib/section-map';
+// Pre-compiled island via the exports map — consumers must not compile raw
+// .tsx out of node_modules (same as practice-exam.astro's ExamRunner import).
+import SectionMap from '@brandon_m_behring/book-scaffold-astro/components/SectionMap';
+import '../styles/section-map.css';
+
+interface Props {
+  headings: MarkdownHeading[];
+  /** Optional context label, e.g. "Part II · Ch 4". Omitted when not derivable. */
+  label?: string;
+}
+const { headings, label } = Astro.props;
+
+const toc = tocHeadings(headings);
+const showMap = toc.length >= 3;
+---
+{showMap && (
+  <nav class="section-map" data-section-map-root aria-label="On this page">
+    {label && <p class="section-map-label">{label}</p>}
+    <p class="section-map-title">On this page</p>
+    <ol class="section-map-list">
+      {toc.map((h) => (
+        <li class={`toc-h${h.depth}`}>
+          <a data-section-id={h.slug} href={`#${h.slug}`} class={`toc-h${h.depth}`}>
+            {h.text}
+          </a>
+        </li>
+      ))}
+    </ol>
+    <SectionMap client:idle headings={toc} />
+  </nav>
+)}

package/components/SectionMap.tsx

@@ -0,0 +1,170 @@
+/**
+ * SectionMap — Preact island driving the right-gutter "On this page" scrollspy
+ * (#section-map).
+ *
+ * Architecture: a CONTROLLER over server-rendered nav links, not a renderer.
+ * SectionMap.astro renders the <nav data-section-map-root> with one
+ * `a[data-section-id="<slug>"]` per h2/h3 (so the nav is a real anchor list with
+ * no JS — but on mobile/no-JS the collapsed ChapterTOC is the fallback and this
+ * gutter nav is CSS-hidden below 64rem). This island receives only the pure
+ * heading manifest (slug/depth/text), observes the matching heading ELEMENTS
+ * (`#<slug>`) in the document via IntersectionObserver, computes the active slug
+ * with the pure `pickActive`, and sets `aria-current="page"` + an `active` class
+ * on the corresponding link (clearing the others). It NEVER injects markup, so
+ * there's zero layout shift — only a class/attribute toggle on existing links.
+ *
+ * DOM contract with SectionMap.astro:
+ *   [data-section-map-root]            the SSR <nav> wrapper (ancestor of this
+ *                                      island's mount point)
+ *   a[data-section-id="<slug>"]        one link per heading; gains/loses
+ *                                      aria-current="page" + class "active"
+ *   #<slug>                            the heading element in the article body
+ *                                      (Astro's MDX slug) — observed, not owned
+ *
+ * Fail-loud (house invariant, like ExamRunner/Flashcards): a missing wrapper
+ * throws. A heading id with no element in the document is skipped gracefully
+ * (the TOC filter can include a heading Astro slugged differently / a deferred
+ * section), BUT if NONE of the manifest's headings resolve to an element, that's
+ * manifest/DOM drift and we throw rather than mount a silently dead nav.
+ *
+ * No animation → no prefers-reduced-motion handling needed (instant class
+ * toggle). No canvas → no book:theme:change listener (CSS tokens recolor the
+ * nav from [data-theme] automatically). Hydrated with `client:idle`.
+ */
+import { useEffect, useRef } from 'preact/hooks';
+import { pickActive, type VisibleHeading } from '../src/lib/section-map';
+import type { MarkdownHeading } from 'astro';
+
+interface Props {
+  /** TOC headings (tocHeadings output) — slug/depth/text only, serializable. */
+  headings: MarkdownHeading[];
+}
+
+export default function SectionMap({ headings }: Props) {
+  const ref = useRef<HTMLSpanElement>(null);
+
+  useEffect(() => {
+    const root = ref.current?.closest<HTMLElement>('[data-section-map-root]');
+    if (!root) {
+      // Fail loud: a silently dead scrollspy (no active highlight, ever) is the
+      // worst failure mode — surface it as an uncaught console error.
+      throw new Error(
+        'SectionMap: no [data-section-map-root] ancestor — mount the island inside ' +
+          'the <nav> that contains its links (see the DOM contract in SectionMap.tsx).',
+      );
+    }
+
+    // Resolve each manifest heading to its body element. CSS.escape: a slug with
+    // an unusual char would otherwise break the selector and throw a DOMException
+    // mid-observe (a frozen scrollspy).
+    type Tracked = { slug: string; el: Element };
+    const tracked: Tracked[] = [];
+    for (const h of headings) {
+      const el = document.getElementById(h.slug);
+      if (el) tracked.push({ slug: h.slug, el });
+      // else: skip gracefully — a filtered heading Astro slugged differently or
+      // a section not in this document. The drift guard below catches a TOTAL miss.
+    }
+    if (tracked.length === 0) {
+      // None resolved → manifest/DOM drift (mirror ExamRunner). A nav whose every
+      // link points at a missing anchor must not pretend to work.
+      throw new Error(
+        `SectionMap: manifest/DOM drift — none of the ${headings.length} heading id(s) ` +
+          `resolve to an element (#${headings.map((h) => h.slug).join(', #')}).`,
+      );
+    }
+    // The last tracked heading in document order (bound here, where the length
+    // guard above proves it exists — `at(-1)`'s type is still `Tracked | undefined`
+    // under noUncheckedIndexedAccess, so narrow it once). Used by the
+    // scrolled-to-bottom path to force the final section active.
+    const lastTracked = tracked[tracked.length - 1] as Tracked;
+
+    // Link lookup by slug (CSS.escape on every slug used in a selector).
+    function linkFor(slug: string): HTMLElement | null {
+      return root!.querySelector<HTMLElement>(
+        `a[data-section-id="${CSS.escape(slug)}"]`,
+      );
+    }
+
+    // Which tracked headings are currently intersecting; recompute reads `tracked`
+    // (document order) and filters by membership so `visible` is document-ordered
+    // too — pickActive's "ties resolve to document order" then actually holds.
+    const inView = new Set<Element>();
+    let active: string | null = null;
+
+    // Set the active slug: clear the previous link, light the next one. Toggle
+    // ONLY class/attr on existing SSR links → no layout shift. Shared by the
+    // observer path (via recompute) and the scrolled-to-bottom path below.
+    function setActive(next: string | null): void {
+      if (next === active) return;
+      if (active !== null) {
+        const prevLink = linkFor(active);
+        if (prevLink) {
+          prevLink.classList.remove('active');
+          prevLink.removeAttribute('aria-current');
+        }
+      }
+      if (next !== null) {
+        const nextLink = linkFor(next);
+        if (nextLink) {
+          nextLink.classList.add('active');
+          nextLink.setAttribute('aria-current', 'page');
+        }
+      }
+      active = next;
+    }
+
+    function recompute(): void {
+      // Iterate `tracked` (document order) filtering by inView — NOT the Set
+      // (insertion order) — so equal-top ties resolve to document order.
+      const visible: VisibleHeading[] = [];
+      for (const t of tracked) {
+        if (inView.has(t.el)) {
+          visible.push({ slug: t.slug, top: t.el.getBoundingClientRect().top });
+        }
+      }
+      setActive(pickActive(visible, active));
+    }
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) inView.add(entry.target);
+          else inView.delete(entry.target);
+        }
+        recompute();
+      },
+      // A negative bottom margin biases "active" toward the heading nearest the
+      // top of the viewport (the section you're reading INTO), not the last one
+      // peeking in at the bottom.
+      { rootMargin: '0px 0px -70% 0px', threshold: 0 },
+    );
+    for (const t of tracked) observer.observe(t.el);
+
+    // Last-section reachability: the -70% bottom margin confines "active" to the
+    // top 30% of the viewport, so a final heading with little content below it
+    // can never scroll INTO that zone — it would never light. When the page is
+    // scrolled to the bottom, force the LAST tracked heading active so the foot
+    // of the chapter always highlights its own section. Passive listeners (no
+    // preventDefault) keep scrolling smooth.
+    function onScroll(): void {
+      const atBottom =
+        window.innerHeight + window.scrollY >=
+        document.documentElement.scrollHeight - 2;
+      if (atBottom) setActive(lastTracked.slug);
+    }
+    window.addEventListener('scroll', onScroll, { passive: true });
+    window.addEventListener('resize', onScroll, { passive: true });
+
+    return () => {
+      observer.disconnect();
+      window.removeEventListener('scroll', onScroll);
+      window.removeEventListener('resize', onScroll);
+    };
+  }, [headings]);
+
+  // A zero-footprint anchor: the island renders only this <span> so it can find
+  // [data-section-map-root] via closest(); all visible nav links are SSR'd by
+  // SectionMap.astro. No markup injected → no layout shift.
+  return <span ref={ref} class="section-map-mount" hidden aria-hidden="true" />;
+}

package/dist/components/ExamRunner.d.ts

@@ -1,6 +1,6 @@
 import * as preact from 'preact';
-import { a as ExamQuestion, R as RoutingChapter } from '../exam-manifest-DbTHo90M.js';
-import '../schemas-DDWDRUxs.js';
+import { a as ExamQuestion, R as RoutingChapter } from '../exam-manifest-DnqyzZ9I.js';
+import '../schemas-CKipJ5Ie.js';
 import 'astro/zod';
 
 interface Props {

package/dist/components/Flashcards.d.ts

@@ -1,6 +1,6 @@
 import * as preact from 'preact';
-import { F as FlashcardRef } from '../flashcards-DPFFQhP8.js';
-import '../schemas-DDWDRUxs.js';
+import { F as FlashcardRef } from '../flashcards-okekZcl8.js';
+import '../schemas-CKipJ5Ie.js';
 import 'astro/zod';
 
 interface Props {

package/dist/components/SectionMap.d.ts

@@ -0,0 +1,10 @@
+import * as preact from 'preact';
+import { MarkdownHeading } from 'astro';
+
+interface Props {
+    /** TOC headings (tocHeadings output) — slug/depth/text only, serializable. */
+    headings: MarkdownHeading[];
+}
+declare function SectionMap({ headings }: Props): preact.JSX.Element;
+
+export { SectionMap as default };

package/dist/components/SectionMap.mjs

@@ -0,0 +1,107 @@
+// components/SectionMap.tsx
+import { useEffect, useRef } from "preact/hooks";
+
+// src/lib/section-map.ts
+function pickActive(visible, prev) {
+  if (visible.length === 0) return prev;
+  let bestNonNeg = null;
+  let bestAbove = null;
+  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;
+  if (bestAbove !== null) return bestAbove.slug;
+  return prev;
+}
+
+// components/SectionMap.tsx
+import { jsx } from "preact/jsx-runtime";
+function SectionMap({ headings }) {
+  const ref = useRef(null);
+  useEffect(() => {
+    const root = ref.current?.closest("[data-section-map-root]");
+    if (!root) {
+      throw new Error(
+        "SectionMap: no [data-section-map-root] ancestor \u2014 mount the island inside the <nav> that contains its links (see the DOM contract in SectionMap.tsx)."
+      );
+    }
+    const tracked = [];
+    for (const h of headings) {
+      const el = document.getElementById(h.slug);
+      if (el) tracked.push({ slug: h.slug, el });
+    }
+    if (tracked.length === 0) {
+      throw new Error(
+        `SectionMap: manifest/DOM drift \u2014 none of the ${headings.length} heading id(s) resolve to an element (#${headings.map((h) => h.slug).join(", #")}).`
+      );
+    }
+    const lastTracked = tracked[tracked.length - 1];
+    function linkFor(slug) {
+      return root.querySelector(
+        `a[data-section-id="${CSS.escape(slug)}"]`
+      );
+    }
+    const inView = /* @__PURE__ */ new Set();
+    let active = null;
+    function setActive(next) {
+      if (next === active) return;
+      if (active !== null) {
+        const prevLink = linkFor(active);
+        if (prevLink) {
+          prevLink.classList.remove("active");
+          prevLink.removeAttribute("aria-current");
+        }
+      }
+      if (next !== null) {
+        const nextLink = linkFor(next);
+        if (nextLink) {
+          nextLink.classList.add("active");
+          nextLink.setAttribute("aria-current", "page");
+        }
+      }
+      active = next;
+    }
+    function recompute() {
+      const visible = [];
+      for (const t of tracked) {
+        if (inView.has(t.el)) {
+          visible.push({ slug: t.slug, top: t.el.getBoundingClientRect().top });
+        }
+      }
+      setActive(pickActive(visible, active));
+    }
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) inView.add(entry.target);
+          else inView.delete(entry.target);
+        }
+        recompute();
+      },
+      // A negative bottom margin biases "active" toward the heading nearest the
+      // top of the viewport (the section you're reading INTO), not the last one
+      // peeking in at the bottom.
+      { rootMargin: "0px 0px -70% 0px", threshold: 0 }
+    );
+    for (const t of tracked) observer.observe(t.el);
+    function onScroll() {
+      const atBottom = window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - 2;
+      if (atBottom) setActive(lastTracked.slug);
+    }
+    window.addEventListener("scroll", onScroll, { passive: true });
+    window.addEventListener("resize", onScroll, { passive: true });
+    return () => {
+      observer.disconnect();
+      window.removeEventListener("scroll", onScroll);
+      window.removeEventListener("resize", onScroll);
+    };
+  }, [headings]);
+  return /* @__PURE__ */ jsx("span", { ref, class: "section-map-mount", hidden: true, "aria-hidden": "true" });
+}
+export {
+  SectionMap as default
+};

package/dist/{exam-manifest-DbTHo90M.d.ts → exam-manifest-DnqyzZ9I.d.ts}

@@ -1,4 +1,4 @@
-import { Q as Question } from './schemas-DDWDRUxs.js';
+import { Q as Question } from './schemas-CKipJ5Ie.js';
 
 /**
  * exam-engine.ts — PURE sampling + scoring for the interactive practice exam

package/dist/{flashcards-DPFFQhP8.d.ts → flashcards-okekZcl8.d.ts}

@@ -1,4 +1,4 @@
-import { G as GlossaryTerm } from './schemas-DDWDRUxs.js';
+import { G as GlossaryTerm } from './schemas-CKipJ5Ie.js';
 
 /**
  * flashcards.ts — PURE deck-manifest bridge between the `glossary` collection