@brandon_m_behring/book-scaffold-astro 3.0.0-alpha.0

package/dist/index.mjs

@@ -0,0 +1,369 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/lib/katex-macros.ts
+var katex_macros_exports = {};
+__export(katex_macros_exports, {
+  ssmMacros: () => ssmMacros
+});
+var ssmMacros;
+var init_katex_macros = __esm({
+  "src/lib/katex-macros.ts"() {
+    "use strict";
+    ssmMacros = {
+      // -----------------------------------------------------------------
+      // Compatibility alias: \bm{x} -> \boldsymbol{x}
+      // KaTeX does not ship \bm. The LaTeX source uses \bm extensively in
+      // ssm-notation.tex for vectors and matrices.
+      // -----------------------------------------------------------------
+      "\\bm": "\\boldsymbol{#1}",
+      // -----------------------------------------------------------------
+      // SSM state space variables (ssm-notation.tex:5-13)
+      // -----------------------------------------------------------------
+      "\\statevec": "\\boldsymbol{h}",
+      // state vector h_t
+      "\\statemat": "\\boldsymbol{A}",
+      // dynamics matrix A
+      "\\inputmat": "\\boldsymbol{B}",
+      // input matrix B
+      "\\outputmat": "\\boldsymbol{C}",
+      // output matrix C
+      "\\feedmat": "\\boldsymbol{D}",
+      // feedthrough matrix D
+      "\\stepsize": "\\Delta",
+      // discretization step
+      "\\discA": "\\bar{\\boldsymbol{A}}",
+      // discretized A
+      "\\discB": "\\bar{\\boldsymbol{B}}",
+      // discretized B
+      // -----------------------------------------------------------------
+      // Dimensions (ssm-notation.tex:16-18)
+      // -----------------------------------------------------------------
+      "\\seqlen": "L",
+      // sequence length
+      "\\statedim": "N",
+      // state dimension
+      "\\inputdim": "D",
+      // input / model dimension
+      // -----------------------------------------------------------------
+      // Scan operator (ssm-notation.tex:23-24)
+      // -----------------------------------------------------------------
+      "\\scanop": "\\oplus",
+      // associative binary operator for diagonal SSMs
+      "\\elemwise": "\\odot",
+      // element-wise product
+      // -----------------------------------------------------------------
+      // Dynamical systems (ssm-notation.tex:27-30)
+      // -----------------------------------------------------------------
+      "\\monodromy": "\\boldsymbol{Z}",
+      // monodromy matrix Z(T)
+      "\\floquet": "\\mu",
+      // Floquet multiplier
+      "\\lyapexp": "\\lambda",
+      // Lyapunov exponent
+      "\\jacobian": "\\boldsymbol{J}",
+      // Jacobian matrix
+      // -----------------------------------------------------------------
+      // Calculus shortcuts (ssm-notation.tex:33-35)
+      // -----------------------------------------------------------------
+      "\\ddt": "\\frac{d}{dt}",
+      "\\pderiv": "\\frac{\\partial #1}{\\partial #2}",
+      // 2 args
+      "\\spectralradius": "\\rho",
+      // -----------------------------------------------------------------
+      // Common sets (preamble:390-393)
+      // -----------------------------------------------------------------
+      "\\R": "\\mathbb{R}",
+      "\\C": "\\mathbb{C}",
+      "\\N": "\\mathbb{N}",
+      "\\Z": "\\mathbb{Z}",
+      // -----------------------------------------------------------------
+      // Probability / statistics (preamble:396-397)
+      // -----------------------------------------------------------------
+      "\\E": "\\mathbb{E}",
+      "\\Prob": "\\mathbb{P}",
+      // -----------------------------------------------------------------
+      // Norms and inner products (preamble:400-402)
+      // -----------------------------------------------------------------
+      "\\norm": "\\lVert #1 \\rVert",
+      "\\ip": "\\langle #1, #2 \\rangle",
+      "\\abs": "\\lvert #1 \\rvert",
+      // -----------------------------------------------------------------
+      // Operators (preamble:405-410)
+      // \DeclareMathOperator* -> \operatorname* (with limits below in display)
+      // \DeclareMathOperator  -> \operatorname
+      // -----------------------------------------------------------------
+      "\\argmax": "\\operatorname*{arg\\,max}",
+      "\\argmin": "\\operatorname*{arg\\,min}",
+      "\\diag": "\\operatorname{diag}",
+      "\\tr": "\\operatorname{tr}",
+      "\\spec": "\\operatorname{spec}",
+      "\\rank": "\\operatorname{rank}",
+      // -----------------------------------------------------------------
+      // Complexity (preamble:413)
+      // -----------------------------------------------------------------
+      "\\bigO": "\\mathcal{O}(#1)"
+    };
+  }
+});
+
+// src/config.ts
+import mdx from "@astrojs/mdx";
+import preact from "@astrojs/preact";
+
+// src/types.ts
+var BOOK_PROFILES = ["academic", "tools", "minimal"];
+var BookConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BookConfigError";
+  }
+};
+function resolveProfile(explicit) {
+  const candidate = explicit ?? process.env.BOOK_PROFILE ?? "minimal";
+  if (!BOOK_PROFILES.includes(candidate)) {
+    throw new BookConfigError(
+      `profile must be one of ${BOOK_PROFILES.join(" | ")} (got ${JSON.stringify(candidate)})`
+    );
+  }
+  if (!explicit && !process.env.BOOK_PROFILE) {
+    console.warn("book-scaffold-astro: BOOK_PROFILE not set; falling back to 'minimal'.");
+  }
+  return candidate;
+}
+
+// src/integration.ts
+import { fileURLToPath } from "url";
+var PACKAGE_NAME = "@brandon_m_behring/book-scaffold-astro";
+var ALWAYS_ON_STYLES = [
+  "tokens.css",
+  "layout.css",
+  "callouts.css",
+  "chapter.css",
+  "typography.css",
+  "print.css"
+];
+var TOOLS_ONLY_STYLES = ["convergence.css", "tool-filter.css"];
+var DEFAULT_ROUTES_ALL = [
+  { pattern: "/chapters", file: "chapters.astro" },
+  { pattern: "/references", file: "references.astro" },
+  { pattern: "/print", file: "print.astro" },
+  { pattern: "/search", file: "search.astro" }
+];
+var DEFAULT_ROUTES_TOOLS = [
+  { pattern: "/convergence", file: "convergence.astro" }
+];
+function resolvePage(file) {
+  return fileURLToPath(new URL(`../pages/${file}`, import.meta.url));
+}
+function bookScaffoldIntegration(opts) {
+  const { profile, extraStyles = [] } = opts;
+  return {
+    name: "book-scaffold-astro",
+    hooks: {
+      "astro:config:setup": ({ injectScript, injectRoute }) => {
+        const styles = profile === "tools" ? [...ALWAYS_ON_STYLES, ...TOOLS_ONLY_STYLES, ...extraStyles] : [...ALWAYS_ON_STYLES, ...extraStyles];
+        for (const sheet of styles) {
+          injectScript("page-ssr", `import '${PACKAGE_NAME}/styles/${sheet}';`);
+        }
+        const routes = profile === "tools" ? [...DEFAULT_ROUTES_ALL, ...DEFAULT_ROUTES_TOOLS] : [...DEFAULT_ROUTES_ALL];
+        for (const route of routes) {
+          injectRoute({
+            pattern: route.pattern,
+            entrypoint: resolvePage(route.file)
+          });
+        }
+      }
+    }
+  };
+}
+
+// src/config.ts
+async function defineBookConfig(opts) {
+  const profile = resolveProfile(opts.profile);
+  const remarkPlugins = [];
+  const rehypePlugins = [];
+  if (profile === "academic") {
+    const { default: remarkMath } = await import("remark-math");
+    const { default: rehypeKatex } = await import("rehype-katex");
+    const { ssmMacros: ssmMacros2 } = await Promise.resolve().then(() => (init_katex_macros(), katex_macros_exports));
+    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: ssmMacros2
+      }
+    ]);
+  }
+  const integrations = [
+    mdx(),
+    preact(),
+    bookScaffoldIntegration({ profile, extraStyles: opts.extraStyles }),
+    ...opts.extraIntegrations ?? []
+  ];
+  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 ?? {}
+    },
+    remarkPlugins: [...remarkPlugins, ...userMarkdown.remarkPlugins ?? []],
+    rehypePlugins: [...rehypePlugins, ...userMarkdown.rehypePlugins ?? []],
+    ...userMarkdown
+  };
+  const {
+    profile: _profile,
+    extraIntegrations: _extraIntegrations,
+    extraStyles: _extraStyles,
+    markdown: _markdown,
+    ...rest
+  } = opts;
+  void _profile;
+  void _extraIntegrations;
+  void _extraStyles;
+  void _markdown;
+  const config = {
+    ...rest,
+    integrations,
+    markdown
+  };
+  return config;
+}
+
+// src/schemas.ts
+import { z } from "astro/zod";
+var toolSlugs = [
+  "claude-code",
+  "gemini-cli",
+  "codex-cli",
+  "cross-tool"
+];
+var volatilityLevels = [
+  "stable-principle",
+  "architectural-pattern",
+  "feature-surface"
+];
+var sourceTiers = [
+  "T1-official",
+  "T2-release-notes",
+  "T3-practitioner",
+  "T4-conjecture"
+];
+var changeKinds = ["added", "removed", "changed", "deprecated"];
+var patternCategories = [
+  "safety",
+  "scale",
+  "context",
+  "interaction",
+  "extension",
+  "other"
+];
+var academicParts = [
+  "foundations",
+  "ssm-core",
+  "beyond-ssm",
+  "integration",
+  "synthesis"
+];
+var chapterStatus = [
+  "implemented",
+  "chapter_only",
+  "reading_only",
+  "prose_only",
+  "code_only",
+  "scaffolded",
+  "planned"
+];
+var academicChapterSchema = z.object({
+  week: z.number().int().min(1).max(99),
+  part: z.enum(academicParts),
+  title: z.string().min(1),
+  status: z.enum(chapterStatus),
+  roadmap_lines: z.tuple([z.number().int(), z.number().int()]).optional(),
+  code_path: z.string().optional(),
+  tests_path: z.string().optional(),
+  notebook_path: z.string().optional(),
+  description: z.string().optional(),
+  draft: z.boolean().default(false)
+});
+var toolsChapterSchema = z.object({
+  title: z.string().min(1),
+  part: z.number().int().min(0).max(10),
+  chapter: z.number().int().min(0).max(99),
+  volatility: z.enum(volatilityLevels),
+  tools_compared: z.array(z.enum(toolSlugs)).min(1),
+  last_verified: z.date(),
+  sources: z.array(z.string()).default([]),
+  description: z.string().optional(),
+  draft: z.boolean().default(false),
+  updated: z.date().optional()
+});
+var sourcesSchema = z.object({
+  url: z.string().url(),
+  title: z.string().min(1),
+  author: z.string().optional(),
+  publish_date: z.date().optional(),
+  captured_at: z.date(),
+  content_hash: z.string().regex(/^sha256:[a-f0-9]+$/).optional(),
+  tier: z.enum(sourceTiers),
+  tool: z.enum(toolSlugs),
+  perma_cc: z.string().url().nullable().optional(),
+  local_cache: z.string().nullable().optional()
+});
+var changelogSchema = z.object({
+  tool: z.enum(toolSlugs),
+  versions: z.array(
+    z.object({
+      version: z.string().min(1),
+      date: z.date(),
+      changes: z.array(
+        z.object({
+          pattern: z.string(),
+          kind: z.enum(changeKinds),
+          note: z.string().min(1),
+          source_key: z.string().optional()
+        })
+      ).default([])
+    })
+  ).default([])
+});
+var patternsSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().optional(),
+  category: z.enum(patternCategories).optional(),
+  convergence_date: z.date().nullable().optional()
+});
+export {
+  BOOK_PROFILES,
+  BookConfigError,
+  academicChapterSchema,
+  academicParts,
+  bookScaffoldIntegration,
+  changeKinds,
+  changelogSchema,
+  chapterStatus,
+  defineBookConfig,
+  patternCategories,
+  patternsSchema,
+  resolveProfile,
+  sourceTiers,
+  sourcesSchema,
+  toolSlugs,
+  toolsChapterSchema,
+  volatilityLevels
+};

package/dist/lib/katex-macros.d.ts

@@ -0,0 +1,26 @@
+/**
+ * src/lib/katex-macros.ts — KaTeX macro definitions ported from the LaTeX guide.
+ *
+ * Source files in the LaTeX tree:
+ *   - guides/shared/ssm-notation.tex   (20 SSM-specific macros)
+ *   - guides/shared/ssm-guide-preamble.sty:387-413  (16 general math macros)
+ *
+ * Wired into astro.config.mjs via:
+ *   rehypeKatex({ strict: 'error', macros: ssmMacros, trust: true })
+ *
+ * KaTeX-specific adaptations:
+ *   - \bm is not part of KaTeX; aliased to \boldsymbol (visually identical
+ *     in stix-two / Computer Modern math fonts).
+ *   - \DeclareMathOperator and \DeclareMathOperator* are translated to
+ *     \operatorname / \operatorname* respectively.
+ *   - \psmallmatrix is an environment in amsmath, not a macro. KaTeX
+ *     macros operate at command level; substitution happens in the
+ *     converter script (latex-to-mdx.mjs in Phase 2.7) — search for
+ *     \begin{psmallmatrix} and replace with \begin{pmatrix}.
+ *
+ * Equation numbering is handled by a separate remark plugin (deferred to
+ * a follow-up session per plan Phase 2.1 Task #9).
+ */
+declare const ssmMacros: Record<string, string>;
+
+export { ssmMacros };

package/dist/lib/katex-macros.mjs

@@ -0,0 +1,98 @@
+// src/lib/katex-macros.ts
+var ssmMacros = {
+  // -----------------------------------------------------------------
+  // Compatibility alias: \bm{x} -> \boldsymbol{x}
+  // KaTeX does not ship \bm. The LaTeX source uses \bm extensively in
+  // ssm-notation.tex for vectors and matrices.
+  // -----------------------------------------------------------------
+  "\\bm": "\\boldsymbol{#1}",
+  // -----------------------------------------------------------------
+  // SSM state space variables (ssm-notation.tex:5-13)
+  // -----------------------------------------------------------------
+  "\\statevec": "\\boldsymbol{h}",
+  // state vector h_t
+  "\\statemat": "\\boldsymbol{A}",
+  // dynamics matrix A
+  "\\inputmat": "\\boldsymbol{B}",
+  // input matrix B
+  "\\outputmat": "\\boldsymbol{C}",
+  // output matrix C
+  "\\feedmat": "\\boldsymbol{D}",
+  // feedthrough matrix D
+  "\\stepsize": "\\Delta",
+  // discretization step
+  "\\discA": "\\bar{\\boldsymbol{A}}",
+  // discretized A
+  "\\discB": "\\bar{\\boldsymbol{B}}",
+  // discretized B
+  // -----------------------------------------------------------------
+  // Dimensions (ssm-notation.tex:16-18)
+  // -----------------------------------------------------------------
+  "\\seqlen": "L",
+  // sequence length
+  "\\statedim": "N",
+  // state dimension
+  "\\inputdim": "D",
+  // input / model dimension
+  // -----------------------------------------------------------------
+  // Scan operator (ssm-notation.tex:23-24)
+  // -----------------------------------------------------------------
+  "\\scanop": "\\oplus",
+  // associative binary operator for diagonal SSMs
+  "\\elemwise": "\\odot",
+  // element-wise product
+  // -----------------------------------------------------------------
+  // Dynamical systems (ssm-notation.tex:27-30)
+  // -----------------------------------------------------------------
+  "\\monodromy": "\\boldsymbol{Z}",
+  // monodromy matrix Z(T)
+  "\\floquet": "\\mu",
+  // Floquet multiplier
+  "\\lyapexp": "\\lambda",
+  // Lyapunov exponent
+  "\\jacobian": "\\boldsymbol{J}",
+  // Jacobian matrix
+  // -----------------------------------------------------------------
+  // Calculus shortcuts (ssm-notation.tex:33-35)
+  // -----------------------------------------------------------------
+  "\\ddt": "\\frac{d}{dt}",
+  "\\pderiv": "\\frac{\\partial #1}{\\partial #2}",
+  // 2 args
+  "\\spectralradius": "\\rho",
+  // -----------------------------------------------------------------
+  // Common sets (preamble:390-393)
+  // -----------------------------------------------------------------
+  "\\R": "\\mathbb{R}",
+  "\\C": "\\mathbb{C}",
+  "\\N": "\\mathbb{N}",
+  "\\Z": "\\mathbb{Z}",
+  // -----------------------------------------------------------------
+  // Probability / statistics (preamble:396-397)
+  // -----------------------------------------------------------------
+  "\\E": "\\mathbb{E}",
+  "\\Prob": "\\mathbb{P}",
+  // -----------------------------------------------------------------
+  // Norms and inner products (preamble:400-402)
+  // -----------------------------------------------------------------
+  "\\norm": "\\lVert #1 \\rVert",
+  "\\ip": "\\langle #1, #2 \\rangle",
+  "\\abs": "\\lvert #1 \\rvert",
+  // -----------------------------------------------------------------
+  // Operators (preamble:405-410)
+  // \DeclareMathOperator* -> \operatorname* (with limits below in display)
+  // \DeclareMathOperator  -> \operatorname
+  // -----------------------------------------------------------------
+  "\\argmax": "\\operatorname*{arg\\,max}",
+  "\\argmin": "\\operatorname*{arg\\,min}",
+  "\\diag": "\\operatorname{diag}",
+  "\\tr": "\\operatorname{tr}",
+  "\\spec": "\\operatorname{spec}",
+  "\\rank": "\\operatorname{rank}",
+  // -----------------------------------------------------------------
+  // Complexity (preamble:413)
+  // -----------------------------------------------------------------
+  "\\bigO": "\\mathcal{O}(#1)"
+};
+export {
+  ssmMacros
+};

package/dist/schemas.d.ts

@@ -0,0 +1,17 @@
+import { e as BookSchemasOptions } from './types-Cz-pwE1N.js';
+import 'astro';
+
+/**
+ * Returns the package's default content collections. Closed shape per Q5;
+ * consumer extends via object spread and Zod `.extend()` (see PACKAGE_DESIGN.md §5).
+ */
+declare function defineBookSchemas(opts?: BookSchemasOptions): {
+    collections: {
+        chapters: unknown;
+        sources: unknown;
+        changelog: unknown;
+        patterns: unknown;
+    };
+};
+
+export { defineBookSchemas };

package/dist/schemas.mjs

@@ -0,0 +1,160 @@
+// src/schemas-entry.ts
+import { defineCollection } from "astro:content";
+import { glob, file } from "astro/loaders";
+
+// src/types.ts
+var BOOK_PROFILES = ["academic", "tools", "minimal"];
+var BookConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BookConfigError";
+  }
+};
+function resolveProfile(explicit) {
+  const candidate = explicit ?? process.env.BOOK_PROFILE ?? "minimal";
+  if (!BOOK_PROFILES.includes(candidate)) {
+    throw new BookConfigError(
+      `profile must be one of ${BOOK_PROFILES.join(" | ")} (got ${JSON.stringify(candidate)})`
+    );
+  }
+  if (!explicit && !process.env.BOOK_PROFILE) {
+    console.warn("book-scaffold-astro: BOOK_PROFILE not set; falling back to 'minimal'.");
+  }
+  return candidate;
+}
+
+// src/schemas.ts
+import { z } from "astro/zod";
+var toolSlugs = [
+  "claude-code",
+  "gemini-cli",
+  "codex-cli",
+  "cross-tool"
+];
+var volatilityLevels = [
+  "stable-principle",
+  "architectural-pattern",
+  "feature-surface"
+];
+var sourceTiers = [
+  "T1-official",
+  "T2-release-notes",
+  "T3-practitioner",
+  "T4-conjecture"
+];
+var changeKinds = ["added", "removed", "changed", "deprecated"];
+var patternCategories = [
+  "safety",
+  "scale",
+  "context",
+  "interaction",
+  "extension",
+  "other"
+];
+var academicParts = [
+  "foundations",
+  "ssm-core",
+  "beyond-ssm",
+  "integration",
+  "synthesis"
+];
+var chapterStatus = [
+  "implemented",
+  "chapter_only",
+  "reading_only",
+  "prose_only",
+  "code_only",
+  "scaffolded",
+  "planned"
+];
+var academicChapterSchema = z.object({
+  week: z.number().int().min(1).max(99),
+  part: z.enum(academicParts),
+  title: z.string().min(1),
+  status: z.enum(chapterStatus),
+  roadmap_lines: z.tuple([z.number().int(), z.number().int()]).optional(),
+  code_path: z.string().optional(),
+  tests_path: z.string().optional(),
+  notebook_path: z.string().optional(),
+  description: z.string().optional(),
+  draft: z.boolean().default(false)
+});
+var toolsChapterSchema = z.object({
+  title: z.string().min(1),
+  part: z.number().int().min(0).max(10),
+  chapter: z.number().int().min(0).max(99),
+  volatility: z.enum(volatilityLevels),
+  tools_compared: z.array(z.enum(toolSlugs)).min(1),
+  last_verified: z.date(),
+  sources: z.array(z.string()).default([]),
+  description: z.string().optional(),
+  draft: z.boolean().default(false),
+  updated: z.date().optional()
+});
+var sourcesSchema = z.object({
+  url: z.string().url(),
+  title: z.string().min(1),
+  author: z.string().optional(),
+  publish_date: z.date().optional(),
+  captured_at: z.date(),
+  content_hash: z.string().regex(/^sha256:[a-f0-9]+$/).optional(),
+  tier: z.enum(sourceTiers),
+  tool: z.enum(toolSlugs),
+  perma_cc: z.string().url().nullable().optional(),
+  local_cache: z.string().nullable().optional()
+});
+var changelogSchema = z.object({
+  tool: z.enum(toolSlugs),
+  versions: z.array(
+    z.object({
+      version: z.string().min(1),
+      date: z.date(),
+      changes: z.array(
+        z.object({
+          pattern: z.string(),
+          kind: z.enum(changeKinds),
+          note: z.string().min(1),
+          source_key: z.string().optional()
+        })
+      ).default([])
+    })
+  ).default([])
+});
+var patternsSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().optional(),
+  category: z.enum(patternCategories).optional(),
+  convergence_date: z.date().nullable().optional()
+});
+
+// src/schemas-entry.ts
+function defineBookSchemas(opts = {}) {
+  const profile = resolveProfile(opts.profile);
+  const chaptersBase = opts.chaptersBase ?? "./src/content/chapters";
+  const chapters = defineCollection({
+    loader: glob({
+      // Exclude underscore-prefixed files (standard "hidden" convention).
+      pattern: ["**/*.{md,mdx}", "!**/_*"],
+      base: chaptersBase
+    }),
+    schema: profile === "academic" ? academicChapterSchema : toolsChapterSchema
+  });
+  const sources = defineCollection({
+    loader: file("sources/manifest.yaml"),
+    schema: sourcesSchema
+  });
+  const changelog = defineCollection({
+    loader: glob({ pattern: "*.yaml", base: "./changelog/tools" }),
+    schema: changelogSchema
+  });
+  const patterns = defineCollection({
+    loader: file("changelog/patterns.yaml"),
+    schema: patternsSchema
+  });
+  return {
+    collections: { chapters, sources, changelog, patterns }
+  };
+}
+export {
+  defineBookSchemas
+};