@brandon_m_behring/book-scaffold-astro 4.26.3 → 4.27.0

package/AGENTS.md

@@ -0,0 +1,6 @@
+# AGENTS.md
+
+The canonical, cross-tool authoring guide is [`CLAUDE.md`](CLAUDE.md) in this
+directory. Read and follow it before changing a book. The guide is
+agent-agnostic despite its filename; this pointer exists so tools that discover
+`AGENTS.md` load the same instructions without maintaining two copies.

package/CLAUDE.md

@@ -14,14 +14,22 @@ If the hub isn't available in your environment (e.g. external contributor), the
 
 ## Profile
 
-Read `BOOK_PROFILE` from the environment or `.env`. It controls:
+Read `BOOK_PRESET` (preferred) or its `BOOK_PROFILE` compatibility alias from
+the environment or `.env`. It controls:
 
-- Which content-collection schema is enforced (`academic` / `tools` / `minimal`)
-- Which markdown integrations run (KaTeX gated on `academic`)
+- Which of the five content-collection schemas is enforced
+- Which markdown integrations run (KaTeX for `academic` and `research-portfolio`)
 - Which callout family is the "default" import in templates
-- Whether ToolFilter / VersionSelector Preact islands mount in the chrome row
+- Whether the ToolFilter Preact island mounts in the automatic chrome row
 
-When in doubt, run `grep BOOK_PROFILE .env astro.config.mjs src/content.config.ts` to see the wiring.
+When in doubt, run `grep -E 'BOOK_(PRESET|PROFILE)' .env astro.config.mjs src/content.config.ts` to see the wiring.
+
+`VersionSelector` is different: it is a manual, prop-driven island because only
+the consuming book knows which versions are actually deployed. Import it from
+`@brandon_m_behring/book-scaffold-astro/components/VersionSelector`, pass
+`versions: [{ href, label, date, current? }]`, and hydrate it where your own
+navigation belongs. It renders nothing for an omitted or empty manifest;
+`Base.astro` never invents or auto-mounts version links.
 
 ## Frontmatter schemas
 
@@ -94,9 +102,9 @@ sources:
 
 Two callout families coexist. Authors import what they need.
 
-**Tools family** (`src/components/callouts/`, 8 components): `SkillBox`, `CaseStudy`, `ConceptBox`, `KeyIdea`, `TryThis`, `Recovery`, `Convergence`, `Divergence`.
+**Tools family** (8 components, imported from the flat `@brandon_m_behring/book-scaffold-astro/components/<Name>.astro` path): `SkillBox`, `CaseStudy`, `ConceptBox`, `KeyIdea`, `TryThis`, `Recovery`, `Convergence`, `Divergence`.
 
-**Academic family** (`src/components/callouts/`, 10 components): `NoteBox`, `ExampleBox`, `DynConnect`, `InsightBox`, `WarnBox`, `CounterBox`, `TipBox`, `OpenQuestion`, `PaperBox`, `ResultBox`. Plus `Theorem` (unified for theorem/proposition/lemma/corollary/definition/example/exercise/remark/proof). **Props (v4.14.3, #121):** `kind=` is canonical; `type=` is accepted as a legacy alias (likewise `title=`/`label=` alias `name=`). An absent or unknown kind **throws at build** (via `src/lib/theorem-label`) rather than rendering an empty label; `book-scaffold validate` flags a `<Theorem>` with neither `kind=` nor `type=` even earlier. **Numbering (v4.18.0, #126):** a theorem with an `id` auto-numbers from `labels.json` — the same index `<XRef>` reads — so the heading number equals every cross-reference to it by construction; explicit `n=` is a fallback for un-id'd theorems. `build-labels` indexes the kind-accurate word (`Proposition 8.1`, not a kind-blind `Theorem 8.1`) and throws on an unknown kind.
+**Academic family** (10 components, using the same flat import path): `NoteBox`, `ExampleBox`, `DynConnect`, `InsightBox`, `WarnBox`, `CounterBox`, `TipBox`, `OpenQuestion`, `PaperBox`, `ResultBox`. Plus `Theorem` (unified for theorem/proposition/lemma/corollary/definition/example/exercise/remark/proof). **Props (v4.14.3, #121):** `kind=` is canonical; `type=` is accepted as a legacy alias (likewise `title=`/`label=` alias `name=`). An absent or unknown kind **throws at build** (via `src/lib/theorem-label`) rather than rendering an empty label; `book-scaffold validate` flags a `<Theorem>` with neither `kind=` nor `type=` even earlier. **Numbering (v4.18.0+, #126/#175):** a theorem with an `id` auto-numbers from `labels.json` — the same index `<XRef>` reads — so the heading number equals every cross-reference to it by construction; explicit `n=` is a fallback for un-id'd theorems. `build-labels` indexes the kind-accurate word (`Proposition 8.1`, not a kind-blind `Theorem 8.1`) and throws on an unknown kind. The theorem family shares one counter by default; set `numberStyle: 'per-kind'` in `defineBookConfig` or a composed `defineStyle` for independent theorem/proposition/lemma/etc. sequences. A `label=` override stays unnumbered and consumes no counter.
 
 **Pedagogy family** (v4.1.0+, any profile, 4 components): `Pitfall` (rose; "common mistake" — distinct from `WarnBox`'s preemptive warning), `WorkedExample` (plum; collapsible `<details>` block with `#worked-example-{id}` anchor for deep links), `YouWillLearn` (gold; chapter-opener with optional `prerequisites` prop), `Diagnostic` (v4.19.0, #110; teal; pre-reading "Do I Know This Already?" DIKTA self-check — a slotted question list + a skip/skim/read routing rubric via `skimTo`, plus an optional collapsible answer key via `slot="answers"`). Slot bullets/code freely; render at any preset.
 
@@ -162,24 +170,41 @@ npm run build:bib            # rebuild references.json after .bib edit
 npm run pdf                  # render dist-pdf/book.pdf via Paged.js
 ```
 
-`prebuild` chains: `build:assets` (bib + figures + notebooks) → `validate` → `astro build`.
+Every generated preset uses the same `prevalidate` hook to rebuild applicable
+bibliography and label indexes, while `prebuild` delegates to validation.
+Figure and notebook conversion remain explicit authoring commands because
+their system tools are optional. `prepdf` always runs the full site build
+before previewing `/print/` and rendering `dist-pdf/book.pdf`.
 
 ## Deploy
 
-Cloudflare Workers + Static Assets via `wrangler.toml`. Recipe 05 has the dashboard flow. URL after first deploy: `https://<book-name>.<account>.workers.dev`.
+The generated `wrangler.toml` uses Cloudflare Workers + Static Assets for
+academic/tools/minimal presets and Cloudflare Pages for course-notes and
+research-portfolio. Recipe 05 documents both flows.
 
 For monorepo Astro projects (Astro project in subdir), prefix build + deploy commands with `cd <subdir> &&`.
 
+Every build emits an audited Cloudflare-format `dist/_headers` by default
+(HSTS, XCTO, Referrer-Policy, Permissions-Policy, and a CSP compatible with
+the shipped inline UI, Pagefind WASM, Cloudflare analytics, and HTTPS images).
+A consumer `public/_headers` wins unchanged. Use
+`securityHeaders: { contentSecurityPolicy: "..." }` to replace only the CSP,
+or `securityHeaders: false` when another layer owns all headers. Recipe 05 has
+the full precedence and customization contract.
+
 ## Validation
 
 `npm run validate` (also runs in prebuild) catches:
 
 - Unknown `<Cite key>` (academic) — bibkey not in `references.json`
 - Unknown `<XRef id>` — id not in `labels.json` (XRef silently renders `[?label]` otherwise)
+- Literal `<Theorem n>` values that disagree with `labels.json` (dynamic expressions and `label=` overrides are skipped)
 - Missing `<Figure src>` files under `public/`
 - Internal markdown links that don't resolve
 - Study-guide questions (v4.17.0, #112) — a question whose frontmatter `domain` isn't in `examDomains`, and duplicate question `id`s
 
+Missing `src/data/labels.json` or `references.json` self-heals before checks by running the corresponding package build script; an existing artifact is never rewritten implicitly.
+
 See `recipes/09-validation.md` to extend.
 
 ## Common authoring tasks
@@ -250,6 +275,6 @@ Types: `feat` / `fix` / `refactor` / `docs` / `test` / `chore` / `release`. One
 
 ## Reading this guide didn't help?
 
-- `recipes/README.md` — index of all 11 recipes
+- `recipes/README.md` — index of all recipes
 - `recipes/08-decisions-ledger.md` — why everything is shaped the way it is
 - `~/.claude/plans/i-want-to-investigate-recursive-yao.md` — full design discussion

package/LATEX_TO_MDX_MAPPING.md

@@ -43,7 +43,7 @@ Component subset table for tools-profile-specific UI (volatility dashboards, con
 | Volatility badge | `Tag` | `volatility` enum chip in chapter meta |
 | Practice tag (`\official{}` / `\practitioner{}` / `\convergence{}`, also `\tagofficial{}` / `\tagpractitioner{}` / `\tagconvergence{}`) | `Tag` | `kind="official" \| "practitioner" \| "convergence"` — inline assertion of source authority. Both the bare and `\tag*` prefixed LaTeX forms map to the same component (see `package/components/Tag.astro`). |
 | Tool comparison | `ToolFilter` (island) | Interactive comparison gate |
-| Version selector | `VersionSelector` (island) | Switch between tool versions |
+| Version selector | `VersionSelector` (island) | Manual opt-in; pass real `{ href, label, date, current? }` deployment entries |
 | Convergence event | `Convergence` | "All tools converged here" timeline marker |
 | Divergence event | `Divergence` | "Tool X went its own way" annotation |
 | Pattern timeline | `PatternTimeline` | Multi-event convergence dashboard |

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 Brandon Behring
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This license covers the toolkit's code, configuration, scripts, and tooling.
+Recipe, pedagogy, example, and substantive guide content is licensed
+separately under CC BY 4.0; see LICENSE-CONTENT.

package/LICENSE-CONTENT

@@ -0,0 +1,19 @@
+Creative Commons Attribution 4.0 International License (CC BY 4.0)
+
+Copyright (c) 2026 Brandon Behring
+
+This license covers prose and authored content shipped in this package,
+including `recipes/`, `pedagogy/`, `examples/`, and substantive prose in
+README.md, CLAUDE.md, and AGENTS.md. Toolkit code and configuration are
+licensed separately under MIT; see LICENSE.
+
+You are free to share and adapt this material for any purpose, including
+commercially, provided that you give appropriate credit, link to the license,
+and indicate whether changes were made. You may not apply additional legal or
+technological restrictions.
+
+Full legal code: https://creativecommons.org/licenses/by/4.0/legalcode
+Human-readable summary: https://creativecommons.org/licenses/by/4.0/
+
+Suggested attribution: "Based on book-scaffold-astro by Brandon Behring,
+licensed under CC BY 4.0."

package/README.md

@@ -0,0 +1,33 @@
+# `@brandon_m_behring/book-scaffold-astro`
+
+Astro 6 + MDX infrastructure for long-form technical books: typed presets,
+Tufte-inspired layouts, citations and cross-references, search, print/PDF
+output, study-guide components, and fail-loud authoring checks.
+
+Start a book with the lock-step CLI:
+
+```bash
+npx @brandon_m_behring/create-book my-book --preset=academic
+cd my-book
+npm install
+npm run dev
+```
+
+Available presets are `academic`, `tools`, `minimal`, `course-notes`, and
+`research-portfolio`. See the
+[repository README](https://github.com/brandon-behring/book-scaffold-astro)
+for the current release overview, and
+[PACKAGE_DESIGN.md](https://github.com/brandon-behring/book-scaffold-astro/blob/main/PACKAGE_DESIGN.md)
+for the complete API contract.
+
+Astro builds emit a Cloudflare-compatible `dist/_headers` with audited
+security defaults. A consumer-owned `public/_headers` wins unchanged;
+`defineBookConfig({ securityHeaders: false })` disables scaffold emission,
+and `securityHeaders.contentSecurityPolicy` replaces only the default CSP.
+See [Recipe 05](./recipes/05-deploy-cloudflare.md#default-security-headers).
+
+## Licensing
+
+Code, configuration, and scripts are MIT-licensed. Recipes, pedagogy, examples,
+and substantive documentation are CC BY 4.0. Both scoped license files ship in
+the package as `LICENSE` and `LICENSE-CONTENT`.

package/components/AssessmentTest.astro

@@ -31,6 +31,7 @@ import { getAllQuestions } from '../src/lib/questions';
 import { assertKnownDomain } from '../src/lib/exam-domains';
 import { buildExamManifest, deriveDomainRouting } from '../src/lib/exam-manifest';
 import '../styles/exam-runner.css';
+import { normalizeBase } from '../src/lib/nav-href';
 
 interface Props {
   /** Heading above the test. Defaults to "Assessment test". */
@@ -83,7 +84,7 @@ const scoreable = entries.filter(
 // #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 baseUrl = normalizeBase(import.meta.env.BASE_URL);
 const manifest = buildExamManifest(entries);
 const domainRouting = deriveDomainRouting(entries, baseUrl);
 const practiceExamHref = (bookConfig.enabledRoutes ?? []).includes('practiceExam')

package/components/ChapterNav.astro

@@ -8,7 +8,7 @@
  * Single-book consumers are byte-identical (defaults → global order + `/chapters/<id>/`).
  */
 import { getNeighbors } from '../src/lib/chapters';
-import { chapterHref } from '../src/lib/nav-href';
+import { chapterHref, normalizeBase } from '../src/lib/nav-href';
 import bookConfig from 'virtual:book-scaffold/book-config';
 
 interface Props {
@@ -18,7 +18,7 @@ const { currentId } = Astro.props;
 
 const chapterRoute = (bookConfig as { chapterRoute?: string }).chapterRoute ?? '/chapters/:id/';
 const bookField = (bookConfig as { bookField?: string }).bookField ?? 'book';
-const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
+const baseUrl = normalizeBase(import.meta.env.BASE_URL);
 
 const { prev, next } = await getNeighbors(currentId, { bookField });
 // Resolve hrefs in frontmatter (casts here, never in the JSX expression container).

package/components/Cite.astro

@@ -1,4 +1,5 @@
 ---
+import { normalizeBase } from '../src/lib/nav-href';
 /**
  * Cite — renders a `\cite{bibkey}` LaTeX citation as a clickable
  * inline reference to the bibliography page.
@@ -45,7 +46,7 @@ interface Props {
 }
 
 const { key, page } = Astro.props;
-const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
+const baseUrl = normalizeBase(import.meta.env.BASE_URL);
 const entry = map[key];
 if (!entry) {
   throw new Error(

package/components/NavContent.astro

@@ -22,11 +22,11 @@ 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';
-import { chapterHref, apparatusHref, bookOf, isCurrentChapter, type ChapterLike } from '../src/lib/nav-href';
+import { chapterHref, apparatusHref, bookOf, isCurrentChapter, type ChapterLike, normalizeBase } from '../src/lib/nav-href';
 
 const profile = import.meta.env.BOOK_PROFILE ?? 'minimal';
 // #142: normalize the base trailing slash (Astro allows base:'/foo' with none).
-const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/*$/, '/');
+const baseUrl = normalizeBase(import.meta.env.BASE_URL);
 
 // v4.26.0 (#80): nav route config (defaults reproduce single-book behavior).
 const chapterRoute = (bookConfig as { chapterRoute?: string }).chapterRoute ?? '/chapters/:id/';

package/components/PartReview.astro

@@ -19,6 +19,7 @@
  */
 import { getCollection } from 'astro:content';
 import { selectPartExercises } from '../src/lib/part-review';
+import { normalizeBase } from '../src/lib/nav-href';
 
 interface Props {
   /** The part to aggregate. Number (tools/minimal/…) or string (academic enum). */
@@ -27,7 +28,7 @@ interface Props {
   title?: string;
 }
 const { part, title } = Astro.props;
-const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
+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.

package/components/Rationale.astro

@@ -17,6 +17,7 @@
  * inside src/content/questions/**.mdx. Slot freely: prose, math, <Cite>, code.
  */
 import bookConfig from 'virtual:book-scaffold/book-config';
+import { baseNoSlash } from '../src/lib/nav-href';
 
 interface Props {
   /** Summary label for the reveal. Defaults to "Answer & rationale". */
@@ -48,8 +49,8 @@ if (appendix && !(bookConfig.enabledRoutes ?? []).includes('answers')) {
 // full rationale must render (the appendix re-renders question bodies via
 // render()). BASE_URL-prefixed + trailing-slash tolerant; an endsWith()
 // heuristic would also fire on e.g. a chapter whose slug is "answers".
-const basePath = (import.meta.env.BASE_URL ?? '/').replace(/\/+$/, '');
-const onAnswersRoute = Astro.url.pathname.replace(/\/+$/, '') === `${basePath}/answers`;
+const basePath = baseNoSlash(import.meta.env.BASE_URL);
+const onAnswersRoute = baseNoSlash(Astro.url.pathname) === `${basePath}/answers`;
 const asLink = appendix && !onAnswersRoute;
 ---
 {asLink ? (

package/components/Sidebar.astro

@@ -17,12 +17,13 @@
  */
 import bookConfig from 'virtual:book-scaffold/book-config';
 import NavContent from './NavContent.astro';
+import { normalizeBase } from '../src/lib/nav-href';
 
 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 = (import.meta.env.BASE_URL ?? '/').replace(/\/*$/, '/');
+const baseUrl = normalizeBase(import.meta.env.BASE_URL);
 ---
 
 <aside class="sidebar" aria-label="Chapter navigation">

package/components/Term.astro

@@ -1,4 +1,5 @@
 ---
+import { normalizeBase } from '../src/lib/nav-href';
 /**
  * Term — inline glossary cross-link (v4.19.0, #115).
  *
@@ -17,7 +18,7 @@ interface Props {
   id: string;
 }
 const { id } = Astro.props;
-const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
+const baseUrl = normalizeBase(import.meta.env.BASE_URL);
 ---
 <a href={`${baseUrl}glossary#term-${id}`} class="term-link"><slot /></a>
 

package/components/TipsCard.astro

@@ -1,4 +1,5 @@
 ---
+import { normalizeBase } from '../src/lib/nav-href';
 /**
  * TipsCard — print-friendly pull-out card listing all numbered tips
  * (v4.3.0, closes #70).
@@ -20,7 +21,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 ?? '/').replace(/\/?$/, '/');
+const baseUrl = normalizeBase(import.meta.env.BASE_URL);
 ---
 <aside class="tips-card" role="contentinfo">
   <h2 class="tips-card-title">Tips</h2>

package/components/VersionSelector.tsx

@@ -1,33 +1,30 @@
 /**
  * VersionSelector — Preact island for the version dropdown.
  *
- * Stage 0: stub data. The real version list arrives in Stage 3 when
- * multi-version CI deploys exist; the component is wired now to prove
- * the islands architecture works with hydration, state, and event
- * handlers.
- *
- * Hydrated with `client:idle` from Base.astro — won't run until the
- * main thread is idle, keeping initial paint fast.
- *
- * Stage 3 will replace the STUB_VERSIONS constant with a runtime fetch
- * or a build-time-injected prop that lists all deployed versions.
+ * Multi-version deployment is owned by the consuming book, so this component
+ * accepts its complete version manifest as a prop. It is a manual opt-in and
+ * is not mounted by Base.astro. With no manifest it renders nothing rather
+ * than presenting package-owned placeholder releases as real navigation.
  */
 import { useState, useRef, useEffect } from 'preact/hooks';
 
-type VersionEntry = {
-  id: string;        // URL subpath segment ('' for latest)
-  label: string;     // display label
-  date: string;      // release date
-  current: boolean;  // mark the version being viewed
-};
+export interface VersionEntry {
+  /** Resolved destination for this deployed version. */
+  href: string;
+  /** Human-readable release label, for example `v4.27`. */
+  label: string;
+  /** Human-readable release date. */
+  date: string;
+  /** Marks the version represented by the current page. */
+  current?: boolean;
+}
 
-// Stub data for Stage 0. Stage 3 will inject the real list.
-const STUB_VERSIONS: VersionEntry[] = [
-  { id: '',     label: 'Latest (main)', date: '2026-04-17', current: true },
-  { id: 'v1.0', label: 'v1.0',          date: '2026-05-01', current: false },
-];
+export interface VersionSelectorProps {
+  /** Consumer-owned deployed-version manifest. Empty/omitted renders nothing. */
+  versions?: readonly VersionEntry[];
+}
 
-export default function VersionSelector() {
+export default function VersionSelector({ versions = [] }: VersionSelectorProps) {
   const [open, setOpen] = useState(false);
   const ref = useRef<HTMLDivElement>(null);
 
@@ -50,9 +47,11 @@ export default function VersionSelector() {
     };
   }, [open]);
 
-  // STUB_VERSIONS is a const literal with >=1 entry so the fallback is
-  // always defined; the bang silences TS's noUncheckedIndexedAccess.
-  const current = STUB_VERSIONS.find((v) => v.current) ?? STUB_VERSIONS[0]!;
+  if (versions.length === 0) return null;
+
+  // If the consumer omits `current`, present the first supplied release as
+  // the current label. The non-empty guard above makes the fallback defined.
+  const current = versions.find((version) => version.current) ?? versions[0]!;
 
   return (
     <div class="version-selector" ref={ref}>
@@ -69,17 +68,21 @@ export default function VersionSelector() {
       </button>
       {open && (
         <ul class="version-selector-menu" role="listbox">
-          {STUB_VERSIONS.map((v) => (
-            <li role="option" aria-selected={v.current}>
-              <a
-                href={v.id ? `/${v.id}/` : '/'}
-                class={v.current ? 'version-current' : ''}
-              >
-                <span class="version-label">{v.label}</span>
-                <span class="version-date">{v.date}</span>
-              </a>
-            </li>
-          ))}
+          {versions.map((version) => {
+            const isCurrent = version === current;
+            return (
+              <li key={version.href} role="option" aria-selected={isCurrent}>
+                <a
+                  href={version.href}
+                  class={isCurrent ? 'version-current' : ''}
+                  aria-current={isCurrent ? 'page' : undefined}
+                >
+                  <span class="version-label">{version.label}</span>
+                  <span class="version-date">{version.date}</span>
+                </a>
+              </li>
+            );
+          })}
         </ul>
       )}
     </div>

package/components/WeekRef.astro

@@ -1,4 +1,5 @@
 ---
+import { normalizeBase } from '../src/lib/nav-href';
 /**
  * WeekRef — inline pointer to another chapter, mapping LaTeX `\weekref{N}{body}`.
  *
@@ -21,7 +22,7 @@ interface Props {
 const { week } = Astro.props;
 const slug = `week${String(week).padStart(2, '0')}`;
 // #142: prefix BASE_URL so the chapter link stays inside a non-root deploy base.
-const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
+const baseUrl = normalizeBase(import.meta.env.BASE_URL);
 const href = `${baseUrl}chapters/${slug}/`;
 ---
 <aside class="week-ref">

package/components/XRef.astro

@@ -1,4 +1,5 @@
 ---
+import { normalizeBase } from '../src/lib/nav-href';
 // XRef — resolves a `\cref{label}` LaTeX reference to a hyperlink.
 //
 // Reads src/data/labels.json built by scripts/build-labels.mjs
@@ -47,7 +48,7 @@ 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(/\/?$/, '/');
+const baseUrl = normalizeBase(import.meta.env.BASE_URL);
 ---
 {entry ? (
   <a href={`${baseUrl}${entry.href.replace(/^\//, '')}`} class="xref">{entry.display}</a>

package/dist/components/VersionSelector.d.ts

@@ -1,5 +1,19 @@
 import * as preact from 'preact';
 
-declare function VersionSelector(): preact.JSX.Element;
+interface VersionEntry {
+    /** Resolved destination for this deployed version. */
+    href: string;
+    /** Human-readable release label, for example `v4.27`. */
+    label: string;
+    /** Human-readable release date. */
+    date: string;
+    /** Marks the version represented by the current page. */
+    current?: boolean;
+}
+interface VersionSelectorProps {
+    /** Consumer-owned deployed-version manifest. Empty/omitted renders nothing. */
+    versions?: readonly VersionEntry[];
+}
+declare function VersionSelector({ versions }: VersionSelectorProps): preact.JSX.Element | null;
 
-export { VersionSelector as default };
+export { type VersionEntry, type VersionSelectorProps, VersionSelector as default };

package/dist/components/VersionSelector.mjs

@@ -1,11 +1,7 @@
 // components/VersionSelector.tsx
 import { useState, useRef, useEffect } from "preact/hooks";
 import { jsx, jsxs } from "preact/jsx-runtime";
-var STUB_VERSIONS = [
-  { id: "", label: "Latest (main)", date: "2026-04-17", current: true },
-  { id: "v1.0", label: "v1.0", date: "2026-05-01", current: false }
-];
-function VersionSelector() {
+function VersionSelector({ versions = [] }) {
   const [open, setOpen] = useState(false);
   const ref = useRef(null);
   useEffect(() => {
@@ -25,7 +21,8 @@ function VersionSelector() {
       window.removeEventListener("keydown", onKey);
     };
   }, [open]);
-  const current = STUB_VERSIONS.find((v) => v.current) ?? STUB_VERSIONS[0];
+  if (versions.length === 0) return null;
+  const current = versions.find((version) => version.current) ?? versions[0];
   return /* @__PURE__ */ jsxs("div", { class: "version-selector", ref, children: [
     /* @__PURE__ */ jsx(
       "button",
@@ -40,17 +37,21 @@ function VersionSelector() {
         children: /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: "v" })
       }
     ),
-    open && /* @__PURE__ */ jsx("ul", { class: "version-selector-menu", role: "listbox", children: STUB_VERSIONS.map((v) => /* @__PURE__ */ jsx("li", { role: "option", "aria-selected": v.current, children: /* @__PURE__ */ jsxs(
-      "a",
-      {
-        href: v.id ? `/${v.id}/` : "/",
-        class: v.current ? "version-current" : "",
-        children: [
-          /* @__PURE__ */ jsx("span", { class: "version-label", children: v.label }),
-          /* @__PURE__ */ jsx("span", { class: "version-date", children: v.date })
-        ]
-      }
-    ) })) })
+    open && /* @__PURE__ */ jsx("ul", { class: "version-selector-menu", role: "listbox", children: versions.map((version) => {
+      const isCurrent = version === current;
+      return /* @__PURE__ */ jsx("li", { role: "option", "aria-selected": isCurrent, children: /* @__PURE__ */ jsxs(
+        "a",
+        {
+          href: version.href,
+          class: isCurrent ? "version-current" : "",
+          "aria-current": isCurrent ? "page" : void 0,
+          children: [
+            /* @__PURE__ */ jsx("span", { class: "version-label", children: version.label }),
+            /* @__PURE__ */ jsx("span", { class: "version-date", children: version.date })
+          ]
+        }
+      ) }, version.href);
+    }) })
   ] });
 }
 export {

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 import { AstroUserConfig, AstroIntegration, MarkdownHeading } from 'astro';
-import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, h as ChaptersRenderer, m as Style } from './types-CWXP1S4b.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 ReleaseStatusConfig, l as RouteToggles, S as StatusBadge, n as StyleInput, V as VolatilityBadge, o as composeStyles, p as defineProfile, q as defineStyle, r as normalizeFrontmatterConfig, s as resolvePreset, t as resolveProfile } from './types-CWXP1S4b.js';
+import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, h as ChaptersRenderer, o as Style } from './types-CZrkqzpC.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, N as NUMBER_STYLES, j as NumberStyle, P as PartKey, k as PartialRouteToggles, l as ProfileDefinition, R as ReleaseStatusConfig, m as RouteToggles, S as SecurityHeadersConfig, n as StatusBadge, p as StyleInput, V as VolatilityBadge, q as composeStyles, r as defineProfile, s as defineStyle, t as normalizeFrontmatterConfig, u as resolvePreset, v as resolveProfile } from './types-CZrkqzpC.js';
 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 { ssmMacros } from './lib/katex-macros.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';
@@ -336,6 +337,24 @@ interface ChapterLike {
     id: string;
     data: Record<string, unknown>;
 }
+/**
+ * Normalize a base URL to exactly one trailing slash (`''`/`undefined` → `'/'`).
+ *
+ * v4.27.0 (#182): promoted from this module's private helper to THE shared
+ * normalizer — 18 `.astro` files previously inlined the same normalization in
+ * three regex idioms. Astro does not guarantee a trailing slash on `base`
+ * (`'/foo'` is a documented form), so every `import.meta.env.BASE_URL` read
+ * must pass through here before href composition: `${normalizeBase(...)}chapters/`.
+ * Takes the base as a PARAMETER because src/lib ships pre-compiled in dist/,
+ * where Vite's import.meta.env replacement cannot reach (see exam-manifest.ts).
+ */
+declare function normalizeBase(baseUrl: string | undefined): string;
+/**
+ * The composing variant (#182): strip ALL trailing slashes (`'/'` → `''`,
+ * `'/foo/'` → `'/foo'`) for `${baseNoSlash(...)}/answers`-style templates
+ * where the literal supplies the slash (Rationale.astro's route detection).
+ */
+declare function baseNoSlash(baseUrl: string | undefined): string;
 /**
  * The entry's book name from `data[bookField]`, or `null` when absent/blank.
  * Single-book schemas (academic/tools/minimal) have no such field → `null`,
@@ -540,11 +559,10 @@ declare const toolsStyle: Style;
 /** Minimal preset — single-author essays / manifestos. */
 declare const minimalStyle: Style;
 /** Course-notes preset — chapters derived from a video course / MOOC / book.
- *  Content-heavy static sites → defaults to Cloudflare Pages deploy. */
+ *  `deploy` is retained as deprecated metadata only (#180). */
 declare const courseNotesStyle: Style;
 /** Research-portfolio preset — academic structure + tools-style provenance + portfolio components.
- *  Defaults to Pages deploy + frontmatter route enabled (portfolios universally need
- *  title-page / disclosure / banner pages). */
+ *  `deploy` is retained as deprecated metadata only (#180); frontmatter routes remain enabled. */
 declare const researchPortfolioStyle: Style;
 /**
  * Registry of all toolkit-shipped styles, keyed by their preset name.
@@ -611,4 +629,4 @@ type TipsConfigInput = Omit<TipsConfig, typeof TipsConfigBrand | '__tipsConfigVe
  */
 declare function defineTips(opts: TipsConfigInput): TipsConfig;
 
-export { ACADEMIC_PART_NAMES, BRANDON_PORTFOLIO_DEFAULT, BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, type ChapterLike, ChaptersRenderer, DEFAULT_GITHUB_BRANCH, type Freshness, type FreshnessStatus, type PartReviewGroup, type PartReviewSelection, Question, type ReviewChapter, type ReviewExercise, Style, type TipsConfig, type TipsConfigInput, UNKNOWN_PART_ORDINAL, type VisibleHeading, type VolatilityLevel, academicChaptersRenderer, academicPartHeading, academicPartName, academicPartOrdinal, academicParts, academicStyle, apparatusHref, assertEnumProp, assertKnownDomain, bookOf, bookScaffoldIntegration, buildGithubUrl, chapterHref, chapterLabel, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, deriveObjectiveMap, distinctChaptersSorted, fallbackChaptersRenderer, freshnessLabel, getFreshness, groupByChapter, groupByDomain, isCurrentChapter, minimalStyle, originUrlFromGitConfig, parseRepoSlug, pickActive, researchPortfolioChaptersRenderer, researchPortfolioStyle, resolveBookHref, resolveGithubRepo, selectPartExercises, slugOf, sortQuestions, tocHeadings, toolsChaptersRenderer, toolsStyle, volatilityLevels };
+export { ACADEMIC_PART_NAMES, BRANDON_PORTFOLIO_DEFAULT, BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, type ChapterLike, ChaptersRenderer, DEFAULT_GITHUB_BRANCH, type Freshness, type FreshnessStatus, type PartReviewGroup, type PartReviewSelection, Question, type ReviewChapter, type ReviewExercise, Style, type TipsConfig, type TipsConfigInput, UNKNOWN_PART_ORDINAL, type VisibleHeading, type VolatilityLevel, academicChaptersRenderer, academicPartHeading, academicPartName, academicPartOrdinal, academicParts, academicStyle, apparatusHref, assertEnumProp, assertKnownDomain, baseNoSlash, bookOf, bookScaffoldIntegration, buildGithubUrl, chapterHref, chapterLabel, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, deriveObjectiveMap, distinctChaptersSorted, fallbackChaptersRenderer, freshnessLabel, getFreshness, groupByChapter, groupByDomain, isCurrentChapter, minimalStyle, normalizeBase, originUrlFromGitConfig, parseRepoSlug, pickActive, researchPortfolioChaptersRenderer, researchPortfolioStyle, resolveBookHref, resolveGithubRepo, selectPartExercises, slugOf, sortQuestions, tocHeadings, toolsChaptersRenderer, toolsStyle, volatilityLevels };