@brandon_m_behring/book-scaffold-astro 4.14.3 → 4.16.0

package/CLAUDE.md

@@ -100,7 +100,7 @@ Two callout families coexist. Authors import what they need.
 
 **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`).
+**Utility components** (`src/components/`, any profile): `Cite`, `XRef`, `Figure`, `MarginNote`, `Sidenote`, `WeekRef`, `CodeRef`, `CodeBlock`, `Tag`, `StatusBadge`, `BookLink` (v4.16.0+; cross-book link — `<BookLink book="design" to="…"/>` resolves `book` against `defineBookConfig({ siblingBooks })` and throws on an unknown book; `<XRef>` is in-book only — #96), `PocLayout` (v4.1.0+; wraps slot in a per-`kind` layout shell — 5 closed-union kinds; see `recipes/15-defining-styles.md`).
 
 **Provenance** (v4.8.0, any profile, **auto-injected by the chapter route — not author-imported**): per-chapter "How this was made" audit-trail block, rendered from the optional `provenance` frontmatter (`ai_tools`, `prompts_archive`, `decisions_log`, `audit_history`, `citation_backstop`). **Opt-out**: a chapter with no `provenance` shows a fallback ("Audit history not yet recorded"). Distinct from `AICollaborationDisclosure` (book-level, manual model+role disclosure). Repo-relative path fields render as `<code>`; only `http(s)` values link.
 

package/components/BookLink.astro

@@ -0,0 +1,32 @@
+---
+/**
+ * BookLink — cross-book link to a sibling scaffold book (#96).
+ *
+ * Each scaffold book is a separate Astro app with its own `labels.json` and
+ * deploy origin, so `<XRef>` can't reach a sibling — a cross-book ref resolves
+ * against the wrong labels and dies. `<BookLink book="design" to="…">` resolves
+ * `book` against the consumer's `siblingBooks` registry
+ * (`defineBookConfig({ siblingBooks })`) — the single place to update when a
+ * sibling redeploys or extracts to its own repo. An unknown `book` throws at
+ * build (fail-loud, see `src/lib/book-link`), never a dead cross-origin link.
+ *
+ * `to` is a path within the sibling book (its router shape), e.g.
+ * `chapters/<slug>/#<id>`. Phase 1 builds the href; Phase 2 (deferred) will
+ * validate `to` against a vendored sibling `labels.json`.
+ *
+ * Usage:
+ *   For design depth see
+ *   <BookLink book="design" to="chapters/patterns/#layered">the layered pattern</BookLink>.
+ */
+import bookConfig from 'virtual:book-scaffold/book-config';
+import { resolveBookHref } from '../src/lib/book-link';
+
+interface Props {
+  book: string;
+  to: string;
+}
+
+const { book, to } = Astro.props;
+const href = resolveBookHref(bookConfig.siblingBooks, book, to);
+---
+<a href={href} rel="external noopener" class="book-link"><slot /></a>

package/components/CodeBlock.astro

@@ -4,9 +4,9 @@
  * build time, with syntax highlighting and a "View on GitHub" header
  * link pointing to the exact line range.
  *
- * Reads the file from the repo root (resolved relative to
- * guides/web/), slices `lines` ("N-M" or "N"), and hands the snippet
- * to Astro's `<Code>` component for Shiki rendering.
+ * Reads the file from the code repo root (the consumer's project root by
+ * default; set BOOK_REPO_ROOT for a monorepo subdir layout), slices `lines`
+ * ("N-M" or "N"), and hands the snippet to Astro's `<Code>` for Shiki.
  *
  * Build fails if:
  *   - The file does not exist on disk
@@ -28,6 +28,7 @@ import { Code } from 'astro:components';
 import { readFileSync, existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { buildGithubUrl } from '../src/lib/repo-url';
+import bookConfig from 'virtual:book-scaffold/book-config';
 
 interface Props {
   src: string;
@@ -37,11 +38,15 @@ interface Props {
 
 const { src, lines, lang } = Astro.props;
 
-// Resolve src relative to repo root. Astro's build runs with cwd =
-// guides/web/, so the repo root is two levels up. Using process.cwd()
+// #109: resolve src relative to the code repo root. Defaults to the consumer's
+// project root (process.cwd() during astro build — book + code in one repo);
+// set BOOK_REPO_ROOT when the code lives elsewhere (e.g. a monorepo where the
+// book is a subdir, the old guides/web/ → '../..' case). Using an env + cwd
 // (not import.meta.dirname) survives Astro's bundling — at runtime
 // import.meta.dirname points to the emitted .mjs chunk, not the source.
-const REPO_ROOT = resolve(process.cwd(), '..', '..');
+const REPO_ROOT = process.env.BOOK_REPO_ROOT
+  ? resolve(process.env.BOOK_REPO_ROOT)
+  : process.cwd();
 const absPath = resolve(REPO_ROOT, src);
 
 if (!existsSync(absPath)) {
@@ -102,7 +107,15 @@ const inferLang = (path: string): string => {
 
 const language = (lang ?? inferLang(src)) as Parameters<typeof Code>[0]['lang'];
 
-const githubUrl = buildGithubUrl(src, startLine, endLine);
+// #109: fail loud rather than link the wrong repo (see CodeRef for the rationale).
+if (!bookConfig.githubRepo) {
+  throw new Error(
+    `<CodeBlock src="${src}">: no GitHub repo resolved. Set githubRepo in ` +
+      `defineBookConfig(), or add a "repository" field to package.json (or an ` +
+      `origin git remote) so the scaffold can auto-detect owner/repo.`,
+  );
+}
+const githubUrl = buildGithubUrl(bookConfig.githubRepo, bookConfig.githubBranch, src, startLine, endLine);
 const rangeText = startLine === endLine ? `:${startLine}` : `:${startLine}-${endLine}`;
 const displayPath = `${src}${rangeText}`;
 ---

package/components/CodeRef.astro

@@ -1,7 +1,8 @@
 ---
 /**
  * CodeRef — inline reference to a specific file (and optional line range)
- * in the post_transformers repo on GitHub.
+ * in the book's GitHub repo (resolved per book — #109: defineBookConfig
+ * `githubRepo`, else auto-detected from package.json / git remote).
  *
  * Maps the LaTeX `\code{path:N}` and `\path{path}` idioms (which only
  * styled monospace text) to a real hyperlink that lands the reader on
@@ -26,6 +27,7 @@
  * synthesized.
  */
 import { buildGithubUrl } from '../src/lib/repo-url';
+import bookConfig from 'virtual:book-scaffold/book-config';
 
 interface Props {
   path: string;
@@ -34,7 +36,18 @@ interface Props {
 }
 
 const { path, line, lineEnd } = Astro.props;
-const url = buildGithubUrl(path, line, lineEnd);
+
+// #109: fail loud rather than link to the wrong repo. `githubRepo` is null
+// only when neither defineBookConfig({ githubRepo }) nor auto-detection
+// (package.json repository / git remote) resolved one.
+if (!bookConfig.githubRepo) {
+  throw new Error(
+    `<CodeRef path="${path}">: no GitHub repo resolved. Set githubRepo in ` +
+      `defineBookConfig(), or add a "repository" field to package.json (or an ` +
+      `origin git remote) so the scaffold can auto-detect owner/repo.`,
+  );
+}
+const url = buildGithubUrl(bookConfig.githubRepo, bookConfig.githubBranch, path, line, lineEnd);
 const hasSlot = await Astro.slots.has('default');
 const basename = path.split('/').pop() ?? path;
 const defaultText =

package/components/PocLayout.astro

@@ -11,12 +11,20 @@
  * 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';
+import { assertEnumProp } from '../src/lib/assert-prop';
+
+const POC_LAYOUT_KINDS = ['tutorial', 'how-to', 'tldr', 'part-summary', 'cheat-sheet'] as const;
+export type PocLayoutKind = (typeof POC_LAYOUT_KINDS)[number];
 
 interface Props {
   kind: PocLayoutKind;
 }
-const { kind } = Astro.props;
+// #109 sweep: fail loud on an out-of-union kind instead of emitting a
+// poc-layout-<bogus> class that matches no CSS rule.
+const kind = assertEnumProp(Astro.props.kind, POC_LAYOUT_KINDS, {
+  component: 'PocLayout',
+  prop: 'kind',
+});
 ---
 <div class={`poc-layout poc-layout-${kind}`}>
   <slot />

package/components/Practice.astro

@@ -11,12 +11,21 @@
  *
  * Family: book-genre (cross-profile).
  */
-type Difficulty = '1' | '2' | '3' | '4';
+import { assertEnumProp } from '../src/lib/assert-prop';
+
+const PRACTICE_DIFFICULTIES = ['1', '2', '3', '4'] as const;
+type Difficulty = (typeof PRACTICE_DIFFICULTIES)[number];
 interface Props {
   id: string;
   difficulty: Difficulty;
 }
-const { id, difficulty } = Astro.props;
+const { id } = Astro.props;
+// #109 sweep: coerce (tolerates difficulty={3} numeric usage), then fail loud
+// on anything outside 1-4 instead of rendering empty / NaN diamond markers.
+const difficulty = assertEnumProp(String(Astro.props.difficulty), PRACTICE_DIFFICULTIES, {
+  component: 'Practice',
+  prop: 'difficulty',
+});
 const anchorId = `practice-${id}`;
 const filled = Number.parseInt(difficulty, 10);
 const markers = '◆'.repeat(filled) + '◇'.repeat(4 - filled);

package/components/StatusBadge.astro

@@ -11,14 +11,18 @@
  * Internal frontmatter retains the 7-state value for STATUS.md alignment;
  * this component is the public-facing translator.
  */
-type InternalStatus =
-  | 'implemented'
-  | 'chapter_only'
-  | 'reading_only'
-  | 'prose_only'
-  | 'code_only'
-  | 'scaffolded'
-  | 'planned';
+import { assertEnumProp } from '../src/lib/assert-prop';
+
+const INTERNAL_STATUSES = [
+  'implemented',
+  'chapter_only',
+  'reading_only',
+  'prose_only',
+  'code_only',
+  'scaffolded',
+  'planned',
+] as const;
+type InternalStatus = (typeof INTERNAL_STATUSES)[number];
 
 type PublicStatus = 'published' | 'draft' | 'coming-soon';
 
@@ -42,7 +46,12 @@ interface Props {
   status: InternalStatus;
 }
 
-const { status } = Astro.props;
+// #109 sweep: fail loud on an unknown status instead of rendering an empty
+// badge label (PUBLIC_OF[undefined] -> undefined -> blank).
+const status = assertEnumProp(Astro.props.status, INTERNAL_STATUSES, {
+  component: 'StatusBadge',
+  prop: 'status',
+});
 const publicStatus = PUBLIC_OF[status];
 const label = PUBLIC_LABEL[publicStatus];
 ---

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { AstroUserConfig, AstroIntegration } from 'astro';
-import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, Y as volatilityLevels, h as ChaptersRenderer, r as academicParts, o as Style } from './types-CULHImU4.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, m as Provenance, R as ResearchPortfolioChapter, n as RouteToggles, S as StatusBadge, p as StyleInput, T as ToolsChapter, V as VolatilityBadge, q as academicChapterSchema, s as changeKinds, t as changelogSchema, u as chapterStatus, v as citationBackstops, w as composeStyles, x as courseNotesChapterSchema, y as defineProfile, z as defineStyle, D as minimalChapterSchema, E as normalizeFrontmatterConfig, G as patternCategories, H as patternsSchema, I as provenanceObject, J as provenanceSchema, K as researchPortfolioChapterSchema, L as resolvePreset, N as resolveProfile, O as sourceTiers, Q as sourceTiersResearch, U as sourcesSchema, W as toolSlugs, X as toolsChapterSchema } from './types-CULHImU4.js';
+import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, Y as volatilityLevels, h as ChaptersRenderer, r as academicParts, o as Style } from './types-BmBIV5qD.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, m as Provenance, R as ResearchPortfolioChapter, n as RouteToggles, S as StatusBadge, p as StyleInput, T as ToolsChapter, V as VolatilityBadge, q as academicChapterSchema, s as changeKinds, t as changelogSchema, u as chapterStatus, v as citationBackstops, w as composeStyles, x as courseNotesChapterSchema, y as defineProfile, z as defineStyle, D as minimalChapterSchema, E as normalizeFrontmatterConfig, G as patternCategories, H as patternsSchema, I as provenanceObject, J as provenanceSchema, K as researchPortfolioChapterSchema, L as resolvePreset, N as resolveProfile, O as sourceTiers, Q as sourceTiersResearch, U as sourcesSchema, W as toolSlugs, X as toolsChapterSchema } from './types-BmBIV5qD.js';
 import 'astro/zod';
 
 /**
@@ -252,6 +252,91 @@ interface ResolvedTheoremLabel {
  */
 declare function theoremLabel(props: TheoremLabelProps): ResolvedTheoremLabel;
 
+/**
+ * repo-url — resolve and build GitHub source links for CodeRef / CodeBlock.
+ *
+ * The repo is no longer hardcoded (#109). `buildGithubUrl` takes an explicit
+ * `repo` + `branch`; the integration resolves them per book — from
+ * `defineBookConfig({ githubRepo })` (override), else auto-detected from the
+ * consumer's own `package.json` `repository` (or git remote) via
+ * `parseRepoSlug`. When nothing resolves, the components throw rather than
+ * emit links to the wrong repo (the old silent default was
+ * `brandon-behring/post_transformers`).
+ */
+/** Default branch when a book configures a repo but no branch. */
+declare const DEFAULT_GITHUB_BRANCH = "main";
+/**
+ * Derive an `owner/repo` slug from an npm `repository` field (string or
+ * `{ url }`) or a raw git remote URL. Handles https, ssh, the `git+` prefix,
+ * a trailing `.git`, and the `github:owner/repo` npm shorthand. Returns null
+ * for anything that isn't a recognizable GitHub repo — no silent guess.
+ */
+declare function parseRepoSlug(repository: string | {
+    url?: string;
+} | null | undefined): string | null;
+/** Extract the `origin` remote URL from the text of a `.git/config` file. */
+declare function originUrlFromGitConfig(gitConfigText: string): string | null;
+/**
+ * Resolve a GitHub `owner/repo` by precedence (#109) — the rule that keeps a
+ * book from ever silently linking to the wrong repo:
+ *   1. explicit `override` (defineBookConfig `githubRepo`)
+ *   2. the consumer's `package.json` `repository`
+ *   3. the `origin` remote in `.git/config`
+ *   4. null — the components then throw rather than guess.
+ */
+declare function resolveGithubRepo(sources: {
+    override?: string | null;
+    packageJsonRepository?: string | {
+        url?: string;
+    } | null;
+    gitConfigText?: string | null;
+}): string | null;
+/**
+ * Build a GitHub line-anchor URL for an explicit repo + branch.
+ *   buildGithubUrl('o/r', 'main', 'a/b.py')        -> https://github.com/o/r/blob/main/a/b.py
+ *   buildGithubUrl('o/r', 'main', 'a/b.py', 42)     -> …/a/b.py#L42
+ *   buildGithubUrl('o/r', 'main', 'a/b.py', 42, 58) -> …/a/b.py#L42-L58
+ */
+declare function buildGithubUrl(repo: string, branch: string, path: string, line?: number, lineEnd?: number): string;
+
+/**
+ * assert-prop — shared fail-loud validator for closed-union component props
+ * (#109 / the v4.15.0 parseProps sweep).
+ *
+ * Astro has no runtime prop validation, so a closed-union prop given an
+ * out-of-range value silently produces a broken render — an empty StatusBadge
+ * label, a `poc-layout-<bogus>` class that matches no CSS, NaN difficulty
+ * markers. This is the same silent-degradation class as the #121 Theorem bug.
+ * `assertEnumProp` converts it into a loud, actionable build-time throw.
+ */
+/**
+ * Return `value` when it's one of `allowed`; otherwise throw an actionable
+ * error naming the component, prop, the offending value, and the legal set.
+ * Never returns a fallback — a closed union with no valid value is an authoring
+ * error that should stop the build, not render something wrong.
+ */
+declare function assertEnumProp<T extends string>(value: unknown, allowed: readonly T[], ctx: {
+    component: string;
+    prop: string;
+}): T;
+
+/**
+ * book-link — resolve a cross-book `<BookLink>` href from the consumer's
+ * sibling-book registry (#96).
+ *
+ * Each scaffold book is a separate Astro app with its own `labels.json` and
+ * deploy origin, so `<XRef>` can't reach a sibling book — a cross-book ref
+ * resolves against the wrong labels and dies. `<BookLink book to>` instead
+ * resolves `book` against a per-consumer registry of sibling base URLs
+ * (`defineBookConfig({ siblingBooks })`) — the single place to update when a
+ * sibling redeploys or extracts to its own repo. An unknown `book` THROWS
+ * rather than emitting a dead cross-origin link (fail-loud, like #109).
+ *
+ * Phase 1 (this): registry-backed href + fail-loud on unknown book. Phase 2
+ * (deferred): validate the `to` id against a vendored sibling `labels.json`.
+ */
+declare function resolveBookHref(siblingBooks: Record<string, string> | null | undefined, book: string, to: string): string;
+
 /**
  * src/styles/built-in.ts — toolkit-shipped Styles, one per BookPreset (v4.0.0).
  *
@@ -353,4 +438,4 @@ type TipsConfigInput = Omit<TipsConfig, typeof TipsConfigBrand | '__tipsConfigVe
  */
 declare function defineTips(opts: TipsConfigInput): TipsConfig;
 
-export { ACADEMIC_PART_NAMES, BRANDON_PORTFOLIO_DEFAULT, BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, ChaptersRenderer, type Freshness, type FreshnessStatus, KIND_LABEL, type ResolvedTheoremLabel, Style, THEOREM_KINDS, type TheoremKind, type TheoremLabelProps, type TipsConfig, type TipsConfigInput, UNKNOWN_PART_ORDINAL, type VolatilityLevel, academicChaptersRenderer, academicPartHeading, academicPartName, academicPartOrdinal, academicParts, academicStyle, bookScaffoldIntegration, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, fallbackChaptersRenderer, freshnessLabel, getFreshness, minimalStyle, researchPortfolioStyle, theoremLabel, toolsChaptersRenderer, toolsStyle, volatilityLevels };
+export { ACADEMIC_PART_NAMES, BRANDON_PORTFOLIO_DEFAULT, BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, ChaptersRenderer, DEFAULT_GITHUB_BRANCH, type Freshness, type FreshnessStatus, KIND_LABEL, type ResolvedTheoremLabel, Style, THEOREM_KINDS, type TheoremKind, type TheoremLabelProps, type TipsConfig, type TipsConfigInput, UNKNOWN_PART_ORDINAL, type VolatilityLevel, academicChaptersRenderer, academicPartHeading, academicPartName, academicPartOrdinal, academicParts, academicStyle, assertEnumProp, bookScaffoldIntegration, buildGithubUrl, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, fallbackChaptersRenderer, freshnessLabel, getFreshness, minimalStyle, originUrlFromGitConfig, parseRepoSlug, researchPortfolioStyle, resolveBookHref, resolveGithubRepo, theoremLabel, toolsChaptersRenderer, toolsStyle, volatilityLevels };

package/dist/index.mjs

@@ -788,6 +788,8 @@ function resolveProfile(explicit) {
 
 // src/integration.ts
 import { fileURLToPath } from "url";
+import { readFileSync as readFileSync2 } from "fs";
+import { join } from "path";
 
 // src/lib/define-style.ts
 function defineStyle(opts) {
@@ -855,6 +857,44 @@ function normalizeFrontmatterConfig(v) {
   return v;
 }
 
+// src/lib/repo-url.ts
+var DEFAULT_GITHUB_BRANCH = "main";
+function parseRepoSlug(repository) {
+  const raw = typeof repository === "string" ? repository : repository && typeof repository === "object" ? repository.url : void 0;
+  if (!raw || typeof raw !== "string") return null;
+  const s = raw.trim();
+  if (s === "") return null;
+  const shorthand = s.match(/^github:([\w.-]+)\/([\w.-]+?)(?:\.git)?$/i);
+  if (shorthand) return `${shorthand[1]}/${shorthand[2]}`;
+  const m = s.replace(/^git\+/, "").match(/github\.com[/:]([\w.-]+)\/([\w.-]+?)(?:\.git)?(?:[/#?].*)?$/i);
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+function originUrlFromGitConfig(gitConfigText) {
+  const m = gitConfigText.match(/\[remote "origin"\][^[]*?url\s*=\s*(\S+)/);
+  return m ? m[1] : null;
+}
+function resolveGithubRepo(sources) {
+  if (sources.override) return sources.override;
+  const fromPkg = parseRepoSlug(sources.packageJsonRepository ?? null);
+  if (fromPkg) return fromPkg;
+  if (sources.gitConfigText) {
+    const fromGit = parseRepoSlug(originUrlFromGitConfig(sources.gitConfigText));
+    if (fromGit) return fromGit;
+  }
+  return null;
+}
+function buildGithubUrl(repo, branch, path, line, lineEnd) {
+  const cleanPath = path.replace(/^\/+/, "");
+  let url = `https://github.com/${repo}/blob/${branch}/${cleanPath}`;
+  if (line !== void 0) {
+    url += `#L${line}`;
+    if (lineEnd !== void 0 && lineEnd !== line) {
+      url += `-L${lineEnd}`;
+    }
+  }
+  return url;
+}
+
 // src/mdx-components-resolver.ts
 import { existsSync as existsSync2 } from "fs";
 import { resolve } from "path";
@@ -915,6 +955,23 @@ function makeBookConfigVitePlugin(config) {
     }
   };
 }
+function resolveBookGithubRepo(override, consumerRoot) {
+  let packageJsonRepository = null;
+  let gitConfigText = null;
+  try {
+    packageJsonRepository = JSON.parse(readFileSync2(join(consumerRoot, "package.json"), "utf8")).repository ?? null;
+  } catch {
+  }
+  try {
+    gitConfigText = readFileSync2(join(consumerRoot, ".git", "config"), "utf8");
+  } catch {
+  }
+  return resolveGithubRepo({
+    override,
+    packageJsonRepository,
+    gitConfigText
+  });
+}
 var PACKAGE_NAME = "@brandon_m_behring/book-scaffold-astro";
 var ROUTE_REGISTRY = {
   references: { pattern: "/references", file: "references.astro" },
@@ -968,7 +1025,12 @@ function bookScaffoldIntegration(opts) {
     // v4.6.0: book-level author + SEO config, propagated through the
     // (renamed) book-config virtual module to Base.astro + Chapter.astro.
     author,
-    seo
+    seo,
+    // v4.15.0 (#109): optional GitHub repo/branch override for CodeRef/CodeBlock.
+    githubRepo,
+    githubBranch,
+    // v4.16.0 (#96): sibling-book registry for cross-book <BookLink>.
+    siblingBooks
   } = opts;
   const def = PROFILES[profile];
   const fmNormalized = normalizeFrontmatterConfig(userOverrides.frontmatter);
@@ -1009,6 +1071,8 @@ function bookScaffoldIntegration(opts) {
         }
         const consumerRoot = fileURLToPath(config.root);
         const resolvedMdxPath = resolveMdxComponentsPath(consumerRoot, mdxComponentsModule);
+        const resolvedGithubRepo = resolveBookGithubRepo(githubRepo, consumerRoot);
+        const resolvedGithubBranch = githubBranch ?? DEFAULT_GITHUB_BRANCH;
         const presetLiteral = JSON.stringify(profile);
         const enabledRouteNames = Object.entries(enabledRoutes).filter(([, on]) => on).map(([name]) => name);
         updateConfig({
@@ -1024,7 +1088,10 @@ function bookScaffoldIntegration(opts) {
                 seo: {
                   ogImage: seo?.ogImage ?? null,
                   twitterHandle: seo?.twitterHandle ?? null
-                }
+                },
+                githubRepo: resolvedGithubRepo,
+                githubBranch: resolvedGithubBranch,
+                siblingBooks: siblingBooks ?? {}
               })
             ],
             define: {
@@ -1157,7 +1224,12 @@ async function defineBookConfig(opts) {
       // Base.astro + Chapter.astro. `seo.sitemap` is NOT passed through —
       // it's consumed below at config-time by the @astrojs/sitemap call.
       author: opts.author,
-      seo: opts.seo ? { ogImage: opts.seo.ogImage, twitterHandle: opts.seo.twitterHandle } : void 0
+      seo: opts.seo ? { ogImage: opts.seo.ogImage, twitterHandle: opts.seo.twitterHandle } : void 0,
+      // v4.15.0 (#109): repo/branch override; integration auto-detects when undefined.
+      githubRepo: opts.githubRepo,
+      githubBranch: opts.githubBranch,
+      // v4.16.0 (#96): cross-book link registry.
+      siblingBooks: opts.siblingBooks
     }),
     ...mergedExtraIntegrations
   ];
@@ -1199,6 +1271,11 @@ async function defineBookConfig(opts) {
     // v4.6.0: strip new book-level SEO opts (author + seo block).
     author: _author,
     seo: _seo,
+    // v4.15.0: strip repo opts so they don't leak into AstroUserConfig.
+    githubRepo: _githubRepo,
+    githubBranch: _githubBranch,
+    // v4.16.0: strip cross-book registry.
+    siblingBooks: _siblingBooks,
     ...rest
   } = opts;
   void _styles;
@@ -1215,6 +1292,9 @@ async function defineBookConfig(opts) {
   void _portfolio;
   void _author;
   void _seo;
+  void _githubRepo;
+  void _githubBranch;
+  void _siblingBooks;
   const katexExternals = wantsKatex ? [] : ["remark-math", "rehype-katex", "katex"];
   const restVite = rest.vite ?? {};
   const restSsr = restVite.ssr ?? {};
@@ -1294,6 +1374,29 @@ function theoremLabel(props) {
   return { kind: raw, fullLabel };
 }
 
+// src/lib/assert-prop.ts
+function assertEnumProp(value, allowed, ctx) {
+  if (typeof value === "string" && allowed.includes(value)) {
+    return value;
+  }
+  const got = value === void 0 ? "nothing" : JSON.stringify(value);
+  throw new Error(
+    `<${ctx.component}>: ${ctx.prop}=${got} is not one of ${allowed.join(", ")}.`
+  );
+}
+
+// src/lib/book-link.ts
+function resolveBookHref(siblingBooks, book, to) {
+  const base = siblingBooks?.[book];
+  if (!base) {
+    const known = siblingBooks ? Object.keys(siblingBooks) : [];
+    throw new Error(
+      `<BookLink book="${book}">: unknown sibling book. Register it in defineBookConfig({ siblingBooks: { "${book}": "https://\u2026" } })` + (known.length ? ` (known: ${known.join(", ")})` : "") + "."
+    );
+  }
+  return `${base.replace(/\/+$/, "")}/${to.replace(/^\/+/, "")}`;
+}
+
 // src/styles/built-in.ts
 var academicStyle = defineStyle({
   name: "academic",
@@ -1340,6 +1443,7 @@ export {
   BRANDON_PORTFOLIO_DEFAULT,
   BUILTIN_STYLES,
   BookConfigError,
+  DEFAULT_GITHUB_BRANCH,
   KIND_LABEL,
   THEOREM_KINDS,
   UNKNOWN_PART_ORDINAL,
@@ -1350,7 +1454,9 @@ export {
   academicPartOrdinal,
   academicParts,
   academicStyle,
+  assertEnumProp,
   bookScaffoldIntegration,
+  buildGithubUrl,
   changeKinds,
   changelogSchema,
   chapterSortKey,
@@ -1370,12 +1476,16 @@ export {
   minimalChapterSchema,
   minimalStyle,
   normalizeFrontmatterConfig,
+  originUrlFromGitConfig,
+  parseRepoSlug,
   patternCategories,
   patternsSchema,
   provenanceObject,
   provenanceSchema,
   researchPortfolioChapterSchema,
   researchPortfolioStyle,
+  resolveBookHref,
+  resolveGithubRepo,
   resolvePreset,
   resolveProfile,
   sourceTiers,

package/dist/schemas.d.ts

@@ -1,5 +1,5 @@
 import { defineCollection } from 'astro:content';
-import { g as BookSchemasOptions } from './types-CULHImU4.js';
+import { g as BookSchemasOptions } from './types-BmBIV5qD.js';
 import 'astro';
 import 'astro/zod';
 

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.14.3",
+  "version": "4.16.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -43,6 +43,7 @@
     "./package.json": "./package.json",
     "./components/AICollaborationDisclosure.astro": "./components/AICollaborationDisclosure.astro",
     "./components/BlockedByCallout.astro": "./components/BlockedByCallout.astro",
+    "./components/BookLink.astro": "./components/BookLink.astro",
     "./components/CaseStudy.astro": "./components/CaseStudy.astro",
     "./components/ChapterHeader.astro": "./components/ChapterHeader.astro",
     "./components/ChapterNav.astro": "./components/ChapterNav.astro",

package/scripts/validate.mjs

@@ -15,6 +15,8 @@
  *      path exists + line in bounds.
  *   6. <Theorem> — has a resolvable kind= (or legacy type=); else it would
  *      render an empty label and throw at build (#121).
+ *   7. <BookLink book="…" to="…"> (#96) — both props present, and book= is a
+ *      key in the consumer's siblingBooks registry (best-effort).
  *
  * Run from the consumer's project root. Closes #8 (was resolving paths
  * from the package's own directory inside node_modules — false negatives
@@ -214,6 +216,9 @@ const RE_MD_LINK = /\[(?:[^\]]*)\]\((\/[^)\s#]+)(?:#[^)]*)?\)/g;
 // #121: a <Theorem> opening tag — capture its attributes to assert a
 // resolvable kind= (or legacy type=) is present.
 const RE_THEOREM = /<Theorem\b([^>]*)>/g;
+// #96: a <BookLink> opening tag — assert book= + to= present, and (best-effort)
+// that book= is a registered sibling.
+const RE_BOOKLINK = /<BookLink\b([^>]*)>/g;
 
 async function fileExists(p) {
   try {
@@ -228,6 +233,25 @@ function lineOf(content, idx) {
   return content.slice(0, idx).split('\n').length;
 }
 
+// #96: best-effort siblingBooks registry keys from astro.config.mjs, so the
+// <BookLink> check can flag an unknown book= earlier than the component's
+// build-time throw. null = couldn't determine → membership not checked (the
+// component still fails loud at build).
+let siblingBookKeys = null;
+{
+  const astroConfigPath = resolve(ROOT, 'astro.config.mjs');
+  if (existsSync(astroConfigPath)) {
+    const block = readFileSync(astroConfigPath, 'utf8').match(/siblingBooks\s*:\s*\{([^}]*)\}/);
+    if (block) {
+      // Anchor each key to an entry boundary ({ , or start) so the `https:` in
+      // a URL value isn't mistaken for a key.
+      siblingBookKeys = new Set(
+        [...block[1].matchAll(/(?:^|[{,])\s*['"]?([\w-]+)['"]?\s*:/g)].map((x) => x[1]),
+      );
+    }
+  }
+}
+
 // ===== Run all checks on each chapter =====
 for (const rel of chapterFiles) {
   const abs = join(CHAPTERS_DIR, rel);
@@ -296,6 +320,23 @@ for (const rel of chapterFiles) {
       );
     }
   }
+
+  // 7. BookLink (#96): structural (book= + to=) + best-effort registry membership.
+  for (const m of content.matchAll(RE_BOOKLINK)) {
+    const attrs = m[1];
+    const bookMatch = attrs.match(/\bbook=["']([^"']+)["']/);
+    if (!bookMatch || !/\bto=["']/.test(attrs)) {
+      fail(rel, lineOf(content, m.index), `<BookLink> requires both book="…" and to="…".`);
+      continue;
+    }
+    if (siblingBookKeys && !siblingBookKeys.has(bookMatch[1])) {
+      fail(
+        rel,
+        lineOf(content, m.index),
+        `<BookLink book="${bookMatch[1]}"> — not in defineBookConfig siblingBooks (${[...siblingBookKeys].join(', ') || 'none'}). Register it or fix the key.`,
+      );
+    }
+  }
 }
 
 // ===== v4.6.0 (issue #77): missing-prereq re-framing =====

package/src/lib/assert-prop.ts

@@ -0,0 +1,30 @@
+/**
+ * assert-prop — shared fail-loud validator for closed-union component props
+ * (#109 / the v4.15.0 parseProps sweep).
+ *
+ * Astro has no runtime prop validation, so a closed-union prop given an
+ * out-of-range value silently produces a broken render — an empty StatusBadge
+ * label, a `poc-layout-<bogus>` class that matches no CSS, NaN difficulty
+ * markers. This is the same silent-degradation class as the #121 Theorem bug.
+ * `assertEnumProp` converts it into a loud, actionable build-time throw.
+ */
+
+/**
+ * Return `value` when it's one of `allowed`; otherwise throw an actionable
+ * error naming the component, prop, the offending value, and the legal set.
+ * Never returns a fallback — a closed union with no valid value is an authoring
+ * error that should stop the build, not render something wrong.
+ */
+export function assertEnumProp<T extends string>(
+  value: unknown,
+  allowed: readonly T[],
+  ctx: { component: string; prop: string },
+): T {
+  if (typeof value === 'string' && (allowed as readonly string[]).includes(value)) {
+    return value as T;
+  }
+  const got = value === undefined ? 'nothing' : JSON.stringify(value);
+  throw new Error(
+    `<${ctx.component}>: ${ctx.prop}=${got} is not one of ${allowed.join(', ')}.`,
+  );
+}

package/src/lib/book-link.ts

@@ -0,0 +1,32 @@
+/**
+ * book-link — resolve a cross-book `<BookLink>` href from the consumer's
+ * sibling-book registry (#96).
+ *
+ * Each scaffold book is a separate Astro app with its own `labels.json` and
+ * deploy origin, so `<XRef>` can't reach a sibling book — a cross-book ref
+ * resolves against the wrong labels and dies. `<BookLink book to>` instead
+ * resolves `book` against a per-consumer registry of sibling base URLs
+ * (`defineBookConfig({ siblingBooks })`) — the single place to update when a
+ * sibling redeploys or extracts to its own repo. An unknown `book` THROWS
+ * rather than emitting a dead cross-origin link (fail-loud, like #109).
+ *
+ * Phase 1 (this): registry-backed href + fail-loud on unknown book. Phase 2
+ * (deferred): validate the `to` id against a vendored sibling `labels.json`.
+ */
+export function resolveBookHref(
+  siblingBooks: Record<string, string> | null | undefined,
+  book: string,
+  to: string,
+): string {
+  const base = siblingBooks?.[book];
+  if (!base) {
+    const known = siblingBooks ? Object.keys(siblingBooks) : [];
+    throw new Error(
+      `<BookLink book="${book}">: unknown sibling book. Register it in ` +
+        `defineBookConfig({ siblingBooks: { "${book}": "https://…" } })` +
+        (known.length ? ` (known: ${known.join(', ')})` : '') +
+        '.',
+    );
+  }
+  return `${base.replace(/\/+$/, '')}/${to.replace(/^\/+/, '')}`;
+}

package/src/lib/repo-url.ts

@@ -1,27 +1,92 @@
 /**
- * Repository URL constants used by CodeRef and CodeBlock components.
+ * repo-url — resolve and build GitHub source links for CodeRef / CodeBlock.
  *
- * Centralized here so renaming the repo or moving branches is a one-file
- * change rather than a hunt across components.
- *
- * If the repo is later mirrored to a different host, update GITHUB_BASE
- * accordingly; the components do not assume GitHub-specific anchor syntax
- * beyond #L<N>-L<M>, which all major hosts (GitHub, GitLab, Codeberg)
- * support.
+ * The repo is no longer hardcoded (#109). `buildGithubUrl` takes an explicit
+ * `repo` + `branch`; the integration resolves them per book — from
+ * `defineBookConfig({ githubRepo })` (override), else auto-detected from the
+ * consumer's own `package.json` `repository` (or git remote) via
+ * `parseRepoSlug`. When nothing resolves, the components throw rather than
+ * emit links to the wrong repo (the old silent default was
+ * `brandon-behring/post_transformers`).
+ */
+
+/** Default branch when a book configures a repo but no branch. */
+export const DEFAULT_GITHUB_BRANCH = 'main';
+
+/**
+ * Derive an `owner/repo` slug from an npm `repository` field (string or
+ * `{ url }`) or a raw git remote URL. Handles https, ssh, the `git+` prefix,
+ * a trailing `.git`, and the `github:owner/repo` npm shorthand. Returns null
+ * for anything that isn't a recognizable GitHub repo — no silent guess.
  */
-export const GITHUB_REPO = 'brandon-behring/post_transformers';
-export const GITHUB_BRANCH = 'main';
-export const GITHUB_BASE = `https://github.com/${GITHUB_REPO}/blob/${GITHUB_BRANCH}`;
+export function parseRepoSlug(
+  repository: string | { url?: string } | null | undefined,
+): string | null {
+  const raw =
+    typeof repository === 'string'
+      ? repository
+      : repository && typeof repository === 'object'
+        ? repository.url
+        : undefined;
+  if (!raw || typeof raw !== 'string') return null;
+  const s = raw.trim();
+  if (s === '') return null;
+
+  // npm shorthand: github:owner/repo
+  const shorthand = s.match(/^github:([\w.-]+)\/([\w.-]+?)(?:\.git)?$/i);
+  if (shorthand) return `${shorthand[1]}/${shorthand[2]}`;
+
+  // https://github.com/owner/repo(.git), git+https://…, ssh git@github.com:owner/repo(.git)
+  const m = s
+    .replace(/^git\+/, '')
+    .match(/github\.com[/:]([\w.-]+)\/([\w.-]+?)(?:\.git)?(?:[/#?].*)?$/i);
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+
+/** Extract the `origin` remote URL from the text of a `.git/config` file. */
+export function originUrlFromGitConfig(gitConfigText: string): string | null {
+  const m = gitConfigText.match(/\[remote "origin"\][^[]*?url\s*=\s*(\S+)/);
+  return m ? m[1]! : null;
+}
+
+/**
+ * Resolve a GitHub `owner/repo` by precedence (#109) — the rule that keeps a
+ * book from ever silently linking to the wrong repo:
+ *   1. explicit `override` (defineBookConfig `githubRepo`)
+ *   2. the consumer's `package.json` `repository`
+ *   3. the `origin` remote in `.git/config`
+ *   4. null — the components then throw rather than guess.
+ */
+export function resolveGithubRepo(sources: {
+  override?: string | null;
+  packageJsonRepository?: string | { url?: string } | null;
+  gitConfigText?: string | null;
+}): string | null {
+  if (sources.override) return sources.override;
+  const fromPkg = parseRepoSlug(sources.packageJsonRepository ?? null);
+  if (fromPkg) return fromPkg;
+  if (sources.gitConfigText) {
+    const fromGit = parseRepoSlug(originUrlFromGitConfig(sources.gitConfigText));
+    if (fromGit) return fromGit;
+  }
+  return null;
+}
 
 /**
- * Build a GitHub line-anchor URL.
- *   buildGithubUrl('experiments/jax/week04/s4.py', 42)        -> .../s4.py#L42
- *   buildGithubUrl('experiments/jax/week04/s4.py', 42, 58)    -> .../s4.py#L42-L58
- *   buildGithubUrl('experiments/jax/week04/s4.py')            -> .../s4.py
+ * Build a GitHub line-anchor URL for an explicit repo + branch.
+ *   buildGithubUrl('o/r', 'main', 'a/b.py')        -> https://github.com/o/r/blob/main/a/b.py
+ *   buildGithubUrl('o/r', 'main', 'a/b.py', 42)     -> …/a/b.py#L42
+ *   buildGithubUrl('o/r', 'main', 'a/b.py', 42, 58) -> …/a/b.py#L42-L58
  */
-export function buildGithubUrl(path: string, line?: number, lineEnd?: number): string {
+export function buildGithubUrl(
+  repo: string,
+  branch: string,
+  path: string,
+  line?: number,
+  lineEnd?: number,
+): string {
   const cleanPath = path.replace(/^\/+/, '');
-  let url = `${GITHUB_BASE}/${cleanPath}`;
+  let url = `https://github.com/${repo}/blob/${branch}/${cleanPath}`;
   if (line !== undefined) {
     url += `#L${line}`;
     if (lineEnd !== undefined && lineEnd !== line) {