@brandon_m_behring/book-scaffold-astro 4.26.3 → 4.27.0

package/dist/index.mjs

@@ -912,6 +912,7 @@ var BOOK_PROFILES = Object.keys(PROFILES);
 // src/types.ts
 import { existsSync, readFileSync } from "fs";
 var BOOK_PRESETS = BOOK_PROFILES;
+var NUMBER_STYLES = ["shared", "per-kind"];
 var BookConfigError = class extends Error {
   constructor(message) {
     super(message);
@@ -936,6 +937,7 @@ function readEnvFile(path = ".env") {
     return {};
   }
 }
+var PRESET_FALLBACK_WARNING = /* @__PURE__ */ Symbol.for("book-scaffold-astro:preset-fallback-warning");
 function resolvePreset(explicitPreset, explicitProfile) {
   let candidate = explicitPreset ?? explicitProfile ?? process.env.BOOK_PRESET ?? process.env.BOOK_PROFILE;
   let source = "default";
@@ -956,7 +958,13 @@ function resolvePreset(explicitPreset, explicitProfile) {
     );
   }
   if (source === "default") {
-    console.warn("book-scaffold-astro: BOOK_PRESET not set; falling back to 'minimal'.");
+    const warningState = globalThis;
+    if (!warningState[PRESET_FALLBACK_WARNING]) {
+      warningState[PRESET_FALLBACK_WARNING] = true;
+      console.warn(
+        "book-scaffold-astro: no preset resolved; falling back to 'minimal' for v4 compatibility. This fallback will be removed in v5. Add a built-in style to defineBookConfig and pass the same preset to defineBookSchemas, or set BOOK_PRESET."
+      );
+    }
   }
   return candidate;
 }
@@ -966,7 +974,7 @@ function resolveProfile(explicit) {
 
 // src/integration.ts
 import { fileURLToPath } from "url";
-import { readFileSync as readFileSync2 } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync2, writeFileSync } from "fs";
 import { join } from "path";
 
 // src/lib/define-style.ts
@@ -981,6 +989,7 @@ function composeStyles(styles) {
   for (const style of styles) {
     if (style.name !== void 0) merged.name = style.name;
     if (style.preset !== void 0) merged.preset = style.preset;
+    if (style.numberStyle !== void 0) merged.numberStyle = style.numberStyle;
     if (style.site !== void 0) merged.site = style.site;
     if (style.deploy !== void 0) merged.deploy = style.deploy;
     if (style.releaseStatus !== void 0) {
@@ -1197,6 +1206,17 @@ var ROUTE_REGISTRY = {
   // empty string → '/[slug]'; arbitrary string → '/<prefix>/[slug]').
   frontmatter: { pattern: "/frontmatter/[slug]", file: "frontmatter/[...slug].astro" }
 };
+var DEFAULT_CONTENT_SECURITY_POLICY = "default-src 'self'; script-src 'self' 'unsafe-inline' 'wasm-unsafe-eval' https://static.cloudflareinsights.com; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self'; connect-src 'self' https://cloudflareinsights.com; object-src 'none'; base-uri 'self'; frame-ancestors 'self'; form-action 'self'";
+function renderSecurityHeaders(contentSecurityPolicy) {
+  const csp = contentSecurityPolicy ?? DEFAULT_CONTENT_SECURITY_POLICY;
+  return `/*
+  Strict-Transport-Security: max-age=31536000; includeSubDomains
+  X-Content-Type-Options: nosniff
+  Referrer-Policy: strict-origin-when-cross-origin
+  Permissions-Policy: camera=(), microphone=(), geolocation=()
+  Content-Security-Policy: ${csp}
+`;
+}
 function frontmatterPatternFromPrefix(prefix) {
   if (prefix === void 0) return ROUTE_REGISTRY.frontmatter.pattern;
   if (prefix === "") return "/[slug]";
@@ -1208,6 +1228,7 @@ function resolvePage(file) {
 function bookScaffoldIntegration(opts) {
   const {
     profile,
+    numberStyle = "shared",
     routes: userOverrides = {},
     extraStyles = [],
     mdxComponentsModule,
@@ -1215,6 +1236,7 @@ function bookScaffoldIntegration(opts) {
     title,
     subtitle,
     releaseStatus,
+    securityHeaders,
     description,
     portfolio,
     // v4.6.0: book-level author + SEO config, propagated through the
@@ -1245,7 +1267,7 @@ function bookScaffoldIntegration(opts) {
     ),
     frontmatter: fmEnabled
   };
-  return {
+  const integration = {
     name: "book-scaffold-astro",
     hooks: {
       "astro:config:setup": ({ injectScript, injectRoute, updateConfig, config }) => {
@@ -1315,9 +1337,38 @@ function bookScaffoldIntegration(opts) {
             }
           }
         });
+      },
+      // v4.27.0 (#188): emit defaults for every build, not only newly
+      // scaffolded projects, so existing consumers become protected on their
+      // next package upgrade. Astro copies public/_headers into the output
+      // before build:done; an existing target therefore means the consumer
+      // owns the complete file and must win byte-for-byte.
+      "astro:build:done": ({ dir, logger }) => {
+        if (securityHeaders === false) {
+          logger.info("security-header emission disabled by defineBookConfig (#188)");
+          return;
+        }
+        const target = join(fileURLToPath(dir), "_headers");
+        if (existsSync3(target)) {
+          logger.info("consumer public/_headers present; scaffold defaults skipped (#188)");
+          return;
+        }
+        writeFileSync(
+          target,
+          renderSecurityHeaders(securityHeaders?.contentSecurityPolicy),
+          "utf8"
+        );
+        logger.info("emitted default security headers; public/_headers overrides them (#188)");
       }
     }
   };
+  Object.defineProperty(integration, "__bookScaffoldResolvedConfig", {
+    value: Object.freeze({ preset: profile, numberStyle }),
+    enumerable: false,
+    configurable: false,
+    writable: false
+  });
+  return integration;
 }
 
 // src/config.ts
@@ -1354,8 +1405,19 @@ async function defineBookConfig(opts) {
   if ("preset" in opts || "profile" in opts) {
     throw v3MigrationError(opts);
   }
+  if (Object.prototype.hasOwnProperty.call(opts, "deploy")) {
+    console.warn(
+      "book-scaffold-astro: defineBookConfig({ deploy }) is inert and deprecated; create-book chooses wrangler.toml from its CLI preset. Remove this field before upgrading to v5 (#180)."
+    );
+  }
   const composed = composeStyles(opts.styles ?? []);
-  const profile = opts.styles === void 0 && composed.preset === void 0 ? "minimal" : composed.preset ?? "minimal";
+  const profile = resolvePreset(composed.preset);
+  const numberStyle = opts.numberStyle ?? composed.numberStyle ?? "shared";
+  if (!NUMBER_STYLES.includes(numberStyle)) {
+    throw new BookConfigError(
+      `numberStyle must be one of ${NUMBER_STYLES.join(" | ")} (got ${JSON.stringify(numberStyle)})`
+    );
+  }
   const site = opts.site ?? composed.site;
   if (!site) {
     throw new BookConfigError(
@@ -1423,6 +1485,7 @@ async function defineBookConfig(opts) {
     sitemap(sitemapOptions),
     bookScaffoldIntegration({
       profile,
+      numberStyle,
       routes: mergedRoutes,
       mdxComponentsModule,
       extraStyles: mergedExtraStyles,
@@ -1433,6 +1496,11 @@ async function defineBookConfig(opts) {
       subtitle: opts.subtitle,
       // v4.26.2 (#149; style inheritance + opt-out fixed in v4.26.3).
       releaseStatus: resolvedReleaseStatus === false ? void 0 : resolvedReleaseStatus,
+      // v4.27.0 (#188): undefined enables the audited defaults, false opts
+      // out, and an object can replace only the CSP. The integration owns
+      // the build:done emission because that is where Astro's output dir is
+      // known and a copied consumer public/_headers can be detected.
+      securityHeaders: opts.securityHeaders,
       description: opts.description,
       portfolio: resolvedPortfolio,
       // v4.6.0: book-level author + SEO config (ogImage, twitterHandle),
@@ -1479,6 +1547,7 @@ async function defineBookConfig(opts) {
   };
   const {
     styles: _styles,
+    numberStyle: _numberStyle,
     site: _site,
     routes: _routes,
     deploy: _deploy,
@@ -1492,6 +1561,8 @@ async function defineBookConfig(opts) {
     subtitle: _subtitle,
     // v4.26.2 (#149): strip the release-state banner config.
     releaseStatus: _releaseStatus,
+    // v4.27.0 (#188): consumed by the scaffold integration at build:done.
+    securityHeaders: _securityHeaders,
     description: _description,
     portfolio: _portfolio,
     // v4.6.0: strip new book-level SEO opts (author + seo block).
@@ -1512,6 +1583,7 @@ async function defineBookConfig(opts) {
     ...rest
   } = opts;
   void _styles;
+  void _numberStyle;
   void _site;
   void _routes;
   void _deploy;
@@ -1523,6 +1595,7 @@ async function defineBookConfig(opts) {
   void _title;
   void _subtitle;
   void _releaseStatus;
+  void _securityHeaders;
   void _description;
   void _portfolio;
   void _author;
@@ -1628,6 +1701,9 @@ function assertEnumProp(value, allowed, ctx) {
   );
 }
 
+// src/index.ts
+init_katex_macros();
+
 // src/lib/book-link.ts
 function resolveBookHref(siblingBooks, book, to) {
   const base = siblingBooks?.[book];
@@ -1641,9 +1717,13 @@ function resolveBookHref(siblingBooks, book, to) {
 }
 
 // src/lib/nav-href.ts
-function normBase(baseUrl) {
+function normalizeBase(baseUrl) {
   return (baseUrl || "/").replace(/\/*$/, "/");
 }
+function baseNoSlash(baseUrl) {
+  return (baseUrl || "/").replace(/\/+$/, "");
+}
+var normBase = normalizeBase;
 function fillTokens(pattern, tokens) {
   return pattern.replace(/:(book|slug|route|id)\b/g, (_m, k) => tokens[k] ?? "");
 }
@@ -1916,6 +1996,7 @@ export {
   BookConfigError,
   DEFAULT_GITHUB_BRANCH,
   KIND_LABEL,
+  NUMBER_STYLES,
   THEOREM_KINDS,
   UNKNOWN_PART_ORDINAL,
   academicChapterSchema,
@@ -1928,6 +2009,7 @@ export {
   apparatusHref,
   assertEnumProp,
   assertKnownDomain,
+  baseNoSlash,
   bloomLevels,
   bookOf,
   bookScaffoldIntegration,
@@ -1962,6 +2044,7 @@ export {
   layoutModes,
   minimalChapterSchema,
   minimalStyle,
+  normalizeBase,
   normalizeFrontmatterConfig,
   originUrlFromGitConfig,
   parseRepoSlug,
@@ -1993,6 +2076,7 @@ export {
   sourceTiersResearch,
   sourcesSchema,
   spreadBlueprint,
+  ssmMacros,
   theoremLabel,
   tocHeadings,
   toolSlugs,

package/dist/schemas.d.ts

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

package/dist/schemas.mjs

@@ -814,6 +814,7 @@ function readEnvFile(path = ".env") {
     return {};
   }
 }
+var PRESET_FALLBACK_WARNING = /* @__PURE__ */ Symbol.for("book-scaffold-astro:preset-fallback-warning");
 function resolvePreset(explicitPreset, explicitProfile) {
   let candidate = explicitPreset ?? explicitProfile ?? process.env.BOOK_PRESET ?? process.env.BOOK_PROFILE;
   let source = "default";
@@ -834,7 +835,13 @@ function resolvePreset(explicitPreset, explicitProfile) {
     );
   }
   if (source === "default") {
-    console.warn("book-scaffold-astro: BOOK_PRESET not set; falling back to 'minimal'.");
+    const warningState = globalThis;
+    if (!warningState[PRESET_FALLBACK_WARNING]) {
+      warningState[PRESET_FALLBACK_WARNING] = true;
+      console.warn(
+        "book-scaffold-astro: no preset resolved; falling back to 'minimal' for v4 compatibility. This fallback will be removed in v5. Add a built-in style to defineBookConfig and pass the same preset to defineBookSchemas, or set BOOK_PRESET."
+      );
+    }
   }
   return candidate;
 }

package/dist/{types-CWXP1S4b.d.ts → types-CZrkqzpC.d.ts}

@@ -353,6 +353,8 @@ interface Style {
     readonly name?: string;
     /** Profile that backs this style — determines schema + default routes + styles + KaTeX wiring. */
     readonly preset?: BookPreset;
+    /** Theorem-family numbering strategy; shallow override (last wins). */
+    readonly numberStyle?: NumberStyle;
     /** Book's deployed origin (sitemap, canonical, Pagefind). Required at composition end;
      *  optional inside a Style (so styles can omit it and consumers can provide per-book). */
     readonly site?: string;
@@ -374,10 +376,10 @@ interface Style {
      *  `remarkPlugins` and `rehypePlugins` arrays concat across the chain;
      *  scalar fields override. */
     readonly markdown?: AstroUserConfig['markdown'];
-    /** Deploy target — drives create-book's wrangler.toml shape.
-     *  - `'workers'`: Cloudflare Workers + Static Assets (default for academic/tools/minimal)
-     *  - `'pages'`: Cloudflare Pages (default for research-portfolio/course-notes)
-     *  Closes #50. */
+    /** Reserved legacy metadata. It is composed but has no runtime or
+     *  create-book effect: create-book chooses wrangler.toml from its CLI
+     *  preset before a consumer Style exists (#180).
+     *  @deprecated Inert in v4; scheduled for removal in v5. */
     readonly deploy?: 'pages' | 'workers';
     /**
      * v4.26.2 (#149; style inheritance fixed in v4.26.3): release-state
@@ -445,7 +447,7 @@ declare function defineStyle(opts: StyleInput): Style;
  *   - Top-level `defineBookConfig` fields beat any style (handled in config.ts)
  *
  * Per-key merge strategy:
- *   - `preset`, `site`, `deploy`, `mdxComponentsModule`, `name`, `releaseStatus`
+ *   - `preset`, `numberStyle`, `site`, `deploy`, `mdxComponentsModule`, `name`, `releaseStatus`
  *     → shallow override (last defined wins; `releaseStatus: false` suppresses)
  *   - `routes` → per-route spread (each route key independently overridable)
  *   - `katexMacros` → per-macro spread (each macro key independently overridable)
@@ -482,6 +484,30 @@ declare function normalizeFrontmatterConfig(v: FrontmatterRouteConfig | undefine
 
 type BookPreset = BookProfile;
 declare const BOOK_PRESETS: readonly ("academic" | "tools" | "minimal" | "course-notes" | "research-portfolio")[];
+/** Theorem-family numbering strategy used by build-labels and validate. */
+type NumberStyle = 'shared' | 'per-kind';
+declare const NUMBER_STYLES: readonly ["shared", "per-kind"];
+/**
+ * v4.27.0 (#188): build-time security-header customization.
+ *
+ * The integration emits a Cloudflare-compatible `dist/_headers` file by
+ * default. Consumers that need a different CSP can replace that one header
+ * while retaining the scaffold's other audited defaults.
+ */
+interface SecurityHeadersConfig {
+    contentSecurityPolicy?: string;
+}
+/**
+ * v4.26.2 (#149): book-level release state rendered by
+ * `<PreReleaseBanner>` across every page.
+ *
+ * Style inheritance and explicit suppression were fixed in v4.26.3.
+ */
+interface ReleaseStatusConfig {
+    state: 'alpha' | 'beta' | 'rc' | 'locked';
+    dismissAt?: string;
+    message?: string;
+}
 /**
  * v4.26.2 (#149): book-level release state rendered by
  * `<PreReleaseBanner>` across every page.
@@ -531,6 +557,13 @@ interface BookConfigOptions {
      *   });
      */
     styles?: readonly Style[];
+    /**
+     * v4.27.0 (#175): theorem-family counter strategy. `shared` preserves the
+     * amsthm-style sequence used through v4.26; `per-kind` gives theorem,
+     * proposition, lemma, and each other theorem kind an independent sequence.
+     * May also be supplied by a Style; top-level config wins.
+     */
+    numberStyle?: NumberStyle;
     /**
      * Optional per-route override of the composed profile's defaults. Use to
      * disable an auto-injected route (e.g. multi-book consumer that ships
@@ -545,10 +578,13 @@ interface BookConfigOptions {
      */
     routes?: PartialRouteToggles;
     /**
-     * v4.0.0 (NEW): deploy target — drives `create-book`'s wrangler.toml shape.
-     * Defaults from the composed style chain (academic/tools/minimal →
-     * 'workers'; course-notes/research-portfolio → 'pages'); per-book override
-     * here beats any style. Closes #50.
+     * v4.0.0 (#50): RESERVED — accepted and style-chain-merged, but currently
+     * has NO runtime effect (#180). The wrangler.toml shape is decided once, at
+     * scaffold time, by `create-book` from the profile name (academic/tools/
+     * minimal → Workers; course-notes/research-portfolio → Pages); setting this
+     * field changes nothing afterward. Wire-or-remove is a v5 decision.
+     * @deprecated Inert in v4; remove this option before v5. Deployment shape
+     * is chosen by create-book or by the consumer's own deployment files.
      */
     deploy?: 'pages' | 'workers';
     /**
@@ -625,6 +661,14 @@ interface BookConfigOptions {
      * composed style chain; set `false` to suppress an inherited banner.
      */
     releaseStatus?: ReleaseStatusConfig | false;
+    /**
+     * v4.27.0 (#188): security headers emitted to `dist/_headers` after an
+     * Astro build. Omit for the scaffold defaults; set `false` to emit no
+     * scaffold-owned file; provide `contentSecurityPolicy` to replace only the
+     * default CSP while retaining HSTS, XCTO, Referrer-Policy, and
+     * Permissions-Policy. A consumer-owned `public/_headers` always wins.
+     */
+    securityHeaders?: SecurityHeadersConfig | false;
     /**
      * v4.5.0: Book description. Read by the auto-injected `/` landing page (lead paragraph + <meta description>).
      * Optional; landing renders no description paragraph if unset.
@@ -757,6 +801,8 @@ interface BookSchemasOptions {
 /** Options for the internal `bookScaffoldIntegration`. See PACKAGE_DESIGN.md §6. */
 interface BookScaffoldIntegrationOptions {
     profile: BookProfile;
+    /** Resolved theorem-family counter strategy exposed to package CLI tooling. */
+    numberStyle?: NumberStyle;
     /**
      * Per-route override; merged into the profile's defaults.
      * v4.0.0: `routes.frontmatter` widened to `boolean | { enabled, prefix? }`
@@ -780,6 +826,8 @@ interface BookScaffoldIntegrationOptions {
     /** v4.26.2 (#149; style inheritance fixed in v4.26.3): resolved
      *  release-state banner propagated via the book-config virtual module. */
     releaseStatus?: ReleaseStatusConfig;
+    /** v4.27.0 (#188): resolved security-header emission policy. */
+    securityHeaders?: SecurityHeadersConfig | false;
     /** v4.5.0: book description, propagated to `/` landing via vite.define. */
     description?: string;
     /**
@@ -831,22 +879,6 @@ interface BookScaffoldIntegrationOptions {
 declare class BookConfigError extends Error {
     constructor(message: string);
 }
-/**
- * Resolve preset from explicit args → env → .env → default. Throws on invalid.
- *
- * v3.4.0 (closes #9): canonical resolver. Accepts both `preset` and `profile`
- * (back-compat) explicit args; reads both `BOOK_PRESET` (preferred) and
- * `BOOK_PROFILE` (alias) env vars; same for .env file lookups.
- *
- * Resolution order:
- *   1. explicitPreset (from defineBookConfig({ preset: ... }))
- *   2. explicitProfile (from defineBookConfig({ profile: ... }))
- *   3. process.env.BOOK_PRESET
- *   4. process.env.BOOK_PROFILE
- *   5. .env BOOK_PRESET
- *   6. .env BOOK_PROFILE
- *   7. 'minimal' (with console.warn)
- */
 declare function resolvePreset(explicitPreset?: BookPreset, explicitProfile?: BookProfile): BookPreset;
 /**
  * Backward-compat alias. New code should use `resolvePreset()`.
@@ -855,4 +887,4 @@ declare function resolvePreset(explicitPreset?: BookPreset, explicitProfile?: Bo
  */
 declare function resolveProfile(explicit?: BookProfile): BookProfile;
 
-export { BOOK_PRESETS as B, type ChapterFor as C, type FreshnessAffordance as F, type PartKey as P, type ReleaseStatusConfig as R, type StatusBadge as S, type VolatilityBadge as V, BOOK_PROFILES as a, BookConfigError as b, type BookConfigOptions as c, type BookPreset as d, type BookProfile as e, type BookScaffoldIntegrationOptions as f, type BookSchemasOptions as g, type ChaptersRenderer as h, type FrontmatterRouteConfig as i, type PartialRouteToggles as j, type ProfileDefinition as k, type RouteToggles as l, type Style as m, type StyleInput as n, composeStyles as o, defineProfile as p, defineStyle as q, normalizeFrontmatterConfig as r, resolvePreset as s, resolveProfile as t };
+export { BOOK_PRESETS as B, type ChapterFor as C, type FreshnessAffordance as F, NUMBER_STYLES as N, type PartKey as P, type ReleaseStatusConfig as R, type SecurityHeadersConfig as S, type VolatilityBadge as V, BOOK_PROFILES as a, BookConfigError as b, type BookConfigOptions as c, type BookPreset as d, type BookProfile as e, type BookScaffoldIntegrationOptions as f, type BookSchemasOptions as g, type ChaptersRenderer as h, type FrontmatterRouteConfig as i, type NumberStyle as j, type PartialRouteToggles as k, type ProfileDefinition as l, type RouteToggles as m, type StatusBadge as n, type Style as o, type StyleInput as p, composeStyles as q, defineProfile as r, defineStyle as s, normalizeFrontmatterConfig as t, resolvePreset as u, resolveProfile as v };

package/layouts/Base.astro

@@ -15,15 +15,15 @@
  *   lang        — html lang attribute (default: en)
  *   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)
+ *                 Below 80rem (1280px) the sidebar is auto-hidden via CSS and
+ *                 the mobile nav drawer is the chapter nav (v4.26.0, #80).
+ *   showChrome  — render the automatic tools chrome (ToolFilter)
  *                 (default: true). Set false on a landing/hub page with no
- *                 chapters/tools/versions; search + theme toggle always render.
+ *                 chapter filtering; search + theme toggle always render.
  *
- * Tools chrome (ToolFilter, VersionSelector): only mounted when
- * 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).
+ * Tools chrome (ToolFilter): only mounted when BOOK_PROFILE !== 'academic' AND
+ * showChrome !== false. VersionSelector is a prop-driven public component that
+ * consumers mount explicitly once they have real deployed-version data.
  *
  * Usage:
  *   ---
@@ -51,12 +51,11 @@ import '../styles/chapter.css';
 import '../styles/tool-filter.css';
 import '../styles/convergence.css';
 import '../styles/print.css';
-// Use package-path imports for the .tsx islands so Vite resolves them
+// Use the package-path import for the .tsx island so Vite resolves it
 // via the exports map (→ pre-compiled dist/components/*.mjs with proper
 // preact JSX). The raw .tsx files are also shipped so consumers can
 // import them directly, but relative imports from inside the package
 // must route through the exports map, not the raw source.
-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.26.2 (#149; style inheritance fixed in v4.26.3): site-wide
@@ -68,6 +67,7 @@ import NavContent from '../components/NavContent.astro';
 // description fallback, ogImage default, twitterHandle) from the
 // book-config virtual module (was landing-config in v4.5.1).
 import bookConfig from 'virtual:book-scaffold/book-config';
+import { normalizeBase } from '../src/lib/nav-href';
 
 const profile = import.meta.env.BOOK_PROFILE ?? 'minimal';
 
@@ -76,10 +76,10 @@ interface Props {
   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.) */
+  /** #163: render the optional automatic tools chrome — the ToolFilter island
+   *  (default true). Set false on landing/hub pages with no chapter filtering;
+   *  the search + theme-toggle cluster always renders. (No-op for the academic
+   *  profile, which never shows the ToolFilter.) */
   showChrome?: boolean;
   /** v4.6.0: Open Graph image URL (relative to site root, or absolute). */
   ogImage?: string;
@@ -97,9 +97,9 @@ const {
   ogType = 'website',
 } = Astro.props;
 
-// Tools chrome (ToolFilter + VersionSelector) renders only for non-academic
+// Automatic tools chrome (ToolFilter) 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
+// landing/hub page (no chapter filtering) 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;
@@ -120,7 +120,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 = normalizeBase(import.meta.env.BASE_URL);
 ---
 
 <!doctype html>
@@ -196,7 +196,6 @@ const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/*$/, '/');
         </a>
       )}
       {showToolsChrome && <ToolFilter client:idle />}
-      {showToolsChrome && <VersionSelector client:idle />}
       <a
         href={`${baseUrl}search/`}
         class="chrome-button"
@@ -217,7 +216,8 @@ const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/*$/, '/');
       </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
+        CSS-hidden ≥80rem where the Sidebar is the nav (layout.css and the
+        controller's desktop auto-close agree on 80rem). 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>
@@ -390,7 +390,8 @@ const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/*$/, '/');
     text-decoration: none;
   }
 
-  /* Version selector dropdown */
+  /* Opt-in VersionSelector dropdown. Base provides its visual language but
+   * deliberately does not mount it without a consumer-owned version manifest. */
   .version-selector {
     position: relative;
     display: inline-block;

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.26.3",
+  "description": "Astro 6 + MDX toolkit for long-form technical books with five typed presets, Tufte typography, citations, search, PDF, and Cloudflare deployment.",
+  "version": "4.27.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -161,9 +161,11 @@
     "pedagogy",
     "examples",
     "CLAUDE.md",
+    "AGENTS.md",
     "README.md",
-    "LATEX_TO_MDX_MAPPING.md",
-    "examples"
+    "LICENSE",
+    "LICENSE-CONTENT",
+    "LATEX_TO_MDX_MAPPING.md"
   ],
   "scripts": {
     "build": "tsup",
@@ -195,6 +197,7 @@
     "@fontsource-variable/roboto": "^5.2.10",
     "@fontsource-variable/source-code-pro": "^5.2.7",
     "pagefind": "^1.5.2",
+    "vite": "^7.3.2",
     "yaml": "^2.9.0"
   },
   "devDependencies": {

package/pages/answers.astro

@@ -26,6 +26,7 @@ import { render } from 'astro:content';
 import bookConfig from 'virtual:book-scaffold/book-config';
 import { getAllQuestions, groupByChapter } from '../src/lib/questions';
 import { assertKnownDomain } from '../src/lib/exam-domains';
+import { normalizeBase } from '../src/lib/nav-href';
 
 // Presence-gate: only touch the collection when the directory holds files.
 const questionModules = import.meta.glob('/src/content/questions/**/*.{md,mdx}', {
@@ -51,7 +52,7 @@ 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 baseUrl = normalizeBase(import.meta.env.BASE_URL);
 const practiceHref = (bookConfig.enabledRoutes ?? []).includes('practiceExam')
   ? `${baseUrl}practice-exam`
   : null;

package/pages/chapters.astro

@@ -26,9 +26,10 @@ import { getAllChapters, type Chapter } from '../src/lib/chapters';
 import { PROFILES } from '../src/profiles/index';
 import { fallbackChaptersRenderer } from '../src/profiles/renderers/fallback-chapters';
 import type { ChaptersRenderer, PartKey } from '../src/lib/chapters-renderer';
+import { normalizeBase } from '../src/lib/nav-href';
 
 // #142: prefix BASE_URL so chapter-card links stay inside a non-root deploy base.
-const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
+const baseUrl = normalizeBase(import.meta.env.BASE_URL);
 
 const profileName = (import.meta.env.BOOK_PROFILE ?? 'minimal') as keyof typeof PROFILES;
 const profileDef = PROFILES[profileName];

package/pages/exercises.astro

@@ -10,6 +10,7 @@
  * page (doesn't fail the build).
  */
 import Base from '../layouts/Base.astro';
+import { normalizeBase } from '../src/lib/nav-href';
 
 // v4.4.0 fix: use Vite's import.meta.glob with a project-root-relative
 // path (same lesson as tips.astro). `/src/data/...` is consumer-project-
@@ -28,7 +29,7 @@ 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(/\/?$/, '/');
+const baseUrl = normalizeBase(import.meta.env.BASE_URL);
 ---
 <Base title="Exercises" description="All exercises in this book, grouped by chapter with deep links.">
   <article class="prose">

package/pages/index.astro

@@ -34,15 +34,16 @@
  */
 import Base from '../layouts/Base.astro';
 import bookConfig from 'virtual:book-scaffold/book-config';
+import { normalizeBase } from '../src/lib/nav-href';
 
 const title = bookConfig.title ?? 'book-scaffold-astro';
 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(/\/?$/, '/');
+// Astro accepts bases with or without a trailing slash. Route every value
+// through the shared helper before composing links (#142, #182).
+const baseUrl = normalizeBase(import.meta.env.BASE_URL);
 
 // Map from internal route name → display label + URL. Only routes that
 // produce a single landing-list entry are listed here (frontmatter is a