@brandon_m_behring/book-scaffold-astro 4.0.0 → 4.1.2

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,23 @@
+---
+/**
+ * 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/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": "4.0.0",
+  "version": "4.1.2",
   "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/scripts/build-labels.mjs

@@ -34,7 +34,8 @@
  * Designed to run in <2 s on a medium book.
  */
 import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
-import { resolve, join, basename, dirname } from 'node:path';
+import { resolve, relative, join, basename, dirname } from 'node:path';
+import { readChaptersBase } from './walk-mdx.mjs';
 
 // --help / -h: non-mutating (closes #14).
 const USAGE = `Usage: book-scaffold build-labels
@@ -56,7 +57,15 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
   process.exit(0);
 }
 
-const CHAPTERS_DIR = process.env.BOOK_CHAPTERS_DIR ?? 'src/content/chapters';
+// v4.1.1 (closes #63): readChaptersBase honors BOOK_CHAPTERS_DIR env (when set)
+// then parses the consumer's content.config.{ts,mjs,js} for a `chapters`
+// collection `loader.base` override. Multi-guide consumers use
+// `src/content/<guide-slug>/` rather than the Astro 5 default.
+const CHAPTERS_DIR_ABS = await readChaptersBase(process.cwd());
+// build-labels uses CHAPTERS_DIR as a path relative to cwd elsewhere in the
+// script (joined with `walkMdx`). Convert the absolute path back to relative
+// for compatibility with the existing call sites.
+const CHAPTERS_DIR = relative(process.cwd(), CHAPTERS_DIR_ABS) || 'src/content/chapters';
 const OUTPUT_PATH = process.env.BOOK_LABELS_OUT ?? 'src/data/labels.json';
 
 /** Component names that participate in cross-referencing. */

package/scripts/validate.mjs

@@ -28,7 +28,7 @@
 import { readFile, access } from 'node:fs/promises';
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve, dirname, join } from 'node:path';
-import { walkMdx } from './walk-mdx.mjs';
+import { walkMdx, readChaptersBase } from './walk-mdx.mjs';
 
 /**
  * Best-effort .env reader. Mirrors `readEnvFile` in src/types.ts; kept inline
@@ -95,7 +95,11 @@ const presetFromFlag = presetFlagIdx >= 0 ? argv[presetFlagIdx + 1] : undefined;
 // Resolves issue #8 — three reference consumers reported "0 chapter(s) checked"
 // because ROOT was the package directory inside node_modules.
 const ROOT = process.cwd();
-const CHAPTERS_DIR = resolve(ROOT, 'src/content/chapters');
+// v4.1.1 (closes #63): read the consumer's content.config.{ts,mjs,js} to
+// honor `loader.base` overrides (multi-guide pattern uses
+// `src/content/<guide-slug>/` instead of the Astro 5 default).
+// Falls back to `src/content/chapters` when no override / no config file.
+const CHAPTERS_DIR = await readChaptersBase(ROOT);
 const PUBLIC_DIR = resolve(ROOT, 'public');
 const DATA_DIR = resolve(ROOT, 'src/data');
 

package/scripts/walk-mdx.mjs

@@ -12,8 +12,9 @@
  * 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';
+import { readFile, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
 
 export async function* walkMdx(dir, baseDir = dir) {
   let entries;
@@ -32,3 +33,68 @@ export async function* walkMdx(dir, baseDir = dir) {
     }
   }
 }
+
+/**
+ * Read the consumer's `content.config.ts` (or `.mjs` / `.js`) and extract
+ * the `loader.base` path for the `chapters` content collection.
+ *
+ * v4.1.1 (closes #63): consumers in the multi-guide / multi-book pattern
+ * override the chapters dir to `src/content/<guide-slug>` rather than the
+ * Astro 5 default `src/content/chapters/`. Without this helper,
+ * `book-scaffold validate` + `book-scaffold build-labels` silently report
+ * 0 chapters because they walk the default path. This helper parses the
+ * consumer's config file and returns the actual base path so both scripts
+ * discover the consumer's chapter files.
+ *
+ * Strategy: regex-parse the source file (avoid runtime import; the file
+ * imports from `astro:content` / `astro/loaders` which don't resolve in
+ * plain Node). Matches both single- and double-quoted string literals;
+ * matches paths with or without the `./` prefix.
+ *
+ * Returns the resolved absolute path. Falls back to
+ * `${projectRoot}/src/content/chapters` when:
+ *   - content.config.{ts,mjs,js} doesn't exist
+ *   - the file exists but no `chapters` collection or `loader.base` found
+ *   - the matched base path uses dynamic forms (variables, template literals)
+ *     instead of a string literal
+ *
+ * Honors env override: BOOK_CHAPTERS_DIR (when set) wins over config parse.
+ */
+export async function readChaptersBase(projectRoot) {
+  const envOverride = process.env.BOOK_CHAPTERS_DIR;
+  if (envOverride) {
+    return resolve(projectRoot, envOverride);
+  }
+  const DEFAULT_BASE = resolve(projectRoot, 'src/content/chapters');
+  for (const ext of ['ts', 'mjs', 'js']) {
+    const configPath = join(projectRoot, `src/content.config.${ext}`);
+    if (!existsSync(configPath)) continue;
+    let source;
+    try {
+      source = await readFile(configPath, 'utf8');
+    } catch {
+      return DEFAULT_BASE;
+    }
+    // Look for a `chapters` collection's `loader.base` string. Permissive
+    // form: match the `chapters` identifier, then within the next 500
+    // chars find `base: 'string'` or `base: "string"`. NOT template
+    // literals (which use backticks and may contain ${} interpolation —
+    // those fall back to the default since the value is dynamic).
+    //
+    // Forms matched:
+    //   - `const chapters = defineCollection({ loader: glob({ base: './foo' }) })`
+    //   - `export const collections = { chapters: defineCollection({ loader: glob({ base: './foo' }) }) }`
+    //   - any indentation / line break style
+    const re = /\bchapters\b[\s\S]{0,500}?\bbase\s*:\s*'([^']+)'|\bchapters\b[\s\S]{0,500}?\bbase\s*:\s*"([^"]+)"/;
+    const m = source.match(re);
+    const captured = m && (m[1] || m[2]);
+    if (captured) {
+      return resolve(projectRoot, captured);
+    }
+    // File exists but no override found — assume the consumer uses the
+    // scaffold's defineBookSchemas() default.
+    return DEFAULT_BASE;
+  }
+  // No content.config.{ts,mjs,js} at all — return the Astro 5 default.
+  return DEFAULT_BASE;
+}

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;