@brandon_m_behring/book-scaffold-astro 3.2.0 → 3.4.0

package/LATEX_TO_MDX_MAPPING.md

@@ -0,0 +1,130 @@
+# LaTeX → MDX component mapping
+
+A consumer-facing reference for converting LaTeX book sources into MDX that consumes `@brandon_m_behring/book-scaffold-astro` components.
+
+The scaffold ships **38 components**. Without this map, a `.tex → .mdx` conversion ends up rediscovering them by grep — and frequently rebuilding duplicates. This doc is the canonical "if your LaTeX source has `\begin{<env>}`, here's the component" reference.
+
+> Pair with [PACKAGE_DESIGN.md](./PACKAGE_DESIGN.md) §17 for the broader migration story and the `defineMdxComponents` helper for consumer-shipped extensions.
+
+## Components shipped by the scaffold
+
+| LaTeX construct | MDX component | Import path | Signature | Notes |
+|---|---|---|---|---|
+| `\begin{tcolorbox}[narrativebox]` | `SkillBox` | `…/components/SkillBox.astro` | `title: string` | Recipe / how-to box |
+| `\begin{tcolorbox}[conceptbox]` | `ConceptBox` | `…/components/ConceptBox.astro` | `term: string` | Single-term definition |
+| `\begin{tcolorbox}[insightbox]` | `InsightBox` | `…/components/InsightBox.astro` | `title?: string` | Non-obvious observation |
+| `\begin{keyconcept}` | `KeyIdea` | `…/components/KeyIdea.astro` | — | Crystallized takeaway |
+| `\begin{warnbox}` / `\warningmargin{}` | `WarnBox` | `…/components/WarnBox.astro` | `title?: string` | Caveats / failure modes |
+| `\begin{notebox}` | `NoteBox` | `…/components/NoteBox.astro` | `title?: string` | Chapter overviews |
+| `\begin{paperbox}` | `PaperBox` | `…/components/PaperBox.astro` | `title?: string` | Paper restatement |
+| `\begin{counterbox}` | `CounterBox` | `…/components/CounterBox.astro` | `title?: string` | Counter-evidence |
+| `\begin{examplebox}` | `ExampleBox` | `…/components/ExampleBox.astro` | `title?: string` | Extended walkthrough |
+| `\begin{openquestion}` | `OpenQuestion` | `…/components/OpenQuestion.astro` | `title?: string` | Research questions |
+| `\begin{trythis}` | `TryThis` | `…/components/TryThis.astro` | `title?: string` | Practice exercise |
+| `\begin{tipbox}` | `TipBox` | `…/components/TipBox.astro` | `title?: string` | Pro tips / shortcuts |
+| `\begin{dynconnect}` | `DynConnect` | `…/components/DynConnect.astro` | `title?: string` | Cross-domain connection |
+| `\begin{theorem}` / `\begin{proposition}` / `\begin{lemma}` / `\begin{corollary}` / `\begin{definition}` / `\begin{remark}` / `\begin{proof}` | `Theorem` | `…/components/Theorem.astro` | `kind, n?, name?, id?` | amsthm family — single component dispatches via `kind` prop |
+| `\marginnote{}` | `MarginNote` | `…/components/MarginNote.astro` | — | Side commentary |
+| `\sidenote{}` | `Sidenote` | `…/components/Sidenote.astro` | — | Auto-numbered marginalia (Tufte) |
+| `\includegraphics + \caption` | `Figure` | `…/components/Figure.astro` | `src, caption?, id?` | XRef-registered |
+| `\cite{}` / `\parencite{}` | `Citation` | `…/components/Citation.astro` | `src, as?` | Resolves `sources` collection |
+| `\cite{}` (inline) | `Cite` | `…/components/Cite.astro` | `key` | Inline citation key |
+| `\xref{}` / `\cref{}` | `XRef` | `…/components/XRef.astro` | `id` | Cross-reference resolver |
+| `\code{path:N}` / inline file refs | `CodeRef` | `…/components/CodeRef.astro` | `path, line?, lineEnd?` | GitHub-linked source ref |
+| (custom Shiki blocks) | `CodeBlock` | `…/components/CodeBlock.astro` | `lang, title?` | Wrapped fenced code |
+| `\recovery{}` | `Recovery` | `…/components/Recovery.astro` | `pattern, symptom?` | Anti-pattern escape |
+| `\casestudy{}` | `CaseStudy` | `…/components/CaseStudy.astro` | `date, title?` | Dated anecdote |
+| `\weekref{}` (academic) | `WeekRef` | `…/components/WeekRef.astro` | `week` | Cross-chapter week ref |
+
+Component subset table for tools-profile-specific UI (volatility dashboards, convergence timelines):
+
+| Construct | Component | Use case |
+|---|---|---|
+| Volatility badge | `Tag` | `volatility` enum chip in chapter meta |
+| Tool comparison | `ToolFilter` (island) | Interactive comparison gate |
+| Version selector | `VersionSelector` (island) | Switch between tool versions |
+| Convergence event | `Convergence` | "All tools converged here" timeline marker |
+| Divergence event | `Divergence` | "Tool X went its own way" annotation |
+| Pattern timeline | `PatternTimeline` | Multi-event convergence dashboard |
+| Status badge | `StatusBadge` | 7→3-state translation (academic) |
+| Source archive | `SourceArchive` | Tier-tagged source listing |
+
+## What is NOT shipped (extension candidates)
+
+The scaffold deliberately doesn't ship these. Add to your consumer via the [`defineMdxComponents`](#consumer-side-extensions-definemdxcomponents) helper described below; surface as a tracked issue if the gap recurs across pilots.
+
+- `\begin{problem}` / `\begin{solution}` — interview-prep problem cards
+- `\begin{vignette}` — multi-step scenario walkthroughs
+- `\begin{decisiontree}` — branching decision logic
+- `\begin{interviewcontext}` — interview-tied learning-outcome callouts
+- `<AnkiCard>` — flashcard widget
+- `<Term>` — glossary term reference with tooltip
+- `<RedFlag>` — escalated warning beyond `WarnBox`
+- `<NarrativeBox>` (with extended props) — if a consumer needs richer narrative annotations beyond `SkillBox`
+
+## Consumer-side extensions: `defineMdxComponents`
+
+When your book uses custom MDX components, create `src/mdx-components.ts` (or `.js` / `.mjs`) at your project root. The scaffold auto-detects it and threads the components through all auto-injected routes (`/print`, future `/pdf`, `/epub`).
+
+```ts
+// consumer's src/mdx-components.ts
+import { defineMdxComponents } from '@brandon_m_behring/book-scaffold-astro';
+import AnkiCard from './components/AnkiCard.astro';
+import NarrativeBox from './components/NarrativeBox.astro';
+import Term from './components/Term.astro';
+
+export default defineMdxComponents({
+  AnkiCard,
+  NarrativeBox,
+  Term,
+});
+```
+
+The `defineMdxComponents<T>()` helper is a TypeScript identity function — it returns the value unchanged, but preserves the exact key→component type mapping for IntelliSense. Same pattern as Vite/Astro `defineConfig`, Zod `z.object`, Drizzle `pgTable`.
+
+To use a non-default path, pass it explicitly:
+
+```ts
+// astro.config.mjs
+export default defineBookConfig({
+  site: '...',
+  mdxComponentsModule: './src/my-custom-components.ts',
+});
+```
+
+## Disabling auto-injected routes
+
+The scaffold auto-injects per-profile defaults (see [PACKAGE_DESIGN.md](./PACKAGE_DESIGN.md) §6). Multi-book consumers (one Astro app, many books under `[book]/[chapter]`) typically want the flat `/chapters` route off:
+
+```ts
+// astro.config.mjs
+import { defineBookConfig } from '@brandon_m_behring/book-scaffold-astro';
+
+export default defineBookConfig({
+  site: '...',
+  profile: 'course-notes',
+  routes: {
+    chapters: false,        // override the profile default
+    convergence: false,
+  },
+});
+```
+
+The shape is fixed (`references | search | print | chapters | convergence`) and TypeScript catches typos like `convergance: false`.
+
+## Common conversion mistakes
+
+Errors observed during the DLAI pilot (closed in v3.3.0 issue #5):
+
+1. **Built `NarrativeBox` from scratch** → should have used `SkillBox`. Same vertical box semantic; `SkillBox` already has the `title` prop.
+2. **Built `ConceptBox` (block container)** → conflicts with scaffold's `ConceptBox` (term-definition signature). Either rename the consumer one (`ConceptBlock`) or use scaffold's signature.
+3. **Built `KeyConcept`** → should have used `KeyIdea`. Same crystallized-takeaway role; the scaffold's name comes from the Tufte-style margin-emphasis convention.
+4. **Built `RedFlag`** → should have used `WarnBox`. Add a higher-severity variant via consumer-side `defineMdxComponents` if needed instead of duplicating WarnBox's semantic.
+5. **Built `Sidenote` with category prop** → conflicts with scaffold's auto-numbered `Sidenote`. The scaffold uses CSS counters; consumer-side category metadata can wrap (e.g., `<TypedSidenote category="recovery"><Sidenote>...</Sidenote></TypedSidenote>`).
+6. **Built duplicate `Citation` and `Figure`** → scaffold's versions are XRef-registered. Use them; extend behavior via wrapper components if richer attribution is needed.
+
+## See also
+
+- [PACKAGE_DESIGN.md](./PACKAGE_DESIGN.md) — full API contract + Phase A planning decisions
+- [README.md](./README.md) — toolkit overview + getting started
+- [CHANGELOG.md](../CHANGELOG.md) — release notes (issue #5 closed in v3.3.0)

package/dist/index.d.ts

@@ -1,135 +1,82 @@
 import { AstroUserConfig, AstroIntegration } from 'astro';
-import { b as BookConfigOptions, d as BookScaffoldIntegrationOptions } from './types-BoCXCvBy.js';
-export { B as BOOK_PROFILES, a as BookConfigError, c as BookProfile, e as BookSchemasOptions, r as resolveProfile } from './types-BoCXCvBy.js';
-import { z } from 'astro/zod';
+import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, y as volatilityLevels } from './types-Bb97Na9S.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, h as CourseNotesChapter, M as MinimalChapter, P as ProfileDefinition, R as RouteToggles, T as ToolsChapter, i as academicChapterSchema, j as academicParts, k as changeKinds, l as changelogSchema, m as chapterStatus, n as courseNotesChapterSchema, o as defineProfile, p as minimalChapterSchema, q as patternCategories, r as patternsSchema, s as resolvePreset, t as resolveProfile, u as sourceTiers, v as sourcesSchema, w as toolSlugs, x as toolsChapterSchema } from './types-Bb97Na9S.js';
+import 'astro/zod';
 
 declare function defineBookConfig(opts: BookConfigOptions): Promise<AstroUserConfig>;
 
 declare function bookScaffoldIntegration(opts: BookScaffoldIntegrationOptions): AstroIntegration;
 
 /**
- * Zod schemas + enum constants for book content collections.
+ * Identity helper — consumers wrap their mdx-components map for TS inference.
+ * Same pattern as Vite/Astro defineConfig: a generic identity function that
+ * preserves the exact shape (vs widening to Record<string, …>).
  *
- * Imports `z` from `astro/zod` (a real module re-export) so schemas can
- * be constructed at package-load time outside an Astro runtime context.
- * `defineBookSchemas` in index.ts wraps these into Astro `defineCollection`
- * calls at the consumer's content-config load time.
+ *   export default defineMdxComponents({ AnkiCard, NarrativeBox });
  *
- * Schemas ported verbatim from v2.0 src/content.config.ts. See
- * PACKAGE_DESIGN.md §5 for the public reproduction.
+ * The generic constraint Record<string, unknown> is intentionally loose:
+ * consumer components are `.astro` files whose runtime type
+ * (AstroComponentFactory) lives in `astro/runtime/server/index.js` — not a
+ * public Astro export, and importing from internals creates fragility. The
+ * looser constraint lets the helper compile cleanly across Astro versions;
+ * IntelliSense still surfaces exact keys.
  */
+declare function defineMdxComponents<T extends Record<string, unknown>>(components: T): T;
 
-declare const toolSlugs: readonly ["claude-code", "gemini-cli", "codex-cli", "cross-tool"];
-declare const volatilityLevels: readonly ["stable-principle", "architectural-pattern", "feature-surface"];
-declare const sourceTiers: readonly ["T1-official", "T2-release-notes", "T3-practitioner", "T4-conjecture"];
-declare const changeKinds: readonly ["added", "removed", "changed", "deprecated"];
-declare const patternCategories: readonly ["safety", "scale", "context", "interaction", "extension", "other"];
-declare const academicParts: readonly ["foundations", "ssm-core", "beyond-ssm", "integration", "synthesis"];
-declare const chapterStatus: readonly ["implemented", "chapter_only", "reading_only", "prose_only", "code_only", "scaffolded", "planned"];
-declare const academicChapterSchema: z.ZodObject<{
-    week: z.ZodNumber;
-    part: z.ZodEnum<{
-        foundations: "foundations";
-        "ssm-core": "ssm-core";
-        "beyond-ssm": "beyond-ssm";
-        integration: "integration";
-        synthesis: "synthesis";
-    }>;
-    title: z.ZodString;
-    status: z.ZodEnum<{
-        implemented: "implemented";
-        chapter_only: "chapter_only";
-        reading_only: "reading_only";
-        prose_only: "prose_only";
-        code_only: "code_only";
-        scaffolded: "scaffolded";
-        planned: "planned";
-    }>;
-    roadmap_lines: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
-    code_path: z.ZodOptional<z.ZodString>;
-    tests_path: z.ZodOptional<z.ZodString>;
-    notebook_path: z.ZodOptional<z.ZodString>;
-    description: z.ZodOptional<z.ZodString>;
-    draft: z.ZodDefault<z.ZodBoolean>;
-}, z.core.$strip>;
-declare const toolsChapterSchema: z.ZodObject<{
-    title: z.ZodString;
-    part: z.ZodNumber;
-    chapter: z.ZodNumber;
-    volatility: z.ZodEnum<{
-        "stable-principle": "stable-principle";
-        "architectural-pattern": "architectural-pattern";
-        "feature-surface": "feature-surface";
-    }>;
-    tools_compared: z.ZodArray<z.ZodEnum<{
-        "claude-code": "claude-code";
-        "gemini-cli": "gemini-cli";
-        "codex-cli": "codex-cli";
-        "cross-tool": "cross-tool";
-    }>>;
-    last_verified: z.ZodDate;
-    sources: z.ZodDefault<z.ZodArray<z.ZodString>>;
-    description: z.ZodOptional<z.ZodString>;
-    draft: z.ZodDefault<z.ZodBoolean>;
-    updated: z.ZodOptional<z.ZodDate>;
-}, z.core.$strip>;
-declare const sourcesSchema: z.ZodObject<{
-    url: z.ZodString;
-    title: z.ZodString;
-    author: z.ZodOptional<z.ZodString>;
-    publish_date: z.ZodOptional<z.ZodDate>;
-    captured_at: z.ZodDate;
-    content_hash: z.ZodOptional<z.ZodString>;
-    tier: z.ZodEnum<{
-        "T1-official": "T1-official";
-        "T2-release-notes": "T2-release-notes";
-        "T3-practitioner": "T3-practitioner";
-        "T4-conjecture": "T4-conjecture";
-    }>;
-    tool: z.ZodEnum<{
-        "claude-code": "claude-code";
-        "gemini-cli": "gemini-cli";
-        "codex-cli": "codex-cli";
-        "cross-tool": "cross-tool";
-    }>;
-    perma_cc: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    local_cache: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-}, z.core.$strip>;
-declare const changelogSchema: z.ZodObject<{
-    tool: z.ZodEnum<{
-        "claude-code": "claude-code";
-        "gemini-cli": "gemini-cli";
-        "codex-cli": "codex-cli";
-        "cross-tool": "cross-tool";
-    }>;
-    versions: z.ZodDefault<z.ZodArray<z.ZodObject<{
-        version: z.ZodString;
-        date: z.ZodDate;
-        changes: z.ZodDefault<z.ZodArray<z.ZodObject<{
-            pattern: z.ZodString;
-            kind: z.ZodEnum<{
-                added: "added";
-                removed: "removed";
-                changed: "changed";
-                deprecated: "deprecated";
-            }>;
-            note: z.ZodString;
-            source_key: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>>;
-    }, z.core.$strip>>>;
-}, z.core.$strip>;
-declare const patternsSchema: z.ZodObject<{
-    name: z.ZodString;
-    description: z.ZodOptional<z.ZodString>;
-    category: z.ZodOptional<z.ZodEnum<{
-        safety: "safety";
-        scale: "scale";
-        context: "context";
-        interaction: "interaction";
-        extension: "extension";
-        other: "other";
-    }>>;
-    convergence_date: z.ZodOptional<z.ZodNullable<z.ZodDate>>;
-}, z.core.$strip>;
+/**
+ * src/lib/freshness.ts — volatility-aware staleness computation.
+ *
+ * Each chapter carries a `last_verified` date and a `volatility` class.
+ * This module maps those to a freshness status the reader can trust.
+ *
+ * Thresholds chosen to align with Ch 15's source-tier audit cadences:
+ *   stable-principle      → 365 days (principles drift annually at most)
+ *   architectural-pattern → 180 days (between annual and quarterly; "on
+ *                                     major release" isn't derivable from
+ *                                     frontmatter)
+ *   feature-surface       → 90 days  (quarterly)
+ *
+ * Status bands (fraction of threshold):
+ *   fresh       (<75%)   — green dot, unobtrusive
+ *   verify-soon (75-100%) — yellow, mild warning
+ *   stale       (>100%)  — amber/red, "verify before trusting"
+ *
+ * Example assertions (verified by visual inspection during Stage 3.1):
+ *   getFreshness(today, 'feature-surface').status     === 'fresh'
+ *   getFreshness(today-70d, 'feature-surface').status === 'verify-soon'
+ *   getFreshness(today-100d, 'feature-surface').status === 'stale'
+ *   getFreshness(today-200d, 'stable-principle').status === 'fresh'
+ *   getFreshness(today-300d, 'stable-principle').status === 'verify-soon'
+ */
+
+type VolatilityLevel = (typeof volatilityLevels)[number];
+type FreshnessStatus = 'fresh' | 'verify-soon' | 'stale';
+interface Freshness {
+    status: FreshnessStatus;
+    daysOld: number;
+    thresholdDays: number;
+    /** Days until stale; negative when already stale. */
+    daysUntil: number;
+}
+/**
+ * Compute freshness for a chapter given its last_verified date + volatility.
+ *
+ * Pure function; caller supplies `now` only in tests. Production callers omit.
+ *
+ * v3.3.0 (closes issue #1): tolerant of `lastVerified === undefined`. Returns
+ * `null` instead of crashing when the chapter schema omits the field (e.g.,
+ * academic profile chapters that don't track verification dates, or consumer
+ * schemas that don't declare last_verified).
+ *
+ * Callers compose with optional chaining:
+ *   const status = getFreshness(d.last_verified, d.volatility)?.status;
+ */
+declare function getFreshness(lastVerified: Date | undefined, volatility: VolatilityLevel, now?: Date): Freshness | null;
+/** Human-readable label for each status; used for ARIA + tooltips.
+ *
+ * v3.3.0: accepts `null` (the new return shape of getFreshness for undefined
+ * inputs). Returns a sentinel "unknown" label so callers can render a neutral
+ * affordance without a separate branch. */
+declare function freshnessLabel(f: Freshness | null): string;
 
-export { BookConfigOptions, BookScaffoldIntegrationOptions, academicChapterSchema, academicParts, bookScaffoldIntegration, changeKinds, changelogSchema, chapterStatus, defineBookConfig, patternCategories, patternsSchema, sourceTiers, sourcesSchema, toolSlugs, toolsChapterSchema, volatilityLevels };
+export { BookConfigOptions, BookScaffoldIntegrationOptions, type Freshness, type FreshnessStatus, type VolatilityLevel, bookScaffoldIntegration, defineBookConfig, defineMdxComponents, freshnessLabel, getFreshness, volatilityLevels };