@brandon_m_behring/book-scaffold-astro 4.27.1 → 4.29.0

package/dist/demo.d.ts

@@ -0,0 +1,96 @@
+import * as preact from 'preact';
+import { ComponentChildren } from 'preact';
+
+declare const DEMO_HEADING_LEVELS: readonly [2, 3, 4, 5, 6];
+type DemoHeadingLevel = (typeof DEMO_HEADING_LEVELS)[number];
+interface DemoFrameProps {
+    /** Visible accessible name for the teaching figure. */
+    title: string;
+    /** Short explanation rendered directly below the title. */
+    description?: string;
+    /** Figure caption rendered after the interactive body. */
+    caption?: ComponentChildren;
+    /** Consumer-owned controls and visualization. */
+    children?: ComponentChildren;
+    /** Optional stable root id for deep links and deterministic child ids. */
+    id?: string;
+    /** Additional class on the root figure. */
+    className?: string;
+    /** Reflect a consumer-owned recomputation/loading state to assistive tech. */
+    busy?: boolean;
+    /** Heading depth in the surrounding document outline. Defaults to 3. */
+    headingLevel?: DemoHeadingLevel;
+}
+declare function DemoFrame({ title, description, caption, children, id, className, busy, headingLevel, }: DemoFrameProps): preact.JSX.Element;
+
+interface SliderProps {
+    /** Visible label associated with the native range input. */
+    label: string;
+    /** Controlled numeric value. */
+    value: number;
+    min: number;
+    max: number;
+    /** Positive increment. Defaults to the native range-input step of 1. */
+    step?: number;
+    /** Receives the parsed numeric value for every native input event. */
+    onValueChange: (value: number) => void;
+    /** Optional stable input id. A hydration-stable id is generated otherwise. */
+    id?: string;
+    name?: string;
+    description?: string;
+    disabled?: boolean;
+    className?: string;
+    /** Formats the visible current-value output. */
+    formatValue?: (value: number) => string;
+    /** Optional spoken value text when the visible format is not descriptive. */
+    getValueText?: (value: number) => string;
+}
+declare function Slider(props: SliderProps): preact.JSX.Element;
+
+/** Semantic metric-card list for interactive teaching figures (#143). */
+declare const STAT_CARD_TONES: readonly ["neutral", "accent", "positive", "warning"];
+type StatCardTone = (typeof STAT_CARD_TONES)[number];
+interface StatCardItem {
+    /** Optional stable key. Defaults to the label, which must then be unique. */
+    id?: string;
+    label: string;
+    value: string | number;
+    /** Optional unit rendered beside the primary value. */
+    unit?: string;
+    /** Secondary explanatory line. */
+    detail?: string;
+    tone?: StatCardTone;
+}
+interface StatCardsProps {
+    items: readonly StatCardItem[];
+    /** Accessible name for the definition list. */
+    label?: string;
+    /** Opt-in announcements for values that change independently of a control. */
+    live?: 'off' | 'polite';
+    className?: string;
+}
+declare function StatCards({ items, label, live, className, }: StatCardsProps): preact.JSX.Element;
+
+type BookTheme = 'light' | 'dark';
+type ThemeColorToken = `--${string}`;
+type ThemeColorSpec = readonly [token: ThemeColorToken, fallback: string];
+type ThemeColorMap = Readonly<Record<string, ThemeColorSpec>>;
+type ResolvedThemeColors<T extends ThemeColorMap> = {
+    readonly [Key in keyof T]: string;
+};
+interface ThemeColorsSnapshot<T extends ThemeColorMap> {
+    /** Null during SSR; resolved on the first client effect. */
+    theme: BookTheme | null;
+    colors: ResolvedThemeColors<T>;
+    /** Null until the client preference is known; animate only when explicitly false. */
+    reducedMotion: boolean | null;
+}
+/**
+ * Resolve CSS custom properties and refresh after theme/motion changes.
+ *
+ * Keep the spec object outside the component (or otherwise stable) so its
+ * intent is obvious and the hook does not need to re-subscribe each render.
+ */
+declare function useThemeColors<const T extends ThemeColorMap>(specs: T): ThemeColorsSnapshot<T>;
+
+export { type BookTheme, DEMO_HEADING_LEVELS, DemoFrame, type DemoFrameProps, type DemoHeadingLevel, type ResolvedThemeColors, STAT_CARD_TONES, Slider, type SliderProps, type StatCardItem, type StatCardTone, StatCards, type StatCardsProps, type ThemeColorMap, type ThemeColorSpec, type ThemeColorToken, type ThemeColorsSnapshot, useThemeColors };

package/dist/demo.mjs

@@ -0,0 +1,353 @@
+// components/demo/DemoFrame.tsx
+import { useId } from "preact/hooks";
+import { jsx, jsxs } from "preact/jsx-runtime";
+var DEMO_HEADING_LEVELS = [2, 3, 4, 5, 6];
+function assertNonEmpty(value, prop) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`DemoFrame: ${prop} must be a non-empty string.`);
+  }
+}
+function generatedBaseId(id, generated) {
+  if (id !== void 0) {
+    assertNonEmpty(id, "id");
+    if (/\s/.test(id)) {
+      throw new Error("DemoFrame: id must not contain whitespace.");
+    }
+    return id;
+  }
+  return `demo-${generated.replace(/[^a-zA-Z0-9_-]/g, "")}`;
+}
+function DemoFrame({
+  title,
+  description,
+  caption,
+  children,
+  id,
+  className,
+  busy = false,
+  headingLevel = 3
+}) {
+  assertNonEmpty(title, "title");
+  if (description !== void 0) assertNonEmpty(description, "description");
+  if (typeof caption === "string") assertNonEmpty(caption, "caption");
+  if (!DEMO_HEADING_LEVELS.includes(headingLevel)) {
+    throw new Error("DemoFrame: headingLevel must be one of 2 | 3 | 4 | 5 | 6.");
+  }
+  const baseId = generatedBaseId(id, useId());
+  const titleId = `${baseId}-title`;
+  const descriptionId = description ? `${baseId}-description` : null;
+  const captionId = caption != null ? `${baseId}-caption` : null;
+  const describedBy = [descriptionId, captionId].filter(Boolean).join(" ") || void 0;
+  const classes = ["demo-frame", className].filter(Boolean).join(" ");
+  const Heading = `h${headingLevel}`;
+  return /* @__PURE__ */ jsxs(
+    "figure",
+    {
+      id,
+      class: classes,
+      "aria-labelledby": titleId,
+      "aria-describedby": describedBy,
+      "aria-busy": busy || void 0,
+      children: [
+        /* @__PURE__ */ jsxs("header", { class: "demo-frame__header", children: [
+          /* @__PURE__ */ jsx(Heading, { id: titleId, class: "demo-frame__title", children: title }),
+          description && /* @__PURE__ */ jsx("p", { id: descriptionId, class: "demo-frame__description", children: description })
+        ] }),
+        /* @__PURE__ */ jsx("div", { class: "demo-frame__body", children }),
+        caption != null && /* @__PURE__ */ jsx("figcaption", { id: captionId, class: "demo-frame__caption", children: caption })
+      ]
+    }
+  );
+}
+
+// components/demo/Slider.tsx
+import { useId as useId2 } from "preact/hooks";
+import { jsx as jsx2, jsxs as jsxs2 } from "preact/jsx-runtime";
+function assertFinite(value, prop) {
+  if (!Number.isFinite(value)) {
+    throw new Error(`Slider: ${prop} must be a finite number.`);
+  }
+}
+function isStepAligned(value, min, step) {
+  const steps = (value - min) / step;
+  const nearest = Math.round(steps);
+  const tolerance = Number.EPSILON * Math.max(1, Math.abs(steps)) * 16;
+  return Math.abs(steps - nearest) <= tolerance;
+}
+function assertSliderProps({
+  label,
+  value,
+  min,
+  max,
+  step = 1,
+  id,
+  description,
+  onValueChange,
+  formatValue,
+  getValueText
+}) {
+  if (typeof label !== "string" || label.trim() === "") {
+    throw new Error("Slider: label must be a non-empty string.");
+  }
+  assertFinite(value, "value");
+  assertFinite(min, "min");
+  assertFinite(max, "max");
+  assertFinite(step, "step");
+  if (max <= min) throw new Error("Slider: max must be greater than min.");
+  if (step <= 0) throw new Error("Slider: step must be greater than 0.");
+  if (value < min || value > max) {
+    throw new Error(`Slider: value ${value} must be within [${min}, ${max}].`);
+  }
+  if (!isStepAligned(value, min, step)) {
+    throw new Error("Slider: value must align with min + (n \xD7 step).");
+  }
+  if (id !== void 0 && (typeof id !== "string" || id.trim() === "" || /\s/.test(id))) {
+    throw new Error("Slider: id must be a non-empty string without whitespace.");
+  }
+  if (description !== void 0 && (typeof description !== "string" || description.trim() === "")) {
+    throw new Error("Slider: description must be a non-empty string.");
+  }
+  if (typeof onValueChange !== "function") {
+    throw new Error("Slider: onValueChange must be a function.");
+  }
+  if (formatValue !== void 0 && typeof formatValue !== "function") {
+    throw new Error("Slider: formatValue must be a function.");
+  }
+  if (getValueText !== void 0 && typeof getValueText !== "function") {
+    throw new Error("Slider: getValueText must be a function.");
+  }
+}
+function Slider(props) {
+  assertSliderProps(props);
+  const {
+    label,
+    value,
+    min,
+    max,
+    step = 1,
+    onValueChange,
+    id,
+    name,
+    description,
+    disabled = false,
+    className,
+    formatValue = String,
+    getValueText = formatValue
+  } = props;
+  const generated = useId2().replace(/[^a-zA-Z0-9_-]/g, "");
+  const inputId = id ?? `demo-slider-${generated}`;
+  const descriptionId = description ? `${inputId}-description` : void 0;
+  const displayValue = formatValue(value);
+  if (typeof displayValue !== "string" || displayValue.trim() === "") {
+    throw new Error("Slider: formatValue must return a non-empty string.");
+  }
+  const valueText = getValueText(value);
+  if (typeof valueText !== "string" || valueText.trim() === "") {
+    throw new Error("Slider: getValueText must return a non-empty string.");
+  }
+  const classes = ["demo-slider", className].filter(Boolean).join(" ");
+  return /* @__PURE__ */ jsxs2("div", { class: classes, "data-disabled": disabled || void 0, children: [
+    /* @__PURE__ */ jsxs2("div", { class: "demo-slider__head", children: [
+      /* @__PURE__ */ jsx2("label", { class: "demo-slider__label", for: inputId, children: label }),
+      /* @__PURE__ */ jsx2("output", { class: "demo-slider__value", for: inputId, children: displayValue })
+    ] }),
+    description && /* @__PURE__ */ jsx2("p", { id: descriptionId, class: "demo-slider__description", children: description }),
+    /* @__PURE__ */ jsx2(
+      "input",
+      {
+        id: inputId,
+        class: "demo-slider__input",
+        type: "range",
+        name,
+        min,
+        max,
+        step,
+        value,
+        disabled,
+        "aria-describedby": descriptionId,
+        "aria-valuetext": valueText,
+        onInput: (event) => {
+          const next = Number.parseFloat(event.currentTarget.value);
+          if (!Number.isFinite(next)) {
+            throw new Error("Slider: native input produced a non-finite value.");
+          }
+          onValueChange(next);
+        }
+      }
+    )
+  ] });
+}
+
+// components/demo/StatCards.tsx
+import { Fragment, jsx as jsx3, jsxs as jsxs3 } from "preact/jsx-runtime";
+var STAT_CARD_TONES = ["neutral", "accent", "positive", "warning"];
+function assertText(value, path) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`StatCards: ${path} must be a non-empty string.`);
+  }
+}
+function assertItems(items) {
+  if (!Array.isArray(items) || items.length === 0) {
+    throw new Error("StatCards: items must contain at least one statistic.");
+  }
+  const keys = /* @__PURE__ */ new Set();
+  for (const [index, item] of items.entries()) {
+    if (item === null || typeof item !== "object") {
+      throw new Error(`StatCards: items[${index}] must be a statistic object.`);
+    }
+    assertText(item.label, `items[${index}].label`);
+    if (typeof item.value !== "string" && typeof item.value !== "number") {
+      throw new Error(`StatCards: items[${index}].value must be a string or number.`);
+    }
+    if (typeof item.value === "number" && !Number.isFinite(item.value)) {
+      throw new Error(`StatCards: items[${index}].value must be finite.`);
+    }
+    if (typeof item.value === "string") assertText(item.value, `items[${index}].value`);
+    if (item.unit !== void 0) assertText(item.unit, `items[${index}].unit`);
+    if (item.detail !== void 0) assertText(item.detail, `items[${index}].detail`);
+    const tone = item.tone ?? "neutral";
+    if (!STAT_CARD_TONES.includes(tone)) {
+      throw new Error(
+        `StatCards: items[${index}].tone must be one of ${STAT_CARD_TONES.join(" | ")}.`
+      );
+    }
+    const key = item.id ?? item.label;
+    assertText(key, `items[${index}].id`);
+    if (keys.has(key)) throw new Error(`StatCards: duplicate item key "${key}".`);
+    keys.add(key);
+  }
+}
+function StatCards({
+  items,
+  label = "Key statistics",
+  live = "off",
+  className
+}) {
+  assertItems(items);
+  assertText(label, "label");
+  if (live !== "off" && live !== "polite") {
+    throw new Error("StatCards: live must be off | polite.");
+  }
+  const classes = ["demo-stat-cards", className].filter(Boolean).join(" ");
+  return /* @__PURE__ */ jsx3(
+    "dl",
+    {
+      class: classes,
+      "aria-label": label,
+      "aria-live": live,
+      "aria-atomic": live === "polite" || void 0,
+      children: items.map((item) => {
+        const tone = item.tone ?? "neutral";
+        return /* @__PURE__ */ jsxs3("div", { class: "demo-stat-card", "data-tone": tone, children: [
+          /* @__PURE__ */ jsx3("dt", { class: "demo-stat-card__label", children: item.label }),
+          /* @__PURE__ */ jsxs3("dd", { class: "demo-stat-card__value", children: [
+            item.value,
+            item.unit && /* @__PURE__ */ jsxs3(Fragment, { children: [
+              " ",
+              /* @__PURE__ */ jsx3("span", { class: "demo-stat-card__unit", children: item.unit })
+            ] })
+          ] }),
+          item.detail && /* @__PURE__ */ jsx3("dd", { class: "demo-stat-card__detail", children: item.detail })
+        ] }, item.id ?? item.label);
+      })
+    }
+  );
+}
+
+// components/demo/useThemeColors.ts
+import { useEffect, useState } from "preact/hooks";
+function fallbackColors(specs) {
+  return Object.fromEntries(
+    Object.entries(specs).map(([key, [, fallback]]) => [key, fallback])
+  );
+}
+function unresolvedSnapshot(specs) {
+  return {
+    theme: null,
+    colors: fallbackColors(specs),
+    reducedMotion: null
+  };
+}
+function assertSpecs(specs) {
+  if (specs === null || typeof specs !== "object" || Array.isArray(specs)) {
+    throw new Error("useThemeColors: specs must be a token-map object.");
+  }
+  const entries = Object.entries(specs);
+  if (entries.length === 0) {
+    throw new Error("useThemeColors: provide at least one CSS token mapping.");
+  }
+  for (const [key, spec] of entries) {
+    if (key.trim() === "") {
+      throw new Error("useThemeColors: color keys must be non-empty strings.");
+    }
+    if (!Array.isArray(spec) || spec.length !== 2) {
+      throw new Error(`useThemeColors: "${key}" must be a [token, fallback] pair.`);
+    }
+    const [token, fallback] = spec;
+    if (typeof token !== "string" || !/^--\S+$/.test(token)) {
+      throw new Error(`useThemeColors: "${key}" token must start with -- and contain no whitespace.`);
+    }
+    if (typeof fallback !== "string" || fallback.trim() === "") {
+      throw new Error(`useThemeColors: "${key}" fallback must be a non-empty string.`);
+    }
+  }
+}
+function effectiveTheme() {
+  const explicit = document.documentElement.getAttribute("data-theme");
+  if (explicit === "light" || explicit === "dark") return explicit;
+  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+function snapshot(specs, themeHint) {
+  const computed = getComputedStyle(document.documentElement);
+  const colors = Object.fromEntries(
+    Object.entries(specs).map(([key, [token, fallback]]) => {
+      const resolved = computed.getPropertyValue(token).trim();
+      return [key, resolved || fallback];
+    })
+  );
+  return {
+    theme: themeHint ?? effectiveTheme(),
+    colors,
+    reducedMotion: window.matchMedia("(prefers-reduced-motion: reduce)").matches
+  };
+}
+function useThemeColors(specs) {
+  assertSpecs(specs);
+  const signature = JSON.stringify(specs);
+  const [current, setCurrent] = useState(() => ({
+    signature,
+    value: unresolvedSnapshot(specs)
+  }));
+  useEffect(() => {
+    const refresh = (themeHint) => setCurrent({
+      signature,
+      value: snapshot(specs, themeHint)
+    });
+    const onThemeChange = (event) => {
+      const detail = event.detail;
+      const theme = detail?.theme === "light" || detail?.theme === "dark" ? detail.theme : void 0;
+      refresh(theme);
+    };
+    const onMediaChange = () => refresh();
+    const colorScheme = window.matchMedia("(prefers-color-scheme: dark)");
+    const reducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)");
+    refresh();
+    window.addEventListener("book:theme:change", onThemeChange);
+    colorScheme.addEventListener("change", onMediaChange);
+    reducedMotion.addEventListener("change", onMediaChange);
+    return () => {
+      window.removeEventListener("book:theme:change", onThemeChange);
+      colorScheme.removeEventListener("change", onMediaChange);
+      reducedMotion.removeEventListener("change", onMediaChange);
+    };
+  }, [signature]);
+  return current.signature === signature ? current.value : unresolvedSnapshot(specs);
+}
+export {
+  DEMO_HEADING_LEVELS,
+  DemoFrame,
+  STAT_CARD_TONES,
+  Slider,
+  StatCards,
+  useThemeColors
+};

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 };