@brandon_m_behring/book-scaffold-astro 4.21.0 → 4.23.0

package/CLAUDE.md

@@ -104,7 +104,7 @@ Two callout families coexist. Authors import what they need.
 
 **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. `<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>`). **Interactive layer (v4.21.0, #112-UI/#113/#114):** `/practice-exam` mounts the **ExamRunner island** (`client:idle`) — Start samples a form client-side (`sampleExam`), hides the rest of the bank + the answer reveals, scores checked radios on submit (`scoreExam`), and reads out per-domain results with weak-domain anchors (no JS → the static bank is the fallback). `<AssessmentTest />` is the whole-book front-matter diagnostic: a cross-domain sampled form whose weak-domain readout routes to the chapters carrying those domains' questions. The `/answers` route (`routes: { answers: true }`) is the Sybex back-appendix — every question grouped by chapter with the correct answer + rationale pre-expanded; `<Rationale appendix for="<id>">` renders inline as a link into it (and throws at build without `for=` or with the route disabled). (Flashcards are the remaining increment — 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>`). **Interactive layer (v4.21.0, #112-UI/#113/#114):** `/practice-exam` mounts the **ExamRunner island** (`client:idle`) — Start samples a form client-side (`sampleExam`), hides the rest of the bank + the answer reveals, scores checked radios on submit (`scoreExam`), and reads out per-domain results with weak-domain anchors (no JS → the static bank is the fallback). `<AssessmentTest />` is the whole-book front-matter diagnostic: a cross-domain sampled form whose weak-domain readout routes to the chapters carrying those domains' questions. The `/answers` route (`routes: { answers: true }`) is the Sybex back-appendix — every question grouped by chapter with the correct answer + rationale pre-expanded; `<Rationale appendix for="<id>">` renders inline as a link into it (and throws at build without `for=` or with the route disabled). **Flashcards (v4.22.0, #116):** the `/flashcards` route (`routes: { flashcards: true }`) turns the glossary into a spaced-recall deck — shuffled, one term at a time, flip-to-check, with knew-it/still-learning buckets persisted to localStorage and a "review unknown only" pass; no JS → the full front+back list reads like a compact glossary. That completes the study-guide epic (#122).
 
 Full reference in `recipes/04-component-library.md`.
 

package/components/Flashcards.tsx

@@ -0,0 +1,247 @@
+/**
+ * Flashcards — Preact island for the spaced-recall deck (#116).
+ *
+ * Same controller-over-server-rendered-cards architecture as ExamRunner: card
+ * backs are MDX glossary definitions (not serializable into island props), so
+ * flashcards.astro renders every card statically and this island receives only
+ * the deck manifest (id + front). Start shuffles (the exam-engine Fisher–Yates)
+ * and shows ONE card at a time — others get the `hidden` attribute, the
+ * wrapper gains data-flashcards-mode="deck", and CSS keyed on that attribute
+ * hides the back of the unflipped current card. Know/still-learning buckets
+ * persist to localStorage (ToolFilter pattern) so the "review unknown only"
+ * pass survives reloads. No JS → the full front+back list stays readable.
+ *
+ * DOM contract with flashcards.astro:
+ *   [data-flashcards-root]          wrapper; gains data-flashcards-mode="deck"
+ *   [data-card-id="<id>"]           one card per term; `hidden` toggled;
+ *                                   gains/loses class "flashcard-flipped"
+ *
+ * Fail-loud (house invariant): a missing wrapper or deck/DOM drift throws a
+ * named error — never silently dead buttons or a silently short deck.
+ *
+ * Hydrated with `client:idle`. Colors via CSS tokens only.
+ */
+import { useEffect, useRef, useState } from 'preact/hooks';
+import { shuffle } from '../src/lib/exam-engine';
+import type { FlashcardRef } from '../src/lib/flashcards';
+
+const STORAGE_KEY = 'book:flashcards:known';
+
+interface Props {
+  /** Deck manifest (buildFlashcardDeck output) — card ids + fronts only. */
+  deck: FlashcardRef[];
+}
+
+type Phase = 'idle' | 'deck';
+
+function readKnown(): Set<string> {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return new Set();
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return new Set();
+    return new Set(parsed.filter((s): s is string => typeof s === 'string'));
+  } catch {
+    return new Set();
+  }
+}
+
+function writeKnown(known: Set<string>): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify([...known]));
+  } catch {
+    /* localStorage unavailable — keep in-memory state only */
+  }
+}
+
+export default function Flashcards({ deck }: Props) {
+  const [phase, setPhase] = useState<Phase>('idle');
+  const [order, setOrder] = useState<string[]>([]);
+  const [pos, setPos] = useState(0);
+  const [flipped, setFlipped] = useState(false);
+  const [known, setKnown] = useState<Set<string>>(new Set());
+  const [unknownOnly, setUnknownOnly] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    // Intersect the stored bucket with the CURRENT deck: a term deleted from
+    // the glossary would otherwise inflate "marked known" forever (even past
+    // deck.length) — evict stale ids on mount and persist the cleaned set.
+    const stored = readKnown();
+    const deckIds = new Set(deck.map((c) => c.id));
+    const cleaned = new Set([...stored].filter((id) => deckIds.has(id)));
+    if (cleaned.size !== stored.size) writeKnown(cleaned);
+    setKnown(cleaned);
+  }, []);
+
+  function requireRoot(): HTMLElement {
+    const r = ref.current?.closest<HTMLElement>('[data-flashcards-root]');
+    if (!r) {
+      throw new Error(
+        'Flashcards: no [data-flashcards-root] ancestor — mount the island inside ' +
+          'the wrapper that contains its cards (see the DOM contract in Flashcards.tsx).',
+      );
+    }
+    return r;
+  }
+  function cardEl(r: HTMLElement, id: string): HTMLElement {
+    const el = r.querySelector<HTMLElement>(`[data-card-id="${CSS.escape(id)}"]`);
+    if (!el) {
+      throw new Error(`Flashcards: deck/DOM drift — no rendered card for term "${id}".`);
+    }
+    return el;
+  }
+  function allCards(r: HTMLElement): HTMLElement[] {
+    return Array.from(r.querySelectorAll<HTMLElement>('[data-card-id]'));
+  }
+
+  function showOnly(r: HTMLElement, id: string): void {
+    for (const card of allCards(r)) {
+      card.hidden = card.dataset.cardId !== id;
+      card.classList.remove('flashcard-flipped');
+    }
+    setFlipped(false);
+  }
+
+  function start(): void {
+    const r = requireRoot();
+    const pool = unknownOnly ? deck.filter((c) => !known.has(c.id)) : deck;
+    if (pool.length === 0) return; // the idle UI disables Start in this state
+    const shuffled = shuffle(pool.map((c) => c.id));
+    // Fail loud on drift before hiding anything (ExamRunner precedent).
+    for (const id of shuffled) cardEl(r, id);
+    r.setAttribute('data-flashcards-mode', 'deck');
+    showOnly(r, shuffled[0]!);
+    setOrder(shuffled);
+    setPos(0);
+    setPhase('deck');
+  }
+
+  function goTo(next: number): void {
+    const r = requireRoot();
+    const clamped = Math.max(0, Math.min(next, order.length - 1));
+    showOnly(r, order[clamped]!);
+    setPos(clamped);
+  }
+
+  function flip(): void {
+    const r = requireRoot();
+    const card = cardEl(r, order[pos]!);
+    const next = !flipped;
+    card.classList.toggle('flashcard-flipped', next);
+    setFlipped(next);
+  }
+
+  function mark(knewIt: boolean): void {
+    const id = order[pos]!;
+    const next = new Set(known);
+    if (knewIt) next.add(id);
+    else next.delete(id);
+    setKnown(next);
+    writeKnown(next);
+    if (pos < order.length - 1) goTo(pos + 1);
+    else end();
+  }
+
+  function end(): void {
+    const r = requireRoot();
+    for (const card of allCards(r)) {
+      card.hidden = false;
+      card.classList.remove('flashcard-flipped');
+    }
+    r.removeAttribute('data-flashcards-mode');
+    setPhase('idle');
+    setOrder([]);
+    setPos(0);
+    setFlipped(false);
+  }
+
+  function resetKnown(): void {
+    const next = new Set<string>();
+    setKnown(next);
+    writeKnown(next);
+  }
+
+  if (deck.length === 0) {
+    return <p class="flashcards-empty">No glossary terms to study yet.</p>;
+  }
+
+  const unknownCount = deck.filter((c) => !known.has(c.id)).length;
+  const poolSize = unknownOnly ? unknownCount : deck.length;
+
+  return (
+    <div class="flashcards-runner" ref={ref}>
+      {phase === 'idle' && (
+        <div class="flashcards-controls">
+          <p class="flashcards-intro">
+            Study the glossary as flashcards: shuffled, one term at a time — recall the
+            definition, flip to check, and sort each card into "knew it" / "still learning".
+          </p>
+          <p class="flashcards-stats" role="status">
+            {deck.length} card{deck.length === 1 ? '' : 's'} · {known.size} marked known
+            {known.size > 0 && (
+              <>
+                {' '}
+                (<button type="button" class="flashcards-link" onClick={resetKnown}>reset</button>)
+              </>
+            )}
+          </p>
+          <label class="flashcards-filter-label">
+            <input
+              type="checkbox"
+              checked={unknownOnly}
+              onInput={(e) => setUnknownOnly((e.target as HTMLInputElement).checked)}
+            />{' '}
+            only cards I don't know yet ({unknownCount})
+          </label>
+          <button
+            type="button"
+            class="flashcards-button flashcards-start"
+            onClick={start}
+            disabled={poolSize === 0}
+          >
+            {poolSize === 0 ? 'All cards marked known — reset to review' : `Start deck (${poolSize})`}
+          </button>
+        </div>
+      )}
+
+      {phase === 'deck' && (
+        <div class="flashcards-controls">
+          <p class="flashcards-progress" role="status">
+            Card {pos + 1} of {order.length} · {known.size} known
+          </p>
+          <div class="flashcards-buttons">
+            <button type="button" class="flashcards-button flashcards-flip" onClick={flip}>
+              {flipped ? 'Hide definition' : 'Flip'}
+            </button>
+            <button type="button" class="flashcards-button flashcards-knew" onClick={() => mark(true)}>
+              Knew it
+            </button>
+            <button type="button" class="flashcards-button flashcards-learning" onClick={() => mark(false)}>
+              Still learning
+            </button>
+            <button
+              type="button"
+              class="flashcards-button flashcards-prev"
+              onClick={() => goTo(pos - 1)}
+              disabled={pos === 0}
+            >
+              ← Prev
+            </button>
+            <button
+              type="button"
+              class="flashcards-button flashcards-next"
+              onClick={() => goTo(pos + 1)}
+              disabled={pos === order.length - 1}
+            >
+              Next →
+            </button>
+            <button type="button" class="flashcards-button flashcards-end" onClick={end}>
+              End — show all
+            </button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

package/components/Sidebar.astro

@@ -14,16 +14,20 @@
  * Visual: ~280px wide, sticky to top, scrollable independently of main.
  * Site title at top doubles as a "home" link.
  *
- * Customize: edit the `siteTitle` / `siteSubtitle` strings below or pass
- * them in as Astro.props from Base.astro if you want per-page overrides.
+ * Customize (v4.23.0, #135): the brand reads `defineBookConfig({ title,
+ * subtitle })` via the book-config virtual module — consumers set both in
+ * astro.config.mjs with zero component overrides. The previous hardcoded
+ * strings remain the fallbacks, so existing books render unchanged until
+ * they configure a title.
  */
 import { getCollection } from 'astro:content';
+import bookConfig from 'virtual:book-scaffold/book-config';
 import { academicParts } from '../src/schemas';
 import { academicPartHeading } from '../src/lib/academic-parts';
 
 const profile = import.meta.env.BOOK_PROFILE ?? 'minimal';
-const siteTitle = 'Book';
-const siteSubtitle = 'A scaffold-astro book';
+const siteTitle = bookConfig.title ?? 'Book';
+const siteSubtitle = bookConfig.subtitle ?? 'A scaffold-astro book';
 
 // Academic profile: part is a string enum. `academicParts` (schemas.ts) is
 // the canonical order, shared with the renderer and ChapterHeader (#95); the

package/dist/components/Flashcards.d.ts

@@ -0,0 +1,12 @@
+import * as preact from 'preact';
+import { F as FlashcardRef } from '../flashcards-DPFFQhP8.js';
+import '../schemas-DDWDRUxs.js';
+import 'astro/zod';
+
+interface Props {
+    /** Deck manifest (buildFlashcardDeck output) — card ids + fronts only. */
+    deck: FlashcardRef[];
+}
+declare function Flashcards({ deck }: Props): preact.JSX.Element;
+
+export { Flashcards as default };

package/dist/components/Flashcards.mjs

@@ -0,0 +1,217 @@
+// components/Flashcards.tsx
+import { useEffect, useRef, useState } from "preact/hooks";
+
+// 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;
+}
+
+// components/Flashcards.tsx
+import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
+var STORAGE_KEY = "book:flashcards:known";
+function readKnown() {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return /* @__PURE__ */ new Set();
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return /* @__PURE__ */ new Set();
+    return new Set(parsed.filter((s) => typeof s === "string"));
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+}
+function writeKnown(known) {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify([...known]));
+  } catch {
+  }
+}
+function Flashcards({ deck }) {
+  const [phase, setPhase] = useState("idle");
+  const [order, setOrder] = useState([]);
+  const [pos, setPos] = useState(0);
+  const [flipped, setFlipped] = useState(false);
+  const [known, setKnown] = useState(/* @__PURE__ */ new Set());
+  const [unknownOnly, setUnknownOnly] = useState(false);
+  const ref = useRef(null);
+  useEffect(() => {
+    const stored = readKnown();
+    const deckIds = new Set(deck.map((c) => c.id));
+    const cleaned = new Set([...stored].filter((id) => deckIds.has(id)));
+    if (cleaned.size !== stored.size) writeKnown(cleaned);
+    setKnown(cleaned);
+  }, []);
+  function requireRoot() {
+    const r = ref.current?.closest("[data-flashcards-root]");
+    if (!r) {
+      throw new Error(
+        "Flashcards: no [data-flashcards-root] ancestor \u2014 mount the island inside the wrapper that contains its cards (see the DOM contract in Flashcards.tsx)."
+      );
+    }
+    return r;
+  }
+  function cardEl(r, id) {
+    const el = r.querySelector(`[data-card-id="${CSS.escape(id)}"]`);
+    if (!el) {
+      throw new Error(`Flashcards: deck/DOM drift \u2014 no rendered card for term "${id}".`);
+    }
+    return el;
+  }
+  function allCards(r) {
+    return Array.from(r.querySelectorAll("[data-card-id]"));
+  }
+  function showOnly(r, id) {
+    for (const card of allCards(r)) {
+      card.hidden = card.dataset.cardId !== id;
+      card.classList.remove("flashcard-flipped");
+    }
+    setFlipped(false);
+  }
+  function start() {
+    const r = requireRoot();
+    const pool = unknownOnly ? deck.filter((c) => !known.has(c.id)) : deck;
+    if (pool.length === 0) return;
+    const shuffled = shuffle(pool.map((c) => c.id));
+    for (const id of shuffled) cardEl(r, id);
+    r.setAttribute("data-flashcards-mode", "deck");
+    showOnly(r, shuffled[0]);
+    setOrder(shuffled);
+    setPos(0);
+    setPhase("deck");
+  }
+  function goTo(next) {
+    const r = requireRoot();
+    const clamped = Math.max(0, Math.min(next, order.length - 1));
+    showOnly(r, order[clamped]);
+    setPos(clamped);
+  }
+  function flip() {
+    const r = requireRoot();
+    const card = cardEl(r, order[pos]);
+    const next = !flipped;
+    card.classList.toggle("flashcard-flipped", next);
+    setFlipped(next);
+  }
+  function mark(knewIt) {
+    const id = order[pos];
+    const next = new Set(known);
+    if (knewIt) next.add(id);
+    else next.delete(id);
+    setKnown(next);
+    writeKnown(next);
+    if (pos < order.length - 1) goTo(pos + 1);
+    else end();
+  }
+  function end() {
+    const r = requireRoot();
+    for (const card of allCards(r)) {
+      card.hidden = false;
+      card.classList.remove("flashcard-flipped");
+    }
+    r.removeAttribute("data-flashcards-mode");
+    setPhase("idle");
+    setOrder([]);
+    setPos(0);
+    setFlipped(false);
+  }
+  function resetKnown() {
+    const next = /* @__PURE__ */ new Set();
+    setKnown(next);
+    writeKnown(next);
+  }
+  if (deck.length === 0) {
+    return /* @__PURE__ */ jsx("p", { class: "flashcards-empty", children: "No glossary terms to study yet." });
+  }
+  const unknownCount = deck.filter((c) => !known.has(c.id)).length;
+  const poolSize = unknownOnly ? unknownCount : deck.length;
+  return /* @__PURE__ */ jsxs("div", { class: "flashcards-runner", ref, children: [
+    phase === "idle" && /* @__PURE__ */ jsxs("div", { class: "flashcards-controls", children: [
+      /* @__PURE__ */ jsx("p", { class: "flashcards-intro", children: 'Study the glossary as flashcards: shuffled, one term at a time \u2014 recall the definition, flip to check, and sort each card into "knew it" / "still learning".' }),
+      /* @__PURE__ */ jsxs("p", { class: "flashcards-stats", role: "status", children: [
+        deck.length,
+        " card",
+        deck.length === 1 ? "" : "s",
+        " \xB7 ",
+        known.size,
+        " marked known",
+        known.size > 0 && /* @__PURE__ */ jsxs(Fragment, { children: [
+          " ",
+          "(",
+          /* @__PURE__ */ jsx("button", { type: "button", class: "flashcards-link", onClick: resetKnown, children: "reset" }),
+          ")"
+        ] })
+      ] }),
+      /* @__PURE__ */ jsxs("label", { class: "flashcards-filter-label", children: [
+        /* @__PURE__ */ jsx(
+          "input",
+          {
+            type: "checkbox",
+            checked: unknownOnly,
+            onInput: (e) => setUnknownOnly(e.target.checked)
+          }
+        ),
+        " ",
+        "only cards I don't know yet (",
+        unknownCount,
+        ")"
+      ] }),
+      /* @__PURE__ */ jsx(
+        "button",
+        {
+          type: "button",
+          class: "flashcards-button flashcards-start",
+          onClick: start,
+          disabled: poolSize === 0,
+          children: poolSize === 0 ? "All cards marked known \u2014 reset to review" : `Start deck (${poolSize})`
+        }
+      )
+    ] }),
+    phase === "deck" && /* @__PURE__ */ jsxs("div", { class: "flashcards-controls", children: [
+      /* @__PURE__ */ jsxs("p", { class: "flashcards-progress", role: "status", children: [
+        "Card ",
+        pos + 1,
+        " of ",
+        order.length,
+        " \xB7 ",
+        known.size,
+        " known"
+      ] }),
+      /* @__PURE__ */ jsxs("div", { class: "flashcards-buttons", children: [
+        /* @__PURE__ */ jsx("button", { type: "button", class: "flashcards-button flashcards-flip", onClick: flip, children: flipped ? "Hide definition" : "Flip" }),
+        /* @__PURE__ */ jsx("button", { type: "button", class: "flashcards-button flashcards-knew", onClick: () => mark(true), children: "Knew it" }),
+        /* @__PURE__ */ jsx("button", { type: "button", class: "flashcards-button flashcards-learning", onClick: () => mark(false), children: "Still learning" }),
+        /* @__PURE__ */ jsx(
+          "button",
+          {
+            type: "button",
+            class: "flashcards-button flashcards-prev",
+            onClick: () => goTo(pos - 1),
+            disabled: pos === 0,
+            children: "\u2190 Prev"
+          }
+        ),
+        /* @__PURE__ */ jsx(
+          "button",
+          {
+            type: "button",
+            class: "flashcards-button flashcards-next",
+            onClick: () => goTo(pos + 1),
+            disabled: pos === order.length - 1,
+            children: "Next \u2192"
+          }
+        ),
+        /* @__PURE__ */ jsx("button", { type: "button", class: "flashcards-button flashcards-end", onClick: end, children: "End \u2014 show all" })
+      ] })
+    ] })
+  ] });
+}
+export {
+  Flashcards as default
+};

package/dist/flashcards-DPFFQhP8.d.ts

@@ -0,0 +1,36 @@
+import { G as GlossaryTerm } from './schemas-DDWDRUxs.js';
+
+/**
+ * flashcards.ts — PURE deck-manifest bridge between the `glossary` collection
+ * and the Flashcards island (#116).
+ *
+ * Same architecture as exam-manifest.ts: card backs are MDX definitions
+ * (server-rendered — not serializable into island props), so the island
+ * receives only this manifest (id + front text) and controls the
+ * server-rendered cards by id. Question/objective-derived cards are a
+ * deliberate later increment; v1 decks are glossary-only.
+ *
+ * No astro:content import — node-tested straight from dist/
+ * (tests/flashcards.test.mjs).
+ */
+
+/** One deck entry: the stable card id + the front (the display term). */
+interface FlashcardRef {
+    id: string;
+    front: string;
+}
+/** The entry shape accepted — a CollectionEntry-like wrapper (glossary
+ *  entries carry the file-derived `id` at the top level, not in data). */
+type GlossaryLike = {
+    id: string;
+    data: Pick<GlossaryTerm, 'term' | 'draft'>;
+};
+/**
+ * Build the deck manifest: published (non-draft) terms, alphabetical by
+ * display term (locale-aware — same order as /glossary, so the static list
+ * fallback and the deck agree). Draft filtering is defensive; the shipped
+ * caller passes getCollection('glossary', e => !e.data.draft) output.
+ */
+declare function buildFlashcardDeck(entries: readonly GlossaryLike[]): FlashcardRef[];
+
+export { type FlashcardRef as F, buildFlashcardDeck as b };

package/dist/index.d.ts

@@ -1,10 +1,11 @@
 import { AstroUserConfig, AstroIntegration } from 'astro';
-import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, h as ChaptersRenderer, l as Style } from './types-uerMuJwT.js';
-export { B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookPreset, e as BookProfile, g as BookSchemasOptions, C as ChapterFor, F as FreshnessAffordance, i as FrontmatterRouteConfig, P as PartKey, j as PartialRouteToggles, k as ProfileDefinition, R as RouteToggles, S as StatusBadge, m as StyleInput, V as VolatilityBadge, n as composeStyles, o as defineProfile, p as defineStyle, q as normalizeFrontmatterConfig, r as resolvePreset, s as resolveProfile } from './types-uerMuJwT.js';
+import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, h as ChaptersRenderer, l as Style } from './types-CGN95mrX.js';
+export { B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookPreset, e as BookProfile, g as BookSchemasOptions, C as ChapterFor, F as FreshnessAffordance, i as FrontmatterRouteConfig, P as PartKey, j as PartialRouteToggles, k as ProfileDefinition, R as RouteToggles, S as StatusBadge, m as StyleInput, V as VolatilityBadge, n as composeStyles, o as defineProfile, p as defineStyle, q as normalizeFrontmatterConfig, r as resolvePreset, s as resolveProfile } from './types-CGN95mrX.js';
 import { D as volatilityLevels, c as academicParts, Q as Question } from './schemas-DDWDRUxs.js';
 export { A as AcademicChapter, B as BloomLevel, C as CourseNotesChapter, G as GlossaryTerm, M as MinimalChapter, P as Provenance, a as QuestionType, R as ResearchPortfolioChapter, T as ToolsChapter, b as academicChapterSchema, d as bloomLevels, e as changeKinds, f as changelogSchema, g as chapterStatus, h as citationBackstops, i as courseNotesChapterSchema, j as glossarySchema, m as minimalChapterSchema, p as patternCategories, k as patternsSchema, l as provenanceObject, n as provenanceSchema, q as questionDifficulties, o as questionSchema, r as questionTypes, s as refineQuestion, t as refinedQuestionSchema, u as researchPortfolioChapterSchema, v as sourceTiers, w as sourceTiersResearch, x as sourcesSchema, y as toolSlugs, z as toolsChapterSchema } from './schemas-DDWDRUxs.js';
 export { KIND_LABEL, ResolvedTheoremLabel, THEOREM_KINDS, TheoremKind, TheoremLabelProps, resolveTheoremNumber, theoremLabel } from './lib/theorem-label.js';
 export { D as DomainScore, E as ExamBlueprint, a as ExamQuestion, b as ExamResult, R as RoutingChapter, c as buildExamManifest, d as deriveDomainRouting, s as sampleExam, e as scoreExam, f as shuffle, g as spreadBlueprint } from './exam-manifest-DbTHo90M.js';
+export { F as FlashcardRef, b as buildFlashcardDeck } from './flashcards-DPFFQhP8.js';
 import 'astro/zod';
 
 /**

package/dist/index.mjs

@@ -571,6 +571,8 @@ var academicProfile = defineProfile({
     // v4.19.0 #115: opt-in per book; requires src/content/glossary/
     answers: false,
     // v4.21.0 #114: opt-in per book; requires src/content/questions/
+    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
   },
@@ -700,6 +702,8 @@ var toolsProfile = defineProfile({
     // v4.19.0 #115: opt-in per book; requires src/content/glossary/
     answers: false,
     // v4.21.0 #114: opt-in per book; requires src/content/questions/
+    flashcards: false,
+    // v4.22.0 #116: opt-in per book; requires src/content/glossary/
     landing: true
     // v4.5.0: auto-inject minimal root landing
   },
@@ -791,6 +795,8 @@ var minimalProfile = defineProfile({
     // v4.19.0 #115: opt-in per book; requires src/content/glossary/
     answers: false,
     // v4.21.0 #114: opt-in per book; requires src/content/questions/
+    flashcards: false,
+    // v4.22.0 #116: opt-in per book; requires src/content/glossary/
     landing: true
     // v4.5.0: auto-inject minimal root landing
   },
@@ -822,6 +828,8 @@ var courseNotesProfile = defineProfile({
     // v4.19.0 #115: opt-in per book; requires src/content/glossary/
     answers: false,
     // v4.21.0 #114: opt-in per book; requires src/content/questions/
+    flashcards: false,
+    // v4.22.0 #116: opt-in per book; requires src/content/glossary/
     landing: true
     // v4.5.0: auto-inject minimal root landing
   },
@@ -857,6 +865,8 @@ var researchPortfolioProfile = defineProfile({
     // v4.19.0 #115: opt-in per book; requires src/content/glossary/
     answers: false,
     // v4.21.0 #114: opt-in per book; requires src/content/questions/
+    flashcards: false,
+    // v4.22.0 #116: opt-in per book; requires src/content/glossary/
     landing: true
     // v4.5.0: auto-inject minimal root landing
   },
@@ -1146,6 +1156,9 @@ var ROUTE_REGISTRY = {
   // v4.21.0 (#114): answer-rationale back-appendix. Opt-in via routes.answers:
   // true; reads the `questions` collection with everything revealed.
   answers: { pattern: "/answers", file: "answers.astro" },
+  // v4.22.0 (#116): glossary flashcards deck. Opt-in via routes.flashcards:
+  // true; reads the `glossary` collection (src/content/glossary/).
+  flashcards: { pattern: "/flashcards", file: "flashcards.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
@@ -1175,6 +1188,7 @@ function bookScaffoldIntegration(opts) {
     mdxComponentsModule,
     // v4.5.0: landing-page data, propagated via virtual module to /index.astro.
     title,
+    subtitle,
     description,
     portfolio,
     // v4.6.0: book-level author + SEO config, propagated through the
@@ -1238,6 +1252,7 @@ function bookScaffoldIntegration(opts) {
               makeMdxComponentsVitePlugin(resolvedMdxPath),
               makeBookConfigVitePlugin({
                 title: title ?? null,
+                subtitle: subtitle ?? null,
                 description: description ?? null,
                 portfolio: portfolio ?? false,
                 enabledRoutes: enabledRouteNames,
@@ -1375,6 +1390,8 @@ async function defineBookConfig(opts) {
       // v4.5.0: pass landing-page data through to the integration so it can
       // be exposed to the auto-injected /index.astro via the virtual module.
       title: opts.title,
+      // v4.23.0 (#135): sidebar brand subtitle.
+      subtitle: opts.subtitle,
       description: opts.description,
       portfolio: resolvedPortfolio,
       // v4.6.0: book-level author + SEO config (ogImage, twitterHandle),
@@ -1426,6 +1443,7 @@ async function defineBookConfig(opts) {
     katexMacros: _katexMacros,
     // v4.5.0: strip new landing-related opts so they don't leak into AstroUserConfig.
     title: _title,
+    subtitle: _subtitle,
     description: _description,
     portfolio: _portfolio,
     // v4.6.0: strip new book-level SEO opts (author + seo block).
@@ -1450,6 +1468,7 @@ async function defineBookConfig(opts) {
   void _markdown;
   void _katexMacros;
   void _title;
+  void _subtitle;
   void _description;
   void _portfolio;
   void _author;
@@ -1725,6 +1744,11 @@ function spreadBlueprint(pool, count) {
   };
 }
 
+// src/lib/flashcards.ts
+function buildFlashcardDeck(entries) {
+  return entries.filter((e) => !e.data.draft).map((e) => ({ id: e.id, front: e.data.term })).sort((a, b) => a.front.localeCompare(b.front));
+}
+
 // src/lib/part-review.ts
 function selectPartExercises(chapters, byChapter, part) {
   const want = String(part);
@@ -1795,6 +1819,7 @@ export {
   bloomLevels,
   bookScaffoldIntegration,
   buildExamManifest,
+  buildFlashcardDeck,
   buildGithubUrl,
   changeKinds,
   changelogSchema,

package/dist/schemas.d.ts

@@ -1,5 +1,5 @@
 import { defineCollection } from 'astro:content';
-import { g as BookSchemasOptions } from './types-uerMuJwT.js';
+import { g as BookSchemasOptions } from './types-CGN95mrX.js';
 import 'astro';
 import './schemas-DDWDRUxs.js';
 import 'astro/zod';

package/dist/schemas.mjs

@@ -449,6 +449,8 @@ var academicProfile = defineProfile({
     // v4.19.0 #115: opt-in per book; requires src/content/glossary/
     answers: false,
     // v4.21.0 #114: opt-in per book; requires src/content/questions/
+    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
   },
@@ -578,6 +580,8 @@ var toolsProfile = defineProfile({
     // v4.19.0 #115: opt-in per book; requires src/content/glossary/
     answers: false,
     // v4.21.0 #114: opt-in per book; requires src/content/questions/
+    flashcards: false,
+    // v4.22.0 #116: opt-in per book; requires src/content/glossary/
     landing: true
     // v4.5.0: auto-inject minimal root landing
   },
@@ -669,6 +673,8 @@ var minimalProfile = defineProfile({
     // v4.19.0 #115: opt-in per book; requires src/content/glossary/
     answers: false,
     // v4.21.0 #114: opt-in per book; requires src/content/questions/
+    flashcards: false,
+    // v4.22.0 #116: opt-in per book; requires src/content/glossary/
     landing: true
     // v4.5.0: auto-inject minimal root landing
   },
@@ -700,6 +706,8 @@ var courseNotesProfile = defineProfile({
     // v4.19.0 #115: opt-in per book; requires src/content/glossary/
     answers: false,
     // v4.21.0 #114: opt-in per book; requires src/content/questions/
+    flashcards: false,
+    // v4.22.0 #116: opt-in per book; requires src/content/glossary/
     landing: true
     // v4.5.0: auto-inject minimal root landing
   },
@@ -735,6 +743,8 @@ var researchPortfolioProfile = defineProfile({
     // v4.19.0 #115: opt-in per book; requires src/content/glossary/
     answers: false,
     // v4.21.0 #114: opt-in per book; requires src/content/questions/
+    flashcards: false,
+    // v4.22.0 #116: opt-in per book; requires src/content/glossary/
     landing: true
     // v4.5.0: auto-inject minimal root landing
   },

package/dist/{types-uerMuJwT.d.ts → types-CGN95mrX.d.ts}

@@ -187,6 +187,14 @@ interface RouteToggles {
      * add a src/content/questions/ directory.
      */
     answers: boolean;
+    /**
+     * v4.22.0 (#116): auto-inject `/flashcards` — a spaced-recall deck generated
+     * from the `glossary` collection (front = term, back = definition), with a
+     * shuffle/flip/known-bucket island persisted to localStorage. Default
+     * `false` per profile — opt in via defineBookConfig({ routes:
+     * { flashcards: true } }) AND add a src/content/glossary/ directory.
+     */
+    flashcards: boolean;
 }
 /** Profile definition — declarative shape for one book profile. */
 interface ProfileDefinition {
@@ -584,6 +592,14 @@ interface BookConfigOptions {
      * default <title> when no per-page title is supplied.
      */
     title?: string;
+    /**
+     * v4.23.0 (#135): Sidebar brand subtitle — the second line under the brand
+     * title in the left chapter-nav. Optional; defaults to the scaffold's
+     * placeholder ('A scaffold-astro book') for backward compatibility. The
+     * brand TITLE is the existing `title` field above (previously the sidebar
+     * hardcoded both strings, so every consumer shipped the placeholder).
+     */
+    subtitle?: string;
     /**
      * v4.5.0: Book description. Read by the auto-injected `/` landing page (lead paragraph + <meta description>).
      * Optional; landing renders no description paragraph if unset.
@@ -700,6 +716,9 @@ interface BookScaffoldIntegrationOptions {
     extraStyles?: readonly string[];
     /** v4.5.0: book title, propagated to `/` landing via vite.define. */
     title?: string;
+    /** v4.23.0 (#135): sidebar brand subtitle, propagated via the book-config
+     *  virtual module to Sidebar.astro. */
+    subtitle?: string;
     /** v4.5.0: book description, propagated to `/` landing via vite.define. */
     description?: string;
     /**

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.21.0",
+  "version": "4.23.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -107,6 +107,10 @@
       "types": "./dist/components/ExamRunner.d.ts",
       "import": "./dist/components/ExamRunner.mjs"
     },
+    "./components/Flashcards": {
+      "types": "./dist/components/Flashcards.d.ts",
+      "import": "./dist/components/Flashcards.mjs"
+    },
     "./components/WarnBox.astro": "./components/WarnBox.astro",
     "./components/WeekRef.astro": "./components/WeekRef.astro",
     "./components/WorkedExample.astro": "./components/WorkedExample.astro",
@@ -122,6 +126,7 @@
     "./styles/poc-layouts.css": "./styles/poc-layouts.css",
     "./styles/tool-filter.css": "./styles/tool-filter.css",
     "./styles/exam-runner.css": "./styles/exam-runner.css",
+    "./styles/flashcards.css": "./styles/flashcards.css",
     "./layouts/Base.astro": "./layouts/Base.astro",
     "./layouts/Chapter.astro": "./layouts/Chapter.astro",
     "./lib": {

package/pages/flashcards.astro

@@ -0,0 +1,109 @@
+---
+/**
+ * Auto-injected /flashcards route — the spaced-recall deck (v4.22.0, #116).
+ *
+ * Sybex-style "electronic flashcards" over the glossary collection: each term
+ * is a card (front = the term, back = the rendered MDX definition). The
+ * Flashcards island (client:idle) shuffles a deck and shows one card at a
+ * time with flip + knew-it/still-learning buckets persisted to localStorage;
+ * "review unknown only" survives reloads. Deliberately an appendix-style
+ * surface, not inline (the Bjork cheat-sheet caution: recall practice, not
+ * re-reading prompts inside prose).
+ *
+ * Card backs are MDX (render() components — not serializable), so all cards
+ * are server-rendered and the island is a controller over them (the
+ * ExamRunner architecture). No JS → the full front+back list reads like a
+ * compact glossary; the deck controls hide via <noscript>.
+ *
+ * Gated on routes.flashcards (default false on every profile). Twin-gate
+ * (mirrors /glossary): presence-probe src/content/glossary/ and render an
+ * honest empty state rather than touching an unregistered collection.
+ * Question/objective-derived cards are a later increment.
+ */
+import Base from '../layouts/Base.astro';
+import { getCollection, render } from 'astro:content';
+import Flashcards from '@brandon_m_behring/book-scaffold-astro/components/Flashcards';
+import { buildFlashcardDeck } from '../src/lib/flashcards';
+import '../styles/flashcards.css';
+
+// Presence-gate: only touch the collection when the directory holds files.
+const glossModules = import.meta.glob('/src/content/glossary/**/*.{md,mdx}', {
+  query: '?raw',
+  import: 'default',
+  eager: true,
+});
+const hasGlossary = Object.keys(glossModules).length > 0;
+
+const entries = hasGlossary ? await getCollection('glossary', (e) => !e.data.draft) : [];
+const deck = buildFlashcardDeck(entries);
+// Render definitions in deck (alphabetical) order so cards and manifest agree.
+const byId = new Map(entries.map((e) => [e.id, e]));
+const rendered = await Promise.all(
+  deck.map(async (card) => {
+    const entry = byId.get(card.id)!;
+    return { ...card, Content: (await render(entry)).Content };
+  }),
+);
+---
+<Base
+  title="Flashcards"
+  description="Glossary flashcards: shuffled recall practice with flip-to-check and known/still-learning buckets."
+>
+  <article class="prose flashcards-page" data-flashcards-root>
+    <h1>Flashcards</h1>
+
+    {!hasGlossary && (
+      <p class="flashcards-empty">
+        No terms found under <code>src/content/glossary/</code> — flashcards are generated
+        from the glossary collection. Add term MDX files (frontmatter <code>term</code> +
+        a definition body) and keep <code>routes: {'{'} flashcards: true {'}'}</code>.
+      </p>
+    )}
+
+    {hasGlossary && (
+      <Fragment>
+        {/* Without JS the island's deck controls would render dead — hide
+            them; the full card list below stays readable. */}
+        <noscript><style is:inline>.flashcards-runner { display: none; }</style></noscript>
+        <Flashcards client:idle deck={deck.map(({ id, front }) => ({ id, front }))} />
+        <section class="flashcards-list">
+          {rendered.map((card) => {
+            const Content = card.Content;
+            return (
+              <div class="flashcard" data-card-id={card.id} id={`card-${card.id}`}>
+                <p class="flashcard-front">{card.front}</p>
+                <div class="flashcard-back"><Content /></div>
+              </div>
+            );
+          })}
+        </section>
+      </Fragment>
+    )}
+  </article>
+
+  <style>
+    .flashcards-page { max-width: 48rem; }
+    .flashcards-empty { color: var(--color-text-muted, #6b7280); }
+    .flashcard {
+      margin-block: 1rem;
+      padding: 1rem 1.1rem;
+      border: 1px solid var(--color-border, #e5e7eb);
+      border-radius: 0.5rem;
+      background: var(--color-surface, transparent);
+    }
+    .flashcard-front {
+      font-weight: 600;
+      font-size: 1.05rem;
+      margin-block: 0 0.5rem;
+    }
+    /* Deck mode (island sets data-flashcards-mode on the wrapper): the back
+       stays hidden until the card is flipped — that's the recall attempt. */
+    [data-flashcards-mode='deck'] .flashcard {
+      min-height: 8rem;
+      border-color: var(--color-accent, #4f46e5);
+    }
+    [data-flashcards-mode='deck'] .flashcard:not(.flashcard-flipped) .flashcard-back {
+      display: none;
+    }
+  </style>
+</Base>

package/recipes/04-component-library.md

@@ -147,7 +147,9 @@ TLS provides confidentiality and integrity via the negotiated cipher suite… <C
 
 - **`<AssessmentTest title? count? passMark?>`** (v4.21.0, #113) — the Sybex-style whole-book front-matter assessment: a cross-domain sampled form (every domain gets a quota, `spreadBlueprint`) scored client-side, with a weak-domain readout routing the reader to the chapters carrying those domains' questions (string chapters link to `/chapters/<slug>/`; numeric chapters render as labels). Drop into a front-matter / intro page like `<ObjectiveMap>`. Presence-gated; only scoreable MCQs render.
 
-The `/practice-exam` route renders the bank grouped by domain with each answer behind a "Show answer" reveal — and (v4.21.0, #112-UI) mounts the **ExamRunner island** (`client:idle`): Start samples a form client-side (pure `sampleExam`), hides the rest of the bank, hides answer reveals while the exam is active, scores checked radio options on submit (`scoreExam`), and renders a per-domain readout with weak-domain anchors. No JS → the static bank with radios + reveals is the fallback. The `/answers` route (v4.21.0, #114; `routes: { answers: true }`) is the back-appendix: every question grouped by chapter with options, the correct answer, and rationales pre-expanded. `cloze` questions are reserved (schema-accepted, render-deferred). Flashcards are the remaining increment — see `docs/plans/active/study-guide-epic_*.md`. (`<Diagnostic>` #110, `<PartReview>` #111, and `/glossary` #115 shipped in v4.19.0; the interactive layer #112-UI/#113/#114 in v4.21.0.)
+- **`/flashcards` route** (v4.22.0, #116; `routes: { flashcards: true }`) — Sybex-style electronic flashcards generated from the glossary collection (front = term, back = the rendered MDX definition). The island shuffles a deck, shows one card at a time (recall first — the back hides until Flip), sorts cards into knew-it/still-learning buckets persisted to localStorage (`book:flashcards:known`), and offers a "review unknown only" pass. Appendix-style surface, deliberately not inline (Bjork: recall practice, not re-reading). No JS → the full front+back list stays readable. Question/objective-derived cards are a later increment.
+
+The `/practice-exam` route renders the bank grouped by domain with each answer behind a "Show answer" reveal — and (v4.21.0, #112-UI) mounts the **ExamRunner island** (`client:idle`): Start samples a form client-side (pure `sampleExam`), hides the rest of the bank, hides answer reveals while the exam is active, scores checked radio options on submit (`scoreExam`), and renders a per-domain readout with weak-domain anchors. No JS → the static bank with radios + reveals is the fallback. The `/answers` route (v4.21.0, #114; `routes: { answers: true }`) is the back-appendix: every question grouped by chapter with options, the correct answer, and rationales pre-expanded. `cloze` questions are reserved (schema-accepted, render-deferred). (`<Diagnostic>` #110, `<PartReview>` #111, and `/glossary` #115 shipped in v4.19.0; the interactive layer #112-UI/#113/#114 in v4.21.0; flashcards #116 in v4.22.0 — completing epic #122. History: `docs/plans/active/study-guide-epic_*.md`.)
 
 ## Mixing families
 

package/src/lib/flashcards.ts

@@ -0,0 +1,40 @@
+/**
+ * flashcards.ts — PURE deck-manifest bridge between the `glossary` collection
+ * and the Flashcards island (#116).
+ *
+ * Same architecture as exam-manifest.ts: card backs are MDX definitions
+ * (server-rendered — not serializable into island props), so the island
+ * receives only this manifest (id + front text) and controls the
+ * server-rendered cards by id. Question/objective-derived cards are a
+ * deliberate later increment; v1 decks are glossary-only.
+ *
+ * No astro:content import — node-tested straight from dist/
+ * (tests/flashcards.test.mjs).
+ */
+import type { GlossaryTerm } from '../schemas.js';
+
+/** One deck entry: the stable card id + the front (the display term). */
+export interface FlashcardRef {
+  id: string;
+  front: string;
+}
+
+/** The entry shape accepted — a CollectionEntry-like wrapper (glossary
+ *  entries carry the file-derived `id` at the top level, not in data). */
+type GlossaryLike = {
+  id: string;
+  data: Pick<GlossaryTerm, 'term' | 'draft'>;
+};
+
+/**
+ * Build the deck manifest: published (non-draft) terms, alphabetical by
+ * display term (locale-aware — same order as /glossary, so the static list
+ * fallback and the deck agree). Draft filtering is defensive; the shipped
+ * caller passes getCollection('glossary', e => !e.data.draft) output.
+ */
+export function buildFlashcardDeck(entries: readonly GlossaryLike[]): FlashcardRef[] {
+  return entries
+    .filter((e) => !e.data.draft)
+    .map((e) => ({ id: e.id, front: e.data.term }))
+    .sort((a, b) => a.front.localeCompare(b.front));
+}

package/src/profile-kit.ts

@@ -102,6 +102,14 @@ export interface RouteToggles {
    * add a src/content/questions/ directory.
    */
   answers: boolean;
+  /**
+   * v4.22.0 (#116): auto-inject `/flashcards` — a spaced-recall deck generated
+   * from the `glossary` collection (front = term, back = definition), with a
+   * shuffle/flip/known-bucket island persisted to localStorage. Default
+   * `false` per profile — opt in via defineBookConfig({ routes:
+   * { flashcards: true } }) AND add a src/content/glossary/ directory.
+   */
+  flashcards: boolean;
 }
 
 /** Profile definition — declarative shape for one book profile. */

package/src/profiles/academic.ts

@@ -28,6 +28,7 @@ export const academicProfile = defineProfile({
     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/
     answers: false, // v4.21.0 #114: opt-in per book; requires src/content/questions/
+    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'],

package/src/profiles/course-notes.ts

@@ -30,6 +30,7 @@ export const courseNotesProfile = defineProfile({
     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/
     answers: false, // v4.21.0 #114: opt-in per book; requires src/content/questions/
+    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'],

package/src/profiles/minimal.ts

@@ -25,6 +25,7 @@ export const minimalProfile = defineProfile({
     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/
     answers: false, // v4.21.0 #114: opt-in per book; requires src/content/questions/
+    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'],

package/src/profiles/research-portfolio.ts

@@ -41,6 +41,7 @@ export const researchPortfolioProfile = defineProfile({
     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/
     answers: false, // v4.21.0 #114: opt-in per book; requires src/content/questions/
+    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'],

package/src/profiles/tools.ts

@@ -25,6 +25,7 @@ export const toolsProfile = defineProfile({
     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/
     answers: false, // v4.21.0 #114: opt-in per book; requires src/content/questions/
+    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: [

package/styles/flashcards.css

@@ -0,0 +1,82 @@
+/* Flashcards island (v4.22.0, #116) — imported by flashcards.astro
+ * (framework-component markup is outside Astro's style scoping, so these ship
+ * as a plain stylesheet like exam-runner.css). Tokens only → dark-mode free. */
+
+.flashcards-runner {
+  margin-block: 1.25rem;
+  padding: 1rem 1.1rem;
+  border: 1px solid var(--color-accent, #4f46e5);
+  border-radius: 0.5rem;
+  background: var(--color-surface, transparent);
+}
+
+.flashcards-empty {
+  color: var(--color-text-muted, #6b7280);
+  font-style: italic;
+}
+
+.flashcards-intro {
+  margin-block: 0 0.5rem;
+  font-size: 0.95rem;
+}
+
+.flashcards-stats,
+.flashcards-progress {
+  margin-block: 0 0.6rem;
+  font-size: 0.9rem;
+  color: var(--color-text-muted, #6b7280);
+}
+
+.flashcards-filter-label {
+  display: block;
+  margin-block-end: 0.75rem;
+  font-size: 0.95rem;
+}
+
+.flashcards-buttons {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+}
+
+.flashcards-button {
+  cursor: pointer;
+  padding: 0.35rem 0.9rem;
+  border: 1px solid var(--color-accent, #4f46e5);
+  border-radius: 0.35rem;
+  background: transparent;
+  color: var(--color-accent, #4f46e5);
+  font: inherit;
+  font-weight: 600;
+}
+
+.flashcards-button:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
+.flashcards-start,
+.flashcards-flip {
+  background: var(--color-accent, #4f46e5);
+  color: var(--color-bg, #fff);
+}
+
+.flashcards-knew {
+  border-color: var(--color-success, #15803d);
+  color: var(--color-success, #15803d);
+}
+
+.flashcards-learning {
+  border-color: var(--color-danger, #b91c1c);
+  color: var(--color-danger, #b91c1c);
+}
+
+.flashcards-link {
+  cursor: pointer;
+  border: none;
+  background: none;
+  padding: 0;
+  font: inherit;
+  color: var(--color-accent, #4f46e5);
+  text-decoration: underline;
+}