@brandon_m_behring/book-scaffold-astro 3.0.0-alpha.4 → 3.0.0-alpha.6

package/components/ChapterHeader.astro

@@ -1,13 +1,16 @@
 ---
 /**
  * ChapterHeader — renders the metadata block at the top of every chapter.
- * Surfaces provenance signals the LaTeX book conveyed implicitly:
- *   - Part + chapter number (position in the book)
- *   - Volatility class (freshness calibration for the reader)
- *   - Tools compared (scope signal)
- *   - Last verified date (how stale are the claims?)
  *
- * Driven entirely from the chapter's frontmatter (see content.config.ts).
+ * Schema-agnostic: the package supports two profile schemas (academic and
+ * tools), so this component renders only the fields that are present on
+ * the chapter data. Tools-profile metadata (volatility, last_verified,
+ * tools_compared) appears when defined; academic-profile metadata (week,
+ * status) appears in its place.
+ *
+ * Use a chapter card's metadata to calibrate how much trust to place in
+ * its specific claims — stable principles age slowly; feature surfaces
+ * age fast.
  */
 import type { CollectionEntry } from 'astro:content';
 import { getFreshness, freshnessLabel } from '../src/lib/freshness';
@@ -17,45 +20,97 @@ interface Props {
 }
 const { data } = Astro.props;
 
-function formatDate(d: Date): string {
-  return d.toISOString().slice(0, 10);
+// Widen for cross-schema field probing. The consumer's content.config.ts
+// resolves `data` to exactly one of the two schemas at build time; this
+// runtime probe handles either without crashing.
+const d = data as Record<string, unknown>;
+
+const hasToolsMeta =
+  typeof d.volatility === 'string' &&
+  d.last_verified instanceof Date &&
+  Array.isArray(d.tools_compared);
+
+const hasAcademicMeta =
+  typeof d.week === 'number' && typeof d.status === 'string';
+
+function formatDate(date: unknown): string {
+  return date instanceof Date ? date.toISOString().slice(0, 10) : '';
 }
 
-const freshness = getFreshness(data.last_verified, data.volatility);
-const freshnessText =
-  freshness.status === 'fresh'
+// Tools-profile freshness — only when all inputs are present + typed.
+const freshness =
+  hasToolsMeta && d.last_verified instanceof Date && typeof d.volatility === 'string'
+    ? getFreshness(d.last_verified, d.volatility as Parameters<typeof getFreshness>[1])
+    : null;
+
+const freshnessText = freshness
+  ? freshness.status === 'fresh'
     ? 'Fresh'
     : freshness.status === 'verify-soon'
       ? 'Verify soon'
-      : 'Stale';
+      : 'Stale'
+  : null;
+
+// Display strings, profile-tagged for clarity in markup.
+const partLabel = (() => {
+  const p = d.part;
+  if (typeof p === 'number') return `Part ${p}`;
+  if (typeof p === 'string' && p.length > 0) return `Part: ${p}`;
+  return null;
+})();
+const chapterNum =
+  typeof d.chapter === 'number' ? `Chapter ${d.chapter}` : null;
+const weekNum = typeof d.week === 'number' ? `Week ${d.week}` : null;
+const statusBadge =
+  typeof d.status === 'string' ? d.status.replace(/_/g, ' ') : null;
+const title = typeof d.title === 'string' ? d.title : '(untitled)';
+const description = typeof d.description === 'string' ? d.description : null;
+const toolsCompared = Array.isArray(d.tools_compared)
+  ? (d.tools_compared as string[])
+  : [];
+const lastVerified = d.last_verified instanceof Date ? d.last_verified : null;
+const updated = d.updated instanceof Date ? d.updated : null;
+const volatility = typeof d.volatility === 'string' ? d.volatility : null;
 ---
 <header class="chapter-header">
   <div class="chapter-meta">
-    <span>Part {data.part}</span>
-    <span>Chapter {data.chapter}</span>
-    <span>
-      Last verified {formatDate(data.last_verified)}
-      <span
-        class="freshness-badge"
-        data-status={freshness.status}
-        aria-label={freshnessLabel(freshness)}
-        title={freshnessLabel(freshness)}
-      >{freshnessText}</span>
-    </span>
-    {data.updated && <span>Updated {formatDate(data.updated)}</span>}
-  </div>
-  <h1>{data.title}</h1>
-  {data.description && <p class="chapter-description">{data.description}</p>}
-  <div class="chapter-badge-row">
-    <span class="chapter-badge-row-label">Volatility:</span>
-    <span class={`volatility-badge volatility-${data.volatility}`}>
-      {data.volatility}
-    </span>
+    {partLabel && <span>{partLabel}</span>}
+    {chapterNum && <span>{chapterNum}</span>}
+    {weekNum && <span>{weekNum}</span>}
+    {statusBadge && (
+      <span class="status-badge" data-status={d.status as string}>
+        {statusBadge}
+      </span>
+    )}
+    {lastVerified && (
+      <span>
+        Last verified {formatDate(lastVerified)}
+        {freshness && freshnessText && (
+          <span
+            class="freshness-badge"
+            data-status={freshness.status}
+            aria-label={freshnessLabel(freshness)}
+            title={freshnessLabel(freshness)}
+          >{freshnessText}</span>
+        )}
+      </span>
+    )}
+    {updated && <span>Updated {formatDate(updated)}</span>}
   </div>
-  {data.tools_compared.length > 0 && (
+  <h1>{title}</h1>
+  {description && <p class="chapter-description">{description}</p>}
+  {hasToolsMeta && volatility && (
+    <div class="chapter-badge-row">
+      <span class="chapter-badge-row-label">Volatility:</span>
+      <span class={`volatility-badge volatility-${volatility}`}>
+        {volatility}
+      </span>
+    </div>
+  )}
+  {hasToolsMeta && toolsCompared.length > 0 && (
     <div class="chapter-badge-row">
       <span class="chapter-badge-row-label">Tools compared:</span>
-      {data.tools_compared.map((t) => <span class="tool-badge">{t}</span>)}
+      {toolsCompared.map((t) => <span class="tool-badge">{t}</span>)}
     </div>
   )}
 </header>

package/dist/index.mjs

@@ -153,11 +153,11 @@ var ALWAYS_ON_STYLES = [
 var TOOLS_ONLY_STYLES = ["convergence.css", "tool-filter.css"];
 var DEFAULT_ROUTES_ALL = [
   { pattern: "/references", file: "references.astro" },
-  { pattern: "/search", file: "search.astro" }
+  { pattern: "/search", file: "search.astro" },
+  { pattern: "/print", file: "print.astro" }
 ];
 var DEFAULT_ROUTES_TOOLS = [
   { pattern: "/chapters", file: "chapters.astro" },
-  { pattern: "/print", file: "print.astro" },
   { pattern: "/convergence", file: "convergence.astro" }
 ];
 function resolvePage(file) {

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.0.0-alpha.4",
+  "version": "3.0.0-alpha.6",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -40,6 +40,7 @@
       "types": "./dist/schemas.d.ts",
       "import": "./dist/schemas.mjs"
     },
+    "./package.json": "./package.json",
     "./components/CaseStudy.astro": "./components/CaseStudy.astro",
     "./components/ChapterHeader.astro": "./components/ChapterHeader.astro",
     "./components/ChapterNav.astro": "./components/ChapterNav.astro",
@@ -109,7 +110,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && rm -f dist/types-*.d.ts",
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {

package/scripts/build-labels.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+/**
+ * build-labels.mjs — emit src/data/labels.json for <XRef> resolution.
+ *
+ * Walks the consumer's `src/content/chapters/**\/*.mdx`, extracts each
+ * labelable component invocation (Theorem, Figure, Section, … — see
+ * `LABELABLE_TYPES` below), and assigns it a display string of the form
+ * `<Type> <chapter>.<n>` (e.g. `Theorem 4.2`), matching the LaTeX `\cref`
+ * convention. The resulting map is consumed by XRef.astro via
+ * `import.meta.glob('/src/data/labels.json', { eager: true })`.
+ *
+ * Per-chapter, per-type counter: each chapter resets the counter, so two
+ * chapters can both have `Theorem 1` without colliding. The chapter
+ * number comes from frontmatter:
+ *   - tools profile: `chapter` field (number).
+ *   - academic profile: `week` field (number).
+ *
+ * Slug used for the href = filename minus `.mdx`. The href shape mirrors
+ * the consumer's pages router: `/chapters/<slug>#<id>`. Academic books
+ * using `[...slug].astro` get the same shape since Astro slugifies
+ * filenames identically.
+ *
+ * Optional override:
+ *   <Theorem id="…" label="Custom display" />
+ *     → labels.json uses "Custom display" instead of the auto-counter.
+ *
+ * Usage:
+ *   node scripts/build-labels.mjs
+ *   book-scaffold build-labels
+ *
+ * Reads from cwd (the consumer's project root); writes
+ * `src/data/labels.json`. Creates `src/data/` if missing.
+ *
+ * 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';
+
+const CHAPTERS_DIR = process.env.BOOK_CHAPTERS_DIR ?? 'src/content/chapters';
+const OUTPUT_PATH = process.env.BOOK_LABELS_OUT ?? 'src/data/labels.json';
+
+/** Component names that participate in cross-referencing. */
+const LABELABLE_TYPES = [
+  'Theorem',
+  'Figure',
+  'ExampleBox',
+  'ResultBox',
+  'NoteBox',
+  'CaseStudy',
+];
+
+/** Display-name prefix used when no `label` override is given. */
+const TYPE_DISPLAY = {
+  Theorem: 'Theorem',
+  Figure: 'Figure',
+  ExampleBox: 'Example',
+  ResultBox: 'Result',
+  NoteBox: 'Note',
+  CaseStudy: 'Case study',
+};
+
+// ===== Frontmatter parsing =====
+
+function parseFrontmatter(source) {
+  // Standard MDX/YAML frontmatter: `---\n…\n---`.
+  const m = source.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return {};
+  const fm = {};
+  for (const line of m[1].split('\n')) {
+    const kv = line.match(/^(\w+)\s*:\s*(.+?)\s*$/);
+    if (!kv) continue;
+    const [, key, raw] = kv;
+    // Strip quotes; coerce numeric scalars.
+    let val = raw.replace(/^["']|["']$/g, '');
+    if (/^-?\d+$/.test(val)) val = parseInt(val, 10);
+    fm[key] = val;
+  }
+  return fm;
+}
+
+function chapterNumberOf(frontmatter) {
+  // Tools profile uses `chapter`; academic uses `week`. Prefer chapter.
+  if (typeof frontmatter.chapter === 'number') return frontmatter.chapter;
+  if (typeof frontmatter.week === 'number') return frontmatter.week;
+  return null;
+}
+
+// ===== Component-invocation parsing =====
+
+/**
+ * Match opening tags of any labelable component, capturing the attrs blob.
+ * Conservative regex: only matches `<ComponentName ... />` or
+ * `<ComponentName ...>` (not closing tags, not self-references in prose).
+ */
+function buildTagRegex() {
+  const names = LABELABLE_TYPES.join('|');
+  return new RegExp(`<(${names})\\b([^>]*?)\\/?>`, 'g');
+}
+
+function extractAttr(attrsBlob, name) {
+  // `name="value"` or `name='value'` or `name={value}`.
+  const dq = attrsBlob.match(new RegExp(`${name}="([^"]*)"`));
+  if (dq) return dq[1];
+  const sq = attrsBlob.match(new RegExp(`${name}='([^']*)'`));
+  if (sq) return sq[1];
+  const ex = attrsBlob.match(new RegExp(`${name}=\\{([^}]*)\\}`));
+  if (ex) return ex[1].trim().replace(/^["'`]|["'`]$/g, '');
+  return null;
+}
+
+// ===== Filesystem walk =====
+
+async function walkChapters(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return out;
+    throw err;
+  }
+  for (const e of entries) {
+    const path = join(dir, e.name);
+    if (e.isDirectory()) {
+      out.push(...(await walkChapters(path)));
+      continue;
+    }
+    if (!e.isFile()) continue;
+    if (!/\.mdx?$/.test(e.name)) continue;
+    if (e.name.startsWith('_')) continue; // hidden by convention
+    out.push(path);
+  }
+  return out;
+}
+
+// ===== Main =====
+
+async function main() {
+  const cwd = process.cwd();
+  const chaptersDir = resolve(cwd, CHAPTERS_DIR);
+  const files = await walkChapters(chaptersDir);
+
+  const labels = {};
+  const tagRegex = buildTagRegex();
+  let totalIds = 0;
+  let chaptersWithIds = 0;
+
+  for (const file of files) {
+    const source = await readFile(file, 'utf8');
+    const fm = parseFrontmatter(source);
+    const chapterNum = chapterNumberOf(fm);
+    const slug = basename(file).replace(/\.mdx?$/, '');
+
+    // Per-chapter counters reset for each file.
+    const counters = {};
+    let foundInChapter = 0;
+
+    for (const match of source.matchAll(tagRegex)) {
+      const [, type, attrs] = match;
+      const id = extractAttr(attrs, 'id');
+      if (!id) continue;
+
+      counters[type] = (counters[type] ?? 0) + 1;
+      foundInChapter += 1;
+      totalIds += 1;
+
+      const labelOverride = extractAttr(attrs, 'label');
+      const display =
+        labelOverride ??
+        (chapterNum != null
+          ? `${TYPE_DISPLAY[type]} ${chapterNum}.${counters[type]}`
+          : `${TYPE_DISPLAY[type]} ${counters[type]}`);
+
+      if (labels[id]) {
+        // Duplicate id — surface but don't fail; consumer's validator
+        // catches collisions with full diagnostic context.
+        process.stderr.write(
+          `build-labels: WARN duplicate id "${id}" (first in ` +
+            `${labels[id].href.split('#')[0]}, now in ${slug})\n`,
+        );
+      }
+      labels[id] = {
+        href: `/chapters/${slug}#${id}`,
+        display,
+      };
+    }
+
+    if (foundInChapter > 0) chaptersWithIds += 1;
+  }
+
+  // Emit deterministic output: keys sorted alphabetically.
+  const sorted = {};
+  for (const k of Object.keys(labels).sort()) sorted[k] = labels[k];
+
+  const outputPath = resolve(cwd, OUTPUT_PATH);
+  await mkdir(dirname(outputPath), { recursive: true });
+  await writeFile(outputPath, JSON.stringify(sorted, null, 2) + '\n', 'utf8');
+
+  process.stdout.write(
+    `build-labels: ${totalIds} id${totalIds === 1 ? '' : 's'} across ` +
+      `${chaptersWithIds} chapter${chaptersWithIds === 1 ? '' : 's'} → ` +
+      `${OUTPUT_PATH}\n`,
+  );
+}
+
+main().catch((err) => {
+  process.stderr.write(`build-labels: fatal: ${err?.message ?? err}\n`);
+  process.exit(1);
+});

package/dist/types-Cz-pwE1N.d.ts

@@ -1,61 +0,0 @@
-import { AstroIntegration, AstroUserConfig } from 'astro';
-
-/**
- * Shared types for @brandon_m_behring/book-scaffold-astro.
- *
- * Public types referenced from PACKAGE_DESIGN.md §4 / §5 / §6. Kept in
- * one place so consumer IntelliSense surfaces a coherent API.
- */
-
-type BookProfile = 'academic' | 'tools' | 'minimal';
-declare const BOOK_PROFILES: readonly ["academic", "tools", "minimal"];
-/**
- * Options for `defineBookConfig`. See PACKAGE_DESIGN.md §4.
- *
- * Note on the index signature: `AstroUserConfig` carries generic
- * parameters (`Locales`, `SessionDriverName`, fonts) that can't be
- * threaded cleanly through a wrapper. Instead we type the package-
- * specific fields strictly and allow arbitrary AstroUserConfig keys
- * via the index signature — consumer types will lint clean but lose
- * full IDE autocomplete on non-package fields. Acceptable trade.
- */
-interface BookConfigOptions {
-    /** Required. Book's deployed origin (sitemap, canonical, Pagefind). */
-    site: string;
-    /**
-     * Optional. Falls back to `process.env.BOOK_PROFILE`, then `'minimal'`.
-     * Explicit param always wins over env.
-     */
-    profile?: BookProfile;
-    /** Optional. Appended to the package-provided integration list. */
-    extraIntegrations?: AstroIntegration[];
-    /**
-     * Optional. CSS basenames to inject in addition to the profile-resolved
-     * set. Cross-profile escape hatch (e.g. an academic book using
-     * `<Convergence>`). Example: `['convergence.css']`.
-     */
-    extraStyles?: string[];
-    /** Optional. Spread-merged into the package-provided markdown config. */
-    markdown?: AstroUserConfig['markdown'];
-    /** Escape hatch for any other AstroUserConfig field. */
-    [key: string]: unknown;
-}
-/** Options for `defineBookSchemas`. See PACKAGE_DESIGN.md §5. */
-interface BookSchemasOptions {
-    profile?: BookProfile;
-    /** Defaults to `'./src/content/chapters'`. */
-    chaptersBase?: string;
-}
-/** Options for the internal `bookScaffoldIntegration`. See PACKAGE_DESIGN.md §6. */
-interface BookScaffoldIntegrationOptions {
-    profile: BookProfile;
-    extraStyles?: string[];
-}
-/** Raised when the resolved profile is not one of `BOOK_PROFILES`. */
-declare class BookConfigError extends Error {
-    constructor(message: string);
-}
-/** Resolve profile from explicit param → env → default. Throws on invalid. */
-declare function resolveProfile(explicit?: BookProfile): BookProfile;
-
-export { BOOK_PROFILES as B, BookConfigError as a, type BookConfigOptions as b, type BookProfile as c, type BookScaffoldIntegrationOptions as d, type BookSchemasOptions as e, resolveProfile as r };