@brandon_m_behring/book-scaffold-astro 4.28.0 → 4.29.0

package/CLAUDE.md

@@ -108,7 +108,9 @@ Two callout families coexist. Authors import what they need.
 
 **Pedagogy family** (v4.1.0+, any profile, 4 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), `Diagnostic` (v4.19.0, #110; teal; pre-reading "Do I Know This Already?" DIKTA self-check — a slotted question list + a skip/skim/read routing rubric via `skimTo`, plus an optional collapsible answer key via `slot="answers"`). Slot bullets/code freely; render at any preset.
 
-**Utility components** (`src/components/`, any profile): `Cite`, `XRef`, `Figure`, `MarginFigure`, `MarginNote`, `Sidenote`, `EvidenceTag`, `Newthought`, `Epigraph`, `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`).
+**Utility components** (`src/components/`, any profile): `Cite`, `XRef`, `Figure`, `MarginFigure`, `MarginNote`, `Sidenote`, `EvidenceTag`, `Newthought`, `Epigraph`, `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; #147 adds `{ url, labels }` entries so `validate` checks literal fragment targets against a vendored sibling `labels.json`, while legacy URL strings warn/skip target validation; `<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`).
+
+**Cross-book heading indexes (#147):** `book-scaffold build-labels` indexes h2–h6 with Astro's heading collector (inline formatting/smartypants plus GitHub duplicate slugs), alongside the historical component IDs. Emitted hrefs are base-less and resolve the evaluated `chapterRoute` / `bookField`; nested content IDs keep their directory. Heading keys are opaque and path-qualified so the same fragment can exist in multiple chapters; `validate` matches exact normalized href values, while component keys stay backward-compatible for XRef. This makes a generated sibling `labels.json` usable for literal `<BookLink ... to="...#anchor">` validation without assuming `/chapters/`. h1 stays excluded as the chapter title.
 
 **Interactive demo substrate (#143; opt-in):** `DemoFrame`, `Slider`, `StatCards`, and `useThemeColors` are named exports from `@brandon_m_behring/book-scaffold-astro/demo`. Import `@brandon_m_behring/book-scaffold-astro/styles/demo.css` on the page that mounts the consumer-owned Preact island; it is never included by a profile and nothing auto-mounts. The substrate owns figure/label/metric semantics, focus/reduced-motion styling, SVG token helpers, and theme-token resolution. Consumers own all data, kernels, charts, and domain interaction policy. See Recipe 23.
 

package/components/BookLink.astro

@@ -11,8 +11,9 @@
  * 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`.
+ * `chapters/<slug>/#<id>`. A `{ url, labels }` registry descriptor lets
+ * `book-scaffold validate` check literal path/fragment targets against a
+ * vendored sibling `labels.json`; URL strings remain runtime-compatible.
  *
  * Usage:
  *   For design depth see

package/dist/index.d.ts

@@ -1,10 +1,11 @@
 import { AstroUserConfig, AstroIntegration, MarkdownHeading } from 'astro';
-import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, h as ChaptersRenderer, o as Style } from './types-CZrkqzpC.js';
-export { B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookPreset, e as BookProfile, g as BookSchemasOptions, C as ChapterFor, F as FreshnessAffordance, i as FrontmatterRouteConfig, N as NUMBER_STYLES, j as NumberStyle, P as PartKey, k as PartialRouteToggles, l as ProfileDefinition, R as ReleaseStatusConfig, m as RouteToggles, S as SecurityHeadersConfig, n as StatusBadge, p as StyleInput, V as VolatilityBadge, q as composeStyles, r as defineProfile, s as defineStyle, t as normalizeFrontmatterConfig, u as resolvePreset, v as resolveProfile } from './types-CZrkqzpC.js';
+import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, h as ChaptersRenderer, p as SiblingBooks, r as Style } from './types-DgSlAew3.js';
+export { B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookPreset, e as BookProfile, g as BookSchemasOptions, C as ChapterFor, F as FreshnessAffordance, i as FrontmatterRouteConfig, N as NUMBER_STYLES, j as NumberStyle, P as PartKey, k as PartialRouteToggles, l as ProfileDefinition, R as ReleaseStatusConfig, m as RouteToggles, S as SecurityHeadersConfig, n as SiblingBookDescriptor, o as SiblingBookEntry, q as StatusBadge, s as StyleInput, V as VolatilityBadge, t as composeStyles, u as defineProfile, v as defineStyle, w as normalizeFrontmatterConfig, x as resolvePreset, y as resolveProfile } from './types-DgSlAew3.js';
 import { E as volatilityLevels, c as academicParts, Q as Question } from './schemas-CKipJ5Ie.js';
 export { A as AcademicChapter, B as BloomLevel, C as CourseNotesChapter, G as GlossaryTerm, M as MinimalChapter, P as Provenance, a as QuestionType, R as ResearchPortfolioChapter, T as ToolsChapter, b as academicChapterSchema, d as bloomLevels, e as changeKinds, f as changelogSchema, g as chapterStatus, h as citationBackstops, i as courseNotesChapterSchema, j as glossarySchema, l as layoutModes, m as minimalChapterSchema, p as patternCategories, k as patternsSchema, n as provenanceObject, o as provenanceSchema, q as questionDifficulties, r as questionSchema, s as questionTypes, t as refineQuestion, u as refinedQuestionSchema, v as researchPortfolioChapterSchema, w as sourceTiers, x as sourceTiersResearch, y as sourcesSchema, z as toolSlugs, D as toolsChapterSchema } from './schemas-CKipJ5Ie.js';
 export { KIND_LABEL, ResolvedTheoremLabel, THEOREM_KINDS, TheoremKind, TheoremLabelProps, resolveTheoremNumber, theoremLabel } from './lib/theorem-label.js';
 export { ssmMacros } from './lib/katex-macros.js';
+export { ChapterLike, apparatusHref, baseNoSlash, bookOf, chapterHref, isCurrentChapter, normalizeBase, slugOf } from './lib/nav-href.js';
 export { D as DomainScore, E as ExamBlueprint, a as ExamQuestion, b as ExamResult, R as RoutingChapter, c as buildExamManifest, d as deriveDomainRouting, s as sampleExam, e as scoreExam, f as shuffle, g as spreadBlueprint } from './exam-manifest-X9IrX1G3.js';
 export { F as FlashcardRef, b as buildFlashcardDeck } from './flashcards-okekZcl8.js';
 import 'astro/zod';
@@ -303,75 +304,12 @@ declare function assertEnumProp<T extends string>(value: unknown, allowed: reado
  * 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`.
+ * #147 extends each registry entry from a URL string to the backward-compatible
+ * `{ url, labels? }` descriptor. Runtime href resolution uses `url`; the
+ * validator uses `labels` to check literal sibling path/fragment targets.
  */
-declare function resolveBookHref(siblingBooks: Record<string, string> | null | undefined, book: string, to: string): string;
 
-/**
- * src/lib/nav-href.ts — pure route-href resolver (#80 multi-book navigation).
- *
- * No `astro:content` import (mirrors chapter-sort.ts) so tsup can include it in
- * the DTS bundle without dragging Astro virtual modules into the build graph.
- * The nav components (Sidebar, ChapterNav, NavContent, …) call these helpers
- * instead of hardcoding the single-book `/chapters/<id>/` URL shape — so ONE set
- * of components serves both a single-book site (the default pattern) and a
- * multi-book consumer whose chapters render at `/<book>/<slug>/`.
- *
- * Patterns are base-relative TOKEN STRINGS (a resolver *function* could not
- * survive the book-config virtual module's `JSON.stringify`, so the config
- * surface is a declarative string resolved here):
- *   :id   → entry.id verbatim, slashes preserved          e.g. 'kg/01-intro'
- *   :book → the entry's book name (see `bookField`), or '' e.g. 'kg'
- *   :slug → entry.id with a leading '<book>/' stripped     e.g. '01-intro'
- * BASE_URL is applied here, so patterns are written base-relative (lead '/').
- *
- * Defaults reproduce the single-book behavior BYTE-FOR-BYTE:
- *   chapterRoute   = '/chapters/:id/'  → `${base}chapters/${id}/`
- *   bookField      = 'book'   (academic/tools schemas have no `book` → bookOf
- *                              returns null → "show all chapters", today's nav)
- *   apparatusRoute = '/:route/'        → `${base}<route>/`
- */
-/** Minimal shape the resolver needs from a chapter collection entry. */
-interface ChapterLike {
-    id: string;
-    data: Record<string, unknown>;
-}
-/**
- * Normalize a base URL to exactly one trailing slash (`''`/`undefined` → `'/'`).
- *
- * v4.27.0 (#182): promoted from this module's private helper to THE shared
- * normalizer — 18 `.astro` files previously inlined the same normalization in
- * three regex idioms. Astro does not guarantee a trailing slash on `base`
- * (`'/foo'` is a documented form), so every `import.meta.env.BASE_URL` read
- * must pass through here before href composition: `${normalizeBase(...)}chapters/`.
- * Takes the base as a PARAMETER because src/lib ships pre-compiled in dist/,
- * where Vite's import.meta.env replacement cannot reach (see exam-manifest.ts).
- */
-declare function normalizeBase(baseUrl: string | undefined): string;
-/**
- * The composing variant (#182): strip ALL trailing slashes (`'/'` → `''`,
- * `'/foo/'` → `'/foo'`) for `${baseNoSlash(...)}/answers`-style templates
- * where the literal supplies the slash (Rationale.astro's route detection).
- */
-declare function baseNoSlash(baseUrl: string | undefined): string;
-/**
- * The entry's book name from `data[bookField]`, or `null` when absent/blank.
- * Single-book schemas (academic/tools/minimal) have no such field → `null`,
- * which callers read as "this is the only book — show every chapter".
- */
-declare function bookOf(entry: ChapterLike, bookField?: string): string | null;
-/** `entry.id` with a leading `'<book>/'` stripped (multi-book) or unchanged. */
-declare function slugOf(entry: ChapterLike, bookField?: string): string;
-/** Resolve a chapter entry to a base-prefixed href via the `chapterRoute` pattern. */
-declare function chapterHref(entry: ChapterLike, pattern?: string, baseUrl?: string, bookField?: string): string;
-/**
- * Resolve a per-book apparatus route (glossary / practice-exam / flashcards /
- * answers) to a base-prefixed href via the `apparatusRoute` pattern.
- */
-declare function apparatusHref(route: string, book: string | null, pattern?: string, baseUrl?: string): string;
-/** Whether `entry` is the page at `currentPath` (trailing-slash tolerant). */
-declare function isCurrentChapter(entry: ChapterLike, currentPath: string, pattern?: string, baseUrl?: string, bookField?: string): boolean;
+declare function resolveBookHref(siblingBooks: SiblingBooks | null | undefined, book: string, to: string): string;
 
 /**
  * exam-domains — validate a question's `domain` against the consumer's closed
@@ -629,4 +567,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, type ChapterLike, ChaptersRenderer, DEFAULT_GITHUB_BRANCH, type Freshness, type FreshnessStatus, type PartReviewGroup, type PartReviewSelection, Question, type ReviewChapter, type ReviewExercise, Style, type TipsConfig, type TipsConfigInput, UNKNOWN_PART_ORDINAL, type VisibleHeading, type VolatilityLevel, academicChaptersRenderer, academicPartHeading, academicPartName, academicPartOrdinal, academicParts, academicStyle, apparatusHref, assertEnumProp, assertKnownDomain, baseNoSlash, bookOf, bookScaffoldIntegration, buildGithubUrl, chapterHref, chapterLabel, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, deriveObjectiveMap, distinctChaptersSorted, fallbackChaptersRenderer, freshnessLabel, getFreshness, groupByChapter, groupByDomain, isCurrentChapter, minimalStyle, normalizeBase, originUrlFromGitConfig, parseRepoSlug, pickActive, researchPortfolioChaptersRenderer, researchPortfolioStyle, resolveBookHref, resolveGithubRepo, selectPartExercises, slugOf, sortQuestions, tocHeadings, toolsChaptersRenderer, toolsStyle, volatilityLevels };
+export { ACADEMIC_PART_NAMES, BRANDON_PORTFOLIO_DEFAULT, BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, ChaptersRenderer, DEFAULT_GITHUB_BRANCH, type Freshness, type FreshnessStatus, type PartReviewGroup, type PartReviewSelection, Question, type ReviewChapter, type ReviewExercise, SiblingBooks, Style, type TipsConfig, type TipsConfigInput, UNKNOWN_PART_ORDINAL, type VisibleHeading, type VolatilityLevel, academicChaptersRenderer, academicPartHeading, academicPartName, academicPartOrdinal, academicParts, academicStyle, assertEnumProp, assertKnownDomain, bookScaffoldIntegration, buildGithubUrl, chapterLabel, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, deriveObjectiveMap, distinctChaptersSorted, fallbackChaptersRenderer, freshnessLabel, getFreshness, groupByChapter, groupByDomain, minimalStyle, originUrlFromGitConfig, parseRepoSlug, pickActive, researchPortfolioChaptersRenderer, researchPortfolioStyle, resolveBookHref, resolveGithubRepo, selectPartExercises, sortQuestions, tocHeadings, toolsChaptersRenderer, toolsStyle, volatilityLevels };

package/dist/index.mjs

@@ -1379,7 +1379,13 @@ function bookScaffoldIntegration(opts) {
     }
   };
   Object.defineProperty(integration, "__bookScaffoldResolvedConfig", {
-    value: Object.freeze({ preset: profile, numberStyle }),
+    value: Object.freeze({
+      preset: profile,
+      numberStyle,
+      siblingBooks: siblingBooks ?? {},
+      chapterRoute: chapterRoute ?? "/chapters/:id/",
+      bookField: bookField ?? "book"
+    }),
     enumerable: false,
     configurable: false,
     writable: false
@@ -1528,7 +1534,7 @@ async function defineBookConfig(opts) {
       // 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.
+      // v4.16.0 (#96), extended in #147: cross-book link registry.
       siblingBooks: opts.siblingBooks,
       // v4.17.0 (#112): per-book exam-domain taxonomy for the questions collection.
       examDomains: opts.examDomains,
@@ -1721,14 +1727,25 @@ function assertEnumProp(value, allowed, ctx) {
 init_katex_macros();
 
 // src/lib/book-link.ts
+function entryUrl(entry) {
+  if (typeof entry === "string") return entry;
+  return entry?.url;
+}
 function resolveBookHref(siblingBooks, book, to) {
-  const base = siblingBooks?.[book];
-  if (!base) {
+  const registered = siblingBooks !== null && siblingBooks !== void 0 && Object.prototype.hasOwnProperty.call(siblingBooks, book);
+  if (!registered) {
     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(", ")})` : "") + "."
     );
   }
+  const entry = siblingBooks[book];
+  const base = entryUrl(entry);
+  if (typeof base !== "string" || base.length === 0) {
+    throw new Error(
+      `<BookLink book="${book}">: invalid siblingBooks entry. Expected a URL string or { url: "https://\u2026", labels?: "./path/to/labels.json" }.`
+    );
+  }
   return `${base.replace(/\/+$/, "")}/${to.replace(/^\/+/, "")}`;
 }
 

package/dist/lib/nav-href.d.ts

@@ -0,0 +1,66 @@
+/**
+ * src/lib/nav-href.ts — pure route-href resolver (#80 multi-book navigation).
+ *
+ * No `astro:content` import (mirrors chapter-sort.ts) so tsup can include it in
+ * the DTS bundle without dragging Astro virtual modules into the build graph.
+ * The nav components (Sidebar, ChapterNav, NavContent, …) call these helpers
+ * instead of hardcoding the single-book `/chapters/<id>/` URL shape — so ONE set
+ * of components serves both a single-book site (the default pattern) and a
+ * multi-book consumer whose chapters render at `/<book>/<slug>/`.
+ *
+ * Patterns are base-relative TOKEN STRINGS (a resolver *function* could not
+ * survive the book-config virtual module's `JSON.stringify`, so the config
+ * surface is a declarative string resolved here):
+ *   :id   → entry.id verbatim, slashes preserved          e.g. 'kg/01-intro'
+ *   :book → the entry's book name (see `bookField`), or '' e.g. 'kg'
+ *   :slug → entry.id with a leading '<book>/' stripped     e.g. '01-intro'
+ * BASE_URL is applied here, so patterns are written base-relative (lead '/').
+ *
+ * Defaults reproduce the single-book behavior BYTE-FOR-BYTE:
+ *   chapterRoute   = '/chapters/:id/'  → `${base}chapters/${id}/`
+ *   bookField      = 'book'   (academic/tools schemas have no `book` → bookOf
+ *                              returns null → "show all chapters", today's nav)
+ *   apparatusRoute = '/:route/'        → `${base}<route>/`
+ */
+/** Minimal shape the resolver needs from a chapter collection entry. */
+interface ChapterLike {
+    id: string;
+    data: Record<string, unknown>;
+}
+/**
+ * Normalize a base URL to exactly one trailing slash (`''`/`undefined` → `'/'`).
+ *
+ * v4.27.0 (#182): promoted from this module's private helper to THE shared
+ * normalizer — 18 `.astro` files previously inlined the same normalization in
+ * three regex idioms. Astro does not guarantee a trailing slash on `base`
+ * (`'/foo'` is a documented form), so every `import.meta.env.BASE_URL` read
+ * must pass through here before href composition: `${normalizeBase(...)}chapters/`.
+ * Takes the base as a PARAMETER because src/lib ships pre-compiled in dist/,
+ * where Vite's import.meta.env replacement cannot reach (see exam-manifest.ts).
+ */
+declare function normalizeBase(baseUrl: string | undefined): string;
+/**
+ * The composing variant (#182): strip ALL trailing slashes (`'/'` → `''`,
+ * `'/foo/'` → `'/foo'`) for `${baseNoSlash(...)}/answers`-style templates
+ * where the literal supplies the slash (Rationale.astro's route detection).
+ */
+declare function baseNoSlash(baseUrl: string | undefined): string;
+/**
+ * The entry's book name from `data[bookField]`, or `null` when absent/blank.
+ * Single-book schemas (academic/tools/minimal) have no such field → `null`,
+ * which callers read as "this is the only book — show every chapter".
+ */
+declare function bookOf(entry: ChapterLike, bookField?: string): string | null;
+/** `entry.id` with a leading `'<book>/'` stripped (multi-book) or unchanged. */
+declare function slugOf(entry: ChapterLike, bookField?: string): string;
+/** Resolve a chapter entry to a base-prefixed href via the `chapterRoute` pattern. */
+declare function chapterHref(entry: ChapterLike, pattern?: string, baseUrl?: string, bookField?: string): string;
+/**
+ * Resolve a per-book apparatus route (glossary / practice-exam / flashcards /
+ * answers) to a base-prefixed href via the `apparatusRoute` pattern.
+ */
+declare function apparatusHref(route: string, book: string | null, pattern?: string, baseUrl?: string): string;
+/** Whether `entry` is the page at `currentPath` (trailing-slash tolerant). */
+declare function isCurrentChapter(entry: ChapterLike, currentPath: string, pattern?: string, baseUrl?: string, bookField?: string): boolean;
+
+export { type ChapterLike, apparatusHref, baseNoSlash, bookOf, chapterHref, isCurrentChapter, normalizeBase, slugOf };

package/dist/lib/nav-href.mjs

@@ -0,0 +1,44 @@
+// src/lib/nav-href.ts
+function normalizeBase(baseUrl) {
+  return (baseUrl || "/").replace(/\/*$/, "/");
+}
+function baseNoSlash(baseUrl) {
+  return (baseUrl || "/").replace(/\/+$/, "");
+}
+var normBase = normalizeBase;
+function fillTokens(pattern, tokens) {
+  return pattern.replace(/:(book|slug|route|id)\b/g, (_m, k) => tokens[k] ?? "");
+}
+function bookOf(entry, bookField = "book") {
+  const v = entry.data[bookField];
+  return typeof v === "string" && v.length > 0 ? v : null;
+}
+function slugOf(entry, bookField = "book") {
+  const book = bookOf(entry, bookField);
+  return book && entry.id.startsWith(`${book}/`) ? entry.id.slice(book.length + 1) : entry.id;
+}
+function chapterHref(entry, pattern = "/chapters/:id/", baseUrl = "/", bookField = "book") {
+  const path = fillTokens(pattern, {
+    id: entry.id,
+    book: bookOf(entry, bookField) ?? "",
+    slug: slugOf(entry, bookField)
+  }).replace(/\/{2,}/g, "/").replace(/^\//, "");
+  return normBase(baseUrl) + path;
+}
+function apparatusHref(route, book, pattern = "/:route/", baseUrl = "/") {
+  const path = fillTokens(pattern, { route, book: book ?? "" }).replace(/\/{2,}/g, "/").replace(/^\//, "");
+  return normBase(baseUrl) + path;
+}
+function isCurrentChapter(entry, currentPath, pattern = "/chapters/:id/", baseUrl = "/", bookField = "book") {
+  const href = chapterHref(entry, pattern, baseUrl, bookField);
+  return currentPath === href || currentPath === href.replace(/\/$/, "");
+}
+export {
+  apparatusHref,
+  baseNoSlash,
+  bookOf,
+  chapterHref,
+  isCurrentChapter,
+  normalizeBase,
+  slugOf
+};

package/dist/schemas.d.ts

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

package/dist/{types-CZrkqzpC.d.ts → types-DgSlAew3.d.ts}

@@ -487,6 +487,22 @@ declare const BOOK_PRESETS: readonly ("academic" | "tools" | "minimal" | "course
 /** Theorem-family numbering strategy used by build-labels and validate. */
 type NumberStyle = 'shared' | 'per-kind';
 declare const NUMBER_STYLES: readonly ["shared", "per-kind"];
+/**
+ * A sibling book with an optional vendored label index for cross-book
+ * `<BookLink>` validation (#147).
+ *
+ * `url` is the deployed book base, including any path prefix. `labels` is a
+ * path to that sibling's vendored `labels.json`, resolved from the consumer
+ * project root by `book-scaffold validate`.
+ */
+interface SiblingBookDescriptor {
+    url: string;
+    labels?: string;
+}
+/** Backward-compatible sibling-book registry entry. */
+type SiblingBookEntry = string | SiblingBookDescriptor;
+/** Registry consumed by `<BookLink>` and the pre-flight validator. */
+type SiblingBooks = Record<string, SiblingBookEntry>;
 /**
  * v4.27.0 (#188): build-time security-header customization.
  *
@@ -738,12 +754,20 @@ interface BookConfigOptions {
     /** v4.15.0 (#109): branch for CodeRef/CodeBlock links. Defaults to `main`. */
     githubBranch?: string;
     /**
-     * v4.16.0 (#96): registry of sibling-book base URLs for cross-book
-     * `<BookLink book="…" to="…" />`. Maps a book key (used as `book=`) to its
-     * deployed origin — the single place to update when a sibling redeploys.
-     * @example siblingBooks: { design: 'https://design.example' }
+     * v4.16.0 (#96), extended in #147: registry for cross-book
+     * `<BookLink book="…" to="…" />`. A string value remains supported. The
+     * descriptor form adds a vendored sibling labels index so literal fragment
+     * targets can be checked by `book-scaffold validate`.
+     *
+     * `url` may include a deployment path prefix. Relative `labels` paths are
+     * resolved from the consumer project root.
+     * @example
+     * siblingBooks: {
+     *   legacy: 'https://legacy.example',
+     *   design: { url: 'https://hub.example/books/design/', labels: './vendor/design-labels.json' },
+     * }
      */
-    siblingBooks?: Record<string, string>;
+    siblingBooks?: SiblingBooks;
     /**
      * v4.17.0 (Tier 3, #112): closed exam-domain taxonomy for the study-guide
      * `questions` collection. A question whose `domain` is not in this list
@@ -861,8 +885,8 @@ interface BookScaffoldIntegrationOptions {
      */
     githubRepo?: string;
     githubBranch?: string;
-    /** v4.16.0 (#96): sibling-book base-URL registry for <BookLink>. */
-    siblingBooks?: Record<string, string>;
+    /** v4.16.0 (#96), extended in #147: sibling-book registry for <BookLink>. */
+    siblingBooks?: SiblingBooks;
     /** v4.17.0 (#112): closed exam-domain taxonomy for the questions collection. */
     examDomains?: readonly string[];
     /** v4.26.0 (#80): chapter-route token pattern, propagated via the book-config
@@ -887,4 +911,4 @@ declare function resolvePreset(explicitPreset?: BookPreset, explicitProfile?: Bo
  */
 declare function resolveProfile(explicit?: BookProfile): BookProfile;
 
-export { BOOK_PRESETS as B, type ChapterFor as C, type FreshnessAffordance as F, NUMBER_STYLES as N, type PartKey as P, type ReleaseStatusConfig as R, type SecurityHeadersConfig as S, type VolatilityBadge as V, BOOK_PROFILES as a, BookConfigError as b, type BookConfigOptions as c, type BookPreset as d, type BookProfile as e, type BookScaffoldIntegrationOptions as f, type BookSchemasOptions as g, type ChaptersRenderer as h, type FrontmatterRouteConfig as i, type NumberStyle as j, type PartialRouteToggles as k, type ProfileDefinition as l, type RouteToggles as m, type StatusBadge as n, type Style as o, type StyleInput as p, composeStyles as q, defineProfile as r, defineStyle as s, normalizeFrontmatterConfig as t, resolvePreset as u, resolveProfile as v };
+export { BOOK_PRESETS as B, type ChapterFor as C, type FreshnessAffordance as F, NUMBER_STYLES as N, type PartKey as P, type ReleaseStatusConfig as R, type SecurityHeadersConfig as S, type VolatilityBadge as V, BOOK_PROFILES as a, BookConfigError as b, type BookConfigOptions as c, type BookPreset as d, type BookProfile as e, type BookScaffoldIntegrationOptions as f, type BookSchemasOptions as g, type ChaptersRenderer as h, type FrontmatterRouteConfig as i, type NumberStyle as j, type PartialRouteToggles as k, type ProfileDefinition as l, type RouteToggles as m, type SiblingBookDescriptor as n, type SiblingBookEntry as o, type SiblingBooks as p, type StatusBadge as q, type Style as r, type StyleInput as s, composeStyles as t, defineProfile as u, defineStyle as v, normalizeFrontmatterConfig as w, resolvePreset as x, resolveProfile as y };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brandon_m_behring/book-scaffold-astro",
   "description": "Astro 6 + MDX toolkit for long-form technical books with five typed presets, Tufte typography, citations, search, PDF, and Cloudflare deployment.",
-  "version": "4.28.0",
+  "version": "4.29.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -196,12 +196,16 @@
     }
   },
   "dependencies": {
+    "@astrojs/markdown-remark": "^7.1.2",
     "@astrojs/sitemap": "^3.6.1",
     "@citation-js/core": "^0.7.21",
     "@citation-js/plugin-bibtex": "^0.7.21",
     "@fontsource-variable/roboto": "^5.2.10",
     "@fontsource-variable/source-code-pro": "^5.2.7",
     "pagefind": "^1.5.2",
+    "remark-mdx": "^3.1.1",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.5",
     "vite": "^7.3.2",
     "yaml": "^2.9.0"
   },

package/recipes/09-validation.md

@@ -14,12 +14,40 @@
 | `[text](/internal-link)` resolves to known chapter slug or top-level route | all | Astro won't fail on dead internal links. Warning, not error (regex misses dynamic routes). |
 | `<CodeRef path="..." line={N} />` path exists + line in bounds | all, if `BOOK_REPO_ROOT` set | Catches stale line numbers after code refactors in the paired experiments/ repo. |
 | `<Theorem>` has a resolvable `kind=` (or legacy `type=`); an id'd theorem resolves in `labels.json`; a literal `n=` agrees with the index (#121, #126, #176) | all | An absent kind throws at build with less context; an unindexed id silently renders the heading unnumbered; a stale literal `n=` contradicts the heading/XRefs. Dynamic expressions and `label=` overrides are skipped. |
-| `<BookLink book= to=>` both present; `book=` registered in `siblingBooks` (#96) | all | Pre-flights the component's build-time throw across all files at once. |
+| `<BookLink book= to=>` both present; `book=` registered; literal fragment target resolves in a declared sibling labels index (#96, #147) | all | Pre-flights the component's build-time throw and dead cross-book anchors across all files at once. |
 | Questions collection: unique `id`s + `domain` in `examDomains` (#112); `<Rationale appendix>` carries `for=` (#114, v4.21.0) | all, when `src/content/questions/` exists | Duplicate ids break the appendix/flashcards cross-ref key; an unregistered domain throws one-at-a-time at build; an appendix rationale without its anchor target throws at build. |
 | `los[].anchor` ↔ `{/* anchor: <slug> */}` prose markers agree both ways (#130, v4.20.0) | all, when frontmatter has `los:` | A declared objective whose prose marker is missing/misspelled (or an orphan marker) builds green otherwise — frontmatter↔prose drift only a hand audit would catch. |
 
 Validate also emits two **non-blocking shadow-route warnings** (exit code unaffected): a consumer-owned `src/pages/chapters/[...slug].astro` without `routes: { chapters: false }` (v4.6.0, #76), and a consumer-owned `src/pages/index.astro` without `routes: { landing: false }` (v4.20.0, #129 — Astro has announced this collision becomes a hard error). See [recipe 18](./18-chapter-route-ownership.md).
 
+### Cross-book labels indexes (#147)
+
+The original URL-string registry remains compatible. Use the descriptor form to opt a sibling into literal path/fragment validation:
+
+```ts
+export default await defineBookConfig({
+  styles: [minimalStyle],
+  site: 'https://docs.example/current/',
+  siblingBooks: {
+    legacy: 'https://legacy.example/',
+    design: {
+      // Deployment bases may be path-proxied; BookLink preserves this prefix.
+      url: 'https://hub.example/library/design/',
+      // Relative paths resolve from this consumer project's root.
+      labels: './vendor/design-labels.json',
+    },
+  },
+});
+```
+
+For a literal `<BookLink book="design" to="/chapters/patterns/#layered">`, validation looks up `layered` and verifies that its indexed `href` matches the authored sibling path. Leading route slashes and the optional slash immediately before `#` are normalized; the sibling deployment base is deliberately not part of the vendored index.
+
+Generate the sibling artifact in that sibling's project with `book-scaffold build-labels`, then vendor or sync the resulting `src/data/labels.json`. The builder indexes Markdown/MDX h2–h6 headings in addition to component IDs. Heading text and anchors come from Astro's Markdown processor, so inline formatting, smartypants, and GitHub-style duplicate suffixes (`repeat`, `repeat-1`, …) match the rendered page. Its base-less hrefs also use the sibling's evaluated `chapterRoute` and `bookField`; a root-routed book configured with `chapterRoute: '/:id/'` therefore emits `chapter-id#anchor`, not `chapters/chapter-id#anchor`.
+
+Heading-entry keys are intentionally opaque and path-qualified: `#summary` can legitimately occur in every chapter. Validation matches the normalized `href` values, so every repeated fragment remains addressable. Component-ID keys keep their historical shape for `<XRef>`; do not use a heading's internal JSON key as an XRef ID or derive it in consumer code.
+
+A declared `labels` file that is missing, unreadable, malformed, or not a JSON object is an error. An unknown book, unknown fragment, wrong path, or malformed label entry is also an error with the source file and target. Dynamic `book=`/`to=` expressions and prop spreads cannot be evaluated safely, so they emit explicit skip warnings. URL strings and `{ url }` descriptors likewise warn for literal fragment links because no index was declared. Non-fragment route links warn and skip: labels indexes describe anchors, not every sibling route.
+
 ## Missing generated artifacts
 
 `src/data/labels.json` and `src/data/references.json` are derived and normally gitignored. v4.27+ `validate` self-heals either missing file unconditionally by invoking the package's own `build-labels` or `build-bib` command before loading data. Existing files are untouched. A failed child command stops validation with the child's original diagnostic and exit status.
@@ -101,7 +129,7 @@ validate: ✗ 17 error(s) in 6 chapter(s) (profile=academic, number-style=shared
   ...
 ```
 
-Warnings (currently: internal-link unresolved) are printed to stderr but don't affect exit code.
+Warnings (internal-link uncertainty plus explicit BookLink skip cases) are printed to stderr but don't affect exit code.
 
 ## Extending the validator
 

package/recipes/22-responsive-nav-and-multibook-routing.md

@@ -83,6 +83,11 @@ import { chapterHref, apparatusHref, bookOf, isCurrentChapter }
 Pure functions, no `astro:content` — pass a `{ id, data }` and the same
 `chapterRoute` / `bookField` you set in `defineBookConfig`.
 
+`book-scaffold build-labels` evaluates those same two fields and routes every
+component and h2–h6 heading entry through `chapterHref`. A root- or multi-book
+site's vendored cross-book index therefore describes its real routes rather
+than silently falling back to `/chapters/<id>/`.
+
 ## Verify
 
 A consumer should drive a cross-device audit (Playwright is ideal): for each rich