@brandon_m_behring/book-scaffold-astro 4.30.0 → 5.0.0

package/components/NavContent.astro

@@ -23,8 +23,12 @@ import bookConfig from 'virtual:book-scaffold/book-config';
 import { academicParts } from '../src/schemas';
 import { academicPartHeading } from '../src/lib/academic-parts';
 import { chapterHref, apparatusHref, bookOf, isCurrentChapter, type ChapterLike, normalizeBase } from '../src/lib/nav-href';
+import { corpusBookIdFromPath, corpusBookIdOf } from '../src/lib/corpus';
 
-const profile = import.meta.env.BOOK_PROFILE ?? 'minimal';
+const profile = import.meta.env.BOOK_PROFILE;
+if (!profile) {
+  throw new Error('book-scaffold runtime is missing the integration-defined BOOK_PROFILE.');
+}
 // #142: normalize the base trailing slash (Astro allows base:'/foo' with none).
 const baseUrl = normalizeBase(import.meta.env.BASE_URL);
 
@@ -45,16 +49,30 @@ const rawChapters = await getCollection('chapters', (entry) => !entry.data.draft
 function entryOf(e: (typeof rawChapters)[number]): ChapterLike {
   return { id: e.id, data: e.data as Record<string, unknown> };
 }
+const entryBook = (entry: (typeof rawChapters)[number]) =>
+  bookConfig.corpus
+    ? corpusBookIdOf(bookConfig.corpus, entry.id)
+    : bookOf(entryOf(entry), bookField);
 const knownBooks = new Set(
-  rawChapters.map((e) => bookOf(entryOf(e), bookField)).filter((b): b is string => b !== null),
+  bookConfig.corpus
+    ? bookConfig.corpus.books.map((book) => book.id)
+    : rawChapters.map(entryBook).filter((book): book is string => book !== null),
 );
-const relPath = currentPath.startsWith(baseUrl) ? currentPath.slice(baseUrl.length) : currentPath.replace(/^\//, '');
-const urlBook = relPath.split('/')[0] ?? '';
-const currentBook = knownBooks.has(urlBook) ? urlBook : null;
+const currentBook = bookConfig.corpus
+  ? corpusBookIdFromPath(bookConfig.corpus, currentPath, baseUrl)
+  : (() => {
+      const relPath = currentPath.startsWith(baseUrl)
+        ? currentPath.slice(baseUrl.length)
+        : currentPath.replace(/^\//, '');
+      const urlBook = relPath.split('/')[0] ?? '';
+      return knownBooks.has(urlBook) ? urlBook : null;
+    })();
 
 const scopedChapters = currentBook
-  ? rawChapters.filter((e) => bookOf(entryOf(e), bookField) === currentBook)
-  : rawChapters;
+  ? rawChapters.filter((entry) => entryBook(entry) === currentBook)
+  : bookConfig.corpus
+    ? []
+    : rawChapters;
 
 // Pre-shape into render-ready rows (all TS casts in frontmatter — Astro's JSX
 // parser mis-tokenizes casts inside expression containers).
@@ -116,8 +134,15 @@ for (const r of rows) {
 }
 
 // Index link: multi-book → the book's TOC at /<book>/; single-book → /chapters/.
-const chaptersIndexHref = currentBook ? `${baseUrl}${currentBook}/` : `${baseUrl}chapters/`;
-const referencesHref = `${baseUrl}references/`;
+const chaptersIndexHref = currentBook
+  ? `${baseUrl}chapters/${currentBook}/`
+  : `${baseUrl}chapters/`;
+const referencesHref = apparatusHref(
+  'references',
+  currentBook,
+  bookConfig.corpus ? '/:book/:route/' : '/:route/',
+  baseUrl,
+);
 
 // Apparatus links (study-guide routes) — surfaced only when the consumer opts in
 // via `apparatusRoutes`. Book-scoped via the same resolver as chapters.
@@ -127,7 +152,11 @@ const APPARATUS_LABELS: Record<string, string> = {
   flashcards: 'Flashcards',
   answers: 'Answers',
 };
-const apparatusLinks = apparatusRoutes.map((route) => {
+const currentBookConfig = currentBook && bookConfig.corpus
+  ? bookConfig.corpus.books.find((book) => book.id === currentBook)
+  : null;
+const visibleApparatusRoutes = currentBookConfig?.apparatus ?? apparatusRoutes;
+const apparatusLinks = visibleApparatusRoutes.map((route) => {
   const href = apparatusHref(route, currentBook, apparatusRoute, baseUrl);
   return {
     href,
@@ -135,6 +164,7 @@ const apparatusLinks = apparatusRoutes.map((route) => {
     isCurrent: currentPath === href || currentPath === href.replace(/\/$/, ''),
   };
 });
+const corpusBooks = bookConfig.corpus?.books ?? [];
 
 function partLabel(key: string): string {
   if (profile === 'academic') return academicPartHeading(key);
@@ -149,7 +179,7 @@ function partLabel(key: string): string {
   >
     All chapters
   </a>
-  {profile === 'academic' && (
+  {profile === 'academic' && !bookConfig.corpus && (
     <a
       href={referencesHref}
       class={`sidebar-link sidebar-link-index ${currentPath === referencesHref ? 'is-current' : ''}`}
@@ -196,6 +226,25 @@ function partLabel(key: string): string {
       </ol>
     </section>
   )}
+
+  {corpusBooks.length > 1 && (
+    <section class="sidebar-part sidebar-corpus-books">
+      <h3 class="sidebar-part-heading">Books</h3>
+      <ol class="sidebar-list">
+        {corpusBooks.map((book) => (
+          <li>
+            <a
+              href={`${baseUrl}${book.id}/`}
+              aria-current={book.id === currentBook ? 'page' : undefined}
+              class={`sidebar-link sidebar-link-book ${book.id === currentBook ? 'is-current' : ''}`}
+            >
+              <span class="sidebar-chapter-title">{book.title}</span>
+            </a>
+          </li>
+        ))}
+      </ol>
+    </section>
+  )}
 </nav>
 
 <style>

package/components/ObjectiveMap.astro

@@ -22,6 +22,7 @@ import bookConfig from 'virtual:book-scaffold/book-config';
 import { getCollection } from 'astro:content';
 import { deriveObjectiveMap, distinctChaptersSorted } from '../src/lib/questions';
 import { assertKnownDomain } from '../src/lib/exam-domains';
+import { corpusBookIdFromPath } from '../src/lib/corpus';
 
 interface Props {
   /** Heading above the table. Defaults to "Exam objective coverage". */
@@ -35,11 +36,22 @@ const questionModules = import.meta.glob('/src/content/questions/**/*.{md,mdx}',
   import: 'default',
   eager: true,
 });
-const hasQuestions = Object.keys(questionModules).length > 0;
+const currentBook = bookConfig.corpus
+  ? corpusBookIdFromPath(bookConfig.corpus, Astro.url.pathname, import.meta.env.BASE_URL)
+  : null;
+if (bookConfig.corpus && !currentBook) {
+  throw new Error('<ObjectiveMap> requires a canonical corpus book route.');
+}
+const hasQuestions = currentBook
+  ? Object.keys(questionModules).some((path) => path.includes(`/questions/${currentBook}/`))
+  : Object.keys(questionModules).length > 0;
 
-const entries = hasQuestions
+const allEntries = hasQuestions
   ? await getCollection('questions', (e) => !e.data.draft)
   : [];
+const entries = currentBook
+  ? allEntries.filter((entry) => entry.id.startsWith(`${currentBook}/`))
+  : allEntries;
 // Fail loud (like /practice-exam): a question with an unregistered / typo'd
 // domain must throw at build, not silently vanish from the coverage matrix.
 for (const e of entries) {

package/components/PartReview.astro

@@ -20,6 +20,12 @@
 import { getCollection } from 'astro:content';
 import { selectPartExercises } from '../src/lib/part-review';
 import { normalizeBase } from '../src/lib/nav-href';
+import bookConfig from 'virtual:book-scaffold/book-config';
+import {
+  corpusBookIdFromPath,
+  localCorpusEntryId,
+  selectBookArtifact,
+} from '../src/lib/corpus';
 
 interface Props {
   /** The part to aggregate. Number (tools/minimal/…) or string (academic enum). */
@@ -32,18 +38,40 @@ const baseUrl = normalizeBase(import.meta.env.BASE_URL);
 
 // 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 }>> }>(
+type ExerciseIndex = Record<string, Array<{ id: string; problem: string }>>;
+const exModules = import.meta.glob<{ default: unknown }>(
   '/src/data/exercises.json',
   { eager: true },
 );
 const exEntry = exModules['/src/data/exercises.json'];
-const byChapter = exEntry?.default ?? {};
+const currentBook = bookConfig.corpus
+  ? corpusBookIdFromPath(bookConfig.corpus, Astro.url.pathname, baseUrl)
+  : null;
+if (bookConfig.corpus && !currentBook) {
+  throw new Error('<PartReview> requires a canonical corpus book route.');
+}
+const byChapter = exEntry
+  ? selectBookArtifact<ExerciseIndex>(
+      exEntry.default,
+      bookConfig.corpus,
+      currentBook,
+      'src/data/exercises.json',
+    )
+  : {};
 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 allChapters = await getCollection('chapters', (e) => !e.data.draft);
+const chapters = currentBook && bookConfig.corpus
+  ? allChapters
+      .filter((entry) => entry.id.startsWith(`${currentBook}/`))
+      .map((entry) => ({
+        ...entry,
+        id: localCorpusEntryId(bookConfig.corpus!, currentBook, entry.id),
+      }))
+  : allChapters;
 const { groups, total } = selectPartExercises(chapters, byChapter, part);
 const heading = title ?? `Part ${part} Review`;
 ---
@@ -67,7 +95,7 @@ const heading = title ?? `Part ${part} Review`;
       </p>
       {groups.map((g) => (
         <section class="part-review-chapter">
-          <h3 class="part-review-chapter-title"><a href={`${baseUrl}chapters/${g.chapter}/`}>{g.chapter}</a></h3>
+          <h3 class="part-review-chapter-title"><a href={`${baseUrl}chapters/${currentBook ? `${currentBook}/` : ''}${g.chapter}/`}>{g.chapter}</a></h3>
           <ol class="part-review-list">
             {g.exercises.map((ex) => (
               <li id={`review-${ex.id}`} class="part-review-item">

package/components/PatternTimeline.astro

@@ -27,11 +27,15 @@ import {
 
 interface Props {
   pattern: PatternEntry;
+  bookId?: string;
+  hasChangelog?: boolean;
 }
-const { pattern } = Astro.props;
+const { pattern, bookId, hasChangelog = true } = Astro.props;
 const data = pattern.data;
 
-const timeline = await getPatternTimeline(pattern.id);
+const timeline = hasChangelog
+  ? await getPatternTimeline(pattern.id, bookId)
+  : [];
 const adopters = toolsInTimeline(timeline);
 
 function formatDate(d: Date): string {

package/components/Rationale.astro

@@ -18,6 +18,7 @@
  */
 import bookConfig from 'virtual:book-scaffold/book-config';
 import { baseNoSlash } from '../src/lib/nav-href';
+import { corpusBookHasApparatusRoute, corpusBookIdFromPath } from '../src/lib/corpus';
 
 interface Props {
   /** Summary label for the reveal. Defaults to "Answer & rationale". */
@@ -37,7 +38,21 @@ if (appendix && !forId) {
       `/answers#answer-<id> anchor target.`,
   );
 }
-if (appendix && !(bookConfig.enabledRoutes ?? []).includes('answers')) {
+const currentBook = bookConfig.corpus
+  ? corpusBookIdFromPath(bookConfig.corpus, Astro.url.pathname, import.meta.env.BASE_URL)
+  : null;
+const answersEnabled = bookConfig.corpus
+  ? Boolean(
+      currentBook &&
+      corpusBookHasApparatusRoute(
+        bookConfig.corpus,
+        currentBook,
+        'answers',
+        bookConfig.apparatusRoutes,
+      ),
+    )
+  : (bookConfig.enabledRoutes ?? []).includes('answers');
+if (appendix && !answersEnabled) {
   throw new Error(
     `<Rationale appendix for="${forId}"> — the answers route is not enabled, so ` +
       `the appendix link would 404. Set routes: { answers: true } in ` +
@@ -50,12 +65,14 @@ if (appendix && !(bookConfig.enabledRoutes ?? []).includes('answers')) {
 // render()). BASE_URL-prefixed + trailing-slash tolerant; an endsWith()
 // heuristic would also fire on e.g. a chapter whose slug is "answers".
 const basePath = baseNoSlash(import.meta.env.BASE_URL);
-const onAnswersRoute = baseNoSlash(Astro.url.pathname) === `${basePath}/answers`;
+const answersBookPrefix = currentBook ? `${currentBook}/` : '';
+const answersPath = `${basePath}/${answersBookPrefix}answers`;
+const onAnswersRoute = baseNoSlash(Astro.url.pathname) === answersPath;
 const asLink = appendix && !onAnswersRoute;
 ---
 {asLink ? (
   <p class="question-rationale-ref">
-    <a href={`${basePath}/answers#answer-${forId}`}>{title} →</a>
+    <a href={`${answersPath}#answer-${forId}`}>{title} →</a>
   </p>
 ) : (
   <details class="question-rationale">

package/components/Sidebar.astro

@@ -18,17 +18,25 @@
 import bookConfig from 'virtual:book-scaffold/book-config';
 import NavContent from './NavContent.astro';
 import { normalizeBase } from '../src/lib/nav-href';
+import { corpusBookIdFromPath, resolveCorpusBook } from '../src/lib/corpus';
 
-const siteTitle = bookConfig.title ?? 'Book';
-const siteSubtitle = bookConfig.subtitle ?? 'A scaffold-astro book';
 // #142: Astro does not guarantee a trailing slash on `base` — normalize so the
 // home link is `${base}/`, not a slash-less `/foo`.
 const baseUrl = normalizeBase(import.meta.env.BASE_URL);
+const currentBookId = bookConfig.corpus
+  ? corpusBookIdFromPath(bookConfig.corpus, Astro.url.pathname, baseUrl)
+  : null;
+const currentBook = currentBookId && bookConfig.corpus
+  ? resolveCorpusBook(bookConfig.corpus, currentBookId)
+  : null;
+const siteTitle = currentBook?.title ?? bookConfig.title ?? 'Book';
+const siteSubtitle = currentBook?.subtitle ?? bookConfig.subtitle ?? 'A scaffold-astro book';
+const homeHref = currentBook ? `${baseUrl}${currentBook.id}/` : baseUrl;
 ---
 
 <aside class="sidebar" aria-label="Chapter navigation">
   <div class="sidebar-inner">
-    <a href={baseUrl} class="sidebar-home">
+    <a href={homeHref} class="sidebar-home">
       <strong>{siteTitle}</strong>
       <span class="sidebar-subtitle">{siteSubtitle}</span>
     </a>

package/components/SourceArchive.astro

@@ -19,14 +19,44 @@ import {
   TIER_DESCRIPTIONS,
 } from '../src/lib/sources';
 
-const grouped = await getSourcesByTier();
+interface SerializedSource {
+  id: string;
+  tier: (typeof sourceTiers)[number];
+  title: string;
+  url: string;
+  author?: string;
+  publish_date?: string | Date;
+  captured_at?: string | Date;
+  tool?: string;
+  perma_cc?: string;
+}
+
+interface Props { sources?: unknown[]; }
+const { sources } = Astro.props;
+const grouped = sources
+  ? Object.fromEntries(
+      sourceTiers.map((tier) => [
+        tier,
+        (sources as SerializedSource[])
+          .filter((source) => source.tier === tier)
+          .map((source) => ({ id: source.id, data: source })),
+      ]),
+    ) as Record<(typeof sourceTiers)[number], Array<{ id: string; data: SerializedSource }>>
+  : await getSourcesByTier();
+
+function asDate(d: string | Date | undefined): Date | undefined {
+  if (!d) return undefined;
+  return d instanceof Date ? d : new Date(d);
+}
 
-function formatDate(d: Date | undefined): string {
+function formatDate(value: string | Date | undefined): string {
+  const d = asDate(value);
   if (!d) return '—';
   return d.toISOString().slice(0, 10);
 }
 
-function year(d: Date | undefined): string | null {
+function year(value: string | Date | undefined): string | null {
+  const d = asDate(value);
   if (!d) return null;
   return String(d.getUTCFullYear());
 }

package/components/Term.astro

@@ -1,5 +1,7 @@
 ---
 import { normalizeBase } from '../src/lib/nav-href';
+import bookConfig from 'virtual:book-scaffold/book-config';
+import { corpusBookHasApparatusRoute, corpusBookIdFromPath } from '../src/lib/corpus';
 /**
  * Term — inline glossary cross-link (v4.19.0, #115).
  *
@@ -19,8 +21,23 @@ interface Props {
 }
 const { id } = Astro.props;
 const baseUrl = normalizeBase(import.meta.env.BASE_URL);
+const currentBook = bookConfig.corpus
+  ? corpusBookIdFromPath(bookConfig.corpus, Astro.url.pathname, baseUrl)
+  : null;
+if (
+  bookConfig.corpus &&
+  (!currentBook ||
+    !corpusBookHasApparatusRoute(
+      bookConfig.corpus,
+      currentBook,
+      'glossary',
+      bookConfig.apparatusRoutes,
+    ))
+) {
+  throw new Error(`<Term id="${id}"> requires the current corpus book's glossary route.`);
+}
 ---
-<a href={`${baseUrl}glossary#term-${id}`} class="term-link"><slot /></a>
+<a href={`${baseUrl}${currentBook ? `${currentBook}/` : ''}glossary#term-${id}`} class="term-link"><slot /></a>
 
 <style>
   .term-link {

package/components/Theorem.astro

@@ -30,6 +30,8 @@
  *   </Theorem>
  */
 import { theoremLabel, resolveTheoremNumber, type TheoremLabelProps } from '../src/lib/theorem-label';
+import bookConfig from 'virtual:book-scaffold/book-config';
+import { corpusBookIdFromPath, selectBookArtifact } from '../src/lib/corpus';
 
 interface Props extends TheoremLabelProps {
   id?: string;
@@ -42,14 +44,22 @@ interface Props extends TheoremLabelProps {
 // 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> }>(
+const labelsModules = import.meta.glob<{ default: unknown }>(
   '/src/data/labels.json',
   { eager: true },
 );
-const labelsMap = (labelsModules['/src/data/labels.json']?.default ?? {}) as Record<
-  string,
-  LabelEntry
->;
+const labelsModule = labelsModules['/src/data/labels.json'];
+const currentBook = bookConfig.corpus
+  ? corpusBookIdFromPath(bookConfig.corpus, Astro.url.pathname, import.meta.env.BASE_URL)
+  : null;
+const labelsMap = labelsModule
+  ? selectBookArtifact<Record<string, LabelEntry>>(
+      labelsModule.default,
+      bookConfig.corpus,
+      currentBook,
+      'src/data/labels.json',
+    )
+  : {};
 
 const { id } = Astro.props;
 // labels.json (by id) is the number source; explicit n= is the fallback when no

package/components/TipsCard.astro

@@ -1,5 +1,11 @@
 ---
 import { normalizeBase } from '../src/lib/nav-href';
+import bookConfig from 'virtual:book-scaffold/book-config';
+import {
+  corpusBookHasApparatusRoute,
+  corpusBookIdFromPath,
+  selectBookArtifact,
+} from '../src/lib/corpus';
 /**
  * TipsCard — print-friendly pull-out card listing all numbered tips
  * (v4.3.0, closes #70).
@@ -16,11 +22,37 @@ import { normalizeBase } from '../src/lib/nav-href';
  */
 // v4.4.0 fix: project-root-relative import via Vite's import.meta.glob
 // (the previous `../../../src/data/tips.json` failed in node_modules contexts).
-const tipsModules = import.meta.glob<{ default: Array<{ n: number; title: string; chapter: string; preview: string }> }>(
+type TipIndexEntry = { n: number; title: string; chapter: string; preview: string };
+const tipsModules = import.meta.glob<{ default: unknown }>(
   '/src/data/tips.json',
   { eager: true },
 );
-const tips = tipsModules['/src/data/tips.json']?.default ?? [];
+const tipsModule = tipsModules['/src/data/tips.json'];
+const tipsPayload = tipsModule?.default ?? [];
+const currentBook = bookConfig.corpus
+  ? corpusBookIdFromPath(bookConfig.corpus, Astro.url.pathname, import.meta.env.BASE_URL)
+  : null;
+const tips = tipsModule
+  ? selectBookArtifact<TipIndexEntry[]>(
+      tipsPayload,
+      bookConfig.corpus,
+      currentBook,
+      'src/data/tips.json',
+    )
+  : [];
+if (
+  tips.length > 0 &&
+  bookConfig.corpus &&
+  (!currentBook ||
+    !corpusBookHasApparatusRoute(
+      bookConfig.corpus,
+      currentBook,
+      'tips',
+      bookConfig.apparatusRoutes,
+    ))
+) {
+  throw new Error(`<TipsCard> requires the current corpus book's tips route.`);
+}
 const baseUrl = normalizeBase(import.meta.env.BASE_URL);
 ---
 <aside class="tips-card" role="contentinfo">
@@ -35,7 +67,12 @@ const baseUrl = normalizeBase(import.meta.env.BASE_URL);
     <ol class="tips-card-list">
       {tips.map((tip) => (
         <li class="tips-card-item">
-          <a href={`${baseUrl}tips#tip-${tip.n}`} class="tips-card-link">
+          <a
+            href={currentBook
+              ? `${baseUrl}${currentBook}/tips#tip-${tip.n}`
+              : `${baseUrl}tips#tip-${tip.n}`}
+            class="tips-card-link"
+          >
             <span class="tips-card-number">{tip.n}.</span>
             <strong class="tips-card-rule">{tip.title}</strong>
           </a>

package/components/XRef.astro

@@ -1,5 +1,7 @@
 ---
 import { normalizeBase } from '../src/lib/nav-href';
+import bookConfig from 'virtual:book-scaffold/book-config';
+import { corpusBookIdFromPath, selectBookArtifact } from '../src/lib/corpus';
 // XRef — resolves a `\cref{label}` LaTeX reference to a hyperlink.
 //
 // Reads src/data/labels.json built by scripts/build-labels.mjs
@@ -32,12 +34,22 @@ type LabelEntry = { href: string; display: string };
 // Resolve labels.json from the consumer's project root (Vite resolves `/`
 // to project root, not the package). Missing file -> empty map -> [?id]
 // placeholders (silent degrade for dev ergonomics; validator catches at CI).
-const labelsModules = import.meta.glob<{ default: Record<string, LabelEntry> }>(
+const labelsModules = import.meta.glob<{ default: unknown }>(
   '/src/data/labels.json',
   { eager: true },
 );
 const labelsModule = labelsModules['/src/data/labels.json'];
-const map = (labelsModule?.default ?? {}) as Record<string, LabelEntry>;
+const currentBook = bookConfig.corpus
+  ? corpusBookIdFromPath(bookConfig.corpus, Astro.url.pathname, import.meta.env.BASE_URL)
+  : null;
+const map = labelsModule
+  ? selectBookArtifact<Record<string, LabelEntry>>(
+      labelsModule.default,
+      bookConfig.corpus,
+      currentBook,
+      'src/data/labels.json',
+    )
+  : {};
 
 interface Props {
   id: string;

package/dist/components/ExamRunner.d.ts

@@ -1,5 +1,5 @@
 import * as preact from 'preact';
-import { a as ExamQuestion, R as RoutingChapter } from '../exam-manifest-X9IrX1G3.js';
+import { a as ExamQuestion, R as RoutingChapter } from '../exam-manifest-DttY7kyZ.js';
 import '../schemas-CKipJ5Ie.js';
 import 'astro/zod';
 

package/dist/components/Flashcards.d.ts

@@ -6,7 +6,12 @@ import 'astro/zod';
 interface Props {
     /** Deck manifest (buildFlashcardDeck output) — card ids + fronts only. */
     deck: FlashcardRef[];
+    /**
+     * Persistence namespace. Corpus routes pass a base- and book-specific key
+     * so repeated local glossary ids never share or erase another book's state.
+     */
+    storageKey?: string;
 }
-declare function Flashcards({ deck }: Props): preact.JSX.Element;
+declare function Flashcards({ deck, storageKey }: Props): preact.JSX.Element;
 
 export { Flashcards as default };

package/dist/components/Flashcards.mjs

@@ -15,10 +15,10 @@ function shuffle(arr, rng = Math.random) {
 
 // components/Flashcards.tsx
 import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
-var STORAGE_KEY = "book:flashcards:known";
-function readKnown() {
+var DEFAULT_STORAGE_KEY = "book:flashcards:known";
+function readKnown(storageKey) {
   try {
-    const raw = localStorage.getItem(STORAGE_KEY);
+    const raw = localStorage.getItem(storageKey);
     if (!raw) return /* @__PURE__ */ new Set();
     const parsed = JSON.parse(raw);
     if (!Array.isArray(parsed)) return /* @__PURE__ */ new Set();
@@ -27,13 +27,16 @@ function readKnown() {
     return /* @__PURE__ */ new Set();
   }
 }
-function writeKnown(known) {
+function writeKnown(storageKey, known) {
   try {
-    localStorage.setItem(STORAGE_KEY, JSON.stringify([...known]));
+    localStorage.setItem(storageKey, JSON.stringify([...known]));
   } catch {
   }
 }
-function Flashcards({ deck }) {
+function Flashcards({ deck, storageKey = DEFAULT_STORAGE_KEY }) {
+  if (typeof storageKey !== "string" || storageKey.trim().length === 0) {
+    throw new Error("Flashcards: storageKey must be a non-empty string.");
+  }
   const [phase, setPhase] = useState("idle");
   const [order, setOrder] = useState([]);
   const [pos, setPos] = useState(0);
@@ -42,12 +45,12 @@ function Flashcards({ deck }) {
   const [unknownOnly, setUnknownOnly] = useState(false);
   const ref = useRef(null);
   useEffect(() => {
-    const stored = readKnown();
+    const stored = readKnown(storageKey);
     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);
+    if (cleaned.size !== stored.size) writeKnown(storageKey, cleaned);
     setKnown(cleaned);
-  }, []);
+  }, [deck, storageKey]);
   function requireRoot() {
     const r = ref.current?.closest("[data-flashcards-root]");
     if (!r) {
@@ -105,7 +108,7 @@ function Flashcards({ deck }) {
     if (knewIt) next.add(id);
     else next.delete(id);
     setKnown(next);
-    writeKnown(next);
+    writeKnown(storageKey, next);
     if (pos < order.length - 1) goTo(pos + 1);
     else end();
   }
@@ -124,7 +127,7 @@ function Flashcards({ deck }) {
   function resetKnown() {
     const next = /* @__PURE__ */ new Set();
     setKnown(next);
-    writeKnown(next);
+    writeKnown(storageKey, next);
   }
   if (deck.length === 0) {
     return /* @__PURE__ */ jsx("p", { class: "flashcards-empty", children: "No glossary terms to study yet." });

package/dist/{exam-manifest-X9IrX1G3.d.ts → exam-manifest-DttY7kyZ.d.ts}

@@ -124,7 +124,7 @@ interface RoutingChapter {
  */
 declare function deriveDomainRouting(entries: readonly (QuestionLike & {
     data: Pick<Question, 'id' | 'chapter' | 'domain'>;
-})[], baseUrl?: string): Record<string, RoutingChapter[]>;
+})[], baseUrl?: string, bookId?: string): Record<string, RoutingChapter[]>;
 /**
  * Build the cross-domain blueprint for assessment mode: spread `count` evenly
  * across the domains present in the pool (floor, minimum 1 per domain), letting