@brandon_m_behring/book-scaffold-astro 4.17.0 → 4.19.0

package/CLAUDE.md

@@ -96,15 +96,15 @@ Two callout families coexist. Authors import what they need.
 
 **Tools family** (`src/components/callouts/`, 8 components): `SkillBox`, `CaseStudy`, `ConceptBox`, `KeyIdea`, `TryThis`, `Recovery`, `Convergence`, `Divergence`.
 
-**Academic family** (`src/components/callouts/`, 10 components): `NoteBox`, `ExampleBox`, `DynConnect`, `InsightBox`, `WarnBox`, `CounterBox`, `TipBox`, `OpenQuestion`, `PaperBox`, `ResultBox`. Plus `Theorem` (unified for theorem/proposition/lemma/corollary/definition/example/exercise/remark/proof). **Props (v4.14.3, #121):** `kind=` is canonical; `type=` is accepted as a legacy alias (likewise `title=`/`label=` alias `name=`). An absent or unknown kind **throws at build** (via `src/lib/theorem-label`) rather than rendering an empty label; `book-scaffold validate` flags a `<Theorem>` with neither `kind=` nor `type=` even earlier.
+**Academic family** (`src/components/callouts/`, 10 components): `NoteBox`, `ExampleBox`, `DynConnect`, `InsightBox`, `WarnBox`, `CounterBox`, `TipBox`, `OpenQuestion`, `PaperBox`, `ResultBox`. Plus `Theorem` (unified for theorem/proposition/lemma/corollary/definition/example/exercise/remark/proof). **Props (v4.14.3, #121):** `kind=` is canonical; `type=` is accepted as a legacy alias (likewise `title=`/`label=` alias `name=`). An absent or unknown kind **throws at build** (via `src/lib/theorem-label`) rather than rendering an empty label; `book-scaffold validate` flags a `<Theorem>` with neither `kind=` nor `type=` even earlier. **Numbering (v4.18.0, #126):** a theorem with an `id` auto-numbers from `labels.json` — the same index `<XRef>` reads — so the heading number equals every cross-reference to it by construction; explicit `n=` is a fallback for un-id'd theorems. `build-labels` indexes the kind-accurate word (`Proposition 8.1`, not a kind-blind `Theorem 8.1`) and throws on an unknown kind.
 
-**Pedagogy family** (v4.1.0+, any profile, 3 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). Slot bullets/code freely; render at any preset.
+**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`).
 
 **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.
 
-**Study-guide (v4.17.0+, #112; opt-in).** A schema-validated `questions` content collection drives an exam-prep "question bank". Author questions under `src/content/questions/**.{md,mdx}` — frontmatter `id` (unique, required) / `type` (`mcq`|`free`|`cloze`) / `chapter` / `domain` (+ optional `part`/`bloom_level`/`objective_id`/`difficulty`), MDX body = the stem. MCQ carries `options: [{ id, text, correct }]` (exactly one `correct: true`); free-response carries an `answer` (model answer). An MCQ must **not** set `answer` — its answer is the option marked `correct`, and explanations for any type go in a `<Rationale>` body block. Declare the per-book domain taxonomy in `defineBookConfig({ examDomains: ['…'] })` — a question whose `domain` isn't registered **throws at build** (fail-loud, like `<BookLink>`'s `siblingBooks`). Enable the static `/practice-exam` route with `defineBookConfig({ routes: { practiceExam: true } })` (renders the bank grouped by domain with answers behind a `<details>` reveal; `cloze` is reserved/render-deferred). `<ObjectiveMap />` renders the exam-domain → chapter coverage matrix auto-derived from the collection (no separate data file). `<Rationale>` is a collapsible answer/explanation marker for a question's MDX body. (Scoring + diagnostics + appendix + flashcards are later increments — see `docs/plans/active/study-guide-epic_*.md`.)
+**Study-guide (v4.17.0+, #112; opt-in).** A schema-validated `questions` content collection drives an exam-prep "question bank". Author questions under `src/content/questions/**.{md,mdx}` — frontmatter `id` (unique, required) / `type` (`mcq`|`free`|`cloze`) / `chapter` / `domain` (+ optional `part`/`bloom_level`/`objective_id`/`difficulty`), MDX body = the stem. MCQ carries `options: [{ id, text, correct }]` (exactly one `correct: true`); free-response carries an `answer` (model answer). An MCQ must **not** set `answer` — its answer is the option marked `correct`, and explanations for any type go in a `<Rationale>` body block. Declare the per-book domain taxonomy in `defineBookConfig({ examDomains: ['…'] })` — a question whose `domain` isn't registered **throws at build** (fail-loud, like `<BookLink>`'s `siblingBooks`). Enable the static `/practice-exam` route with `defineBookConfig({ routes: { practiceExam: true } })` (renders the bank grouped by domain with answers behind a `<details>` reveal; `cloze` is reserved/render-deferred). `<ObjectiveMap />` renders the exam-domain → chapter coverage matrix auto-derived from the collection (no separate data file). `<Rationale>` is a collapsible answer/explanation marker for a question's MDX body. `<Diagnostic>` (v4.19.0, #110) renders a per-chapter pre-reading "Do I Know This Already?" self-check (pedagogy family above; static `<details>` answer reveal). `<PartReview part={N} />` (v4.19.0, #111) aggregates a Part's `<Exercise>` items for interleaved review — reusing the `build-exercises` index + the chapters' `part` field (run `book-scaffold build-exercises` first; presence-gated otherwise). A **searchable glossary** (v4.19.0, #115): author terms under `src/content/glossary/**` (frontmatter `term` + an MDX-body definition), enable the static `/glossary` route via `defineBookConfig({ routes: { glossary: true } })`, and link inline with `<Term id="…">…</Term>` (→ `/glossary#term-<id>`). (Scoring, the rationale appendix, and flashcards are later increments — see `docs/plans/active/study-guide-epic_*.md`.)
 
 Full reference in `recipes/04-component-library.md`.
 

package/components/Diagnostic.astro

@@ -0,0 +1,56 @@
+---
+/**
+ * Diagnostic — pre-reading "Do I Know This Already?" self-check (#110).
+ *
+ * Pearson / Cisco-Press DIKTA pattern: a short retrieval list the reader
+ * attempts BEFORE reading, plus a skip/skim/read routing rubric — visually
+ * distinct from the post-chapter <Exercise>/<Practice>. Static: the optional
+ * answer key reveals via native <details> (no JS; the scored engine is the
+ * separate #112 increment). Pedagogically this is pre-testing (Bjork): a
+ * retrieval attempt before study strengthens later recall even when the guess
+ * is wrong, so the reader should try before peeking.
+ *
+ * Slots:
+ *   default     — the numbered question list (the retrieval items)
+ *   "answers"   — OPTIONAL collapsible answer key (rendered only when provided)
+ *
+ * Family: teal (--callout-diagnostic, a blue+green blend) — a cool hue held
+ * distinct from the warm pedagogy callouts (Pitfall crimson, WorkedExample
+ * plum, YouWillLearn gold) and the plum Exercise/Practice.
+ */
+interface Props {
+  /** Heading. Default "Do I know this already?". */
+  title?: string;
+  /** Section to skim ahead to when confident. Default "Exam essentials". */
+  skimTo?: string;
+  /** Full override of the routing sentence (else built from skimTo). */
+  routing?: string;
+}
+const {
+  title = 'Do I know this already?',
+  skimTo = 'Exam essentials',
+  routing,
+} = Astro.props;
+const hasAnswers = Astro.slots.has('answers');
+---
+<aside class="callout callout-diagnostic" role="note">
+  <div class="callout-diagnostic-header">
+    <strong class="callout-title">{title}</strong>
+    <span class="callout-chip">Diagnostic</span>
+  </div>
+  <p class="callout-routing">
+    {routing ? routing : (
+      <Fragment>
+        Answer these confidently and you can skim ahead to <strong>{skimTo}</strong>;
+        if any is shaky, read closely — each is developed below.
+      </Fragment>
+    )}
+  </p>
+  <div class="callout-body"><slot /></div>
+  {hasAnswers && (
+    <details class="callout-diagnostic-answers">
+      <summary>Check your answers</summary>
+      <div class="callout-body"><slot name="answers" /></div>
+    </details>
+  )}
+</aside>

package/components/PartReview.astro

@@ -0,0 +1,81 @@
+---
+/**
+ * PartReview — aggregate a Part's <Exercise> items for interleaved review (#111).
+ *
+ * Cisco-Press / Pearson "Part Review": after a group of chapters (a Part — e.g.
+ * a cert domain) the reader gets that part's exercises collected in one place
+ * for spaced, interleaved practice. Reuses `src/data/exercises.json` (emitted by
+ * `book-scaffold build-exercises`) plus the chapters collection's `part` field —
+ * no new build step. Drop `<PartReview part={N} />` at the end of a part's last
+ * chapter or on a part-summary page.
+ *
+ * `part` accepts a number (tools/minimal/course-notes/research-portfolio
+ * profiles, where `part` is numeric) or a string (academic `part` enum).
+ *
+ * Presence-gated (twin-gate, like /exercises): with no exercises.json it renders
+ * a build hint rather than failing; with the index but no items in this part it
+ * says so honestly. `<Practice>` aggregation + a book-level `/review` route are
+ * later increments (see docs/plans/active/study-guide-epic_*.md).
+ */
+import { getCollection } from 'astro:content';
+import { selectPartExercises } from '../src/lib/part-review';
+
+interface Props {
+  /** The part to aggregate. Number (tools/minimal/…) or string (academic enum). */
+  part: number | string;
+  /** Heading override. Default "Part {part} Review". */
+  title?: string;
+}
+const { part, title } = Astro.props;
+
+// Reuse the build-exercises index (keyed by chapter slug). Project-root-relative
+// glob (the tips.astro / exercises.astro lesson) so it resolves across consumers.
+const exModules = import.meta.glob<{ default: Record<string, Array<{ id: string; problem: string }>> }>(
+  '/src/data/exercises.json',
+  { eager: true },
+);
+const exEntry = exModules['/src/data/exercises.json'];
+const byChapter = exEntry?.default ?? {};
+const hasIndex = Boolean(exEntry);
+
+// Filter this part's chapters, sort to book order, and join the index — pure +
+// unit-tested in src/lib/part-review.ts (`part` is String-coerced, so a
+// number-vs-string prop can't silently miss). This component just renders it.
+const chapters = await getCollection('chapters', (e) => !e.data.draft);
+const { groups, total } = selectPartExercises(chapters, byChapter, part);
+const heading = title ?? `Part ${part} Review`;
+---
+<aside class="part-review" aria-label={heading}>
+  <h2 class="part-review-title">{heading}</h2>
+
+  {!hasIndex && (
+    <p class="part-review-empty">
+      No <code>src/data/exercises.json</code> — run <code>npx book-scaffold build-exercises</code> to populate the review.
+    </p>
+  )}
+
+  {hasIndex && total === 0 && (
+    <p class="part-review-empty">No exercises found in this part's chapters yet.</p>
+  )}
+
+  {total > 0 && (
+    <Fragment>
+      <p class="part-review-summary">
+        {total} exercise{total === 1 ? '' : 's'} across {groups.length} chapter{groups.length === 1 ? '' : 's'} — interleaved review.
+      </p>
+      {groups.map((g) => (
+        <section class="part-review-chapter">
+          <h3 class="part-review-chapter-title"><a href={`/chapters/${g.chapter}/`}>{g.chapter}</a></h3>
+          <ol class="part-review-list">
+            {g.exercises.map((ex) => (
+              <li id={`review-${ex.id}`} class="part-review-item">
+                <span class="part-review-item-id">{ex.id}</span>
+                <span class="part-review-item-problem">{ex.problem}</span>
+              </li>
+            ))}
+          </ol>
+        </section>
+      ))}
+    </Fragment>
+  )}
+</aside>

package/components/Term.astro

@@ -0,0 +1,33 @@
+---
+/**
+ * Term — inline glossary cross-link (v4.19.0, #115).
+ *
+ * <Term id="agentic-loop">agent loop</Term> renders the slot text as a link to
+ * the glossary entry's anchor (/glossary#term-<id>). `id` is the glossary file's
+ * entry id (filename slug, e.g. `agentic-loop` for agentic-loop.mdx). Static
+ * link — no tooltip/definition preview in v1. Pairs with the `glossary`
+ * collection + the /glossary route (defineBookConfig({ routes: { glossary: true } })).
+ *
+ * Like <XRef>, this does not validate the target at render — a dangling id
+ * produces a link to a missing anchor, caught by review (a future `validate`
+ * check can resolve <Term id> against the glossary collection).
+ */
+interface Props {
+  /** Glossary entry id (filename slug) — the /glossary#term-<id> anchor target. */
+  id: string;
+}
+const { id } = Astro.props;
+---
+<a href={`/glossary#term-${id}`} class="term-link"><slot /></a>
+
+<style>
+  .term-link {
+    color: inherit;
+    text-decoration: underline dotted;
+    text-decoration-color: var(--callout-info, #3B6FA0);
+    text-underline-offset: 0.15em;
+  }
+  .term-link:hover {
+    text-decoration-style: solid;
+  }
+</style>

package/components/Theorem.astro

@@ -10,29 +10,54 @@
  * (ssm-foundations ch1–11 + the LaTeX-env mental model pass `type=`). `name`
  * is canonical with `title=`/`label=` accepted. An absent or unknown kind
  * THROWS at build (see `src/lib/theorem-label`) — it never renders an empty
- * label. Pass `n` to number the environment.
+ * label.
  *
- * Auto-numbering note: the LaTeX preamble shares a counter between
- * theorem/proposition/lemma/corollary and gives definition/example/exercise/
- * remark their own; in MDX the author passes `n` explicitly when it matters.
+ * Auto-numbering (#126): when the theorem has an `id`, its number is read from
+ * `src/data/labels.json` — the same map <XRef> resolves — so the heading number
+ * EQUALS every cross-reference to it by construction. No hand-passed `n=`, no
+ * drift; inserting a theorem renumbers the chapter from one counter
+ * (`book-scaffold build-labels`). Explicit `n=` stays a fallback for an un-id'd
+ * theorem (or before labels.json is built); when an id resolves, the labels.json
+ * number wins so the two surfaces can never disagree.
  *
  * Usage:
- *   <Theorem kind="theorem" n="4.2" name="Stable continuous-time eigenvalues" id="thm-w4-stability">
- *     For …
+ *   <Theorem kind="theorem" name="Stable continuous-time eigenvalues" id="thm-w4-stability">
+ *     For …                      // number auto-resolved from labels.json
  *   </Theorem>
  *
  *   <Theorem kind="definition" n="4.1" name="HiPPO-LegS">
- *     The HiPPO-LegS state matrix …
+ *     The HiPPO-LegS state matrix …   // explicit n= (un-cross-referenced)
  *   </Theorem>
  */
-import { theoremLabel, type TheoremLabelProps } from '../src/lib/theorem-label';
+import { theoremLabel, resolveTheoremNumber, type TheoremLabelProps } from '../src/lib/theorem-label';
 
 interface Props extends TheoremLabelProps {
   id?: string;
 }
 
+// #126: resolve THIS theorem's number from the same labels.json that <XRef>
+// reads, so the heading number == the cross-reference display by construction.
+// build-labels.mjs writes { href, display, number } keyed by id. Mirror XRef's
+// project-root glob (Vite resolves `/` to the consumer root, not the package);
+// a missing file → empty map → fall back to explicit n= (the same soft-degrade
+// path as XRef — the validator catches unknown ids at CI).
+type LabelEntry = { href: string; display: string; number?: string | null };
+const labelsModules = import.meta.glob<{ default: Record<string, LabelEntry> }>(
+  '/src/data/labels.json',
+  { eager: true },
+);
+const labelsMap = (labelsModules['/src/data/labels.json']?.default ?? {}) as Record<
+  string,
+  LabelEntry
+>;
+
 const { id } = Astro.props;
-const { kind, fullLabel } = theoremLabel(Astro.props);
+// labels.json (by id) is the number source; explicit n= is the fallback when no
+// id resolves. When both exist the shared source wins — that is what guarantees
+// heading == xref (a stale n= can't reintroduce drift).
+const entry = id ? labelsMap[id] : undefined;
+const resolvedN = resolveTheoremNumber(entry, Astro.props.n);
+const { kind, fullLabel } = theoremLabel({ ...Astro.props, n: resolvedN });
 ---
 <div class="theorem" data-kind={kind} id={id}>
   <span class="theorem-label">{fullLabel}.</span>

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { AstroUserConfig, AstroIntegration } from 'astro';
-import { d as BookConfigOptions, g as BookScaffoldIntegrationOptions, a5 as volatilityLevels, i as ChaptersRenderer, t as academicParts, Q as Question, q as Style } from './types-CMPuyZGP.js';
-export { A as AcademicChapter, B as BOOK_PRESETS, a as BOOK_PROFILES, b as BloomLevel, c as BookConfigError, e as BookPreset, f as BookProfile, h as BookSchemasOptions, C as ChapterFor, j as CourseNotesChapter, F as FreshnessAffordance, k as FrontmatterRouteConfig, M as MinimalChapter, P as PartKey, l as PartialRouteToggles, m as ProfileDefinition, n as Provenance, o as QuestionType, R as ResearchPortfolioChapter, p as RouteToggles, S as StatusBadge, r as StyleInput, T as ToolsChapter, V as VolatilityBadge, s as academicChapterSchema, u as bloomLevels, v as changeKinds, w as changelogSchema, x as chapterStatus, y as citationBackstops, z as composeStyles, D as courseNotesChapterSchema, E as defineProfile, G as defineStyle, H as minimalChapterSchema, I as normalizeFrontmatterConfig, J as patternCategories, K as patternsSchema, L as provenanceObject, N as provenanceSchema, O as questionDifficulties, U as questionSchema, W as questionTypes, X as refineQuestion, Y as refinedQuestionSchema, Z as researchPortfolioChapterSchema, _ as resolvePreset, $ as resolveProfile, a0 as sourceTiers, a1 as sourceTiersResearch, a2 as sourcesSchema, a3 as toolSlugs, a4 as toolsChapterSchema } from './types-CMPuyZGP.js';
+import { d as BookConfigOptions, g as BookScaffoldIntegrationOptions, a7 as volatilityLevels, i as ChaptersRenderer, t as academicParts, Q as Question, q as Style } from './types-DJgLQGP9.js';
+export { A as AcademicChapter, B as BOOK_PRESETS, a as BOOK_PROFILES, b as BloomLevel, c as BookConfigError, e as BookPreset, f as BookProfile, h as BookSchemasOptions, C as ChapterFor, j as CourseNotesChapter, F as FreshnessAffordance, k as FrontmatterRouteConfig, G as GlossaryTerm, M as MinimalChapter, P as PartKey, l as PartialRouteToggles, m as ProfileDefinition, n as Provenance, o as QuestionType, R as ResearchPortfolioChapter, p as RouteToggles, S as StatusBadge, r as StyleInput, T as ToolsChapter, V as VolatilityBadge, s as academicChapterSchema, u as bloomLevels, v as changeKinds, w as changelogSchema, x as chapterStatus, y as citationBackstops, z as composeStyles, D as courseNotesChapterSchema, E as defineProfile, H as defineStyle, I as glossarySchema, J as minimalChapterSchema, K as normalizeFrontmatterConfig, L as patternCategories, N as patternsSchema, O as provenanceObject, U as provenanceSchema, W as questionDifficulties, X as questionSchema, Y as questionTypes, Z as refineQuestion, _ as refinedQuestionSchema, $ as researchPortfolioChapterSchema, a0 as resolvePreset, a1 as resolveProfile, a2 as sourceTiers, a3 as sourceTiersResearch, a4 as sourcesSchema, a5 as toolSlugs, a6 as toolsChapterSchema } from './types-DJgLQGP9.js';
+export { KIND_LABEL, ResolvedTheoremLabel, THEOREM_KINDS, TheoremKind, TheoremLabelProps, resolveTheoremNumber, theoremLabel } from './lib/theorem-label.js';
 import 'astro/zod';
 
 /**
@@ -204,54 +205,6 @@ declare function academicPartOrdinal(part: string): number;
  */
 declare function academicPartHeading(part: string): string;
 
-/**
- * theorem-label — resolve a `<Theorem>` component's label from its props,
- * failing loud instead of rendering a silent empty label (#121).
- *
- * Vocabulary: `kind` is canonical; `type` is an accepted **legacy alias** (many
- * consumer books — ssm-foundations ch1–11 — and the LaTeX `\begin{<env>}`
- * mental model pass `type=`). Likewise `name` is canonical with `title`/`label`
- * accepted as aliases. Aliases keep existing content valid; they are synonyms,
- * not deprecations, so they neither warn nor throw.
- *
- * Failure mode: an absent or unrecognized kind THROWS a build-failing,
- * actionable error rather than computing `KIND_LABEL[undefined]` → a bare "."
- * (the v4.8–4.14 silent defect, live across 32+ ssm-foundations theorems). A
- * typo'd kind — silent before — now stops the build with the offending value.
- *
- * Extracted from the `Theorem.astro` frontmatter so the contract is unit-tested
- * in the pure `node --test` suite (see tests/theorem-label.test.mjs) — the same
- * single-source-of-truth move as `academic-parts.ts` (#95).
- */
-declare const THEOREM_KINDS: readonly ["theorem", "proposition", "lemma", "corollary", "definition", "example", "exercise", "remark", "proof"];
-type TheoremKind = (typeof THEOREM_KINDS)[number];
-declare const KIND_LABEL: Record<TheoremKind, string>;
-interface TheoremLabelProps {
-    /** Canonical environment selector. */
-    kind?: string;
-    /** Legacy alias for `kind` (LaTeX-env mental model; ssm-foundations ch1–11). */
-    type?: string;
-    /** Explicit number, e.g. "4.2"; omit for an unnumbered environment. */
-    n?: string;
-    /** Canonical display name shown in parentheses. */
-    name?: string;
-    /** Legacy aliases for `name`. */
-    title?: string;
-    label?: string;
-}
-interface ResolvedTheoremLabel {
-    /** The validated, canonical kind (for `data-kind`). */
-    kind: TheoremKind;
-    /** The composed "Kind N (Name)" label (never empty). */
-    fullLabel: string;
-}
-/**
- * Resolve a `<Theorem>`'s `kind` (canonical or legacy `type=`) and compose its
- * full label. Throws — never returns an empty label — when the kind is absent
- * or not one of {@link THEOREM_KINDS}.
- */
-declare function theoremLabel(props: TheoremLabelProps): ResolvedTheoremLabel;
-
 /**
  * repo-url — resolve and build GitHub source links for CodeRef / CodeBlock.
  *
@@ -403,6 +356,111 @@ declare function distinctChaptersSorted<T extends {
     data: Pick<Question, 'chapter'>;
 }>(entries: readonly T[]): string[];
 
+/**
+ * exam-engine.ts — PURE sampling + scoring for the interactive practice exam
+ * (#112) and the cross-domain assessment test (#113).
+ *
+ * No DOM, no Preact: this is the testable core both the PracticeExam island and
+ * the AssessmentTest reuse, exercised in tests/exam-engine.test.mjs (node:test,
+ * no browser). The islands are thin UI over these functions — selection state +
+ * rendering only — so the *logic* (which questions, what score, which weak
+ * domains) is verified without a headless browser.
+ *
+ * Randomness is injected (`rng`, default Math.random) so the sampler is
+ * deterministic under test (pass a seeded rng) and varied in the browser.
+ */
+/** The minimum a question contributes to sampling + scoring. The stem (MDX
+ *  body) is rendered server-side, NOT carried here. */
+interface ExamQuestion {
+    id: string;
+    domain: string;
+    /** MCQ options; exactly one carries `correct: true` (enforced by the schema). */
+    options: ReadonlyArray<{
+        id: string;
+        correct?: boolean;
+    }>;
+}
+interface ExamBlueprint {
+    /** Total questions to sample (clamped to pool size). */
+    count: number;
+    /** Optional per-domain quota (a Bloom/weight blueprint). Filled first, then
+     *  topped up from the rest of the pool to reach `count`. */
+    perDomain?: Readonly<Record<string, number>>;
+}
+/**
+ * Fisher–Yates shuffle with an injectable rng (default Math.random). Pure: it
+ * copies the input rather than mutating it.
+ *
+ * `rng` MUST return a value in `[0, 1)` (Math.random's contract). `j` is
+ * additionally clamped to `i` so a defective rng returning exactly `1.0` can't
+ * index out of bounds (`Math.floor(1.0 * (i+1)) === i+1`), which would otherwise
+ * punch a hole into `a` and grow its length.
+ */
+declare function shuffle<T>(arr: readonly T[], rng?: () => number): T[];
+/**
+ * Sample a question form from the pool. With a `perDomain` blueprint, each
+ * domain's quota is filled first (clamped to availability), then the form is
+ * topped up from the remaining pool to reach `count`. Never returns duplicates;
+ * never more than the pool holds. The result is shuffled so domain-grouped
+ * picks aren't clustered.
+ *
+ * Caller contracts: `rng` returns `[0, 1)` (passed through to `shuffle`); and
+ * `Σ perDomain ≤ count` — quotas summing past `count` are honored in
+ * `Object.entries` order until the budget is spent, so later-listed domains are
+ * silently starved. Validating/clamping the blueprint sum is the caller's job;
+ * a guard can graduate here once a real consumer needs it.
+ */
+declare function sampleExam(pool: readonly ExamQuestion[], blueprint: ExamBlueprint, rng?: () => number): ExamQuestion[];
+interface DomainScore {
+    domain: string;
+    correct: number;
+    total: number;
+}
+interface ExamResult {
+    correct: number;
+    total: number;
+    /** Whole-percent score, 0–100 (0 when no questions). */
+    pct: number;
+    /** Per-domain rollup, in first-seen order. */
+    byDomain: DomainScore[];
+    /** Domains scoring below `passMark` — what the assessment routes the reader to. */
+    weakDomains: string[];
+}
+/**
+ * Score a set of answered questions. `answers` maps question id → chosen option
+ * id; a question is correct when the chosen option is the one flagged
+ * `correct`. Unanswered or wrongly-answered questions count as incorrect.
+ * Rolls up per domain and flags domains below `passMark` (default 0.7) as weak.
+ */
+declare function scoreExam(questions: readonly ExamQuestion[], answers: Readonly<Record<string, string>>, passMark?: number): ExamResult;
+
+/** One exercise as emitted by `book-scaffold build-exercises` (src/data/exercises.json). */
+interface ReviewExercise {
+    id: string;
+    problem: string;
+}
+/** A chapter entry — structurally what `getCollection('chapters')` yields. */
+interface ReviewChapter {
+    id: string;
+    data: Record<string, unknown>;
+}
+interface PartReviewGroup {
+    chapter: string;
+    exercises: ReviewExercise[];
+}
+interface PartReviewSelection {
+    groups: PartReviewGroup[];
+    total: number;
+}
+/**
+ * Select a Part's exercises, in book order, joining `chapters` (filtered by
+ * `part`) against the `byChapter` index (keyed by chapter id). `part` is matched
+ * with `String()` coercion so `<PartReview part="2" />` finds numeric-`part`
+ * chapters and vice versa (the fail-silent trap a strict `===` left). Chapters
+ * with no exercises in the index are skipped; `total` sums the rest.
+ */
+declare function selectPartExercises(chapters: readonly ReviewChapter[], byChapter: Readonly<Record<string, ReviewExercise[]>>, part: number | string): PartReviewSelection;
+
 /**
  * src/styles/built-in.ts — toolkit-shipped Styles, one per BookPreset (v4.0.0).
  *
@@ -504,4 +562,4 @@ type TipsConfigInput = Omit<TipsConfig, typeof TipsConfigBrand | '__tipsConfigVe
  */
 declare function defineTips(opts: TipsConfigInput): TipsConfig;
 
-export { ACADEMIC_PART_NAMES, BRANDON_PORTFOLIO_DEFAULT, BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, ChaptersRenderer, DEFAULT_GITHUB_BRANCH, type Freshness, type FreshnessStatus, KIND_LABEL, Question, type ResolvedTheoremLabel, Style, THEOREM_KINDS, type TheoremKind, type TheoremLabelProps, type TipsConfig, type TipsConfigInput, UNKNOWN_PART_ORDINAL, type VolatilityLevel, academicChaptersRenderer, academicPartHeading, academicPartName, academicPartOrdinal, academicParts, academicStyle, assertEnumProp, assertKnownDomain, bookScaffoldIntegration, buildGithubUrl, chapterLabel, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, deriveObjectiveMap, distinctChaptersSorted, fallbackChaptersRenderer, freshnessLabel, getFreshness, groupByChapter, groupByDomain, minimalStyle, originUrlFromGitConfig, parseRepoSlug, researchPortfolioStyle, resolveBookHref, resolveGithubRepo, sortQuestions, theoremLabel, toolsChaptersRenderer, toolsStyle, volatilityLevels };
+export { ACADEMIC_PART_NAMES, BRANDON_PORTFOLIO_DEFAULT, BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, ChaptersRenderer, DEFAULT_GITHUB_BRANCH, type DomainScore, type ExamBlueprint, type ExamQuestion, type ExamResult, type Freshness, type FreshnessStatus, type PartReviewGroup, type PartReviewSelection, Question, type ReviewChapter, type ReviewExercise, Style, type TipsConfig, type TipsConfigInput, UNKNOWN_PART_ORDINAL, type VolatilityLevel, academicChaptersRenderer, academicPartHeading, academicPartName, academicPartOrdinal, academicParts, academicStyle, assertEnumProp, assertKnownDomain, bookScaffoldIntegration, buildGithubUrl, chapterLabel, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, deriveObjectiveMap, distinctChaptersSorted, fallbackChaptersRenderer, freshnessLabel, getFreshness, groupByChapter, groupByDomain, minimalStyle, originUrlFromGitConfig, parseRepoSlug, researchPortfolioStyle, resolveBookHref, resolveGithubRepo, sampleExam, scoreExam, selectPartExercises, shuffle, sortQuestions, toolsChaptersRenderer, toolsStyle, volatilityLevels };

package/dist/index.mjs

@@ -462,6 +462,18 @@ function refineQuestion(q, ctx) {
   }
 }
 var refinedQuestionSchema = questionSchema.superRefine(refineQuestion);
+var glossarySchema = z.object({
+  term: z.string().trim().min(1),
+  // display term (required)
+  aliases: z.array(z.string()).default([]),
+  // synonyms / alternate spellings (searchable)
+  domain: z.string().optional(),
+  // optional grouping (e.g. an exam domain)
+  see: z.array(z.string()).default([]),
+  // related glossary entry ids (cross-links)
+  tags: z.array(z.string()).default([]),
+  draft: z.boolean().default(false)
+}).strict();
 
 // src/lib/academic-parts.ts
 var ACADEMIC_PART_NAMES = {
@@ -555,6 +567,8 @@ var academicProfile = defineProfile({
     // v4.4.0: opt-in per book; requires build-exercises
     practiceExam: false,
     // v4.17.0 #112: opt-in per book; requires src/content/questions/
+    glossary: false,
+    // v4.19.0 #115: 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
   },
@@ -680,6 +694,8 @@ var toolsProfile = defineProfile({
     // v4.4.0: opt-in per book
     practiceExam: false,
     // v4.17.0 #112: opt-in per book; requires src/content/questions/
+    glossary: false,
+    // v4.19.0 #115: opt-in per book; requires src/content/glossary/
     landing: true
     // v4.5.0: auto-inject minimal root landing
   },
@@ -767,6 +783,8 @@ var minimalProfile = defineProfile({
     // v4.4.0: opt-in per book
     practiceExam: false,
     // v4.17.0 #112: opt-in per book; requires src/content/questions/
+    glossary: false,
+    // v4.19.0 #115: opt-in per book; requires src/content/glossary/
     landing: true
     // v4.5.0: auto-inject minimal root landing
   },
@@ -794,6 +812,8 @@ var courseNotesProfile = defineProfile({
     // v4.4.0: opt-in per book
     practiceExam: false,
     // v4.17.0 #112: opt-in per book; requires src/content/questions/
+    glossary: false,
+    // v4.19.0 #115: opt-in per book; requires src/content/glossary/
     landing: true
     // v4.5.0: auto-inject minimal root landing
   },
@@ -825,6 +845,8 @@ var researchPortfolioProfile = defineProfile({
     // v4.4.0: opt-in per book
     practiceExam: false,
     // v4.17.0 #112: opt-in per book; requires src/content/questions/
+    glossary: false,
+    // v4.19.0 #115: opt-in per book; requires src/content/glossary/
     landing: true
     // v4.5.0: auto-inject minimal root landing
   },
@@ -1108,6 +1130,9 @@ var ROUTE_REGISTRY = {
   // v4.17.0 (Tier 3, #112): static practice question-bank. Opt-in via
   // routes.practiceExam: true; reads the `questions` collection + examDomains.
   practiceExam: { pattern: "/practice-exam", file: "practice-exam.astro" },
+  // v4.19.0 (#115): searchable key-terms glossary. Opt-in via routes.glossary:
+  // true; reads the `glossary` collection (src/content/glossary/).
+  glossary: { pattern: "/glossary", file: "glossary.astro" },
   // v4.5.0: minimal root landing page. Reads title/description/portfolio/routes
   // from vite.define-injected import.meta.env vars. Default-on per profile;
   // consumers with their own src/pages/index.astro override (file-system route
@@ -1498,6 +1523,9 @@ function theoremLabel(props) {
   const fullLabel = name ? `${numbered} (${name})` : numbered;
   return { kind: raw, fullLabel };
 }
+function resolveTheoremNumber(entry, n) {
+  return entry?.number ?? n;
+}
 
 // src/lib/assert-prop.ts
 function assertEnumProp(value, allowed, ctx) {
@@ -1588,6 +1616,77 @@ function distinctChaptersSorted(entries) {
   }).map(chapterLabel);
 }
 
+// src/lib/exam-engine.ts
+function shuffle(arr, rng = Math.random) {
+  const a = arr.slice();
+  for (let i = a.length - 1; i > 0; i--) {
+    const j = Math.min(i, Math.floor(rng() * (i + 1)));
+    const ai = a[i];
+    a[i] = a[j];
+    a[j] = ai;
+  }
+  return a;
+}
+function sampleExam(pool, blueprint, rng = Math.random) {
+  const count = Math.max(0, Math.min(blueprint.count, pool.length));
+  const picked = [];
+  const used = /* @__PURE__ */ new Set();
+  if (blueprint.perDomain) {
+    for (const [domain, quota] of Object.entries(blueprint.perDomain)) {
+      const inDomain = shuffle(
+        pool.filter((q) => q.domain === domain && !used.has(q.id)),
+        rng
+      );
+      for (const q of inDomain.slice(0, Math.max(0, quota))) {
+        if (picked.length >= count) break;
+        picked.push(q);
+        used.add(q.id);
+      }
+    }
+  }
+  for (const q of shuffle(pool.filter((q2) => !used.has(q2.id)), rng)) {
+    if (picked.length >= count) break;
+    picked.push(q);
+    used.add(q.id);
+  }
+  return shuffle(picked, rng);
+}
+function scoreExam(questions, answers, passMark = 0.7) {
+  const order = [];
+  const tally = /* @__PURE__ */ new Map();
+  let correct = 0;
+  for (const q of questions) {
+    const chosen = answers[q.id];
+    const right = chosen !== void 0 && q.options.some((o) => o.correct === true && o.id === chosen);
+    if (right) correct++;
+    if (!tally.has(q.domain)) {
+      tally.set(q.domain, { correct: 0, total: 0 });
+      order.push(q.domain);
+    }
+    const t = tally.get(q.domain);
+    t.total++;
+    if (right) t.correct++;
+  }
+  const total = questions.length;
+  const byDomain = order.map((domain) => ({ domain, ...tally.get(domain) }));
+  const weakDomains = byDomain.filter((d) => d.total > 0 && d.correct / d.total < passMark).map((d) => d.domain);
+  return {
+    correct,
+    total,
+    pct: total === 0 ? 0 : Math.round(correct / total * 100),
+    byDomain,
+    weakDomains
+  };
+}
+
+// src/lib/part-review.ts
+function selectPartExercises(chapters, byChapter, part) {
+  const want = String(part);
+  const groups = chapters.filter((c) => String(c.data.part ?? "") === want).sort((a, b) => chapterSortKey(a.data) - chapterSortKey(b.data)).map((c) => ({ chapter: c.id, exercises: byChapter[c.id] ?? [] })).filter((g) => g.exercises.length > 0);
+  const total = groups.reduce((n, g) => n + g.exercises.length, 0);
+  return { groups, total };
+}
+
 // src/styles/built-in.ts
 var academicStyle = defineStyle({
   name: "academic",
@@ -1669,6 +1768,7 @@ export {
   fallbackChaptersRenderer,
   freshnessLabel,
   getFreshness,
+  glossarySchema,
   groupByChapter,
   groupByDomain,
   minimalChapterSchema,
@@ -1691,6 +1791,11 @@ export {
   resolveGithubRepo,
   resolvePreset,
   resolveProfile,
+  resolveTheoremNumber,
+  sampleExam,
+  scoreExam,
+  selectPartExercises,
+  shuffle,
   sortQuestions,
   sourceTiers,
   sourceTiersResearch,