@brandon_m_behring/book-scaffold-astro 4.31.0 → 5.1.0

package/dist/index.mjs

@@ -913,6 +913,17 @@ var BOOK_PROFILES = Object.keys(PROFILES);
 import { existsSync, readFileSync } from "fs";
 var BOOK_PRESETS = BOOK_PROFILES;
 var NUMBER_STYLES = ["shared", "per-kind"];
+var CORPUS_APPARATUS_ROUTES = [
+  "references",
+  "print",
+  "convergence",
+  "tips",
+  "exercises",
+  "practice-exam",
+  "glossary",
+  "flashcards",
+  "answers"
+];
 var BookConfigError = class extends Error {
   constructor(message) {
     super(message);
@@ -937,35 +948,25 @@ function readEnvFile(path = ".env") {
     return {};
   }
 }
-var PRESET_FALLBACK_WARNING = /* @__PURE__ */ Symbol.for("book-scaffold-astro:preset-fallback-warning");
 function resolvePreset(explicitPreset, explicitProfile) {
   let candidate = explicitPreset ?? explicitProfile ?? process.env.BOOK_PRESET ?? process.env.BOOK_PROFILE;
-  let source = "default";
-  if (explicitPreset || explicitProfile) source = "param";
-  else if (process.env.BOOK_PRESET || process.env.BOOK_PROFILE) source = "env";
   if (!candidate) {
     const env = readEnvFile();
     const fromFile = env.BOOK_PRESET ?? env.BOOK_PROFILE;
     if (fromFile) {
       candidate = fromFile;
-      source = "dotenv";
     }
   }
-  candidate = candidate ?? "minimal";
+  if (!candidate) {
+    throw new BookConfigError(
+      `book-scaffold-astro: no book preset was resolved. Add a built-in Style to \`defineBookConfig({ styles: [...] })\` and pass the same preset to \`defineBookSchemas({ preset: "..." })\`, pass one \`defineBookCorpus\` manifest to both entrypoints, or set BOOK_PRESET in the environment or .env. Valid presets: ${BOOK_PRESETS.join(" | ")}. See https://github.com/brandon-behring/book-scaffold-astro/blob/main/package/MIGRATION-v4-to-v5.md.`
+    );
+  }
   if (!BOOK_PRESETS.includes(candidate)) {
     throw new BookConfigError(
       `preset must be one of ${BOOK_PRESETS.join(" | ")} (got ${JSON.stringify(candidate)})`
     );
   }
-  if (source === "default") {
-    const warningState = globalThis;
-    if (!warningState[PRESET_FALLBACK_WARNING]) {
-      warningState[PRESET_FALLBACK_WARNING] = true;
-      console.warn(
-        "book-scaffold-astro: no preset resolved; falling back to 'minimal' for v4 compatibility. This fallback will be removed in v5. Add a built-in style to defineBookConfig and pass the same preset to defineBookSchemas, or set BOOK_PRESET."
-      );
-    }
-  }
   return candidate;
 }
 function resolveProfile(explicit) {
@@ -977,8 +978,316 @@ import { fileURLToPath } from "url";
 import { existsSync as existsSync3, readFileSync as readFileSync2, writeFileSync } from "fs";
 import { join } from "path";
 
+// src/lib/corpus.ts
+var BOOK_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var BOOK_CORPUS_BRAND = /* @__PURE__ */ Symbol.for(
+  "@brandon_m_behring/book-scaffold-astro/BookCorpus/v1"
+);
+var RESERVED_CORPUS_BOOK_IDS = Object.freeze([
+  "assets",
+  "chapters",
+  "search",
+  "questions",
+  "glossary",
+  "frontmatter",
+  "_astro",
+  "_og",
+  "pagefind"
+]);
+var CORPUS_OWNED_ROUTE_FIELDS = Object.freeze([
+  "chapterRoute",
+  "bookField",
+  "apparatusRoute",
+  "apparatusRoutes"
+]);
+var CORPUS_APPARATUS_TOGGLE_BY_ROUTE = Object.freeze({
+  references: "references",
+  print: "print",
+  convergence: "convergence",
+  tips: "tips",
+  exercises: "exercises",
+  "practice-exam": "practiceExam",
+  glossary: "glossary",
+  flashcards: "flashcards",
+  answers: "answers"
+});
+var RESERVED = new Set(RESERVED_CORPUS_BOOK_IDS);
+var APPARATUS = new Set(CORPUS_APPARATUS_ROUTES);
+var RESERVED_CONTENT_ROOTS = Object.freeze({
+  questions: "src/content/questions/ is the dedicated questions collection root",
+  glossary: "src/content/glossary/ is the dedicated glossary collection root",
+  frontmatter: "src/content/frontmatter/ is the shared frontmatter collection root"
+});
+var TOP_LEVEL_KEYS = /* @__PURE__ */ new Set(["preset", "books"]);
+var BRANDED_CORPUS_KEYS = /* @__PURE__ */ new Set(["__bookCorpusVersion", "preset", "books"]);
+var CORPUS_ARTIFACT_KEYS = /* @__PURE__ */ new Set(["schemaVersion", "books"]);
+var BOOK_KEYS = /* @__PURE__ */ new Set([
+  "id",
+  "title",
+  "subtitle",
+  "description",
+  "author",
+  "image",
+  "apparatus"
+]);
+function objectRecord(value, label) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new BookConfigError(`${label} must be an object.`);
+  }
+  return value;
+}
+function rejectUnknownKeys(value, allowed, label) {
+  const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+  if (unknown.length > 0) {
+    throw new BookConfigError(
+      `${label} has unknown field${unknown.length === 1 ? "" : "s"}: ${unknown.join(", ")}.`
+    );
+  }
+}
+function optionalNonBlankString(value, label) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new BookConfigError(`${label} must be a non-blank string when provided.`);
+  }
+  return value;
+}
+function validateBook(value, index) {
+  const label = `defineBookCorpus books[${index}]`;
+  const input = objectRecord(value, label);
+  rejectUnknownKeys(input, BOOK_KEYS, label);
+  const id = optionalNonBlankString(input.id, `${label}.id`);
+  if (id === void 0 || !BOOK_ID.test(id)) {
+    throw new BookConfigError(
+      `${label}.id must match [a-z0-9]+(?:-[a-z0-9]+)* (got ${JSON.stringify(input.id)}).`
+    );
+  }
+  if (RESERVED.has(id)) {
+    const reason = RESERVED_CONTENT_ROOTS[id] ?? "the scaffold owns that route or asset namespace";
+    throw new BookConfigError(
+      `${label}.id ${JSON.stringify(id)} is reserved because ${reason}; choose a book-specific id.`
+    );
+  }
+  const title = optionalNonBlankString(input.title, `${label}.title`);
+  if (title === void 0) {
+    throw new BookConfigError(`${label}.title must be a non-blank string.`);
+  }
+  let apparatus;
+  if (input.apparatus !== void 0) {
+    if (!Array.isArray(input.apparatus)) {
+      throw new BookConfigError(`${label}.apparatus must be an array when provided.`);
+    }
+    const seen = /* @__PURE__ */ new Set();
+    const routes = [];
+    for (const route of input.apparatus) {
+      if (typeof route !== "string" || !APPARATUS.has(route)) {
+        throw new BookConfigError(
+          `${label}.apparatus contains ${JSON.stringify(route)}; expected a subset of ` + CORPUS_APPARATUS_ROUTES.join(" | ") + "."
+        );
+      }
+      if (seen.has(route)) {
+        throw new BookConfigError(`${label}.apparatus contains duplicate route ${JSON.stringify(route)}.`);
+      }
+      seen.add(route);
+      routes.push(route);
+    }
+    apparatus = Object.freeze(routes);
+  }
+  const book = {
+    id,
+    title,
+    ...optionalField("subtitle", optionalNonBlankString(input.subtitle, `${label}.subtitle`)),
+    ...optionalField("description", optionalNonBlankString(input.description, `${label}.description`)),
+    ...optionalField("author", optionalNonBlankString(input.author, `${label}.author`)),
+    ...optionalField("image", optionalNonBlankString(input.image, `${label}.image`)),
+    ...apparatus === void 0 ? {} : { apparatus }
+  };
+  return Object.freeze(book);
+}
+function optionalField(key, value) {
+  return value === void 0 ? {} : { [key]: value };
+}
+function defineBookCorpus(inputValue) {
+  const input = objectRecord(inputValue, "defineBookCorpus input");
+  rejectUnknownKeys(input, TOP_LEVEL_KEYS, "defineBookCorpus input");
+  if (typeof input.preset !== "string" || !BOOK_PRESETS.includes(input.preset)) {
+    throw new BookConfigError(
+      `defineBookCorpus preset must be one of ${BOOK_PRESETS.join(" | ")} (got ${JSON.stringify(input.preset)}).`
+    );
+  }
+  if (!Array.isArray(input.books) || input.books.length === 0) {
+    throw new BookConfigError("defineBookCorpus books must be a non-empty array.");
+  }
+  const books = input.books.map(validateBook);
+  const seen = /* @__PURE__ */ new Set();
+  for (const book of books) {
+    if (seen.has(book.id)) {
+      throw new BookConfigError(`defineBookCorpus book id ${JSON.stringify(book.id)} is duplicated.`);
+    }
+    seen.add(book.id);
+  }
+  const corpus = {
+    __bookCorpusVersion: 1,
+    preset: input.preset,
+    books: Object.freeze(books)
+  };
+  Object.defineProperty(corpus, BOOK_CORPUS_BRAND, {
+    value: true,
+    enumerable: false,
+    configurable: false,
+    writable: false
+  });
+  return Object.freeze(corpus);
+}
+function assertBookCorpus(value) {
+  const invalid = () => new BookConfigError(
+    "corpus must be created by defineBookCorpus() from this book-scaffold major."
+  );
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw invalid();
+  }
+  const input = value;
+  if (input[BOOK_CORPUS_BRAND] !== true || input.__bookCorpusVersion !== 1 || !Object.isFrozen(value) || !Object.isFrozen(input.books)) {
+    throw invalid();
+  }
+  try {
+    rejectUnknownKeys(input, BRANDED_CORPUS_KEYS, "corpus");
+    if (typeof input.preset !== "string" || !BOOK_PRESETS.includes(input.preset)) {
+      throw invalid();
+    }
+    if (!Array.isArray(input.books) || input.books.length === 0) throw invalid();
+    const seen = /* @__PURE__ */ new Set();
+    for (const [index, rawBook] of input.books.entries()) {
+      if (!Object.isFrozen(rawBook)) throw invalid();
+      const book = validateBook(rawBook, index);
+      if (seen.has(book.id)) throw invalid();
+      seen.add(book.id);
+      if (book.apparatus !== void 0) {
+        const original = rawBook.apparatus;
+        if (!Object.isFrozen(original)) throw invalid();
+      }
+    }
+  } catch (error) {
+    if (error instanceof BookConfigError && error.message.startsWith("corpus must be created")) {
+      throw error;
+    }
+    throw invalid();
+  }
+}
+function corpusApparatusRoutesForBook(corpus, bookId, inheritedRoutes = []) {
+  const book = resolveCorpusBook(corpus, bookId);
+  return book.apparatus ?? inheritedRoutes;
+}
+function corpusBookHasApparatusRoute(corpus, bookId, route, inheritedRoutes = []) {
+  return corpusApparatusRoutesForBook(corpus, bookId, inheritedRoutes).includes(route);
+}
+function selectBookArtifact(value, corpus, bookId, artifact = "artifact") {
+  if (!corpus) return value;
+  if (!bookId) {
+    throw new Error(`${artifact}: cannot select a corpus payload without a current book.`);
+  }
+  resolveCorpusBook(corpus, bookId);
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(
+      `${artifact} is not a corpus artifact envelope; expected \`{ "schemaVersion": 1, "books": { ... } }\`.`
+    );
+  }
+  const envelopeRecord = value;
+  rejectUnknownKeys(envelopeRecord, CORPUS_ARTIFACT_KEYS, artifact);
+  const envelope = envelopeRecord;
+  if (envelope.schemaVersion !== 1 || envelope.books === null || typeof envelope.books !== "object" || Array.isArray(envelope.books)) {
+    throw new BookConfigError(
+      `${artifact} is not a corpus artifact envelope; expected \`{ "schemaVersion": 1, "books": { ... } }\`.`
+    );
+  }
+  const books = envelope.books;
+  const expected = corpus.books.map((book) => book.id);
+  const actual = Object.keys(books);
+  const missing = expected.filter((id) => !Object.prototype.hasOwnProperty.call(books, id));
+  const unknown = actual.filter((id) => !expected.includes(id));
+  if (missing.length > 0 || unknown.length > 0) {
+    throw new Error(
+      `${artifact} book keys do not match the corpus manifest` + (missing.length > 0 ? `; missing ${missing.join(", ")}` : "") + (unknown.length > 0 ? `; unknown ${unknown.join(", ")}` : "") + "."
+    );
+  }
+  return books[bookId];
+}
+function resolveCorpusBook(corpus, id) {
+  const book = corpus.books.find((candidate) => candidate.id === id);
+  if (!book) {
+    throw new BookConfigError(
+      `Unknown corpus book ${JSON.stringify(id)}; expected one of ${corpus.books.map((candidate) => candidate.id).join(" | ")}.`
+    );
+  }
+  return book;
+}
+function corpusBookIdOf(corpus, entryId) {
+  const candidate = entryId.split("/")[0] ?? "";
+  return corpus.books.some((book) => book.id === candidate) ? candidate : null;
+}
+function localCorpusEntryId(corpus, bookId, entryId) {
+  resolveCorpusBook(corpus, bookId);
+  const prefix = `${bookId}/`;
+  if (!entryId.startsWith(prefix) || entryId.length === prefix.length) {
+    throw new Error(
+      `Collection entry ${JSON.stringify(entryId)} is outside corpus book ${JSON.stringify(bookId)}.`
+    );
+  }
+  return entryId.slice(prefix.length);
+}
+function filterCorpusEntries(entries, corpus, bookId) {
+  if (!corpus) return [...entries];
+  if (!bookId) throw new Error("Cannot scope corpus content without a current book.");
+  resolveCorpusBook(corpus, bookId);
+  const prefix = `${bookId}/`;
+  return entries.filter((entry) => entry.id.startsWith(prefix));
+}
+function corpusCollectionEntryId(corpus, entry, data, options = {}) {
+  const label = options.label ?? "Content entry";
+  const normalized = entry.replaceAll("\\", "/").replace(/^\.\//, "");
+  const [bookId, ...localParts] = normalized.split("/");
+  if (!bookId || !corpus.books.some((book) => book.id === bookId)) {
+    throw new Error(`${label} ${JSON.stringify(entry)} is outside the registered corpus books.`);
+  }
+  if (Object.prototype.hasOwnProperty.call(data, "book") && data.book !== bookId) {
+    throw new Error(
+      `${label} ${JSON.stringify(entry)} has frontmatter book ${JSON.stringify(data.book)}, but its registered path owner is ${JSON.stringify(bookId)}.`
+    );
+  }
+  const fileId = localParts.join("/").replace(/\.(?:md|mdx)$/i, "");
+  const configured = options.slugField ? data[options.slugField] : void 0;
+  const localId = typeof configured === "string" ? configured : fileId;
+  const localSegments = localId.split("/");
+  let hasInvalidEncodedSegment = false;
+  for (const segment of localSegments) {
+    try {
+      const decoded = decodeURIComponent(segment);
+      if (decoded === "." || decoded === ".." || decoded.includes("/") || decoded.includes("\\")) {
+        hasInvalidEncodedSegment = true;
+      }
+    } catch {
+      hasInvalidEncodedSegment = true;
+    }
+  }
+  if (localId.length === 0 || localId.startsWith("/") || localId.endsWith("/") || localId.includes("\\") || localSegments.some((part) => part === "." || part === ".." || part.length === 0) || hasInvalidEncodedSegment) {
+    throw new Error(
+      `${label} ${JSON.stringify(entry)} resolved invalid corpus id ${JSON.stringify(localId)}.`
+    );
+  }
+  return `${bookId}/${localId}`;
+}
+function corpusBookIdFromPath(corpus, pathname, baseUrl = "/") {
+  const normalizedBase2 = baseUrl === "/" ? "/" : `/${baseUrl.replace(/^\/+|\/+$/g, "")}/`;
+  const relative = pathname.startsWith(normalizedBase2) ? pathname.slice(normalizedBase2.length) : pathname.replace(/^\/+/, "");
+  const segments = relative.split("/").filter(Boolean);
+  const candidate = segments[0] === "chapters" ? segments[1] : segments[0];
+  return candidate && corpus.books.some((book) => book.id === candidate) ? candidate : null;
+}
+
 // src/lib/define-style.ts
 function defineStyle(opts) {
+  if (Object.prototype.hasOwnProperty.call(opts, "deploy")) {
+    throw removedDeployError("defineStyle");
+  }
   return { __styleVersion: 1, ...opts };
 }
 function composeStyles(styles) {
@@ -987,11 +1296,13 @@ function composeStyles(styles) {
   }
   const merged = {};
   for (const style of styles) {
+    if (Object.prototype.hasOwnProperty.call(style, "deploy")) {
+      throw removedDeployError("composeStyles");
+    }
     if (style.name !== void 0) merged.name = style.name;
     if (style.preset !== void 0) merged.preset = style.preset;
     if (style.numberStyle !== void 0) merged.numberStyle = style.numberStyle;
     if (style.site !== void 0) merged.site = style.site;
-    if (style.deploy !== void 0) merged.deploy = style.deploy;
     if (style.releaseStatus !== void 0) {
       merged.releaseStatus = style.releaseStatus;
     }
@@ -1031,6 +1342,11 @@ function composeStyles(styles) {
   }
   return defineStyle(merged);
 }
+function removedDeployError(context) {
+  return new BookConfigError(
+    `book-scaffold-astro v5 removed ${context}({ deploy }) because the field never controlled deployment. Remove it and configure wrangler.toml or your deployment platform directly. See https://github.com/brandon-behring/book-scaffold-astro/blob/main/package/MIGRATION-v4-to-v5.md.`
+  );
+}
 function mergeMarkdown(a, b) {
   if (!a) return b;
   if (!b) return a;
@@ -1189,6 +1505,9 @@ var ROUTE_REGISTRY = {
   // Pre-v4.3.0 each consumer wrote this file by hand; all instances were
   // mechanical copies of the same boilerplate.
   chaptersSlug: { pattern: "/chapters/[...slug]", file: "chapters/[...slug].astro" },
+  // v5.0.0 (#80): corpus-only landing and per-book chapter index.
+  corpusBook: { pattern: "/[book]", file: "book.astro" },
+  corpusChapters: { pattern: "/chapters/[book]", file: "chapters-book.astro" },
   convergence: { pattern: "/convergence", file: "convergence.astro" },
   // v4.3.0 (#70): cross-volume numbered-tips index. Opt-in via
   // routes.tips: true; pairs with build-tips script + <Tip> component.
@@ -1241,8 +1560,30 @@ function resolvePage(file) {
   return fileURLToPath(new URL(`../pages/${file}`, import.meta.url));
 }
 function bookScaffoldIntegration(opts) {
+  if (!BOOK_PRESETS.includes(opts.profile)) {
+    throw new BookConfigError(
+      `bookScaffoldIntegration profile must be one of ${BOOK_PRESETS.join(" | ")} (got ${JSON.stringify(opts.profile)}).`
+    );
+  }
+  if (opts.corpus !== void 0) {
+    assertBookCorpus(opts.corpus);
+    if (opts.corpus.preset !== opts.profile) {
+      throw new BookConfigError(
+        `bookScaffoldIntegration corpus preset ${JSON.stringify(opts.corpus.preset)} does not match profile ${JSON.stringify(opts.profile)}. One preset applies to the whole corpus.`
+      );
+    }
+    const incompatible = CORPUS_OWNED_ROUTE_FIELDS.filter(
+      (field) => Object.prototype.hasOwnProperty.call(opts, field)
+    );
+    if (incompatible.length > 0) {
+      throw new BookConfigError(
+        `Corpus mode owns ${incompatible.join(", ")}; remove the explicit ${incompatible.length === 1 ? "override" : "overrides"} so injected routes and navigation agree.`
+      );
+    }
+  }
   const {
     profile,
+    corpus,
     numberStyle = "shared",
     routes: userOverrides = {},
     extraStyles = [],
@@ -1282,6 +1623,32 @@ function bookScaffoldIntegration(opts) {
     ),
     frontmatter: fmEnabled
   };
+  const enabledRouteNames = Object.freeze(
+    Object.entries(enabledRoutes).filter(([, on]) => on).map(([name]) => name)
+  );
+  if (corpus) {
+    for (const book of corpus.books) {
+      for (const route of book.apparatus ?? []) {
+        const toggle = CORPUS_APPARATUS_TOGGLE_BY_ROUTE[route];
+        if (!enabledRoutes[toggle]) {
+          throw new BookConfigError(
+            `Corpus book ${JSON.stringify(book.id)} enables apparatus route ${JSON.stringify(route)}, but RouteToggles.${toggle} is disabled. Enable routes.${toggle} globally or remove the book apparatus entry.`
+          );
+        }
+      }
+    }
+  }
+  const inheritedCorpusApparatusRoutes = corpus ? CORPUS_APPARATUS_ROUTES.filter(
+    (route) => enabledRoutes[CORPUS_APPARATUS_TOGGLE_BY_ROUTE[route]]
+  ) : [];
+  const corpusApparatusRoutes = corpus ? CORPUS_APPARATUS_ROUTES.filter(
+    (route) => corpus.books.some(
+      (book) => (book.apparatus ?? inheritedCorpusApparatusRoutes).includes(route)
+    )
+  ) : [];
+  const corpusApparatusToggleKeys = new Set(
+    Object.values(CORPUS_APPARATUS_TOGGLE_BY_ROUTE)
+  );
   const integration = {
     name: "book-scaffold-astro",
     hooks: {
@@ -1296,24 +1663,39 @@ function bookScaffoldIntegration(opts) {
         const routesToInject = [];
         for (const [name, on] of Object.entries(enabledRoutes)) {
           if (!on) continue;
+          if (corpus && corpusApparatusToggleKeys.has(name)) continue;
           routesToInject.push(name);
-          if (name === "chapters") routesToInject.push("chaptersSlug");
+          if (name === "chapters") {
+            routesToInject.push("chaptersSlug");
+            if (corpus) routesToInject.push("corpusChapters");
+          }
+          if (name === "landing" && corpus) routesToInject.push("corpusBook");
         }
         for (const name of routesToInject) {
           const route = ROUTE_REGISTRY[name];
           if (!route) continue;
-          const pattern = name === "frontmatter" ? frontmatterPatternFromPrefix(fmPrefix) : route.pattern;
+          let pattern = name === "frontmatter" ? frontmatterPatternFromPrefix(fmPrefix) : route.pattern;
+          if (corpus && name === "chaptersSlug") {
+            pattern = "/chapters/[book]/[...slug]";
+          }
           injectRoute({
             pattern,
             entrypoint: resolvePage(route.file)
           });
         }
+        if (corpus) {
+          for (const route of corpusApparatusRoutes) {
+            injectRoute({
+              pattern: `/[book]/${route}`,
+              entrypoint: resolvePage(`corpus-apparatus/${route}.astro`)
+            });
+          }
+        }
         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({
           vite: {
             plugins: [
@@ -1339,8 +1721,9 @@ function bookScaffoldIntegration(opts) {
                 // reproduce the single-book `/chapters/<id>/` behavior exactly.
                 chapterRoute: chapterRoute ?? "/chapters/:id/",
                 bookField: bookField ?? "book",
-                apparatusRoute: apparatusRoute ?? "/:route/",
-                apparatusRoutes: apparatusRoutes ?? []
+                apparatusRoute: corpus ? "/:book/:route/" : apparatusRoute ?? "/:route/",
+                apparatusRoutes: corpus ? inheritedCorpusApparatusRoutes : apparatusRoutes ?? [],
+                corpus: corpus ?? null
               })
             ],
             define: {
@@ -1383,8 +1766,13 @@ function bookScaffoldIntegration(opts) {
       preset: profile,
       numberStyle,
       siblingBooks: siblingBooks ?? {},
-      chapterRoute: chapterRoute ?? "/chapters/:id/",
-      bookField: bookField ?? "book"
+      corpus: corpus ?? null,
+      chapterRoute: corpus ? "/chapters/:id/" : chapterRoute ?? "/chapters/:id/",
+      bookField: bookField ?? "book",
+      apparatusRoute: corpus ? "/:book/:route/" : apparatusRoute ?? "/:route/",
+      apparatusRoutes: corpus ? inheritedCorpusApparatusRoutes : apparatusRoutes ?? [],
+      enabledRoutes: enabledRouteNames,
+      frontmatterRoute: frontmatterPatternFromPrefix(fmPrefix)
     }),
     enumerable: false,
     configurable: false,
@@ -1428,12 +1816,38 @@ async function defineBookConfig(opts) {
     throw v3MigrationError(opts);
   }
   if (Object.prototype.hasOwnProperty.call(opts, "deploy")) {
-    console.warn(
-      "book-scaffold-astro: defineBookConfig({ deploy }) is inert and deprecated; create-book chooses wrangler.toml from its CLI preset. Remove this field before upgrading to v5 (#180)."
+    throw new BookConfigError(
+      "book-scaffold-astro v5 removed defineBookConfig({ deploy }) because the field never controlled deployment. Remove it and configure wrangler.toml or your deployment platform directly. See https://github.com/brandon-behring/book-scaffold-astro/blob/main/package/MIGRATION-v4-to-v5.md."
     );
   }
   const composed = composeStyles(opts.styles ?? []);
-  const profile = resolvePreset(composed.preset);
+  const corpus = opts.corpus;
+  if (corpus !== void 0) {
+    assertBookCorpus(corpus);
+  }
+  const profile = resolvePreset(composed.preset ?? corpus?.preset);
+  if (corpus !== void 0) {
+    if (corpus.preset !== profile) {
+      throw new BookConfigError(
+        `defineBookConfig corpus preset ${JSON.stringify(corpus.preset)} does not match the composed Style preset ${JSON.stringify(profile)}. One preset applies to the whole corpus.`
+      );
+    }
+    const incompatible = CORPUS_OWNED_ROUTE_FIELDS.filter(
+      (field) => Object.prototype.hasOwnProperty.call(opts, field)
+    );
+    if (incompatible.length > 0) {
+      throw new BookConfigError(
+        `Corpus mode owns ${incompatible.join(", ")}; remove the explicit ${incompatible.length === 1 ? "override" : "overrides"} so injected routes and navigation agree.`
+      );
+    }
+    const siblingKeys = new Set(Object.keys(opts.siblingBooks ?? {}));
+    const duplicateOwner = corpus.books.find((book) => siblingKeys.has(book.id));
+    if (duplicateOwner) {
+      throw new BookConfigError(
+        `Book id ${JSON.stringify(duplicateOwner.id)} exists in both corpus.books and siblingBooks. A key must be either local or externally deployed, never both.`
+      );
+    }
+  }
   const numberStyle = opts.numberStyle ?? composed.numberStyle ?? "shared";
   if (!NUMBER_STYLES.includes(numberStyle)) {
     throw new BookConfigError(
@@ -1507,6 +1921,7 @@ async function defineBookConfig(opts) {
     sitemap(sitemapOptions),
     bookScaffoldIntegration({
       profile,
+      corpus,
       numberStyle,
       routes: mergedRoutes,
       mdxComponentsModule,
@@ -1538,11 +1953,16 @@ async function defineBookConfig(opts) {
       siblingBooks: opts.siblingBooks,
       // v4.17.0 (#112): per-book exam-domain taxonomy for the questions collection.
       examDomains: opts.examDomains,
-      // v4.26.0 (#80): book-aware nav route patterns (undefined → single-book defaults).
-      chapterRoute: opts.chapterRoute,
-      bookField: opts.bookField,
-      apparatusRoute: opts.apparatusRoute,
-      apparatusRoutes: opts.apparatusRoutes
+      // v4.26.0 (#80): book-aware nav route patterns (undefined → single-book
+      // defaults). Corpus mode owns these fields, so do not manufacture own
+      // properties with undefined values when handing the validated manifest
+      // to the independently exported integration.
+      ...corpus ? {} : {
+        chapterRoute: opts.chapterRoute,
+        bookField: opts.bookField,
+        apparatusRoute: opts.apparatusRoute,
+        apparatusRoutes: opts.apparatusRoutes
+      }
     }),
     ...mergedExtraIntegrations
   ];
@@ -1569,10 +1989,10 @@ async function defineBookConfig(opts) {
   };
   const {
     styles: _styles,
+    corpus: _corpus,
     numberStyle: _numberStyle,
     site: _site,
     routes: _routes,
-    deploy: _deploy,
     mdxComponentsModule: _mdxComponentsModule,
     extraIntegrations: _extraIntegrations,
     extraStyles: _extraStyles,
@@ -1605,10 +2025,10 @@ async function defineBookConfig(opts) {
     ...rest
   } = opts;
   void _styles;
+  void _corpus;
   void _numberStyle;
   void _site;
   void _routes;
-  void _deploy;
   void _mdxComponentsModule;
   void _extraIntegrations;
   void _extraStyles;
@@ -1727,6 +2147,54 @@ function assertEnumProp(value, allowed, ctx) {
 init_katex_macros();
 
 // src/lib/book-link.ts
+var CORPUS_BOOK_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function normalizedBase(baseUrl) {
+  const inner = baseUrl.replace(/^\/+|\/+$/g, "");
+  return inner.length === 0 ? "/" : `/${inner}/`;
+}
+function invalidLocalTarget(book, to, reason) {
+  throw new Error(
+    `<BookLink book="${book}" to=${JSON.stringify(to)}>: invalid local corpus target (${reason}).`
+  );
+}
+function resolveCorpusBookHref(book, to, baseUrl = "/") {
+  if (!CORPUS_BOOK_ID.test(book)) {
+    throw new Error(`<BookLink book=${JSON.stringify(book)}>: invalid corpus book id.`);
+  }
+  if (typeof to !== "string" || to.trim().length === 0) {
+    invalidLocalTarget(book, String(to), "target must be non-empty");
+  }
+  if (to !== to.trim()) invalidLocalTarget(book, to, "surrounding whitespace is not allowed");
+  if (/^[a-z][a-z0-9+.-]*:/i.test(to) || to.startsWith("/") || to.includes("\\")) {
+    invalidLocalTarget(book, to, "absolute URLs and paths are not allowed");
+  }
+  if (/[\u0000-\u001f\u007f]/.test(to)) {
+    invalidLocalTarget(book, to, "control characters are not allowed");
+  }
+  const suffixIndex = [...[to.indexOf("?"), to.indexOf("#")]].filter((index) => index >= 0).reduce((minimum, index) => Math.min(minimum, index), to.length);
+  const path = to.slice(0, suffixIndex);
+  const suffix = to.slice(suffixIndex);
+  if (path.length === 0) invalidLocalTarget(book, to, "query-only and fragment-only targets are not allowed");
+  const segments = path.replace(/\/+$/, "").split("/");
+  if (segments.some((segment) => segment.length === 0)) {
+    invalidLocalTarget(book, to, "empty path segments are not allowed");
+  }
+  for (const segment of segments) {
+    let decoded;
+    try {
+      decoded = decodeURIComponent(segment);
+    } catch {
+      invalidLocalTarget(book, to, "malformed percent encoding");
+    }
+    if (decoded === "." || decoded === ".." || decoded.includes("/") || decoded.includes("\\")) {
+      invalidLocalTarget(book, to, "path traversal is not allowed");
+    }
+  }
+  const base = normalizedBase(baseUrl);
+  const local = segments.join("/");
+  const destination = local === "chapters" ? `chapters/${book}` : local.startsWith("chapters/") ? `chapters/${book}/${local.slice("chapters/".length)}` : `${book}/${local}`;
+  return `${base}${destination}/`.replace(/\/{2,}/g, "/") + suffix;
+}
 function entryUrl(entry) {
   if (typeof entry === "string") return entry;
   return entry?.url;
@@ -1922,7 +2390,7 @@ function buildExamManifest(entries) {
     options: (e.data.options ?? []).map((o) => ({ id: o.id, correct: o.correct === true }))
   }));
 }
-function deriveDomainRouting(entries, baseUrl = "/") {
+function deriveDomainRouting(entries, baseUrl = "/", bookId) {
   const base = baseUrl.replace(/\/?$/, "/");
   const out = {};
   const seen = /* @__PURE__ */ new Set();
@@ -1933,7 +2401,7 @@ function deriveDomainRouting(entries, baseUrl = "/") {
     seen.add(key);
     (out[e.data.domain] ??= []).push({
       label,
-      href: typeof e.data.chapter === "string" ? `${base}chapters/${e.data.chapter}/` : null
+      href: typeof e.data.chapter === "string" ? `${base}chapters/${bookId ? `${bookId}/` : ""}${e.data.chapter}/` : null
     });
   }
   return out;
@@ -1984,28 +2452,23 @@ function selectPartExercises(chapters, byChapter, part) {
 // src/styles/built-in.ts
 var academicStyle = defineStyle({
   name: "academic",
-  preset: "academic",
-  deploy: "workers"
+  preset: "academic"
 });
 var toolsStyle = defineStyle({
   name: "tools",
-  preset: "tools",
-  deploy: "workers"
+  preset: "tools"
 });
 var minimalStyle = defineStyle({
   name: "minimal",
-  preset: "minimal",
-  deploy: "workers"
+  preset: "minimal"
 });
 var courseNotesStyle = defineStyle({
   name: "course-notes",
-  preset: "course-notes",
-  deploy: "pages"
+  preset: "course-notes"
 });
 var researchPortfolioStyle = defineStyle({
   name: "research-portfolio",
   preset: "research-portfolio",
-  deploy: "pages",
   routes: { frontmatter: { enabled: true, prefix: "frontmatter" } }
 });
 var BUILTIN_STYLES = {
@@ -2027,9 +2490,12 @@ export {
   BRANDON_PORTFOLIO_DEFAULT,
   BUILTIN_STYLES,
   BookConfigError,
+  CORPUS_APPARATUS_ROUTES,
+  CORPUS_APPARATUS_TOGGLE_BY_ROUTE,
   DEFAULT_GITHUB_BRANCH,
   KIND_LABEL,
   NUMBER_STYLES,
+  RESERVED_CORPUS_BOOK_IDS,
   THEOREM_KINDS,
   UNKNOWN_PART_ORDINAL,
   academicChapterSchema,
@@ -2040,6 +2506,7 @@ export {
   academicParts,
   academicStyle,
   apparatusHref,
+  assertBookCorpus,
   assertEnumProp,
   assertKnownDomain,
   baseNoSlash,
@@ -2057,9 +2524,15 @@ export {
   chapterStatus,
   citationBackstops,
   composeStyles,
+  corpusApparatusRoutesForBook,
+  corpusBookHasApparatusRoute,
+  corpusBookIdFromPath,
+  corpusBookIdOf,
+  corpusCollectionEntryId,
   courseNotesChapterSchema,
   courseNotesStyle,
   defineBookConfig,
+  defineBookCorpus,
   defineMdxComponents,
   defineProfile,
   defineStyle,
@@ -2068,6 +2541,7 @@ export {
   deriveObjectiveMap,
   distinctChaptersSorted,
   fallbackChaptersRenderer,
+  filterCorpusEntries,
   freshnessLabel,
   getFreshness,
   glossarySchema,
@@ -2075,6 +2549,7 @@ export {
   groupByDomain,
   isCurrentChapter,
   layoutModes,
+  localCorpusEntryId,
   minimalChapterSchema,
   minimalStyle,
   normalizeBase,
@@ -2095,12 +2570,15 @@ export {
   researchPortfolioChaptersRenderer,
   researchPortfolioStyle,
   resolveBookHref,
+  resolveCorpusBook,
+  resolveCorpusBookHref,
   resolveGithubRepo,
   resolvePreset,
   resolveProfile,
   resolveTheoremNumber,
   sampleExam,
   scoreExam,
+  selectBookArtifact,
   selectPartExercises,
   shuffle,
   slugOf,