@brandon_m_behring/book-scaffold-astro 3.7.1 → 4.1.0

package/CLAUDE.md

@@ -66,7 +66,9 @@ Two callout families coexist. Authors import what they need.
 
 **Academic family** (`src/components/callouts/`, 10 components): `NoteBox`, `ExampleBox`, `DynConnect`, `InsightBox`, `WarnBox`, `CounterBox`, `TipBox`, `OpenQuestion`, `PaperBox`, `ResultBox`. Plus `Theorem` (unified for theorem/proposition/lemma/corollary/definition/example/exercise/remark/proof).
 
-**Utility components** (`src/components/`, any profile): `Cite`, `XRef`, `Figure`, `MarginNote`, `Sidenote`, `WeekRef`, `CodeRef`, `CodeBlock`, `Tag`, `StatusBadge`.
+**Pedagogy family** (v4.1.0+, any profile, 3 components): `Pitfall` (rose; "common mistake" — distinct from `WarnBox`'s preemptive warning), `WorkedExample` (plum; collapsible `<details>` block with `#worked-example-{id}` anchor for deep links), `YouWillLearn` (gold; chapter-opener with optional `prerequisites` prop). Slot bullets/code freely; render at any preset.
+
+**Utility components** (`src/components/`, any profile): `Cite`, `XRef`, `Figure`, `MarginNote`, `Sidenote`, `WeekRef`, `CodeRef`, `CodeBlock`, `Tag`, `StatusBadge`, `PocLayout` (v4.1.0+; wraps slot in a per-`kind` layout shell — 5 closed-union kinds; see `recipes/15-defining-styles.md`).
 
 Full reference in `recipes/04-component-library.md`.
 

package/components/Pitfall.astro

@@ -0,0 +1,17 @@
+---
+/**
+ * Pitfall — distinct from generic <WarnBox>.
+ * Retrospective "this often goes wrong" callout (vs WarnBox's preemptive
+ * "this could go wrong"). React.dev "Pitfall" vocabulary. Closes #58.
+ *
+ * Family: crimson (--callout-pitfall, deeper than warn-rose).
+ */
+interface Props {
+  title?: string;
+}
+const { title = 'Common mistake' } = Astro.props;
+---
+<aside class="callout callout-pitfall" role="note">
+  <strong class="callout-title">{title}</strong>
+  <div class="callout-body"><slot /></div>
+</aside>

package/components/PocLayout.astro

@@ -0,0 +1,28 @@
+---
+/**
+ * PocLayout — per-PoC-kind layout selector (closes #56).
+ *
+ * Wraps slotted content in a <div> that swaps 3 CSS variables per kind
+ * (line-length, vertical rhythm, heading emphasis). 5 closed-union kinds.
+ *
+ * CSS variable surface defined in package/styles/poc-layouts.css. Authors
+ * can override per-kind in their own stylesheets via `:where(.poc-layout-X)`.
+ *
+ * Closed `kind` union: discriminated literal type. To add a 6th kind in
+ * a future release, expand the union + add a CSS block in poc-layouts.css.
+ */
+export type PocLayoutKind =
+  | 'tutorial'
+  | 'how-to'
+  | 'tldr'
+  | 'part-summary'
+  | 'cheat-sheet';
+
+interface Props {
+  kind: PocLayoutKind;
+}
+const { kind } = Astro.props;
+---
+<div class={`poc-layout poc-layout-${kind}`}>
+  <slot />
+</div>

package/components/WorkedExample.astro

@@ -0,0 +1,29 @@
+---
+/**
+ * WorkedExample — collapsible demonstration block (closes #57).
+ *
+ * Pedagogical worked-example-effect treatment (Sweller/Cooper). Uses
+ * native <details>; collapsed by default unless `expanded` prop set.
+ * The outer aside carries `id="worked-example-{id}"` for deep links
+ * from TL;DRs or cheat-sheets. Prefix avoids collision with author
+ * heading anchors.
+ *
+ * Family: plum (--callout-worked, reuses --callout-official authority hue).
+ */
+interface Props {
+  id: string;
+  title: string;
+  expanded?: boolean;
+}
+const { id, title, expanded = false } = Astro.props;
+const anchorId = `worked-example-${id}`;
+---
+<aside class="callout callout-worked" id={anchorId} role="note">
+  <details open={expanded}>
+    <summary>
+      <strong class="callout-title">{title}</strong>
+      <span class="callout-chip">Worked example</span>
+    </summary>
+    <div class="callout-body"><slot /></div>
+  </details>
+</aside>

package/components/YouWillLearn.astro

@@ -0,0 +1,24 @@
+---
+/**
+ * YouWillLearn — chapter-opener "what this chapter delivers" callout
+ * (closes #59). React.dev pedagogy vocabulary; Bloom's-taxonomy framing.
+ *
+ * Slotted body — author writes markdown bullets directly.
+ * Optional `prerequisites` prop renders a small "Before you start" sub-block.
+ *
+ * Family: gold (--callout-learn, reuses --callout-insight to signal importance).
+ */
+interface Props {
+  prerequisites?: string;
+}
+const { prerequisites } = Astro.props;
+---
+<aside class="callout callout-learn" role="note">
+  {prerequisites && (
+    <div class="callout-prereq">
+      <strong class="callout-prereq-label">Before you start:</strong> {prerequisites}
+    </div>
+  )}
+  <strong class="callout-title">You will learn</strong>
+  <div class="callout-body"><slot /></div>
+</aside>

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,8 +869,62 @@ 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 = [];
@@ -800,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
@@ -819,45 +954,49 @@ 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;
@@ -865,6 +1004,7 @@ async function defineBookConfig(opts) {
   void _katexMacros;
   const katexExternals = wantsKatex ? [] : ["remark-math", "rehype-katex", "katex"];
   const config = {
+    site,
     ...rest,
     integrations,
     markdown,
@@ -895,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,
@@ -926,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/dist/schemas.mjs

@@ -1,5 +1,5 @@
 // src/schemas-entry.ts
-import { existsSync as existsSync2 } from "fs";
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
 import { defineCollection } from "astro:content";
 import { glob, file } from "astro/loaders";
 
@@ -565,6 +565,15 @@ function resolvePreset(explicitPreset, explicitProfile) {
 }
 
 // src/schemas-entry.ts
+function isYamlEmpty(path) {
+  try {
+    const raw = readFileSync2(path, "utf8");
+    const stripped = raw.split(/\r?\n/).map((line) => line.replace(/#.*$/, "").trim()).filter((line) => line.length > 0).join("");
+    return stripped === "" || stripped === "[]";
+  } catch {
+    return false;
+  }
+}
 function frontmatterCollection(schema, base = "./src/content/frontmatter") {
   return defineCollection({
     loader: glob({
@@ -589,7 +598,7 @@ function defineBookSchemas(opts = {}) {
   const collections = {
     chapters
   };
-  if (existsSync2("./sources/manifest.yaml")) {
+  if (existsSync2("./sources/manifest.yaml") && !isYamlEmpty("./sources/manifest.yaml")) {
     collections.sources = defineCollection({
       loader: file("sources/manifest.yaml"),
       schema: sourcesSchema

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.1",
+  "version": "4.1.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -65,6 +65,8 @@
     "./components/OpenQuestion.astro": "./components/OpenQuestion.astro",
     "./components/PaperBox.astro": "./components/PaperBox.astro",
     "./components/PatternTimeline.astro": "./components/PatternTimeline.astro",
+    "./components/Pitfall.astro": "./components/Pitfall.astro",
+    "./components/PocLayout.astro": "./components/PocLayout.astro",
     "./components/PolicyRef.astro": "./components/PolicyRef.astro",
     "./components/PreReleaseBanner.astro": "./components/PreReleaseBanner.astro",
     "./components/Recovery.astro": "./components/Recovery.astro",
@@ -88,7 +90,9 @@
     },
     "./components/WarnBox.astro": "./components/WarnBox.astro",
     "./components/WeekRef.astro": "./components/WeekRef.astro",
+    "./components/WorkedExample.astro": "./components/WorkedExample.astro",
     "./components/XRef.astro": "./components/XRef.astro",
+    "./components/YouWillLearn.astro": "./components/YouWillLearn.astro",
     "./styles/tokens.css": "./styles/tokens.css",
     "./styles/layout.css": "./styles/layout.css",
     "./styles/callouts.css": "./styles/callouts.css",
@@ -96,6 +100,7 @@
     "./styles/typography.css": "./styles/typography.css",
     "./styles/print.css": "./styles/print.css",
     "./styles/convergence.css": "./styles/convergence.css",
+    "./styles/poc-layouts.css": "./styles/poc-layouts.css",
     "./styles/tool-filter.css": "./styles/tool-filter.css",
     "./layouts/Base.astro": "./layouts/Base.astro",
     "./layouts/Chapter.astro": "./layouts/Chapter.astro",

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/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;
+}

package/styles/callouts.css

@@ -162,6 +162,54 @@
   background: var(--color-bg-subtle);
 }
 
+/* Crimson — Pitfall (v4.1.0, #58). Distinct from warn-rose: deeper, more
+ * saturated. Used for "common mistake" / retrospective error patterns. */
+.callout-pitfall {
+  border-left-color: var(--callout-pitfall);
+  background: var(--warm-crimson-tint);
+}
+
+/* Plum-dashed — WorkedExample (v4.1.0, #57). Reuses callout-official
+ * (plum) bar; <details>/<summary> chrome is plain — no extra structure. */
+.callout-worked {
+  border-left-color: var(--callout-worked);
+  background: var(--warm-plum-tint);
+}
+.callout-worked summary {
+  cursor: pointer;
+  list-style: none;
+  display: flex;
+  align-items: baseline;
+  gap: var(--space-3);
+}
+.callout-worked summary::-webkit-details-marker {
+  display: none;
+}
+.callout-worked .callout-chip {
+  font-size: var(--text-xs);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  padding: 0 var(--space-2);
+  border: 1px solid var(--callout-worked);
+  border-radius: var(--radius-sm);
+  color: var(--callout-worked);
+}
+
+/* Gold — YouWillLearn (v4.1.0, #59). Reuses callout-insight (gold) hue;
+ * "Before you start" prereq sub-block sits above the title in muted style. */
+.callout-learn {
+  border-left-color: var(--callout-learn);
+  background: var(--warm-gold-tint);
+}
+.callout-learn .callout-prereq {
+  font-size: var(--text-sm);
+  color: var(--color-text-muted);
+  margin-bottom: var(--space-2);
+}
+.callout-learn .callout-prereq-label {
+  color: var(--color-text);
+}
+
 /* ===== Theorem family (Theorem.astro) =====
  * Plain (theorem/proposition/lemma/corollary): italic body
  * Definition family (definition/example/exercise/remark/proof): upright body

package/styles/poc-layouts.css

@@ -0,0 +1,57 @@
+/* poc-layouts.css — per-PoC-kind layout variables (v4.1.0, closes #56).
+ *
+ * Each kind swaps 3 CSS variables that downstream stylesheets (chapter.css,
+ * layout.css) can read. Consumers can override per-kind in their own
+ * stylesheets via `:where(.poc-layout-X) { --bs-content-line-length: ... }`.
+ *
+ * Variable surface (intentionally narrow):
+ *   --bs-content-line-length       — main column max line length (ch)
+ *   --bs-content-vertical-rhythm   — body line-height multiplier
+ *   --bs-heading-emphasis          — heading font-weight (400-900)
+ */
+
+:where(.poc-layout-tutorial) {
+  --bs-content-line-length: 70ch;
+  --bs-content-vertical-rhythm: 1.6;
+  --bs-heading-emphasis: 600;
+}
+
+:where(.poc-layout-how-to) {
+  --bs-content-line-length: 68ch;
+  --bs-content-vertical-rhythm: 1.5;
+  --bs-heading-emphasis: 700;
+}
+
+:where(.poc-layout-tldr) {
+  --bs-content-line-length: 65ch;
+  --bs-content-vertical-rhythm: 1.4;
+  --bs-heading-emphasis: 500;
+}
+
+:where(.poc-layout-part-summary) {
+  --bs-content-line-length: 90ch;
+  --bs-content-vertical-rhythm: 1.5;
+  --bs-heading-emphasis: 600;
+}
+
+:where(.poc-layout-cheat-sheet) {
+  --bs-content-line-length: 55ch;
+  --bs-content-vertical-rhythm: 1.3;
+  --bs-heading-emphasis: 600;
+}
+
+/* All kinds: apply the variables to the wrapper itself.
+ * Authors can read these vars from descendants for tighter control. */
+.poc-layout {
+  max-width: var(--bs-content-line-length, 70ch);
+  line-height: var(--bs-content-vertical-rhythm, 1.6);
+}
+
+.poc-layout :is(h1, h2, h3, h4, h5, h6) {
+  font-weight: var(--bs-heading-emphasis, 600);
+}
+
+/* Cheat-sheet: tables should fill the available width since the column is narrower. */
+.poc-layout-cheat-sheet table {
+  width: 100%;
+}

package/styles/tokens.css

@@ -14,6 +14,7 @@
   --warm-green:  #4A7E3F;  /* positive: tips, practitioner */
   --warm-plum:   #8A4E82;  /* authority: official, exercises */
   --warm-gold:   #C09840;  /* insight: convergence, reasoning */
+  --warm-crimson:#A03838;  /* pitfall: deeper red distinct from warm-rose */
 
   /* Warm neutrals (Anthropic-derived) */
   --paper:       #FDFCF9;  /* page background — slightly off-white */
@@ -27,6 +28,7 @@
   --warm-green-tint: color-mix(in srgb, var(--warm-green) 6%, var(--paper));
   --warm-plum-tint:  color-mix(in srgb, var(--warm-plum)  6%, var(--paper));
   --warm-gold-tint:  color-mix(in srgb, var(--warm-gold)  6%, var(--paper));
+  --warm-crimson-tint:color-mix(in srgb, var(--warm-crimson) 6%, var(--paper));
 
   /* ===== Layer 2: Semantic roles (light mode) ===== */
   --color-bg:         var(--paper);
@@ -45,6 +47,9 @@
   --callout-tip:      var(--warm-green);
   --callout-official: var(--warm-plum);
   --callout-insight:  var(--warm-gold);
+  --callout-pitfall:  var(--warm-crimson);
+  --callout-worked:   var(--warm-plum);
+  --callout-learn:    var(--warm-gold);
 
   /* ===== Typography scale ===== */
   --font-body: 'Roboto Variable', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;