@brandon_m_behring/book-scaffold-astro 4.15.0 → 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/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-CjOseOSG.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-CjOseOSG.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';
 
 /**
@@ -320,6 +320,23 @@ declare function assertEnumProp<T extends string>(value: unknown, allowed: reado
     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).
  *
@@ -421,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, 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, resolveGithubRepo, 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

@@ -1028,7 +1028,9 @@ function bookScaffoldIntegration(opts) {
     seo,
     // v4.15.0 (#109): optional GitHub repo/branch override for CodeRef/CodeBlock.
     githubRepo,
-    githubBranch
+    githubBranch,
+    // v4.16.0 (#96): sibling-book registry for cross-book <BookLink>.
+    siblingBooks
   } = opts;
   const def = PROFILES[profile];
   const fmNormalized = normalizeFrontmatterConfig(userOverrides.frontmatter);
@@ -1088,7 +1090,8 @@ function bookScaffoldIntegration(opts) {
                   twitterHandle: seo?.twitterHandle ?? null
                 },
                 githubRepo: resolvedGithubRepo,
-                githubBranch: resolvedGithubBranch
+                githubBranch: resolvedGithubBranch,
+                siblingBooks: siblingBooks ?? {}
               })
             ],
             define: {
@@ -1224,7 +1227,9 @@ async function defineBookConfig(opts) {
       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
+      githubBranch: opts.githubBranch,
+      // v4.16.0 (#96): cross-book link registry.
+      siblingBooks: opts.siblingBooks
     }),
     ...mergedExtraIntegrations
   ];
@@ -1269,6 +1274,8 @@ async function defineBookConfig(opts) {
     // 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;
@@ -1287,6 +1294,7 @@ async function defineBookConfig(opts) {
   void _seo;
   void _githubRepo;
   void _githubBranch;
+  void _siblingBooks;
   const katexExternals = wantsKatex ? [] : ["remark-math", "rehype-katex", "katex"];
   const restVite = rest.vite ?? {};
   const restSsr = restVite.ssr ?? {};
@@ -1377,6 +1385,18 @@ function assertEnumProp(value, allowed, ctx) {
   );
 }
 
+// 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",
@@ -1464,6 +1484,7 @@ export {
   provenanceSchema,
   researchPortfolioChapterSchema,
   researchPortfolioStyle,
+  resolveBookHref,
   resolveGithubRepo,
   resolvePreset,
   resolveProfile,

package/dist/schemas.d.ts

@@ -1,5 +1,5 @@
 import { defineCollection } from 'astro:content';
-import { g as BookSchemasOptions } from './types-CjOseOSG.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.15.0",
+  "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/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(/^\/+/, '')}`;
+}