@brandon_m_behring/book-scaffold-astro 3.7.0 → 4.0.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { AstroUserConfig, AstroIntegration } from 'astro';
-import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, H as volatilityLevels, h as ChaptersRenderer } from './types-C5CamFM0.js';
-export { A as AcademicChapter, B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookPreset, e as BookProfile, g as BookSchemasOptions, C as ChapterFor, i as CourseNotesChapter, F as FreshnessAffordance, M as MinimalChapter, P as PartKey, j as ProfileDefinition, R as ResearchPortfolioChapter, k as RouteToggles, S as StatusBadge, T as ToolsChapter, V as VolatilityBadge, l as academicChapterSchema, m as academicParts, n as changeKinds, o as changelogSchema, p as chapterStatus, q as courseNotesChapterSchema, r as defineProfile, s as minimalChapterSchema, t as patternCategories, u as patternsSchema, v as researchPortfolioChapterSchema, w as resolvePreset, x as resolveProfile, y as sourceTiers, z as sourceTiersResearch, D as sourcesSchema, E as toolSlugs, G as toolsChapterSchema } from './types-C5CamFM0.js';
+import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, Q as volatilityLevels, h as ChaptersRenderer, n as Style } from './types-DR0-GwxO.js';
+export { A as AcademicChapter, B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookPreset, e as BookProfile, g as BookSchemasOptions, C as ChapterFor, i as CourseNotesChapter, F as FreshnessAffordance, j as FrontmatterRouteConfig, M as MinimalChapter, P as PartKey, k as PartialRouteToggles, l as ProfileDefinition, R as ResearchPortfolioChapter, m as RouteToggles, S as StatusBadge, o as StyleInput, T as ToolsChapter, V as VolatilityBadge, p as academicChapterSchema, q as academicParts, r as changeKinds, s as changelogSchema, t as chapterStatus, u as composeStyles, v as courseNotesChapterSchema, w as defineProfile, x as defineStyle, y as minimalChapterSchema, z as normalizeFrontmatterConfig, D as patternCategories, E as patternsSchema, G as researchPortfolioChapterSchema, H as resolvePreset, I as resolveProfile, J as sourceTiers, K as sourceTiersResearch, L as sourcesSchema, N as toolSlugs, O as toolsChapterSchema } from './types-DR0-GwxO.js';
 import 'astro/zod';
 
 declare function defineBookConfig(opts: BookConfigOptions): Promise<AstroUserConfig>;
@@ -143,4 +143,56 @@ declare const academicChaptersRenderer: ChaptersRenderer;
 
 declare const fallbackChaptersRenderer: ChaptersRenderer;
 
-export { BookConfigOptions, BookScaffoldIntegrationOptions, ChaptersRenderer, type Freshness, type FreshnessStatus, type VolatilityLevel, academicChaptersRenderer, bookScaffoldIntegration, chapterSortKey, defineBookConfig, defineMdxComponents, fallbackChaptersRenderer, freshnessLabel, getFreshness, toolsChaptersRenderer, volatilityLevels };
+/**
+ * src/styles/built-in.ts — toolkit-shipped Styles, one per BookPreset (v4.0.0).
+ *
+ * Each profile that the toolkit shipped in v3 (academic, tools, minimal,
+ * course-notes, research-portfolio) is now mirrored by a built-in Style
+ * importable by consumers:
+ *
+ *   import { defineBookConfig, academicStyle } from '@brandon_m_behring/book-scaffold-astro';
+ *   export default await defineBookConfig({ styles: [academicStyle], site: '...' });
+ *
+ * Consumers can compose built-in styles with their own:
+ *
+ *   import { researchPortfolioStyle, defineStyle } from '@brandon_m_behring/book-scaffold-astro';
+ *   const guidesFamilyStyle = defineStyle({ site: 'https://guides.brandon-behring.dev/' });
+ *   export default await defineBookConfig({
+ *     styles: [researchPortfolioStyle, guidesFamilyStyle],
+ *     // ...
+ *   });
+ *
+ * The v3 `preset: '...'` shorthand is replaced by this explicit style chain.
+ * See MIGRATION-v3-to-v4.md.
+ */
+
+/** Academic preset — weekly curriculum, 7-state status, KaTeX wired, BibTeX pipeline. */
+declare const academicStyle: Style;
+/** Tools preset — AI-CLI comparison content with volatility + sources. */
+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. */
+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). */
+declare const researchPortfolioStyle: Style;
+/**
+ * Registry of all toolkit-shipped styles, keyed by their preset name.
+ *
+ * `satisfies` (TS 4.9+) keeps the inferred narrow type while validating the
+ * shape: `BUILTIN_STYLES['academic']` resolves to `typeof academicStyle`,
+ * not to generic `Style`. Used by the v3 → v4 migration error path
+ * (config.ts) to construct auto-suggested replacements.
+ */
+declare const BUILTIN_STYLES: {
+    readonly academic: Style;
+    readonly tools: Style;
+    readonly minimal: Style;
+    readonly 'course-notes': Style;
+    readonly 'research-portfolio': Style;
+};
+
+export { BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, ChaptersRenderer, type Freshness, type FreshnessStatus, Style, type VolatilityLevel, academicChaptersRenderer, academicStyle, bookScaffoldIntegration, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, fallbackChaptersRenderer, freshnessLabel, getFreshness, minimalStyle, researchPortfolioStyle, toolsChaptersRenderer, toolsStyle, volatilityLevels };

package/dist/index.mjs

@@ -685,6 +685,72 @@ function resolveProfile(explicit) {
 // src/integration.ts
 import { fileURLToPath } from "url";
 
+// src/lib/define-style.ts
+function defineStyle(opts) {
+  return { __styleVersion: 1, ...opts };
+}
+function composeStyles(styles) {
+  if (styles.length === 0) {
+    return defineStyle({});
+  }
+  const merged = {};
+  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.site !== void 0) merged.site = style.site;
+    if (style.deploy !== void 0) merged.deploy = style.deploy;
+    if (style.mdxComponentsModule !== void 0) {
+      merged.mdxComponentsModule = style.mdxComponentsModule;
+    }
+    if (style.routes !== void 0) {
+      merged.routes = {
+        ...merged.routes ?? {},
+        ...style.routes
+      };
+    }
+    if (style.katexMacros !== void 0) {
+      merged.katexMacros = {
+        ...merged.katexMacros ?? {},
+        ...style.katexMacros
+      };
+    }
+    if (style.extra !== void 0) {
+      merged.extra = {
+        ...merged.extra ?? {},
+        ...style.extra
+      };
+    }
+    if (style.extraStyles !== void 0) {
+      const prev = merged.extraStyles ?? [];
+      merged.extraStyles = [...prev, ...style.extraStyles];
+    }
+    if (style.extraIntegrations !== void 0) {
+      const prev = merged.extraIntegrations ?? [];
+      merged.extraIntegrations = [...prev, ...style.extraIntegrations];
+    }
+    if (style.markdown !== void 0) {
+      const prev = merged.markdown ?? void 0;
+      merged.markdown = mergeMarkdown(prev, style.markdown);
+    }
+  }
+  return defineStyle(merged);
+}
+function mergeMarkdown(a, b) {
+  if (!a) return b;
+  if (!b) return a;
+  return {
+    ...a,
+    ...b,
+    remarkPlugins: [...a.remarkPlugins ?? [], ...b.remarkPlugins ?? []],
+    rehypePlugins: [...a.rehypePlugins ?? [], ...b.rehypePlugins ?? []]
+  };
+}
+function normalizeFrontmatterConfig(v) {
+  if (v === void 0) return void 0;
+  if (typeof v === "boolean") return { enabled: v };
+  return v;
+}
+
 // src/mdx-components-resolver.ts
 import { existsSync as existsSync2 } from "fs";
 import { resolve } from "path";
@@ -738,15 +804,32 @@ var ROUTE_REGISTRY = {
   // v3.4.0 (#7): consumer-collection-backed frontmatter route. Opt-in via
   // routes: { frontmatter: true } AND content.config.ts defining the
   // collection (use frontmatterCollection() helper from /schemas subpath).
+  // v4.0.0 (#49): widened to object form `{ enabled, prefix? }`; pattern
+  // computed from `prefix` (default 'frontmatter' → '/frontmatter/[slug]';
+  // empty string → '/[slug]'; arbitrary string → '/<prefix>/[slug]').
   frontmatter: { pattern: "/frontmatter/[slug]", file: "frontmatter/[...slug].astro" }
 };
+function frontmatterPatternFromPrefix(prefix) {
+  if (prefix === void 0) return ROUTE_REGISTRY.frontmatter.pattern;
+  if (prefix === "") return "/[slug]";
+  return `/${prefix}/[slug]`;
+}
 function resolvePage(file) {
   return fileURLToPath(new URL(`../pages/${file}`, import.meta.url));
 }
 function bookScaffoldIntegration(opts) {
   const { profile, routes: userOverrides = {}, extraStyles = [], mdxComponentsModule } = opts;
   const def = PROFILES[profile];
-  const enabledRoutes = { ...def.routes, ...userOverrides };
+  const fmNormalized = normalizeFrontmatterConfig(userOverrides.frontmatter);
+  const fmEnabled = fmNormalized?.enabled ?? def.routes.frontmatter;
+  const fmPrefix = fmNormalized && "prefix" in fmNormalized ? fmNormalized.prefix : void 0;
+  const enabledRoutes = {
+    ...def.routes,
+    ...Object.fromEntries(
+      Object.entries(userOverrides).filter(([k]) => k !== "frontmatter")
+    ),
+    frontmatter: fmEnabled
+  };
   return {
     name: "book-scaffold-astro",
     hooks: {
@@ -762,8 +845,9 @@ function bookScaffoldIntegration(opts) {
           if (!on) continue;
           const route = ROUTE_REGISTRY[name];
           if (!route) continue;
+          const pattern = name === "frontmatter" ? frontmatterPatternFromPrefix(fmPrefix) : route.pattern;
           injectRoute({
-            pattern: route.pattern,
+            pattern,
             entrypoint: resolvePage(route.file)
           });
         }
@@ -785,11 +869,66 @@ function bookScaffoldIntegration(opts) {
 }
 
 // src/config.ts
+function v3MigrationError(opts) {
+  const v3Value = opts.preset ?? opts.profile;
+  const v3FieldUsed = "preset" in opts ? "preset" : "profile";
+  const styleExportName = v3Value && BOOK_PRESETS.includes(v3Value) ? `${v3Value === "research-portfolio" ? "researchPortfolio" : v3Value === "course-notes" ? "courseNotes" : v3Value}Style` : null;
+  const knownReplacement = styleExportName ? `
+Replace this:
+  defineBookConfig({ ${v3FieldUsed}: ${JSON.stringify(v3Value)}, ... })
+
+With this:
+  import { defineBookConfig, ${styleExportName} } from '@brandon_m_behring/book-scaffold-astro';
+  defineBookConfig({ styles: [${styleExportName}], ... })
+` : `
+Replace the \`${v3FieldUsed}: <value>\` field with a \`styles: [<...Style>]\` array.
+The v4 toolkit exports built-in styles for each preset: academicStyle, toolsStyle,
+minimalStyle, courseNotesStyle, researchPortfolioStyle.
+`;
+  return new BookConfigError(
+    `book-scaffold-astro v4.0.0 removed the \`${v3FieldUsed}\` field on defineBookConfig.
+${knownReplacement}
+See https://github.com/brandon-behring/book-scaffold-astro/blob/main/package/MIGRATION-v3-to-v4.md
+for the full migration guide. If you hit friction migrating, please file an issue at
+https://github.com/brandon-behring/book-scaffold-astro/issues \u2014 v4 is fresh and the API
+will evolve based on real friction reports.`
+  );
+}
 async function defineBookConfig(opts) {
-  const profile = resolvePreset(opts.preset, opts.profile);
+  if ("preset" in opts || "profile" in opts) {
+    throw v3MigrationError(opts);
+  }
+  const composed = composeStyles(opts.styles ?? []);
+  const profile = opts.styles === void 0 && composed.preset === void 0 ? "minimal" : composed.preset ?? "minimal";
+  const site = opts.site ?? composed.site;
+  if (!site) {
+    throw new BookConfigError(
+      "book-scaffold-astro v4.0.0: `site` is required. Provide it via the top-level `site` field in defineBookConfig OR via a Style in the `styles` array."
+    );
+  }
+  const mergedRoutes = {
+    ...composed.routes ?? {},
+    ...opts.routes ?? {}
+  };
+  const consumerKatexMacros = {
+    ...composed.katexMacros ?? {},
+    ...opts.katexMacros ?? {}
+  };
+  const mergedExtraStyles = [
+    ...composed.extraStyles ?? [],
+    ...opts.extraStyles ?? []
+  ];
+  const mergedExtraIntegrations = [
+    ...composed.extraIntegrations ?? [],
+    ...opts.extraIntegrations ?? []
+  ];
+  const mdxComponentsModule = opts.mdxComponentsModule ?? composed.mdxComponentsModule;
+  const composedMarkdown = composed.markdown ?? {};
+  const userMarkdown = opts.markdown ?? {};
+  const wantsKatex = PROFILES[profile]?.katex === true;
   const remarkPlugins = [];
   const rehypePlugins = [];
-  if (profile === "academic") {
+  if (wantsKatex) {
     const { default: remarkMath } = await import(
       /* @vite-ignore */
       "remark-math"
@@ -799,14 +938,11 @@ async function defineBookConfig(opts) {
       "rehype-katex"
     );
     const { ssmMacros: ssmMacros2 } = await Promise.resolve().then(() => (init_katex_macros(), katex_macros_exports));
-    const macros = { ...ssmMacros2, ...opts.katexMacros ?? {} };
+    const macros = { ...ssmMacros2, ...consumerKatexMacros };
     remarkPlugins.push(remarkMath);
     rehypePlugins.push([
       rehypeKatex,
       {
-        // Strict mode: build fails on undefined macros, malformed expressions,
-        // unsupported AMS environments. Trades developer pain at write-time
-        // for catching errors before deploy.
         strict: "error",
         trust: true,
         macros
@@ -818,52 +954,57 @@ async function defineBookConfig(opts) {
     preact(),
     bookScaffoldIntegration({
       profile,
-      routes: opts.routes,
-      // v3.3.0 — per-route override (issue #3)
-      mdxComponentsModule: opts.mdxComponentsModule,
-      // v3.3.0 — explicit mdx-components path (issue #2)
-      extraStyles: opts.extraStyles
+      routes: mergedRoutes,
+      mdxComponentsModule,
+      extraStyles: mergedExtraStyles
     }),
-    ...opts.extraIntegrations ?? []
+    ...mergedExtraIntegrations
+  ];
+  const finalRemark = [
+    ...remarkPlugins,
+    ...composedMarkdown.remarkPlugins ?? [],
+    ...userMarkdown.remarkPlugins ?? []
+  ];
+  const finalRehype = [
+    ...rehypePlugins,
+    ...composedMarkdown.rehypePlugins ?? [],
+    ...userMarkdown.rehypePlugins ?? []
   ];
-  const userMarkdown = opts.markdown ?? {};
   const markdown = {
     shikiConfig: {
-      // css-variables mode lets code blocks switch dark/light theme without
-      // rebuilding. Tokens map to --astro-code-* CSS vars in tokens.css.
       theme: "css-variables",
       wrap: false,
-      ...userMarkdown.shikiConfig ?? {}
+      ...userMarkdown.shikiConfig ?? composedMarkdown.shikiConfig ?? {}
     },
-    remarkPlugins: [...remarkPlugins, ...userMarkdown.remarkPlugins ?? []],
-    rehypePlugins: [...rehypePlugins, ...userMarkdown.rehypePlugins ?? []],
-    ...userMarkdown
+    ...composedMarkdown,
+    ...userMarkdown,
+    remarkPlugins: finalRemark,
+    rehypePlugins: finalRehype
   };
   const {
-    preset: _preset,
-    // v3.4.0
-    profile: _profile,
+    styles: _styles,
+    site: _site,
     routes: _routes,
-    // v3.3.0
+    deploy: _deploy,
     mdxComponentsModule: _mdxComponentsModule,
-    // v3.3.0
     extraIntegrations: _extraIntegrations,
     extraStyles: _extraStyles,
     markdown: _markdown,
     katexMacros: _katexMacros,
-    // v3.6.0 (closes #22)
     ...rest
   } = opts;
-  void _preset;
-  void _profile;
+  void _styles;
+  void _site;
   void _routes;
+  void _deploy;
   void _mdxComponentsModule;
   void _extraIntegrations;
   void _extraStyles;
   void _markdown;
   void _katexMacros;
-  const katexExternals = profile === "academic" ? [] : ["remark-math", "rehype-katex", "katex"];
+  const katexExternals = wantsKatex ? [] : ["remark-math", "rehype-katex", "katex"];
   const config = {
+    site,
     ...rest,
     integrations,
     markdown,
@@ -894,29 +1035,72 @@ function chapterSortKey(data) {
   const within = typeof data.chapter === "number" ? data.chapter : typeof data.week === "number" ? data.week : 0;
   return partOrdinal * 1e3 + within;
 }
+
+// src/styles/built-in.ts
+var academicStyle = defineStyle({
+  name: "academic",
+  preset: "academic",
+  deploy: "workers"
+});
+var toolsStyle = defineStyle({
+  name: "tools",
+  preset: "tools",
+  deploy: "workers"
+});
+var minimalStyle = defineStyle({
+  name: "minimal",
+  preset: "minimal",
+  deploy: "workers"
+});
+var courseNotesStyle = defineStyle({
+  name: "course-notes",
+  preset: "course-notes",
+  deploy: "pages"
+});
+var researchPortfolioStyle = defineStyle({
+  name: "research-portfolio",
+  preset: "research-portfolio",
+  deploy: "pages",
+  routes: { frontmatter: { enabled: true, prefix: "frontmatter" } }
+});
+var BUILTIN_STYLES = {
+  academic: academicStyle,
+  tools: toolsStyle,
+  minimal: minimalStyle,
+  "course-notes": courseNotesStyle,
+  "research-portfolio": researchPortfolioStyle
+};
 export {
   BOOK_PRESETS,
   BOOK_PROFILES,
+  BUILTIN_STYLES,
   BookConfigError,
   academicChapterSchema,
   academicChaptersRenderer,
   academicParts,
+  academicStyle,
   bookScaffoldIntegration,
   changeKinds,
   changelogSchema,
   chapterSortKey,
   chapterStatus,
+  composeStyles,
   courseNotesChapterSchema,
+  courseNotesStyle,
   defineBookConfig,
   defineMdxComponents,
   defineProfile,
+  defineStyle,
   fallbackChaptersRenderer,
   freshnessLabel,
   getFreshness,
   minimalChapterSchema,
+  minimalStyle,
+  normalizeFrontmatterConfig,
   patternCategories,
   patternsSchema,
   researchPortfolioChapterSchema,
+  researchPortfolioStyle,
   resolvePreset,
   resolveProfile,
   sourceTiers,
@@ -925,5 +1109,6 @@ export {
   toolSlugs,
   toolsChapterSchema,
   toolsChaptersRenderer,
+  toolsStyle,
   volatilityLevels
 };

package/dist/schemas.d.ts

@@ -1,5 +1,5 @@
 import { defineCollection } from 'astro:content';
-import { g as BookSchemasOptions } from './types-C5CamFM0.js';
+import { g as BookSchemasOptions } from './types-DR0-GwxO.js';
 import 'astro';
 import 'astro/zod';
 

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

package/recipes/15-defining-styles.md

@@ -0,0 +1,215 @@
+# Recipe 15 — Defining and composing Styles (v4.0.0+)
+
+A **Style** is a typed, named, importable config bundle. Define a style once; import it into many books; override per-book explicitly.
+
+This recipe replaces the v3 `preset: 'X'` shorthand with explicit composition. See `MIGRATION-v3-to-v4.md` for the migration steps.
+
+---
+
+## TL;DR
+
+```ts
+// shared/styles/research-guide.ts
+import { defineStyle, researchPortfolioStyle } from '@brandon_m_behring/book-scaffold-astro';
+
+export const researchGuideStyle = defineStyle({
+  name: 'research-guide',
+  site: 'https://guides.brandon-behring.dev/',
+  routes: { frontmatter: { enabled: true, prefix: '' } },
+  // Composes naturally: styles: [researchPortfolioStyle, researchGuideStyle]
+});
+
+// guides/foo/astro.config.mjs
+import { defineBookConfig, researchPortfolioStyle } from '@brandon_m_behring/book-scaffold-astro';
+import { researchGuideStyle } from '../shared/styles/research-guide.js';
+
+export default await defineBookConfig({
+  styles: [researchPortfolioStyle, researchGuideStyle],
+  // any per-book overrides here
+});
+```
+
+---
+
+## What is a Style
+
+A Style is an object containing config values, branded for type safety. The full type is documented in JSDoc on `defineStyle()`. All fields are optional:
+
+```ts
+defineStyle({
+  name?: string;                     // for debug/error messages; optional
+  preset?: 'academic' | 'tools' | ...; // determines schema + default routes + styles
+  site?: string;
+  routes?: PartialRouteToggles;      // per-route override (frontmatter widened to object form)
+  katexMacros?: Record<string, string>;
+  extraStyles?: readonly string[];
+  extraIntegrations?: readonly AstroIntegration[];
+  mdxComponentsModule?: string;
+  markdown?: AstroUserConfig['markdown'];
+  deploy?: 'pages' | 'workers';      // v4.0.0 NEW (#50)
+  extra?: Record<string, unknown>;   // scoped consumer-side metadata
+});
+```
+
+---
+
+## Pattern A: workspace-local style
+
+Use when you have many books in a workspace + a style cluster you don't yet need to publish externally.
+
+**File**: `shared/styles/research-guide.ts` (or any path in your workspace)
+
+**Import**: relative path from each consuming book.
+
+```ts
+import { researchGuideStyle } from '../../shared/styles/research-guide.js';
+```
+
+**Versioning**: git. The style is just code in your repo; edit it and rebuild downstream books.
+
+**Pros**: zero ceremony, co-located with the books that use it, no npm publish.
+
+**Cons**: doesn't help OTHER consumers (outside your workspace) reuse the style.
+
+---
+
+## Pattern B: separate npm package
+
+Use when a style stabilizes + has interest beyond your workspace.
+
+**Package**: e.g., `@brandon_m_behring/style-research-guides` (any name).
+
+**Publish**: standard `npm publish`. Versioning via semver; consumers pin to `^1.0.0`.
+
+**Import**: package name in each consuming book.
+
+```ts
+import { researchGuideStyle } from '@brandon_m_behring/style-research-guides';
+```
+
+**Pros**: cleanest cross-consumer sharing; semver versioning out-of-the-box.
+
+**Cons**: heavyweight for a workspace-internal style; publishing overhead per release.
+
+**Promotion path**: start every style as workspace-local (Pattern A). When a style stabilizes + an external consumer asks for it, promote to npm — only the import path changes; the Style object itself is unchanged.
+
+---
+
+## Composition: `styles: [...]` array
+
+Multiple styles compose left-to-right. Later styles override earlier ones for conflicts.
+
+```ts
+defineBookConfig({
+  styles: [baseStyle, brandStyle, projectStyle],
+  // top-level fields here override anything from the styles
+});
+```
+
+**Precedence (highest last)**:
+1. Built-in style's defaults (e.g., `academicStyle.routes`)
+2. `styles[0]`
+3. `styles[1]`
+4. ...
+5. `styles[N]`
+6. Top-level `defineBookConfig` fields
+
+---
+
+## Per-key merge strategy
+
+Different fields have different merge semantics. Documented:
+
+| Field | Strategy |
+|---|---|
+| `name`, `preset`, `site`, `deploy`, `mdxComponentsModule` | Shallow override (last wins) |
+| `routes` | Per-route spread (each route key independently overridable) |
+| `routes.frontmatter` | Per-route spread; later value (boolean OR object) wholly replaces earlier |
+| `katexMacros` | Object spread (per-macro override) |
+| `extra` | Object spread (per-key consumer-metadata override) |
+| `extraStyles` | Array concat (additive — no dedup) |
+| `extraIntegrations` | Array concat (additive) |
+| `markdown.remarkPlugins` | Array concat (additive) |
+| `markdown.rehypePlugins` | Array concat (additive) |
+
+**Why arrays concat (not dedupe)**: matches Tailwind plugin arrays + ESLint flat config rules — one mental model: "arrays concat, non-arrays last-wins." If you compose styles that both list the same CSS file, you get it twice (browser dedups at parse time; benign in practice). If real consumer pain surfaces, we'll add a `dedupe: true` opt-in.
+
+---
+
+## Built-in styles
+
+The toolkit ships one style per preset. Import individually or via the registry:
+
+```ts
+import {
+  academicStyle,
+  toolsStyle,
+  minimalStyle,
+  courseNotesStyle,
+  researchPortfolioStyle,
+  BUILTIN_STYLES,
+} from '@brandon_m_behring/book-scaffold-astro';
+
+// Direct import:
+defineBookConfig({ styles: [researchPortfolioStyle], ... });
+
+// Or via registry (useful for dynamic dispatch):
+defineBookConfig({ styles: [BUILTIN_STYLES['research-portfolio']], ... });
+```
+
+Each built-in style has a `name` matching its preset, a `preset` field, and sane `deploy` defaults (academic/tools/minimal → 'workers'; course-notes/research-portfolio → 'pages').
+
+---
+
+## Escape hatch: consumer-side metadata via `extra`
+
+Fields the toolkit knows about must be typed. For workflow-specific metadata that should travel with the style but isn't toolkit config, use the scoped `extra` field:
+
+```ts
+defineStyle({
+  name: 'guides-v0.2',
+  preset: 'research-portfolio',
+  extra: {
+    pedagogyTier: 'experimental',
+    team: 'engineering',
+    docsVersion: '0.2',
+  },
+});
+```
+
+- `extra` survives composition as per-key spread (later entries override earlier per key).
+- The toolkit ignores `extra` entirely — it's for YOUR tooling (style linters, CI scripts, custom Astro integrations that read `style.extra.X`, etc.).
+- This pattern preserves typo protection on known fields: `defineStyle({ presset: 'academic' })` errors at compile time because `presset` isn't `preset` and isn't `extra`.
+
+---
+
+## Forward compatibility (`__styleVersion`)
+
+Every Style carries a `__styleVersion: 1` marker (set automatically by `defineStyle()`). Future API-shape changes can detect old Style objects and apply version-appropriate handling.
+
+**You don't set it.** It's auto-applied. Don't read it in consumer code.
+
+When v5 ships (whenever that is), `__styleVersion: 1` styles continue to work via internal adaptation. New Style features in v5+ may bump this marker.
+
+---
+
+## Feedback loop
+
+v4 is fresh. The `defineStyle` API will evolve based on real friction reports.
+
+**If you hit a wall** — composition pattern that doesn't compose, merge semantic that surprises you, type that won't infer, missing field — **file an issue at https://github.com/brandon-behring/book-scaffold-astro/issues** with:
+
+- The `consumer:<your-workspace>` label (so we can batch reports from the same consumer)
+- A minimal reproduction showing what you were trying to express
+- What got in the way
+
+The v4.x release line is explicitly the iteration window for this API. Use it.
+
+---
+
+## See also
+
+- `MIGRATION-v3-to-v4.md` — step-by-step migration from v3 `preset:` shorthand
+- `PACKAGE_DESIGN.md §4` — `defineBookConfig` API reference
+- `PACKAGE_DESIGN.md §4a` — `defineStyle` API reference
+- `recipes/12-where-to-file-issues.md` — the broader consumer-driven evolution loop this fits into

package/scripts/build-bib.mjs

@@ -83,7 +83,22 @@ async function main() {
     }
     throw err;
   }
-  const cite = new Cite(bibText);
+  // v4.0.0 (closes #54): strip `%`-comment lines before passing to citation-js.
+  // The plugin-bibtex lexer doesn't honor BibTeX's %-line-comment semantics —
+  // any `@TYPE` token inside a commented block is consumed as an entry start,
+  // then fails at the first real entry below. This caused 4 hotfix releases
+  // in v3.6.1→v3.6.4 chasing the same parse quirk; the pre-pass eliminates the
+  // entire class of bug.
+  //
+  // BibTeX's real comment grammar is "% at the start of a line (after optional
+  // whitespace) to end of line". Mid-line `%` (e.g., `note = {50% confidence}`)
+  // is NOT a comment and is preserved.
+  const sanitizedBib = bibText
+    .split(/\r?\n/)
+    .map((line) => (line.trimStart().startsWith('%') ? '' : line))
+    .join('\n');
+
+  const cite = new Cite(sanitizedBib);
   const data = cite.data;
 
   // Detect duplicates the way biber would (citation-js silently

package/scripts/validate.mjs

@@ -26,9 +26,9 @@
  * Exit code = total failure count (0 = pass, >=1 = errors).
  */
 import { readFile, access } from 'node:fs/promises';
-import { glob } from 'node:fs/promises';
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve, dirname, join } from 'node:path';
+import { walkMdx } from './walk-mdx.mjs';
 
 /**
  * Best-effort .env reader. Mirrors `readEnvFile` in src/types.ts; kept inline
@@ -134,8 +134,13 @@ const refs = await loadJson(join(DATA_DIR, 'references.json'));
 const labels = await loadJson(join(DATA_DIR, 'labels.json'));
 
 // ===== Collect chapter files =====
+// v3.7.1 (closes #52): walkMdx (in ./walk-mdx.mjs) is a recursive readdir
+// walker that replaces the previous `glob` import from `node:fs/promises`.
+// The `glob` API was added in Node 22 but consumer CI templates ship
+// Node 20 — `npm run validate` crashed on every consumer's prebuild hook.
+// Walker uses readdir + path only; works on Node 18+.
 const chapterFiles = [];
-for await (const f of glob('**/*.{md,mdx}', { cwd: CHAPTERS_DIR })) {
+for await (const f of walkMdx(CHAPTERS_DIR)) {
   if (!f.split('/').pop().startsWith('_')) chapterFiles.push(f);
 }
 

package/scripts/walk-mdx.mjs

@@ -0,0 +1,34 @@
+/**
+ * scripts/walk-mdx.mjs — recursive .md/.mdx file walker for content trees.
+ *
+ * Extracted from scripts/validate.mjs in v3.7.1 (closes #52) so it can be
+ * unit-tested without running validate's side-effectful top-level await.
+ *
+ * Replaces the previous `glob` import from `node:fs/promises` (Node 22+
+ * only). The walker below uses `readdir` only — works on Node 18+ so
+ * consumer CIs running `node-version: '20'` no longer crash on the
+ * scaffold's prebuild validate hook.
+ *
+ * Output: relative paths in POSIX form ("subdir/file.mdx"), matching what
+ * the previous `glob('**\/*.{md,mdx}', { cwd })` produced.
+ */
+import { readdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+
+export async function* walkMdx(dir, baseDir = dir) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return; // dir missing or unreadable — treat as zero chapters
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walkMdx(full, baseDir);
+    } else if (/\.(md|mdx)$/.test(entry.name)) {
+      // Normalize to forward slashes for cross-platform stability.
+      yield relative(baseDir, full).split(/[\\/]/).join('/');
+    }
+  }
+}

package/src/lib/define-style.ts

@@ -0,0 +1,302 @@
+/**
+ * src/lib/define-style.ts — `defineStyle` API + composition (v4.0.0).
+ *
+ * Closes #35 followup architecture work. A `Style` is a typed, named,
+ * importable config bundle that consumers can compose across many books
+ * in the same cluster. Replaces the v3.x `preset` field as the primary
+ * way to configure a book.
+ *
+ * Design principles (D6 + D12 from the v4.0.0 plan):
+ *   - Pure data (no Astro virtual modules) — safe for tsup's DTS bundle,
+ *     same constraint as src/lib/chapter-sort.ts (v3.5.2).
+ *   - Every field optional — composition fills gaps; no required fields
+ *     means new fields are always additive.
+ *   - Branded type — prevents confusion with plain Partial<BookConfigOptions>
+ *     even though they're structurally close.
+ *   - Closed shape for known fields (no `[key: string]: unknown` index
+ *     signature) — catches typos at compile time (the v3 `convergance`
+ *     lesson, see PR #9 v3.4.0).
+ *   - Scoped escape hatch via `extra?: Record<string, unknown>` — consumer-
+ *     side metadata can travel with the style without breaking typo
+ *     protection on toolkit-known fields.
+ *   - Readonly throughout — Style objects are immutable DTOs.
+ *   - Version marker (`__styleVersion`) — future API-shape changes can
+ *     be detected at composition time without breaking existing styles.
+ *
+ * See `recipes/15-defining-styles.md` for usage patterns + MIGRATION-v3-to-v4.md
+ * for migration from the v3 `preset:` shorthand.
+ */
+import type { AstroIntegration, AstroUserConfig } from 'astro';
+import type { BookPreset, RouteToggles } from '../types.js';
+
+// ===== Branded nominal type =====
+
+/** Internal brand symbol — prevents confusion between Style and plain config objects.
+ *  TYPE-ONLY: `declare const` means there's no runtime value. The brand exists
+ *  purely at compile time as a structural guard: TypeScript will reject a plain
+ *  `Partial<BookConfigOptions>` where a `Style` is expected, because the brand
+ *  key isn't present in the plain object's type. At runtime, Style is just an
+ *  object with `__styleVersion: 1` — no Symbol keys to enumerate or test for. */
+declare const StyleBrand: unique symbol;
+
+// ===== Widened route toggles =====
+
+/**
+ * Widened form of the frontmatter route config (closes #49).
+ * Pre-v4 was just `boolean`; v4 supports an object form with `prefix` so
+ * consumers can mount frontmatter pages at root (`prefix: ''` → `/[slug]`)
+ * or under a custom prefix (`prefix: 'pages'` → `/pages/[slug]`).
+ *
+ * Default prefix (when unset OR when boolean `true` is used): `'frontmatter'`,
+ * matching the v3 behavior.
+ */
+export type FrontmatterRouteConfig =
+  | boolean
+  | {
+      readonly enabled: boolean;
+      readonly prefix?: string;
+    };
+
+/**
+ * Partial route toggles for use inside Style. Same shape as `Partial<RouteToggles>`
+ * except `frontmatter` is widened to `FrontmatterRouteConfig` (closes #49).
+ */
+export type PartialRouteToggles = Partial<Omit<RouteToggles, 'frontmatter'>> & {
+  readonly frontmatter?: FrontmatterRouteConfig;
+};
+
+// ===== Style type =====
+
+/**
+ * A typed config bundle. Composed via `styles: [...]` in `defineBookConfig`.
+ *
+ * All fields are optional and immutable. Use `defineStyle()` to create a
+ * Style with proper branding + version marker.
+ *
+ * For consumer-side metadata that should travel with the style but isn't
+ * toolkit configuration, use the scoped `extra` field rather than adding
+ * unknown top-level fields (which the closed shape rejects).
+ */
+export interface Style {
+  /** @internal Brand for nominal typing. Set by defineStyle(); not observable. */
+  readonly [StyleBrand]: true;
+  /** @internal Version marker for future API-shape evolution. Set by defineStyle(). */
+  readonly __styleVersion: 1;
+
+  /** Optional human-readable name; surfaces in debug output and error messages.
+   *  Anonymous styles fall back to their index in the composition chain. */
+  readonly name?: string;
+
+  /** Profile that backs this style — determines schema + default routes + styles + KaTeX wiring. */
+  readonly preset?: BookPreset;
+
+  /** 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;
+
+  /** Per-route override; merges per-key across the style chain. */
+  readonly routes?: PartialRouteToggles;
+
+  /** Consumer-defined KaTeX macros, shallow-merged per macro across the style chain.
+   *  Closes #22 (v3.6.0); same merge semantics. */
+  readonly katexMacros?: Readonly<Record<string, string>>;
+
+  /** CSS basenames injected in addition to the profile-resolved set.
+   *  Composed via array concat (additive). */
+  readonly extraStyles?: readonly string[];
+
+  /** Appended to the package-provided integration list.
+   *  Composed via array concat (additive). */
+  readonly extraIntegrations?: readonly AstroIntegration[];
+
+  /** Explicit path to consumer's mdx-components map (relative to project root).
+   *  Last non-undefined value wins across the chain. */
+  readonly mdxComponentsModule?: string;
+
+  /** Spread-merged into the package-provided markdown config.
+   *  `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. */
+  readonly deploy?: 'pages' | 'workers';
+
+  /**
+   * Scoped consumer-side metadata. Ignored by the toolkit; survives composition
+   * as per-key spread (last wins per key). Use this for workflow data that
+   * should travel with the style but isn't toolkit config.
+   *
+   * @example
+   *   defineStyle({
+   *     name: 'guides-family',
+   *     preset: 'research-portfolio',
+   *     extra: { pedagogyTier: 'experimental', team: 'engineering' },
+   *   })
+   */
+  readonly extra?: Readonly<Record<string, unknown>>;
+}
+
+/** Input type for `defineStyle()`: same as Style, minus the internal brand + version fields. */
+export type StyleInput = Omit<Style, typeof StyleBrand | '__styleVersion'>;
+
+// ===== defineStyle helper =====
+
+/**
+ * Create a Style — a typed, named, importable config bundle.
+ *
+ * Identity function with auto-applied brand + version marker. Zero runtime
+ * overhead beyond object spread.
+ *
+ * @example workspace-local style
+ *   // shared/styles/guides-family.ts
+ *   import { defineStyle } from '@brandon_m_behring/book-scaffold-astro';
+ *   export const guidesFamilyStyle = defineStyle({
+ *     name: 'guides-family',
+ *     preset: 'research-portfolio',
+ *     site: 'https://guides.brandon-behring.dev/',
+ *     routes: { frontmatter: { enabled: true, prefix: '' } },
+ *     deploy: 'pages',
+ *   });
+ *
+ *   // guides/foo/astro.config.mjs
+ *   import { defineBookConfig } from '@brandon_m_behring/book-scaffold-astro';
+ *   import { guidesFamilyStyle } from '../shared/styles/guides-family';
+ *   export default await defineBookConfig({
+ *     styles: [guidesFamilyStyle],
+ *     site: 'https://foo.guides.brandon-behring.dev/',  // overrides style's site
+ *   });
+ *
+ * @example built-in style composition
+ *   import { defineBookConfig, researchPortfolioStyle } from '@brandon_m_behring/book-scaffold-astro';
+ *   export default await defineBookConfig({
+ *     styles: [researchPortfolioStyle],
+ *     site: 'https://my-book.example/',
+ *   });
+ *
+ * See `recipes/15-defining-styles.md` for the full pattern catalog.
+ */
+export function defineStyle(opts: StyleInput): Style {
+  return { __styleVersion: 1, ...opts } as Style;
+}
+
+// ===== composeStyles =====
+
+/**
+ * Merge an array of Styles into a single resolved Style.
+ *
+ * Composition order (precedence ascending — last wins for conflicts):
+ *   - Earlier styles in the array set defaults
+ *   - Later styles override earlier
+ *   - Top-level `defineBookConfig` fields beat any style (handled in config.ts)
+ *
+ * Per-key merge strategy:
+ *   - `preset`, `site`, `deploy`, `mdxComponentsModule`, `name` → shallow override (last wins)
+ *   - `routes` → per-route spread (each route key independently overridable)
+ *   - `katexMacros` → per-macro spread (each macro key independently overridable)
+ *   - `extra` → per-key spread (consumer metadata accumulates across the chain)
+ *   - `extraStyles`, `extraIntegrations` → array concat (additive; no dedup)
+ *   - `markdown` → spread, with `remarkPlugins` and `rehypePlugins` arrays concat
+ *
+ * @returns a fully-typed Style representing the composed configuration.
+ *   Empty input returns an empty Style with no fields set (all undefined).
+ */
+export function composeStyles(styles: readonly Style[]): Style {
+  if (styles.length === 0) {
+    return defineStyle({});
+  }
+
+  const merged: Record<string, unknown> = {};
+
+  for (const style of styles) {
+    // Shallow override for primitives + readonly-scalar fields.
+    if (style.name !== undefined) merged.name = style.name;
+    if (style.preset !== undefined) merged.preset = style.preset;
+    if (style.site !== undefined) merged.site = style.site;
+    if (style.deploy !== undefined) merged.deploy = style.deploy;
+    if (style.mdxComponentsModule !== undefined) {
+      merged.mdxComponentsModule = style.mdxComponentsModule;
+    }
+
+    // Per-route spread.
+    if (style.routes !== undefined) {
+      merged.routes = {
+        ...((merged.routes as PartialRouteToggles | undefined) ?? {}),
+        ...style.routes,
+      };
+    }
+
+    // Per-macro spread.
+    if (style.katexMacros !== undefined) {
+      merged.katexMacros = {
+        ...((merged.katexMacros as Record<string, string> | undefined) ?? {}),
+        ...style.katexMacros,
+      };
+    }
+
+    // Per-key spread for consumer metadata.
+    if (style.extra !== undefined) {
+      merged.extra = {
+        ...((merged.extra as Record<string, unknown> | undefined) ?? {}),
+        ...style.extra,
+      };
+    }
+
+    // Array concat for additive fields.
+    if (style.extraStyles !== undefined) {
+      const prev = (merged.extraStyles as readonly string[] | undefined) ?? [];
+      merged.extraStyles = [...prev, ...style.extraStyles];
+    }
+    if (style.extraIntegrations !== undefined) {
+      const prev =
+        (merged.extraIntegrations as readonly AstroIntegration[] | undefined) ?? [];
+      merged.extraIntegrations = [...prev, ...style.extraIntegrations];
+    }
+
+    // markdown: spread with array-concat for the two plugin arrays.
+    if (style.markdown !== undefined) {
+      const prev = (merged.markdown as AstroUserConfig['markdown'] | undefined) ?? undefined;
+      merged.markdown = mergeMarkdown(prev, style.markdown);
+    }
+  }
+
+  return defineStyle(merged as StyleInput);
+}
+
+/**
+ * Merge two `markdown` config blocks. Scalar fields override (last wins);
+ * `remarkPlugins` and `rehypePlugins` arrays concat (additive — same
+ * semantics as `extraStyles` / `extraIntegrations`).
+ */
+function mergeMarkdown(
+  a: AstroUserConfig['markdown'] | undefined,
+  b: AstroUserConfig['markdown'] | undefined,
+): AstroUserConfig['markdown'] {
+  if (!a) return b;
+  if (!b) return a;
+  return {
+    ...a,
+    ...b,
+    remarkPlugins: [...(a.remarkPlugins ?? []), ...(b.remarkPlugins ?? [])],
+    rehypePlugins: [...(a.rehypePlugins ?? []), ...(b.rehypePlugins ?? [])],
+  };
+}
+
+// ===== Normalization helpers =====
+
+/**
+ * Normalize the widened `routes.frontmatter` value to its object form for
+ * downstream use. `true` → `{ enabled: true }`, `false` → `{ enabled: false }`,
+ * object → returned as-is.
+ *
+ * Used by the integration when computing the route URL pattern from the prefix.
+ */
+export function normalizeFrontmatterConfig(
+  v: FrontmatterRouteConfig | undefined,
+): { enabled: boolean; prefix?: string } | undefined {
+  if (v === undefined) return undefined;
+  if (typeof v === 'boolean') return { enabled: v };
+  return v;
+}