@brandon_m_behring/book-scaffold-astro 4.25.0 → 4.25.2

package/components/AssessmentTest.astro

@@ -80,10 +80,14 @@ for (const e of entries) {
 const scoreable = entries.filter(
   (e) => e.data.type === 'mcq' && (e.data.options?.length ?? 0) > 0,
 );
+// #142: thread the deploy base through the routing map + practice-exam link.
+// deriveDomainRouting takes baseUrl as a param (not import.meta.env) because it
+// ships pre-compiled in dist/ where Vite's env replacement does not reach.
+const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
 const manifest = buildExamManifest(entries);
-const domainRouting = deriveDomainRouting(entries);
+const domainRouting = deriveDomainRouting(entries, baseUrl);
 const practiceExamHref = (bookConfig.enabledRoutes ?? []).includes('practiceExam')
-  ? '/practice-exam'
+  ? `${baseUrl}practice-exam`
   : null;
 
 const rendered = await Promise.all(

package/components/ChapterNav.astro

@@ -10,7 +10,7 @@ interface Props {
 }
 const { currentId } = Astro.props;
 const { prev, next } = await getNeighbors(currentId);
-const baseUrl = import.meta.env.BASE_URL ?? '/';
+const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
 ---
 {(prev || next) && (
   <nav class="chapter-nav" aria-label="Chapter navigation">

package/components/Cite.astro

@@ -45,7 +45,7 @@ interface Props {
 }
 
 const { key, page } = Astro.props;
-const baseUrl = import.meta.env.BASE_URL ?? '/';
+const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
 const entry = map[key];
 if (!entry) {
   throw new Error(

package/components/PartReview.astro

@@ -27,7 +27,7 @@ interface Props {
   title?: string;
 }
 const { part, title } = Astro.props;
-const baseUrl = import.meta.env.BASE_URL ?? '/';
+const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
 
 // Reuse the build-exercises index (keyed by chapter slug). Project-root-relative
 // glob (the tips.astro / exercises.astro lesson) so it resolves across consumers.

package/components/Sidebar.astro

@@ -28,7 +28,7 @@ import { academicPartHeading } from '../src/lib/academic-parts';
 const profile = import.meta.env.BOOK_PROFILE ?? 'minimal';
 const siteTitle = bookConfig.title ?? 'Book';
 const siteSubtitle = bookConfig.subtitle ?? 'A scaffold-astro book';
-const baseUrl = import.meta.env.BASE_URL ?? '/';
+const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
 
 // Academic profile: part is a string enum. `academicParts` (schemas.ts) is
 // the canonical order, shared with the renderer and ChapterHeader (#95); the

package/components/Term.astro

@@ -17,7 +17,7 @@ interface Props {
   id: string;
 }
 const { id } = Astro.props;
-const baseUrl = import.meta.env.BASE_URL ?? '/';
+const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
 ---
 <a href={`${baseUrl}glossary#term-${id}`} class="term-link"><slot /></a>
 

package/components/TipsCard.astro

@@ -20,7 +20,7 @@ const tipsModules = import.meta.glob<{ default: Array<{ n: number; title: string
   { eager: true },
 );
 const tips = tipsModules['/src/data/tips.json']?.default ?? [];
-const baseUrl = import.meta.env.BASE_URL ?? '/';
+const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
 ---
 <aside class="tips-card" role="contentinfo">
   <h2 class="tips-card-title">Tips</h2>

package/components/WeekRef.astro

@@ -20,7 +20,9 @@ interface Props {
 }
 const { week } = Astro.props;
 const slug = `week${String(week).padStart(2, '0')}`;
-const href = `/chapters/${slug}/`;
+// #142: prefix BASE_URL so the chapter link stays inside a non-root deploy base.
+const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
+const href = `${baseUrl}chapters/${slug}/`;
 ---
 <aside class="week-ref">
   <span class="week-ref-arrow" aria-hidden="true">→</span>

package/components/XRef.astro

@@ -44,9 +44,13 @@ interface Props {
 
 const { id } = Astro.props;
 const entry = map[id];
+// #142: labels.json stores a base-less `chapters/<slug>#<id>` ref; prefix
+// BASE_URL at render. The leading-slash strip tolerates a labels.json built
+// by an older (pre-#142) build-labels that still emits a root-absolute href.
+const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
 ---
 {entry ? (
-  <a href={entry.href} class="xref">{entry.display}</a>
+  <a href={`${baseUrl}${entry.href.replace(/^\//, '')}`} class="xref">{entry.display}</a>
 ) : (
   <span class="xref xref-unknown" title={`Unknown label: ${id}`}>[?{id}]</span>
 )}

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-DnqyzZ9I.js';
+import { a as ExamQuestion, R as RoutingChapter } from '../exam-manifest-X9IrX1G3.js';
 import '../schemas-CKipJ5Ie.js';
 import 'astro/zod';
 

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

@@ -115,11 +115,16 @@ interface RoutingChapter {
  * Derive the weak-domain → chapters routing map for `<AssessmentTest>` (#113):
  * for each domain, the distinct chapters (in book order) that carry ≥1 question
  * in it. String chapters are slugs (the schema's kebab-case branch) and link to
- * `/chapters/<slug>/`; numeric chapters render as plain labels.
+ * `${baseUrl}chapters/<slug>/`; numeric chapters render as plain labels.
+ *
+ * `baseUrl` (default '/') is the deploy base, injected by the .astro caller from
+ * import.meta.env.BASE_URL — NOT read here, because this lib ships pre-compiled
+ * in dist/ where Vite's env replacement does not reach, so a self-read would
+ * silently drop the base under a non-root deploy (#142).
  */
 declare function deriveDomainRouting(entries: readonly (QuestionLike & {
     data: Pick<Question, 'id' | 'chapter' | 'domain'>;
-})[]): Record<string, RoutingChapter[]>;
+})[], baseUrl?: 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

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookP
 import { E as volatilityLevels, c as academicParts, Q as Question } from './schemas-CKipJ5Ie.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, l as layoutModes, m as minimalChapterSchema, p as patternCategories, k as patternsSchema, n as provenanceObject, o as provenanceSchema, q as questionDifficulties, r as questionSchema, s as questionTypes, t as refineQuestion, u as refinedQuestionSchema, v as researchPortfolioChapterSchema, w as sourceTiers, x as sourceTiersResearch, y as sourcesSchema, z as toolSlugs, D as toolsChapterSchema } from './schemas-CKipJ5Ie.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-DnqyzZ9I.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-X9IrX1G3.js';
 export { F as FlashcardRef, b as buildFlashcardDeck } from './flashcards-okekZcl8.js';
 import 'astro/zod';
 

package/dist/index.mjs

@@ -1729,7 +1729,8 @@ function buildExamManifest(entries) {
     options: (e.data.options ?? []).map((o) => ({ id: o.id, correct: o.correct === true }))
   }));
 }
-function deriveDomainRouting(entries) {
+function deriveDomainRouting(entries, baseUrl = "/") {
+  const base = baseUrl.replace(/\/?$/, "/");
   const out = {};
   const seen = /* @__PURE__ */ new Set();
   for (const e of sortQuestions(entries)) {
@@ -1739,7 +1740,7 @@ function deriveDomainRouting(entries) {
     seen.add(key);
     (out[e.data.domain] ??= []).push({
       label,
-      href: typeof e.data.chapter === "string" ? `/chapters/${e.data.chapter}/` : null
+      href: typeof e.data.chapter === "string" ? `${base}chapters/${e.data.chapter}/` : null
     });
   }
   return out;

package/layouts/Base.astro

@@ -16,10 +16,14 @@
  *   showSidebar — render the left chapter-navigation sidebar (default: true).
  *                 Set false for the landing page or any full-bleed surface.
  *                 Below 1024px the sidebar is auto-hidden via CSS regardless.
+ *   showChrome  — render the tools chrome (ToolFilter + VersionSelector)
+ *                 (default: true). Set false on a landing/hub page with no
+ *                 chapters/tools/versions; search + theme toggle always render.
  *
  * Tools chrome (ToolFilter, VersionSelector): only mounted when
- * BOOK_PROFILE !== 'academic'. Academic-profile books get no JS islands
- * in the chrome row (search + theme toggle only).
+ * BOOK_PROFILE !== 'academic' AND showChrome !== false. Academic-profile books
+ * (and any page with showChrome={false}) get no JS islands in the chrome row
+ * (search + theme toggle only).
  *
  * Usage:
  *   ---
@@ -61,13 +65,17 @@ import Sidebar from '../components/Sidebar.astro';
 import bookConfig from 'virtual:book-scaffold/book-config';
 
 const profile = import.meta.env.BOOK_PROFILE ?? 'minimal';
-const showToolsChrome = profile !== 'academic';
 
 interface Props {
   title: string;
   description?: string;
   lang?: string;
   showSidebar?: boolean;
+  /** #163: render the optional "tools chrome" — the ToolFilter +
+   *  VersionSelector islands (default true). Set false on landing/hub pages
+   *  with no chapters/tools/versions; the search + theme-toggle cluster always
+   *  renders. (No-op for the academic profile, which never shows them.) */
+  showChrome?: boolean;
   /** v4.6.0: Open Graph image URL (relative to site root, or absolute). */
   ogImage?: string;
   /** v4.6.0: Open Graph type. Defaults to 'website'; Chapter.astro passes 'article'. */
@@ -79,10 +87,18 @@ const {
   description,
   lang = 'en',
   showSidebar = true,
+  showChrome = true,
   ogImage,
   ogType = 'website',
 } = Astro.props;
 
+// Tools chrome (ToolFilter + VersionSelector) renders only for non-academic
+// profiles AND when the page opts in via showChrome (default true). A
+// landing/hub page (no chapters/tools/versions) passes showChrome={false} to
+// get the search + theme-toggle cluster only — the chrome-free path that
+// previously forced borrowing the academic profile (and its katex deps). #163.
+const showToolsChrome = (profile !== 'academic') && showChrome;
+
 // v4.6.0: canonical + og:url need Astro.site. defineBookConfig throws at
 // config-load if `site` is missing, so Astro.site is guaranteed populated
 // here. `new URL` resolves the relative pathname against it.
@@ -99,7 +115,7 @@ const absoluteOgImage = resolvedOgImage
 const twitterHandle = bookConfig.seo?.twitterHandle ?? null;
 const ogSiteName = bookConfig.title ?? title;
 const ogDescription = description ?? bookConfig.description ?? '';
-const baseUrl = import.meta.env.BASE_URL ?? '/';
+const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
 ---
 
 <!doctype html>

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.25.0",
+  "version": "4.25.2",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",

package/pages/answers.astro

@@ -50,13 +50,15 @@ const rendered = await Promise.all(
 
 const byChapter = groupByChapter(rendered);
 const total = rendered.length;
+// #142: practice-exam + chapter links must prefix the deploy base.
+const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
 const practiceHref = (bookConfig.enabledRoutes ?? []).includes('practiceExam')
-  ? '/practice-exam'
+  ? `${baseUrl}practice-exam`
   : null;
 
 /** A string chapter ref is a slug (schema kebab-case branch) → linkable. */
 function chapterHref(chapter: number | string): string | null {
-  return typeof chapter === 'string' ? `/chapters/${chapter}/` : null;
+  return typeof chapter === 'string' ? `${baseUrl}chapters/${chapter}/` : null;
 }
 ---
 <Base

package/pages/chapters.astro

@@ -27,6 +27,9 @@ import { PROFILES } from '../src/profiles/index';
 import { fallbackChaptersRenderer } from '../src/profiles/renderers/fallback-chapters';
 import type { ChaptersRenderer, PartKey } from '../src/lib/chapters-renderer';
 
+// #142: prefix BASE_URL so chapter-card links stay inside a non-root deploy base.
+const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
+
 const profileName = (import.meta.env.BOOK_PROFILE ?? 'minimal') as keyof typeof PROFILES;
 const profileDef = PROFILES[profileName];
 const renderer: ChaptersRenderer =
@@ -112,7 +115,7 @@ for (const c of chapters) {
         <ol class="chapter-list">
           {cards.map((card) => (
             <li class="chapter-card" data-tools={card.toolsAttr}>
-              <a href={`/chapters/${card.c.id}/`} class="chapter-card-link">
+              <a href={`${baseUrl}chapters/${card.c.id}/`} class="chapter-card-link">
                 <div class="chapter-card-meta">
                   <span class="chapter-card-number">{card.number}</span>
                   {card.volatility && (

package/pages/exercises.astro

@@ -26,6 +26,9 @@ const loadError = exEntry
 
 const chapters = Object.keys(byChapter).sort();
 const total = chapters.reduce((sum, c) => sum + byChapter[c].length, 0);
+
+// #142: chapter deep-links must prefix the deploy base.
+const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
 ---
 <Base title="Exercises" description="All exercises in this book, grouped by chapter with deep links.">
   <article class="prose">
@@ -47,12 +50,12 @@ const total = chapters.reduce((sum, c) => sum + byChapter[c].length, 0);
     {chapters.map((chapter) => (
       <section class="exercises-chapter" id={`chapter-${chapter}`}>
         <h2 class="exercises-chapter-title">
-          Chapter: <a href={`/chapters/${chapter}/`}>{chapter}</a>
+          Chapter: <a href={`${baseUrl}chapters/${chapter}/`}>{chapter}</a>
         </h2>
         <ol class="exercises-list">
           {byChapter[chapter].map((ex) => (
             <li class="exercises-item">
-              <a href={`/chapters/${chapter}/#exercise-${ex.id}`} class="exercises-link">
+              <a href={`${baseUrl}chapters/${chapter}/#exercise-${ex.id}`} class="exercises-link">
                 <strong class="exercises-id">Exercise {ex.id}</strong>
                 <span class="exercises-preview">{ex.problem.slice(0, 120)}{ex.problem.length > 120 ? '…' : ''}</span>
               </a>

package/pages/index.astro

@@ -40,17 +40,21 @@ const description = bookConfig.description;
 const portfolio = bookConfig.portfolio;
 const enabledRoutes = bookConfig.enabledRoutes;
 
+// Astro guarantees BASE_URL carries a trailing slash ('/' or '/foo/'), so
+// `${baseUrl}chapters/` resolves correctly under any deploy base (#142).
+const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
+
 // Map from internal route name → display label + URL. Only routes that
 // produce a single landing-list entry are listed here (frontmatter is a
 // slug pattern; chaptersSlug is dynamic; landing IS this page).
 const ROUTE_LABELS: Record<string, { label: string; href: string }> = {
-  chapters:    { label: 'Chapters',     href: '/chapters/' },
-  search:      { label: 'Search',       href: '/search/' },
-  references:  { label: 'References',   href: '/references/' },
-  print:       { label: 'Print view',   href: '/print/' },
-  convergence: { label: 'Convergence',  href: '/convergence/' },
-  tips:        { label: 'Tips',         href: '/tips/' },
-  exercises:   { label: 'Exercises',    href: '/exercises/' },
+  chapters:    { label: 'Chapters',     href: `${baseUrl}chapters/` },
+  search:      { label: 'Search',       href: `${baseUrl}search/` },
+  references:  { label: 'References',   href: `${baseUrl}references/` },
+  print:       { label: 'Print view',   href: `${baseUrl}print/` },
+  convergence: { label: 'Convergence',  href: `${baseUrl}convergence/` },
+  tips:        { label: 'Tips',         href: `${baseUrl}tips/` },
+  exercises:   { label: 'Exercises',    href: `${baseUrl}exercises/` },
 };
 
 const visibleRoutes = enabledRoutes

package/pages/search.astro

@@ -11,13 +11,17 @@
  * `astro dev`. See README for dev-search workflow.
  */
 import Base from '../layouts/Base.astro';
+
+// #142: Pagefind writes its bundle to dist/pagefind/, served under the deploy
+// base — so the asset URLs must prefix BASE_URL or they 404 under a non-root base.
+const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
 ---
 
 <Base
   title="Search · book-template-astro"
   description="Full-text search across the book. Indexed via Pagefind at build time; all queries run in the browser."
 >
-  <link rel="stylesheet" href="/pagefind/pagefind-ui.css" slot="head" />
+  <link rel="stylesheet" href={`${baseUrl}pagefind/pagefind-ui.css`} slot="head" />
 
   <div class="prose search-page">
     <h1>Search</h1>
@@ -29,7 +33,7 @@ import Base from '../layouts/Base.astro';
     <div id="search"></div>
   </div>
 
-  <script src="/pagefind/pagefind-ui.js" is:inline></script>
+  <script src={`${baseUrl}pagefind/pagefind-ui.js`} is:inline></script>
   <script is:inline>
     // Initialize after the Pagefind bundle has loaded.
     window.addEventListener('DOMContentLoaded', () => {

package/pages/tips.astro

@@ -25,6 +25,9 @@ const tips = tipsEntry?.default ?? [];
 const loadError = tipsEntry
   ? null
   : 'src/data/tips.json not found — run `npx book-scaffold build-tips` to generate.';
+
+// #142: chapter back-links must prefix the deploy base.
+const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
 ---
 <Base title="Tips" description="Numbered tips from this book, drawn from <Tip> instances in chapters.">
   <article class="prose">
@@ -47,7 +50,7 @@ const loadError = tipsEntry
               <p class="tips-index-preview">{tip.preview}</p>
             )}
             <p class="tips-index-meta">
-              From <a href={`/chapters/${tip.chapter}/`}>{tip.chapter}</a>
+              From <a href={`${baseUrl}chapters/${tip.chapter}/`}>{tip.chapter}</a>
             </p>
           </li>
         ))}

package/recipes/04-component-library.md

@@ -153,7 +153,7 @@ TLS provides confidentiality and integrity via the negotiated cipher suite… <C
 
 - **`/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`.)
+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/implemented/study-guide-epic_*.md`.)
 
 ## Mixing families
 

package/recipes/20-anki-export.md

@@ -152,7 +152,7 @@ if (!byBook.has(book)) byBook.set(book, []);
 byBook.get(book).push({ ... });
 ```
 
-Then write one file per book key. Multi-book corpus routing is itself out of scope at v4.x ([deferred, see #15](../../PACKAGE_DESIGN.md#15a-deferred-scope-post-v4x)) — if you need it, the same consumer-side pattern applies.
+Then write one file per book key. Multi-book corpus routing is itself out of scope at v4.x ([deferred, see §15a](../../PACKAGE_DESIGN.md#15a-deferred-scope-post-v4x); tracked on #80) — if you need it, the same consumer-side pattern applies.
 
 ## Common gotchas
 

package/recipes/21-multi-guide-single-app.md

@@ -2,7 +2,7 @@
 
 **Profile**: any (proven on research-portfolio).
 
-**TL;DR**: To host more than one guide/book in a single Astro app, keep ONE `chapters` collection rooted at `src/content/` and namespace every entry id by its guide folder via a `generateId` in the glob loader. The scaffold's existing rest-param route (`/chapters/[...slug]/`) then serves `/chapters/<guide>/<slug>/` for every guide with **no scaffold changes**. This is the blessed interim pattern until multibook (#15) ships first-class support.
+**TL;DR**: To host more than one guide/book in a single Astro app, keep ONE `chapters` collection rooted at `src/content/` and namespace every entry id by its guide folder via a `generateId` in the glob loader. The scaffold's existing rest-param route (`/chapters/[...slug]/`) then serves `/chapters/<guide>/<slug>/` for every guide with **no scaffold changes**. This is the blessed interim pattern until multibook (#80) ships first-class support.
 
 ## The pattern
 
@@ -52,15 +52,15 @@ The scaffold's auto-injected `pages/chapters/[...slug].astro` routes on `params:
 
 ## Gotcha 2 — `validate` counts everything under the base
 
-With `base: './src/content'`, `book-scaffold validate` walks the whole base — shared folders like `frontmatter/` are counted as "chapters" (e.g. `16 chapter(s)` for 13 + 2 real chapters + an authors page). The checks still run correctly per file; only the count is inflated. Excluding non-guide folders from the *loader* pattern does not affect the validator's walk. Guide-aware validation is part of the first-class multibook design (#15).
+With `base: './src/content'`, `book-scaffold validate` walks the whole base — shared folders like `frontmatter/` are counted as "chapters" (e.g. `16 chapter(s)` for 13 + 2 real chapters + an authors page). The checks still run correctly per file; only the count is inflated. Excluding non-guide folders from the *loader* pattern does not affect the validator's walk. Guide-aware validation is part of the first-class multibook design (#80).
 
 ## Gotcha 3 — the `/chapters/` index mixes guides
 
-The auto-injected `/chapters/` index lists every entry in the collection — i.e. all guides interleaved. If you want per-guide landing pages, add consumer-owned pages (e.g. `src/pages/evaluation/index.astro`) that `getCollection('chapters', (e) => e.id.startsWith('evaluation/'))`. A grouped-by-guide index is also on the #15 wishlist.
+The auto-injected `/chapters/` index lists every entry in the collection — i.e. all guides interleaved. If you want per-guide landing pages, add consumer-owned pages (e.g. `src/pages/evaluation/index.astro`) that `getCollection('chapters', (e) => e.id.startsWith('evaluation/'))`. A grouped-by-guide index is also on the #80 wishlist.
 
 ## When to expect first-class support
 
-This recipe is the interim, zero-scaffold-change path. Issue [#15 (multibook)](https://github.com/brandon-behring/book-scaffold-astro/issues/15) tracks a `books`/`guides` registry that would emit per-guide indexes, a guides landing, and guide-scoped `validate`. It was deferred pending 2–3 independent consumers; `guides-ai-engineering` (#132) is the second — file your use case on #15 to add weight.
+This recipe is the interim, zero-scaffold-change path. Issue [#80 (multibook)](https://github.com/brandon-behring/book-scaffold-astro/issues/80) tracks a `books`/`guides` registry that would emit per-guide indexes, a guides landing, and guide-scoped `validate` (the original #15 is closed; #80 is the live v5.x tracker). It was deferred pending 2–3 independent consumers; `guides-ai-engineering` (#132) is the second — file your use case on #80 to add weight.
 
 ## Canonical files
 

package/recipes/README.md

@@ -26,7 +26,7 @@ Terse pointers into canonical code for the most common book-authoring workflows.
 | 18 | [Chapter route ownership](18-chapter-route-ownership.md) | any | When to override the auto-injected `/chapters/[...slug]/` route |
 | 19 | [Prevalidate hook](19-prevalidate-hook.md) | any | Wire `prevalidate` to run `build:bib` + `build:labels` before `validate` |
 | 20 | [Anki deck export (consumer-side)](20-anki-export.md) | any (esp. course-notes, research-portfolio) | Roll-your-own `<AnkiCard>` + extractor; scaffold deliberately doesn't ship this |
-| 21 | [Multiple guides in one app](21-multi-guide-single-app.md) | any | `generateId` namespacing over one collection; flat-slug footgun; interim until multibook (#15) |
+| 21 | [Multiple guides in one app](21-multi-guide-single-app.md) | any | `generateId` namespacing over one collection; flat-slug footgun; interim until multibook (#80) |
 
 ## How to read recipes
 

package/scripts/build-labels.mjs

@@ -259,7 +259,9 @@ async function main() {
         );
       }
       labels[id] = {
-        href: `/chapters/${slug}#${id}`,
+        // #142: base-less ref — XRef.astro prefixes BASE_URL at render so one
+        // labels.json serves any deploy base (root or path-proxied series).
+        href: `chapters/${slug}#${id}`,
         display,
         number: labelOverride ? null : number,
       };

package/src/lib/exam-manifest.ts

@@ -49,11 +49,20 @@ export interface RoutingChapter {
  * Derive the weak-domain → chapters routing map for `<AssessmentTest>` (#113):
  * for each domain, the distinct chapters (in book order) that carry ≥1 question
  * in it. String chapters are slugs (the schema's kebab-case branch) and link to
- * `/chapters/<slug>/`; numeric chapters render as plain labels.
+ * `${baseUrl}chapters/<slug>/`; numeric chapters render as plain labels.
+ *
+ * `baseUrl` (default '/') is the deploy base, injected by the .astro caller from
+ * import.meta.env.BASE_URL — NOT read here, because this lib ships pre-compiled
+ * in dist/ where Vite's env replacement does not reach, so a self-read would
+ * silently drop the base under a non-root deploy (#142).
  */
 export function deriveDomainRouting(
   entries: readonly (QuestionLike & { data: Pick<Question, 'id' | 'chapter' | 'domain'> })[],
+  baseUrl = '/',
 ): Record<string, RoutingChapter[]> {
+  // #142: normalize so a no-trailing-slash base ('/foo') still yields '/foo/chapters/'
+  // rather than '/foochapters/' (Astro does NOT guarantee a trailing slash on base).
+  const base = baseUrl.replace(/\/?$/, '/');
   const out: Record<string, RoutingChapter[]> = {};
   const seen = new Set<string>(); // domain\u0000label pairs already routed
   for (const e of sortQuestions(entries)) {
@@ -63,7 +72,7 @@ export function deriveDomainRouting(
     seen.add(key);
     (out[e.data.domain] ??= []).push({
       label,
-      href: typeof e.data.chapter === 'string' ? `/chapters/${e.data.chapter}/` : null,
+      href: typeof e.data.chapter === 'string' ? `${base}chapters/${e.data.chapter}/` : null,
     });
   }
   return out;

package/styles/chapter.css

@@ -230,3 +230,18 @@
   }
   .chapter-nav .next { grid-column: 1; text-align: left; }
 }
+
+/* Display math (KaTeX) — scroll a too-wide equation WITHIN its own block instead
+   of forcing a horizontal scroll on the whole page. KaTeX sets no `overflow` on
+   `.katex-display`, so it defaults to `visible`; a wide equation (long
+   derivations, big matrices) then overflows the viewport and the page scrolls
+   sideways on mobile. WCAG 1.4.10 Reflow. See book-scaffold-astro#162.
+   overflow-y is deliberately NOT set: once overflow-x is non-visible the CSS
+   overflow rule already computes overflow-y to `auto`, so there is no spurious
+   vertical scrollbar — and an explicit `hidden` would silently clip tall
+   equations if a consumer ever constrains .katex-display's height. */
+.katex-display {
+  overflow-x: auto;
+  /* a little room so the horizontal scrollbar doesn't clip the equation's descenders */
+  padding-block-end: 0.25rem;
+}