@brandon_m_behring/book-scaffold-astro 4.25.3 → 4.26.2

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { AstroUserConfig, AstroIntegration, MarkdownHeading } from 'astro';
-import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, h as ChaptersRenderer, l as Style } from './types-Bn7rKhgP.js';
-export { B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookPreset, e as BookProfile, g as BookSchemasOptions, C as ChapterFor, F as FreshnessAffordance, i as FrontmatterRouteConfig, P as PartKey, j as PartialRouteToggles, k as ProfileDefinition, R as RouteToggles, S as StatusBadge, m as StyleInput, V as VolatilityBadge, n as composeStyles, o as defineProfile, p as defineStyle, q as normalizeFrontmatterConfig, r as resolvePreset, s as resolveProfile } from './types-Bn7rKhgP.js';
+import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, h as ChaptersRenderer, l as Style } from './types-Hue-uSeQ.js';
+export { B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookPreset, e as BookProfile, g as BookSchemasOptions, C as ChapterFor, F as FreshnessAffordance, i as FrontmatterRouteConfig, P as PartKey, j as PartialRouteToggles, k as ProfileDefinition, R as RouteToggles, S as StatusBadge, m as StyleInput, V as VolatilityBadge, n as composeStyles, o as defineProfile, p as defineStyle, q as normalizeFrontmatterConfig, r as resolvePreset, s as resolveProfile } from './types-Hue-uSeQ.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';
@@ -144,18 +144,31 @@ declare const academicChaptersRenderer: ChaptersRenderer;
 
 /**
  * src/profiles/renderers/fallback-chapters.ts — ChaptersRenderer used by
- * profiles that don't ship a dedicated renderer (minimal, course-notes,
- * research-portfolio). Dispatches by field presence — exactly the v3.5.2
+ * profiles that don't ship a dedicated renderer (minimal, course-notes).
+ * Dispatches by field presence — exactly the v3.5.2
  * logic that lived inline in pages/chapters.astro before #35.
  *
  * Safety net for shapes we haven't designed for explicitly. If a consumer
- * opts a course-notes or research-portfolio book into `routes.chapters: true`,
+ * opts a course-notes book into `routes.chapters: true`,
  * the fallback renders reasonably without crashing. Custom output for those
  * profiles is a v4+ extension point (consumer-overridable renderer).
  */
 
 declare const fallbackChaptersRenderer: ChaptersRenderer;
 
+/**
+ * Research-portfolio /chapters renderer.
+ *
+ * The portfolio schema intentionally permits numeric Parts through 20. The
+ * generic fallback renderer inherits the tools profile's historical
+ * `part >= 6` appendix convention, which mislabels a portfolio's sixth Part
+ * as "Appendices" and its chapters as Appendix a/b/.... Keep the fallback's
+ * field-shape dispatch for every other affordance, but make numeric Parts
+ * ordinary numbered Parts throughout the portfolio schema's full range.
+ */
+
+declare const researchPortfolioChaptersRenderer: ChaptersRenderer;
+
 /**
  * src/lib/academic-parts.ts — single source of truth for academic-profile
  * part labels (#95).
@@ -294,6 +307,53 @@ declare function assertEnumProp<T extends string>(value: unknown, allowed: reado
  */
 declare function resolveBookHref(siblingBooks: Record<string, string> | null | undefined, book: string, to: string): string;
 
+/**
+ * src/lib/nav-href.ts — pure route-href resolver (#80 multi-book navigation).
+ *
+ * No `astro:content` import (mirrors chapter-sort.ts) so tsup can include it in
+ * the DTS bundle without dragging Astro virtual modules into the build graph.
+ * The nav components (Sidebar, ChapterNav, NavContent, …) call these helpers
+ * instead of hardcoding the single-book `/chapters/<id>/` URL shape — so ONE set
+ * of components serves both a single-book site (the default pattern) and a
+ * multi-book consumer whose chapters render at `/<book>/<slug>/`.
+ *
+ * Patterns are base-relative TOKEN STRINGS (a resolver *function* could not
+ * survive the book-config virtual module's `JSON.stringify`, so the config
+ * surface is a declarative string resolved here):
+ *   :id   → entry.id verbatim, slashes preserved          e.g. 'kg/01-intro'
+ *   :book → the entry's book name (see `bookField`), or '' e.g. 'kg'
+ *   :slug → entry.id with a leading '<book>/' stripped     e.g. '01-intro'
+ * BASE_URL is applied here, so patterns are written base-relative (lead '/').
+ *
+ * Defaults reproduce the single-book behavior BYTE-FOR-BYTE:
+ *   chapterRoute   = '/chapters/:id/'  → `${base}chapters/${id}/`
+ *   bookField      = 'book'   (academic/tools schemas have no `book` → bookOf
+ *                              returns null → "show all chapters", today's nav)
+ *   apparatusRoute = '/:route/'        → `${base}<route>/`
+ */
+/** Minimal shape the resolver needs from a chapter collection entry. */
+interface ChapterLike {
+    id: string;
+    data: Record<string, unknown>;
+}
+/**
+ * The entry's book name from `data[bookField]`, or `null` when absent/blank.
+ * Single-book schemas (academic/tools/minimal) have no such field → `null`,
+ * which callers read as "this is the only book — show every chapter".
+ */
+declare function bookOf(entry: ChapterLike, bookField?: string): string | null;
+/** `entry.id` with a leading `'<book>/'` stripped (multi-book) or unchanged. */
+declare function slugOf(entry: ChapterLike, bookField?: string): string;
+/** Resolve a chapter entry to a base-prefixed href via the `chapterRoute` pattern. */
+declare function chapterHref(entry: ChapterLike, pattern?: string, baseUrl?: string, bookField?: string): string;
+/**
+ * Resolve a per-book apparatus route (glossary / practice-exam / flashcards /
+ * answers) to a base-prefixed href via the `apparatusRoute` pattern.
+ */
+declare function apparatusHref(route: string, book: string | null, pattern?: string, baseUrl?: string): string;
+/** Whether `entry` is the page at `currentPath` (trailing-slash tolerant). */
+declare function isCurrentChapter(entry: ChapterLike, currentPath: string, pattern?: string, baseUrl?: string, bookField?: string): boolean;
+
 /**
  * exam-domains — validate a question's `domain` against the consumer's closed
  * `examDomains` taxonomy (Tier 3, #112).
@@ -551,4 +611,4 @@ type TipsConfigInput = Omit<TipsConfig, typeof TipsConfigBrand | '__tipsConfigVe
  */
 declare function defineTips(opts: TipsConfigInput): TipsConfig;
 
-export { ACADEMIC_PART_NAMES, BRANDON_PORTFOLIO_DEFAULT, BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, ChaptersRenderer, DEFAULT_GITHUB_BRANCH, type Freshness, type FreshnessStatus, 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, assertEnumProp, assertKnownDomain, bookScaffoldIntegration, buildGithubUrl, chapterLabel, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, deriveObjectiveMap, distinctChaptersSorted, fallbackChaptersRenderer, freshnessLabel, getFreshness, groupByChapter, groupByDomain, minimalStyle, originUrlFromGitConfig, parseRepoSlug, pickActive, researchPortfolioStyle, resolveBookHref, resolveGithubRepo, selectPartExercises, 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, 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 };

package/dist/index.mjs

@@ -851,6 +851,17 @@ var courseNotesProfile = defineProfile({
   sitemapFilter: (page) => !page.includes("/print/")
 });
 
+// src/profiles/renderers/research-portfolio-chapters.ts
+var researchPortfolioChaptersRenderer = {
+  ...fallbackChaptersRenderer,
+  formatPartLabel(part) {
+    return typeof part === "number" ? `Part ${part}` : fallbackChaptersRenderer.formatPartLabel(part);
+  },
+  isAppendix(_part) {
+    return false;
+  }
+};
+
 // src/profiles/research-portfolio.ts
 var researchPortfolioProfile = defineProfile({
   name: "research-portfolio",
@@ -883,8 +894,9 @@ var researchPortfolioProfile = defineProfile({
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css", "section-map.css"],
   katex: true,
   // math is common in research content
-  // v3.7.0 (#35): portfolio schema is a union of academic + tools shapes — fallback renderer dispatches per chapter via field presence
-  chaptersRenderer: fallbackChaptersRenderer
+  // Portfolio schema is a union of academic + tools shapes, but unlike the
+  // tools profile its numeric Parts remain numbered through the schema max 20.
+  chaptersRenderer: researchPortfolioChaptersRenderer
 });
 
 // src/profiles/index.ts
@@ -1199,6 +1211,7 @@ function bookScaffoldIntegration(opts) {
     // v4.5.0: landing-page data, propagated via virtual module to /index.astro.
     title,
     subtitle,
+    releaseStatus,
     description,
     portfolio,
     // v4.6.0: book-level author + SEO config, propagated through the
@@ -1211,7 +1224,12 @@ function bookScaffoldIntegration(opts) {
     // v4.16.0 (#96): sibling-book registry for cross-book <BookLink>.
     siblingBooks,
     // v4.17.0 (#112): exam-domain taxonomy for the questions collection.
-    examDomains
+    examDomains,
+    // v4.26.0 (#80): book-aware nav route patterns.
+    chapterRoute,
+    bookField,
+    apparatusRoute,
+    apparatusRoutes
   } = opts;
   const def = PROFILES[profile];
   const fmNormalized = normalizeFrontmatterConfig(userOverrides.frontmatter);
@@ -1263,6 +1281,7 @@ function bookScaffoldIntegration(opts) {
               makeBookConfigVitePlugin({
                 title: title ?? null,
                 subtitle: subtitle ?? null,
+                releaseStatus: releaseStatus ?? null,
                 description: description ?? null,
                 portfolio: portfolio ?? false,
                 enabledRoutes: enabledRouteNames,
@@ -1274,7 +1293,13 @@ function bookScaffoldIntegration(opts) {
                 githubRepo: resolvedGithubRepo,
                 githubBranch: resolvedGithubBranch,
                 siblingBooks: siblingBooks ?? {},
-                examDomains: examDomains ?? []
+                examDomains: examDomains ?? [],
+                // v4.26.0 (#80): book-aware nav route patterns; defaults
+                // reproduce the single-book `/chapters/<id>/` behavior exactly.
+                chapterRoute: chapterRoute ?? "/chapters/:id/",
+                bookField: bookField ?? "book",
+                apparatusRoute: apparatusRoute ?? "/:route/",
+                apparatusRoutes: apparatusRoutes ?? []
               })
             ],
             define: {
@@ -1402,6 +1427,8 @@ async function defineBookConfig(opts) {
       title: opts.title,
       // v4.23.0 (#135): sidebar brand subtitle.
       subtitle: opts.subtitle,
+      // v4.27.0 (#149): release-state banner (top-level beats the style chain).
+      releaseStatus: opts.releaseStatus ?? composed.releaseStatus,
       description: opts.description,
       portfolio: resolvedPortfolio,
       // v4.6.0: book-level author + SEO config (ogImage, twitterHandle),
@@ -1416,7 +1443,12 @@ async function defineBookConfig(opts) {
       // v4.16.0 (#96): cross-book link registry.
       siblingBooks: opts.siblingBooks,
       // v4.17.0 (#112): per-book exam-domain taxonomy for the questions collection.
-      examDomains: opts.examDomains
+      examDomains: opts.examDomains,
+      // v4.26.0 (#80): book-aware nav route patterns (undefined → single-book defaults).
+      chapterRoute: opts.chapterRoute,
+      bookField: opts.bookField,
+      apparatusRoute: opts.apparatusRoute,
+      apparatusRoutes: opts.apparatusRoutes
     }),
     ...mergedExtraIntegrations
   ];
@@ -1454,6 +1486,8 @@ async function defineBookConfig(opts) {
     // v4.5.0: strip new landing-related opts so they don't leak into AstroUserConfig.
     title: _title,
     subtitle: _subtitle,
+    // v4.27.0 (#149): strip the release-state banner config.
+    releaseStatus: _releaseStatus,
     description: _description,
     portfolio: _portfolio,
     // v4.6.0: strip new book-level SEO opts (author + seo block).
@@ -1466,6 +1500,11 @@ async function defineBookConfig(opts) {
     siblingBooks: _siblingBooks,
     // v4.17.0: strip exam-domain taxonomy.
     examDomains: _examDomains,
+    // v4.26.0 (#80): strip book-aware nav route patterns.
+    chapterRoute: _chapterRoute,
+    bookField: _bookField,
+    apparatusRoute: _apparatusRoute,
+    apparatusRoutes: _apparatusRoutes,
     ...rest
   } = opts;
   void _styles;
@@ -1479,6 +1518,7 @@ async function defineBookConfig(opts) {
   void _katexMacros;
   void _title;
   void _subtitle;
+  void _releaseStatus;
   void _description;
   void _portfolio;
   void _author;
@@ -1487,6 +1527,10 @@ async function defineBookConfig(opts) {
   void _githubBranch;
   void _siblingBooks;
   void _examDomains;
+  void _chapterRoute;
+  void _bookField;
+  void _apparatusRoute;
+  void _apparatusRoutes;
   const katexExternals = wantsKatex ? [] : ["remark-math", "rehype-katex", "katex"];
   const restVite = rest.vite ?? {};
   const restSsr = restVite.ssr ?? {};
@@ -1592,6 +1636,38 @@ function resolveBookHref(siblingBooks, book, to) {
   return `${base.replace(/\/+$/, "")}/${to.replace(/^\/+/, "")}`;
 }
 
+// src/lib/nav-href.ts
+function normBase(baseUrl) {
+  return (baseUrl || "/").replace(/\/*$/, "/");
+}
+function fillTokens(pattern, tokens) {
+  return pattern.replace(/:(book|slug|route|id)\b/g, (_m, k) => tokens[k] ?? "");
+}
+function bookOf(entry, bookField = "book") {
+  const v = entry.data[bookField];
+  return typeof v === "string" && v.length > 0 ? v : null;
+}
+function slugOf(entry, bookField = "book") {
+  const book = bookOf(entry, bookField);
+  return book && entry.id.startsWith(`${book}/`) ? entry.id.slice(book.length + 1) : entry.id;
+}
+function chapterHref(entry, pattern = "/chapters/:id/", baseUrl = "/", bookField = "book") {
+  const path = fillTokens(pattern, {
+    id: entry.id,
+    book: bookOf(entry, bookField) ?? "",
+    slug: slugOf(entry, bookField)
+  }).replace(/\/{2,}/g, "/").replace(/^\//, "");
+  return normBase(baseUrl) + path;
+}
+function apparatusHref(route, book, pattern = "/:route/", baseUrl = "/") {
+  const path = fillTokens(pattern, { route, book: book ?? "" }).replace(/\/{2,}/g, "/").replace(/^\//, "");
+  return normBase(baseUrl) + path;
+}
+function isCurrentChapter(entry, currentPath, pattern = "/chapters/:id/", baseUrl = "/", bookField = "book") {
+  const href = chapterHref(entry, pattern, baseUrl, bookField);
+  return currentPath === href || currentPath === href.replace(/\/$/, "");
+}
+
 // src/lib/exam-domains.ts
 function assertKnownDomain(examDomains, domain, ctx) {
   if (!examDomains || !examDomains.includes(domain)) {
@@ -1845,15 +1921,18 @@ export {
   academicPartOrdinal,
   academicParts,
   academicStyle,
+  apparatusHref,
   assertEnumProp,
   assertKnownDomain,
   bloomLevels,
+  bookOf,
   bookScaffoldIntegration,
   buildExamManifest,
   buildFlashcardDeck,
   buildGithubUrl,
   changeKinds,
   changelogSchema,
+  chapterHref,
   chapterLabel,
   chapterSortKey,
   chapterStatus,
@@ -1875,6 +1954,7 @@ export {
   glossarySchema,
   groupByChapter,
   groupByDomain,
+  isCurrentChapter,
   layoutModes,
   minimalChapterSchema,
   minimalStyle,
@@ -1892,6 +1972,7 @@ export {
   refineQuestion,
   refinedQuestionSchema,
   researchPortfolioChapterSchema,
+  researchPortfolioChaptersRenderer,
   researchPortfolioStyle,
   resolveBookHref,
   resolveGithubRepo,
@@ -1902,6 +1983,7 @@ export {
   scoreExam,
   selectPartExercises,
   shuffle,
+  slugOf,
   sortQuestions,
   sourceTiers,
   sourceTiersResearch,

package/dist/schemas.d.ts

@@ -1,5 +1,5 @@
 import { defineCollection } from 'astro:content';
-import { g as BookSchemasOptions } from './types-Bn7rKhgP.js';
+import { g as BookSchemasOptions } from './types-Hue-uSeQ.js';
 import 'astro';
 import './schemas-CKipJ5Ie.js';
 import 'astro/zod';

package/dist/schemas.mjs

@@ -729,6 +729,17 @@ var courseNotesProfile = defineProfile({
   sitemapFilter: (page) => !page.includes("/print/")
 });
 
+// src/profiles/renderers/research-portfolio-chapters.ts
+var researchPortfolioChaptersRenderer = {
+  ...fallbackChaptersRenderer,
+  formatPartLabel(part) {
+    return typeof part === "number" ? `Part ${part}` : fallbackChaptersRenderer.formatPartLabel(part);
+  },
+  isAppendix(_part) {
+    return false;
+  }
+};
+
 // src/profiles/research-portfolio.ts
 var researchPortfolioProfile = defineProfile({
   name: "research-portfolio",
@@ -761,8 +772,9 @@ var researchPortfolioProfile = defineProfile({
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css", "section-map.css"],
   katex: true,
   // math is common in research content
-  // v3.7.0 (#35): portfolio schema is a union of academic + tools shapes — fallback renderer dispatches per chapter via field presence
-  chaptersRenderer: fallbackChaptersRenderer
+  // Portfolio schema is a union of academic + tools shapes, but unlike the
+  // tools profile its numeric Parts remain numbered through the schema max 20.
+  chaptersRenderer: researchPortfolioChaptersRenderer
 });
 
 // src/profiles/index.ts

package/dist/{types-Bn7rKhgP.d.ts → types-Hue-uSeQ.d.ts}

@@ -379,6 +379,12 @@ interface Style {
      *  - `'pages'`: Cloudflare Pages (default for research-portfolio/course-notes)
      *  Closes #50. */
     readonly deploy?: 'pages' | 'workers';
+    /** v4.27.0 (#149): release-state banner; shallow override (last wins). */
+    readonly releaseStatus?: {
+        state: 'alpha' | 'beta' | 'rc' | 'locked';
+        dismissAt?: string;
+        message?: string;
+    };
     /**
      * Scoped consumer-side metadata. Ignored by the toolkit; survives composition
      * as per-key spread (last wins per key). Use this for workflow data that
@@ -600,6 +606,17 @@ interface BookConfigOptions {
      * hardcoded both strings, so every consumer shipped the placeholder).
      */
     subtitle?: string;
+    /**
+     * v4.27.0 (#149): book-level release state. When set, Base.astro renders
+     * the existing <PreReleaseBanner> site-wide (top of <body>) with these
+     * props — previously the banner was author-import-only, so auto-layout
+     * consumers (ssm-foundations) had no way to wire it. Omit for no banner.
+     */
+    releaseStatus?: {
+        state: 'alpha' | 'beta' | 'rc' | 'locked';
+        dismissAt?: string;
+        message?: string;
+    };
     /**
      * v4.5.0: Book description. Read by the auto-injected `/` landing page (lead paragraph + <meta description>).
      * Optional; landing renders no description paragraph if unset.
@@ -684,6 +701,39 @@ interface BookConfigOptions {
      * @example examDomains: ['secure-network-architecture', 'identity-and-access']
      */
     examDomains?: readonly string[];
+    /**
+     * v4.26.0 (#80): URL pattern for a chapter entry, consumed by the book-aware
+     * Sidebar / ChapterNav / NavContent so they emit correct links on a multi-book
+     * consumer. Base-relative token string — `:id` (entry.id), `:book` (the
+     * entry's book, see `bookField`), `:slug` (id minus the leading `<book>/`).
+     * Default `'/chapters/:id/'` reproduces the single-book behavior byte-for-byte;
+     * a multi-book consumer whose chapters render at `/<book>/<slug>/` (entry.id =
+     * `'<book>/<slug>'`) sets `'/:id/'`. Resolved by the pure `chapterHref` helper.
+     */
+    chapterRoute?: string;
+    /**
+     * v4.26.0 (#80): frontmatter field naming a chapter's book (multi-book book
+     * scoping). Default `'book'`. Absent on single-book schemas → the sidebar shows
+     * every chapter (today's behavior); present → the sidebar filters to the
+     * current book and the `:book` / `:slug` route tokens resolve.
+     */
+    bookField?: string;
+    /**
+     * v4.26.0 (#80): URL pattern for a per-book apparatus route (practice-exam /
+     * glossary / flashcards / answers) surfaced in the nav. Tokens `:book` +
+     * `:route`. Default `'/:route/'` (single-book, flat); a multi-book consumer
+     * sets `'/:book/:route/'`. Resolved by the pure `apparatusHref` helper.
+     */
+    apparatusRoute?: string;
+    /**
+     * v4.26.0 (#80): the apparatus route slugs to surface in the nav (sidebar +
+     * drawer) — a subset of `practice-exam | glossary | flashcards | answers`.
+     * Default `[]` (no apparatus links in nav — existing single-book books render
+     * unchanged). A multi-book consumer that owns per-book apparatus routes sets
+     * e.g. `['practice-exam','glossary','flashcards','answers']`; each is rendered
+     * via `apparatusHref(slug, currentBook, apparatusRoute, base)`.
+     */
+    apparatusRoutes?: readonly string[];
     /** Escape hatch for any other AstroUserConfig field. */
     [key: string]: unknown;
 }
@@ -719,6 +769,13 @@ interface BookScaffoldIntegrationOptions {
     /** v4.23.0 (#135): sidebar brand subtitle, propagated via the book-config
      *  virtual module to Sidebar.astro. */
     subtitle?: string;
+    /** v4.27.0 (#149): release-state banner, propagated via the book-config
+     *  virtual module; Base.astro renders <PreReleaseBanner> when set. */
+    releaseStatus?: {
+        state: 'alpha' | 'beta' | 'rc' | 'locked';
+        dismissAt?: string;
+        message?: string;
+    };
     /** v4.5.0: book description, propagated to `/` landing via vite.define. */
     description?: string;
     /**
@@ -756,6 +813,15 @@ interface BookScaffoldIntegrationOptions {
     siblingBooks?: Record<string, string>;
     /** v4.17.0 (#112): closed exam-domain taxonomy for the questions collection. */
     examDomains?: readonly string[];
+    /** v4.26.0 (#80): chapter-route token pattern, propagated via the book-config
+     *  virtual module to the book-aware nav. Default '/chapters/:id/'. */
+    chapterRoute?: string;
+    /** v4.26.0 (#80): frontmatter field naming a chapter's book. Default 'book'. */
+    bookField?: string;
+    /** v4.26.0 (#80): apparatus-route token pattern. Default '/:route/'. */
+    apparatusRoute?: string;
+    /** v4.26.0 (#80): apparatus route slugs to surface in the nav. Default []. */
+    apparatusRoutes?: readonly string[];
 }
 /** Raised when the resolved profile is not one of `BOOK_PROFILES`. */
 declare class BookConfigError extends Error {

package/layouts/Base.astro

@@ -59,6 +59,10 @@ import '../styles/print.css';
 import VersionSelector from '@brandon_m_behring/book-scaffold-astro/components/VersionSelector';
 import ToolFilter from '@brandon_m_behring/book-scaffold-astro/components/ToolFilter';
 import Sidebar from '../components/Sidebar.astro';
+// v4.27.0 (#149): site-wide release-state banner, driven by defineBookConfig.
+import PreReleaseBanner from '../components/PreReleaseBanner.astro';
+// v4.26.0 (#80): the mobile/tablet drawer reuses the same book-scoped nav source.
+import NavContent from '../components/NavContent.astro';
 // v4.6.0: SEO meta tags read book-level identity (title fallback,
 // description fallback, ogImage default, twitterHandle) from the
 // book-config virtual module (was landing-config in v4.5.1).
@@ -115,7 +119,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 ?? '/').replace(/\/?$/, '/');
+const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/*$/, '/');
 ---
 
 <!doctype html>
@@ -163,7 +167,33 @@ const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
     <slot name="head" />
   </head>
   <body>
+    {/* v4.27.0 (#149): book-level release banner — first element in <body> so
+        every page (chapters, apparatus, landing) declares its state. Renders
+        only when defineBookConfig({ releaseStatus }) is set. */}
+    {bookConfig.releaseStatus && (
+      <PreReleaseBanner
+        state={bookConfig.releaseStatus.state}
+        dismissAt={bookConfig.releaseStatus.dismissAt}
+        message={bookConfig.releaseStatus.message}
+      />
+    )}
     <div class="chrome-buttons">
+      {/* v4.26.0 (#80): hamburger → mobile/tablet nav drawer. <a href="#nav-drawer">
+          so it opens via :target with no JS; the controller below enhances it. */}
+      {showSidebar && (
+        <a
+          id="nav-toggle"
+          class="chrome-button nav-toggle"
+          href="#nav-drawer"
+          role="button"
+          aria-controls="nav-drawer"
+          aria-expanded="false"
+          aria-haspopup="dialog"
+          aria-label="Open chapter navigation"
+        >
+          <span aria-hidden="true">☰</span>
+        </a>
+      )}
       {showToolsChrome && <ToolFilter client:idle />}
       {showToolsChrome && <VersionSelector client:idle />}
       <a
@@ -185,6 +215,20 @@ const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
         <span class="theme-toggle-icon dark-icon" aria-hidden="true">☾</span>
       </button>
     </div>
+    {/* v4.26.0 (#80): mobile/tablet nav drawer (sibling of <main>, NOT a <main>).
+        CSS-hidden ≥64rem where the Sidebar is the nav. role=dialog + the inline
+        controller below provide focus-trap/ESC; `:target` is the no-JS fallback. */}
+    {showSidebar && (
+      <div id="nav-drawer" class="nav-drawer" data-nav-drawer>
+        <a class="nav-drawer-backdrop" href="#" data-nav-close tabindex="-1" aria-hidden="true"></a>
+        <div class="nav-drawer-panel" role="dialog" aria-modal="true" aria-label="Chapter navigation" tabindex="-1">
+          <a class="nav-drawer-dismiss chrome-button" href="#" data-nav-close aria-label="Close navigation">
+            <span aria-hidden="true">✕</span>
+          </a>
+          <NavContent />
+        </div>
+      </div>
+    )}
     {showSidebar ? (
       <div class="layout-with-sidebar">
         <Sidebar />
@@ -236,6 +280,79 @@ const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
         } catch (e) { /* older browsers: no media-query change events */ }
       })();
     </script>
+    {/*
+      Nav-drawer controller (v4.26.0, #80). Progressive enhancement over the
+      `:target` no-JS baseline: intercepts the hamburger to toggle `.is-open`
+      (so no history hash is pushed), traps focus inside the dialog, closes on
+      ESC / backdrop / dismiss, restores focus to the opener, and locks body
+      scroll. No-op on pages without the drawer (landing: showSidebar=false).
+    */}
+    <script is:inline>
+      (function () {
+        var drawer = document.getElementById('nav-drawer');
+        var toggle = document.getElementById('nav-toggle');
+        if (!drawer || !toggle) return;
+        var panel = drawer.querySelector('.nav-drawer-panel');
+        var opener = null;
+        function focusables() {
+          return Array.prototype.slice
+            .call(panel.querySelectorAll('a[href], button:not([disabled]), [tabindex]:not([tabindex="-1"])'))
+            .filter(function (el) { return el.offsetParent !== null; });
+        }
+        // C1 (#80, codex@medium): count the :target no-JS-fallback state too, so a
+        // drawer opened via a '#nav-drawer' hash (with JS active) is still closable by
+        // backdrop / dismiss / ESC (close() clears the hash); else it would be stranded.
+        function isOpen() { return drawer.classList.contains('is-open') || location.hash === '#nav-drawer'; }
+        function open(e) {
+          if (e) e.preventDefault();
+          opener = document.activeElement;
+          drawer.classList.add('is-open');
+          toggle.setAttribute('aria-expanded', 'true');
+          document.documentElement.classList.add('nav-drawer-locked');
+          var f = focusables();
+          (f[0] || panel).focus();
+        }
+        function close(e) {
+          if (e) e.preventDefault();
+          if (!isOpen()) return;
+          drawer.classList.remove('is-open');
+          toggle.setAttribute('aria-expanded', 'false');
+          document.documentElement.classList.remove('nav-drawer-locked');
+          if (location.hash === '#nav-drawer') {
+            history.replaceState(null, '', location.pathname + location.search);
+          }
+          if (opener && typeof opener.focus === 'function') opener.focus();
+        }
+        toggle.addEventListener('click', function (e) { isOpen() ? close(e) : open(e); });
+        drawer.addEventListener('click', function (e) {
+          var t = e.target;
+          if (t && t.closest && t.closest('[data-nav-close]')) close(e);
+        });
+        document.addEventListener('keydown', function (e) {
+          if (!isOpen()) return;
+          if (e.key === 'Escape') { close(e); return; }
+          if (e.key === 'Tab') {
+            var f = focusables();
+            if (!f.length) return;
+            var first = f[0], last = f[f.length - 1];
+            if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus(); }
+            else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
+          }
+        });
+        // F5 (a11y, #80): role="button" must activate on Space; native anchors only
+        // fire click on Enter, so bind Space explicitly (preventDefault stops scroll).
+        toggle.addEventListener('keydown', function (e) {
+          if (e.key === ' ' || e.key === 'Spacebar') { e.preventDefault(); isOpen() ? close(e) : open(e); }
+        });
+        // F1 (#80): if the viewport grows into the desktop range (>=80rem) while the
+        // drawer is open, the drawer + toggle + backdrop go display:none — close() to
+        // clear .is-open and release the body scroll-lock so the page isn't stranded.
+        var mq = window.matchMedia('(min-width: 80rem)');
+        var onDesktop = function (ev) { if (ev.matches) close(); };
+        if (mq.addEventListener) mq.addEventListener('change', onDesktop);
+        else if (mq.addListener) mq.addListener(onDesktop);
+      })();
+    </script>
   </body>
 </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.3",
+  "version": "4.26.2",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -69,6 +69,7 @@
     "./components/KeyIdea.astro": "./components/KeyIdea.astro",
     "./components/MarginFigure.astro": "./components/MarginFigure.astro",
     "./components/MarginNote.astro": "./components/MarginNote.astro",
+    "./components/NavContent.astro": "./components/NavContent.astro",
     "./components/Newthought.astro": "./components/Newthought.astro",
     "./components/NoteBox.astro": "./components/NoteBox.astro",
     "./components/ObjectiveMap.astro": "./components/ObjectiveMap.astro",

package/recipes/08-decisions-ledger.md

@@ -122,6 +122,16 @@ Until v3.0 triggers, accept that bug fixes don't auto-flow to existing books. Bo
 **Reasoning**: #82 itself was a coverage gap — don't trade coverage for speed.
 **Deviate when**: Never delete a visual gate without equivalent-or-better coverage in the replacement.
 
+### D21 — Book-aware nav config is declarative token strings, not resolver functions (#80, v4.26.0)
+**Decision**: `defineBookConfig`'s nav-route fields (`chapterRoute` / `bookField` / `apparatusRoute` / `apparatusRoutes`) are declarative TOKEN STRINGS (`'/:id/'`, `':book'`, `':slug'`, `':route'`) resolved by a pure `nav-href` lib — NOT a `chapterHref(entry) => string` callback.
+**Reasoning**: the book-config virtual module serializes via `JSON.stringify` (`integration.ts`); a function serializes to `undefined`. Token strings cross the boundary intact and cover every known multi-book route shape. A consumer needing real logic already owns its route components (recipe 18) and can import `chapterHref` directly.
+**Deviate when**: a consumer's URL scheme can't be expressed with `:id`/`:book`/`:slug` token substitution — then they own the route components, no worse than pre-4.26.
+
+### D22 — Mobile nav is an inline controller + the 3-column gutter FITS (not suppressed) (#80, v4.26.0)
+**Decision**: (a) the sub-1280px nav drawer is an inline vanilla `<script>` controller over a `:target` no-JS baseline, NOT a Preact island. (b) The right-gutter overflow (the Tufte `.section-map`/sidenote float overflowing beside the sidebar at 1024/1440px) is fixed by making it FIT — trim the shared measures (`--measure-main` 60/66/78ch, `--measure-side` 20/20/24ch) + the sidebar (14/16rem), and activate the full 3-column (sidebar + floated gutter) at **≥80rem (1280px)** instead of 64rem (below that: drawer + full-width content + ChapterTOC). NOT suppressing/hiding the scrollspy.
+**Reasoning**: the drawer is event-wiring (open/close/focus-trap), not Preact rendering — the inline script is instant (no hydration flash), zero `.tsx` compile risk, and matches the existing theme-toggle precedent. The fit-not-suppress gutter keeps the Tufte scrollspy at true-desktop widths (it's the design's point); narrower measures are also closer to the ideal reading column. Verified `scrollWidth == clientWidth` across the consumer's responsive audit harness (390–1440px).
+**Deviate when**: a consumer wants the gutter scrollspy at 1024–1280px — they'd need an even narrower measure or a different sidebar treatment at that band; document the trade-off.
+
 ## How to use this ledger
 
 When a future change in the scaffold contradicts a decision above, update this ledger first. Don't change behavior silently — the ledger is the durable record of "why this is shaped like it is."