@brandon_m_behring/book-scaffold-astro 4.29.0 → 4.30.0

package/CLAUDE.md

@@ -201,6 +201,7 @@ the full precedence and customization contract.
 - Literal `<Theorem n>` values that disagree with `labels.json` (dynamic expressions and `label=` overrides are skipped)
 - Missing `<Figure src>` files under `public/`
 - Internal markdown links that don't resolve
+- Authored root-absolute Markdown/HTML/JSX `href` or `src` targets that escape a configured non-root Astro `base` (#190). Structurally parsed and decoded literal targets fail with file/line context; root-base books, external/protocol-relative URLs, fragments, dynamic JSX expressions, and already base-prefixed targets are unaffected. `rel="external"` does not change URL resolution or opt out. Validation never rewrites prose.
 - Study-guide questions (v4.17.0, #112) — a question whose frontmatter `domain` isn't in `examDomains`, and duplicate question `id`s
 
 Missing `src/data/labels.json` or `references.json` self-heals before checks by running the corresponding package build script; an existing artifact is never rewritten implicitly.

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.29.0",
+  "version": "4.30.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -190,9 +190,6 @@
     },
     "rehype-katex": {
       "optional": true
-    },
-    "remark-math": {
-      "optional": true
     }
   },
   "dependencies": {
@@ -203,6 +200,8 @@
     "@fontsource-variable/roboto": "^5.2.10",
     "@fontsource-variable/source-code-pro": "^5.2.7",
     "pagefind": "^1.5.2",
+    "parse5": "^7.3.0",
+    "remark-math": "^6.0.0",
     "remark-mdx": "^3.1.1",
     "remark-parse": "^11.0.0",
     "unified": "^11.0.5",

package/recipes/09-validation.md

@@ -2,7 +2,7 @@
 
 **Profile**: any (Cite checks skip under non-academic).
 
-**TL;DR**: `npm run validate` runs `scripts/validate.mjs` against all chapter MDX files. It first regenerates missing `labels.json` and `references.json`, then catches typo'd bibkeys / XRef ids / Figure paths / internal links that `astro build` would either miss or surface with poor context. Auto-runs as `prebuild`; recommend wiring into pre-commit too.
+**TL;DR**: `npm run validate` runs `scripts/validate.mjs` against chapter MD/MDX files (plus its question-collection checks). It first regenerates missing `labels.json` and `references.json`, then catches typo'd bibkeys / XRef ids / Figure paths / internal links that `astro build` would either miss or surface with poor context. Auto-runs as `prebuild`; recommend wiring into pre-commit too.
 
 ## What gets checked
 
@@ -17,6 +17,7 @@
 | `<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. |
+| Literal authored Markdown/HTML/JSX `href`/`src` stays inside a non-root Astro `base` (#190) | all | A browser resolves `/chapters/...` from the host root, bypassing Astro's deployment base and producing a convincing 404. This is a build-blocking error, not a rewrite. |
 
 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).
 
@@ -48,6 +49,24 @@ Heading-entry keys are intentionally opaque and path-qualified: `#summary` can l
 
 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.
 
+## Authored links under a non-root base (#190)
+
+When evaluated `astro.config.*` sets a non-root base such as `base: '/library/books/'`, a root-absolute authored URL escapes that deployment mount:
+
+```mdx
+<!-- Errors: both resolve from the host root, outside /library/books/. -->
+[Chapter one](/chapters/one/)
+<img src="/figures/overview.svg" alt="Overview" />
+
+<!-- Valid: explicitly remains inside the configured base. -->
+[Chapter one](/library/books/chapters/one/)
+<a href={`${import.meta.env.BASE_URL}references/`}>References</a>
+```
+
+The validator structurally parses inline Markdown links and images, Markdown reference definitions, quoted or unquoted HTML `href`/`src`, and quoted or statically braced JSX string attributes. HTML entities and JavaScript string escapes are decoded before containment is checked. It reports the authored file and line, the evaluated target, the evaluated base, and a browser-normalized base-prefixed replacement. It also scans question MD/MDX files already visited by validation.
+
+The check is deliberately validation-only: it does not mutate or rewrite content, and there is no opt-out. Under the root base (`/`) it is inert. Protocol URLs (`https:`, `mailto:`, `data:`, and others), protocol-relative URLs (`//cdn…`), fragments, relative targets, targets already inside the base, and dynamic JSX expressions are excluded. `rel="external"` describes a relationship but does not change where a browser navigates, so it does not exempt a host-root URL. Frontmatter, comments, fenced/inline/indented code examples, and `<pre>`/`<code>` examples are excluded by their parsed Markdown/MDX structure so documentation snippets do not become false diagnostics.
+
 ## 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.
@@ -96,7 +115,7 @@ For pre-commit: add to `.pre-commit-config.yaml`:
 
 ## Preset / chaptersBase resolution (v4.7.0+, #75)
 
-The validator evaluates `astro.config.*` through Vite first. A resolved scaffold integration supplies the composed preset and `numberStyle`, so CLI tooling sees the same Style chain as the Astro build. Without such an integration, the legacy preset chain remains: `--preset` → process `BOOK_PRESET`/`BOOK_PROFILE` → root `.env` → the literal value in `defineBookSchemas` → a warned `minimal` v4 compatibility fallback. Every selected value is checked against the five-preset enum; config-evaluation failures stop validation instead of silently using defaults.
+The validator evaluates `astro.config.*` through Vite first. A resolved scaffold integration supplies the composed preset and `numberStyle`, so CLI tooling sees the same Style chain as the Astro build. The evaluated Astro `base` is read from that same config regardless of whether the scaffold integration is present; omission defaults to `/`. Without such an integration, the legacy preset chain remains: `--preset` → process `BOOK_PRESET`/`BOOK_PROFILE` → root `.env` → the literal value in `defineBookSchemas` → a warned `minimal` v4 compatibility fallback. Every selected value is checked against the five-preset enum; config-evaluation failures stop validation instead of silently using defaults.
 
 `chaptersBase` resolution still consults `BOOK_CHAPTERS_DIR`, content configuration, then `src/content/chapters`. The v4.5+ canonical form is:
 

package/scripts/authored-links.mjs

@@ -0,0 +1,328 @@
+/**
+ * Structural authored-link discovery for `book-scaffold validate` (#190).
+ *
+ * Markdown and MDX are parsed into their real syntax trees so code examples,
+ * comments, nested labels, JSX expressions, and literal decoding follow the
+ * same grammar as the rendered book. Raw HTML is parsed only from ranges that
+ * the Markdown AST identified as HTML. This module never rewrites content.
+ */
+import { parseFragment } from 'parse5';
+import remarkMath from 'remark-math';
+import remarkMdx from 'remark-mdx';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+
+const ORIGIN = 'https://book-scaffold.invalid';
+const processors = new Map();
+
+/** Normalize the portion of Astro's `base` relevant to containment checks. */
+export function normalizeAstroBase(base = '/') {
+  const value = typeof base === 'string' && base.length > 0 ? base : '/';
+  const withLeadingSlash = value.startsWith('/') ? value : `/${value}`;
+  const pathname = new URL(withLeadingSlash, ORIGIN).pathname;
+  return pathname.replace(/\/+$/, '') || '/';
+}
+
+/**
+ * Parse a browser-rooted same-origin target. A single leading backslash is
+ * included because WHATWG HTTP URL parsing treats it as a root slash. True
+ * protocol-relative URLs and inputs that resolve onto another host are not
+ * internal authored targets.
+ */
+function rootTargetUrl(target) {
+  if (typeof target !== 'string') return null;
+  const value = target.trim();
+  if (!value.startsWith('/') && !value.startsWith('\\')) return null;
+  if (value.startsWith('//') || value.startsWith('\\\\')) return null;
+
+  try {
+    const url = new URL(value, ORIGIN);
+    return url.origin === ORIGIN ? url : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Browser-normalized pathname for a same-origin root target, else null. */
+export function rootTargetPathname(target) {
+  const url = rootTargetUrl(target);
+  return url ? url.pathname.replace(/\/+$/, '') || '/' : null;
+}
+
+/**
+ * True only for a same-origin root target outside `base`.
+ * Protocols, protocol-relative URLs, fragments, relative URLs, and targets
+ * already under the configured base all return false.
+ */
+export function rootTargetEscapesBase(target, base) {
+  const normalizedBase = normalizeAstroBase(base);
+  if (normalizedBase === '/') return false;
+
+  const pathname = rootTargetPathname(target);
+  if (pathname === null) return false;
+  return pathname !== normalizedBase && !pathname.startsWith(`${normalizedBase}/`);
+}
+
+/**
+ * Return a browser-normalized, base-contained suggestion for a violating
+ * target. Normalizing before prefixing prevents `..` (including percent-
+ * encoded dot segments) from escaping the base a second time.
+ */
+export function suggestBaseContainedTarget(target, base) {
+  const normalizedBase = normalizeAstroBase(base);
+  const url = rootTargetUrl(target);
+  if (!url) return target;
+  const prefix = normalizedBase === '/' ? '' : normalizedBase;
+  return `${prefix}${url.pathname}${url.search}${url.hash}`;
+}
+
+function blankFrontmatter(content) {
+  return content.replace(
+    /^\uFEFF?---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/,
+    (match) => match.replace(/[^\r\n]/g, ' '),
+  );
+}
+
+function processorFor(format, math) {
+  const key = `${format}:${math ? 'math' : 'plain'}`;
+  if (!processors.has(key)) {
+    const processor = unified().use(remarkParse);
+    if (format === 'mdx') processor.use(remarkMdx);
+    // Math syntax is profile-dependent. Enabling it for every book would hide
+    // real links authored between dollar signs in non-math profiles.
+    if (math) processor.use(remarkMath);
+    processors.set(key, processor);
+  }
+  return processors.get(key);
+}
+
+function positionStart(node) {
+  return node?.position?.start?.offset ?? 0;
+}
+
+function attributeValueOffset(source, start, end) {
+  const attribute = source.slice(start, end);
+  const equals = attribute.indexOf('=');
+  if (equals < 0) return start;
+
+  let offset = equals + 1;
+  while (/\s/.test(attribute[offset] ?? '')) offset += 1;
+  if (attribute[offset] === '"' || attribute[offset] === "'") offset += 1;
+  return start + offset;
+}
+
+function markdownDestinationOffset(node, source) {
+  const start = positionStart(node);
+  const end = node?.position?.end?.offset ?? start;
+  const authored = source.slice(start, end);
+  const marker = node.type === 'definition' ? authored.lastIndexOf(']:') : authored.lastIndexOf('](');
+  if (marker < 0) return start;
+
+  let offset = marker + 2;
+  while (/\s/.test(authored[offset] ?? '')) offset += 1;
+  if (authored[offset] === '<') offset += 1;
+  return start + offset;
+}
+
+function literalMdxAttribute(attribute, source) {
+  if (typeof attribute.value === 'string') {
+    return {
+      target: attribute.value,
+      index: attributeValueOffset(
+        source,
+        positionStart(attribute),
+        attribute.position?.end?.offset ?? positionStart(attribute),
+      ),
+    };
+  }
+
+  if (attribute.value?.type !== 'mdxJsxAttributeValueExpression') return null;
+  const program = attribute.value.data?.estree;
+  if (program?.body?.length !== 1 || program.body[0]?.type !== 'ExpressionStatement') return null;
+  const expression = program.body[0].expression;
+
+  if (expression?.type === 'Literal' && typeof expression.value === 'string') {
+    return { target: expression.value, index: expression.start ?? positionStart(attribute) };
+  }
+  if (
+    expression?.type === 'TemplateLiteral' &&
+    expression.expressions?.length === 0 &&
+    expression.quasis?.length === 1 &&
+    typeof expression.quasis[0].value?.cooked === 'string'
+  ) {
+    return {
+      target: expression.quasis[0].value.cooked,
+      index: expression.quasis[0].start ?? expression.start ?? positionStart(attribute),
+    };
+  }
+  return null;
+}
+
+/**
+ * Resolve one JSX prop in source order. A later explicit literal overrides an
+ * earlier spread, while a later spread or dynamic expression makes the final
+ * runtime value unknowable. This mirrors JSX object-spread semantics.
+ */
+function literalMdxProp(element, name, source) {
+  let result = null;
+  for (const attribute of element.attributes ?? []) {
+    if (attribute.type === 'mdxJsxExpressionAttribute') {
+      result = null;
+      continue;
+    }
+    if (
+      attribute.type !== 'mdxJsxAttribute' ||
+      typeof attribute.name !== 'string' ||
+      attribute.name.toLowerCase() !== name
+    ) {
+      continue;
+    }
+    result = literalMdxAttribute(attribute, source);
+  }
+  return result;
+}
+
+function htmlSourceFromRanges(source, ranges) {
+  const chars = new Array(source.length);
+  for (let i = 0; i < source.length; i += 1) {
+    chars[i] = source[i] === '\n' || source[i] === '\r' ? source[i] : ' ';
+  }
+  for (const [start, end] of ranges) {
+    for (let i = start; i < end; i += 1) chars[i] = source[i];
+  }
+  return chars.join('');
+}
+
+function collectParsedHtmlTargets(source, ranges, add) {
+  if (ranges.length === 0) return;
+  const htmlSource = htmlSourceFromRanges(source, ranges);
+  const tree = parseFragment(htmlSource, { sourceCodeLocationInfo: true });
+
+  const visit = (node, insideCode = false) => {
+    const tagName = typeof node.tagName === 'string' ? node.tagName.toLowerCase() : null;
+    const inCodeContainer = insideCode || tagName === 'pre' || tagName === 'code';
+
+    if (tagName && !inCodeContainer) {
+      for (const attribute of node.attrs ?? []) {
+        const name = attribute.name.toLowerCase();
+        if (name !== 'href' && name !== 'src') continue;
+        const location = node.sourceCodeLocation?.attrs?.[attribute.name];
+        const start = location?.startOffset ?? node.sourceCodeLocation?.startOffset ?? 0;
+        const end = location?.endOffset ?? start;
+        add(attribute.value, attributeValueOffset(source, start, end), `${name} attribute`);
+      }
+    }
+
+    for (const child of node.childNodes ?? []) visit(child, inCodeContainer);
+    if (node.content) visit(node.content, inCodeContainer);
+  };
+
+  visit(tree);
+}
+
+function formatFrom(options) {
+  const format = typeof options === 'string' ? options : options?.format ?? 'mdx';
+  if (format !== 'md' && format !== 'mdx') {
+    throw new TypeError(`authored link parser format must be "md" or "mdx" (got ${JSON.stringify(format)})`);
+  }
+  return format;
+}
+
+/**
+ * Return every statically knowable authored Markdown/HTML/MDX href/src target.
+ * Result indices use the original source's UTF-16 offsets and are intended for
+ * file/line diagnostics; decoded targets need not occur verbatim at that index.
+ */
+export function findAuthoredTargets(content, options = {}) {
+  if (typeof content !== 'string') throw new TypeError('authored link content must be a string');
+  const format = formatFrom(options);
+  const math = typeof options === 'object' && options?.math === true;
+  const source = blankFrontmatter(content);
+  const tree = processorFor(format, math).parse(source);
+  const targets = [];
+  const seen = new Set();
+  const rawHtmlRanges = [];
+  const referencedIdentifiers = new Set();
+  const definitions = new Map();
+
+  const add = (target, index, kind) => {
+    if (typeof target !== 'string') return;
+    const value = target.trim();
+    const key = `${index}:${kind}:${value}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    targets.push({ target: value, index, kind });
+  };
+
+  const visit = (node) => {
+    if (!node || typeof node !== 'object') return;
+
+    if (node.type === 'link' || node.type === 'image') {
+      const kind = node.type === 'image' ? 'Markdown image destination' : 'Markdown link destination';
+      add(node.url, markdownDestinationOffset(node, source), kind);
+    }
+
+    if (
+      (node.type === 'linkReference' || node.type === 'imageReference') &&
+      typeof node.identifier === 'string'
+    ) {
+      referencedIdentifiers.add(node.identifier);
+    }
+
+    if (node.type === 'definition' && typeof node.identifier === 'string') {
+      // CommonMark resolves duplicate labels to the first definition.
+      if (!definitions.has(node.identifier)) definitions.set(node.identifier, node);
+    }
+
+    if (node.type === 'html') {
+      const start = positionStart(node);
+      rawHtmlRanges.push([start, node.position?.end?.offset ?? start]);
+      return;
+    }
+
+    if (node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement') {
+      const name = typeof node.name === 'string' ? node.name : '';
+      if (name === 'pre' || name === 'code') return;
+      for (const attributeName of ['href', 'src']) {
+        const literal = literalMdxProp(node, attributeName, source);
+        if (literal) add(literal.target, literal.index, `${attributeName} attribute`);
+      }
+    }
+
+    // Code nodes contain source text but no rendered links. MDX expressions and
+    // ESM nodes are also opaque unless they are a parsed JSX attribute above.
+    if (
+      node.type === 'code' ||
+      node.type === 'inlineCode' ||
+      node.type === 'mdxFlowExpression' ||
+      node.type === 'mdxTextExpression' ||
+      node.type === 'mdxjsEsm'
+    ) {
+      return;
+    }
+
+    for (const child of node.children ?? []) visit(child);
+  };
+
+  visit(tree);
+  for (const identifier of referencedIdentifiers) {
+    const definition = definitions.get(identifier);
+    if (definition) {
+      add(
+        definition.url,
+        markdownDestinationOffset(definition, source),
+        'Markdown reference destination',
+      );
+    }
+  }
+  if (format === 'md') collectParsedHtmlTargets(source, rawHtmlRanges, add);
+  return targets.sort((a, b) => a.index - b.index);
+}
+
+/** Find only literal targets that browser-resolve outside `base`. */
+export function findEscapingAuthoredTargets(content, base, options = {}) {
+  if (normalizeAstroBase(base) === '/') return [];
+  return findAuthoredTargets(content, options).filter(({ target }) =>
+    rootTargetEscapesBase(target, base),
+  );
+}

package/scripts/resolve-book-config.mjs

@@ -8,6 +8,7 @@ export const DEFAULT_TOOLING_CONFIG = Object.freeze({
   siblingBooks: Object.freeze({}),
   chapterRoute: '/chapters/:id/',
   bookField: 'book',
+  base: '/',
   integrationFound: false,
 });
 
@@ -56,6 +57,17 @@ function resolveNonEmptyString(value, fallback, field, configPath) {
   return value;
 }
 
+function resolveBase(value, configPath) {
+  if (value == null || value === '') return '/';
+  if (typeof value !== 'string') {
+    throw new Error(
+      `book-scaffold tooling: ${configPath} resolved invalid Astro base ` +
+        `${JSON.stringify(value)}; expected a string.`,
+    );
+  }
+  return value;
+}
+
 function resolveSiblingBooks(value, configPath) {
   if (value == null) return {};
   if (typeof value !== 'object' || Array.isArray(value)) {
@@ -135,15 +147,16 @@ export async function loadResolvedBookConfig(projectRoot = process.cwd()) {
   const integrations = Array.isArray(loaded.config?.integrations)
     ? loaded.config.integrations.flat(Infinity)
     : [];
+  const base = resolveBase(loaded.config?.base, configPath);
   const integration = integrations.find((candidate) => candidate?.name === 'book-scaffold-astro');
-  if (!integration) return { ...DEFAULT_TOOLING_CONFIG };
+  if (!integration) return { ...DEFAULT_TOOLING_CONFIG, base };
 
   const metadata = integration.__bookScaffoldResolvedConfig;
   if (!metadata) {
     // A config can contain an older scaffold integration with no metadata.
     // Preserve the historical numbering default rather than treating upgrade
     // sequencing as a config error.
-    return { ...DEFAULT_TOOLING_CONFIG, integrationFound: true };
+    return { ...DEFAULT_TOOLING_CONFIG, base, integrationFound: true };
   }
 
   const numberStyle = metadata.numberStyle ?? 'shared';
@@ -165,6 +178,7 @@ export async function loadResolvedBookConfig(projectRoot = process.cwd()) {
       'bookField',
       configPath,
     ),
+    base,
     integrationFound: true,
   };
 }

package/scripts/validate.mjs

@@ -25,6 +25,8 @@
  *   9. Learning-objective anchors (#130) — when a chapter declares frontmatter
  *      `los:` entries with `anchor:` slugs, the declared set and the prose's
  *      MDX anchor-comment marker set must agree in both directions.
+ *  10. Authored root-absolute href/src targets (#190) — under a non-root Astro
+ *      base, literal Markdown, HTML, and JSX targets must stay inside that base.
  *
  * Run from the consumer's project root. Closes #8 (was resolving paths
  * from the package's own directory inside node_modules — false negatives
@@ -35,25 +37,33 @@
  *   book-scaffold validate --preset academic
  *   BOOK_REPO_ROOT=/abs/path npx book-scaffold validate
  *
- * Exit code = total failure count (0 = pass, >=1 = errors).
+ * Exit code = total failure count capped at 255 (0 = pass, >=1 = errors).
  */
 import { readFile, access } from 'node:fs/promises';
 import { existsSync, readFileSync } from 'node:fs';
-import { resolve, dirname, join } from 'node:path';
+import { resolve, dirname, extname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { unified } from 'unified';
 import remarkParse from 'remark-parse';
+import remarkMath from 'remark-math';
 import remarkMdx from 'remark-mdx';
 import { walkMdx, readChaptersBase, readBookSchemaConfig } from './walk-mdx.mjs';
 import { readEnvFile } from './read-env.mjs';
 import { loadResolvedBookConfig } from './resolve-book-config.mjs';
+import {
+  findAuthoredTargets,
+  normalizeAstroBase,
+  rootTargetEscapesBase,
+  rootTargetPathname,
+  suggestBaseContainedTarget,
+} from './authored-links.mjs';
 
 // --help / -h: non-mutating (closes #14).
 const USAGE = `Usage: book-scaffold validate [--preset <name>]
 
 Pre-flight content validator. Checks Cite keys, XRef ids, Figure srcs,
-internal markdown links, and (when BOOK_REPO_ROOT is set) CodeRef paths.
+internal authored links, and (when BOOK_REPO_ROOT is set) CodeRef paths.
 
 Options:
   --preset <name>    academic | tools | minimal | course-notes | research-portfolio
@@ -65,7 +75,7 @@ Env:
   BOOK_PROFILE       Backward-compat alias for BOOK_PRESET.
   BOOK_REPO_ROOT     Absolute path to a sibling code repo for CodeRef checks.
 
-Exit code = total failure count.
+Exit code = total failure count, capped at 255 so failures never wrap to success.
 `;
 
 if (process.argv.includes('--help') || process.argv.includes('-h')) {
@@ -143,6 +153,7 @@ if (!PRESET_CANDIDATE) {
 }
 // Alias kept for downstream message text only; the resolution above is canonical.
 const PROFILE = PRESET;
+const MATH_ENABLED = PROFILE === 'academic' || PROFILE === 'research-portfolio';
 const REPO_ROOT = process.env.BOOK_REPO_ROOT ?? null;
 
 // v4.6.0 (issue #76 Layer 3b): chapter-route shadow warning. Detect a
@@ -303,12 +314,11 @@ const validTopLevelRoutes = new Set([
   '/', '/chapters/', '/references/', '/search/', '/print/', '/convergence/',
 ]);
 
-// ===== Pattern helpers (regex-based; cheap, good enough for MDX) =====
+// ===== Pattern helpers for component-specific checks =====
 const RE_CITE = /<Cite[^>]+key=["']([^"']+)["']/g;
 const RE_XREF = /<XRef[^>]+id=["']([^"']+)["']/g;
 const RE_FIGURE = /<Figure[^>]+src=["']([^"']+)["']/g;
 const RE_CODEREF = /<CodeRef[^>]+path=["']([^"']+)["'](?:[^>]*line=\{(\d+)\})?(?:[^>]*lineEnd=\{(\d+)\})?/g;
-const RE_MD_LINK = /\[(?:[^\]]*)\]\((\/[^)\s#]+)(?:#[^)]*)?\)/g;
 // #121: a <Theorem> opening tag — capture its attributes to assert a
 // resolvable kind= (or legacy type=) is present.
 const RE_THEOREM = /<Theorem\b([^>]*)>/g;
@@ -316,6 +326,7 @@ const RE_THEOREM = /<Theorem\b([^>]*)>/g;
 // regex stops at `>` inside a quoted value or expression and can mistake text
 // inside another prop for a real book=/to= assignment.
 const mdxParser = unified().use(remarkParse).use(remarkMdx);
+if (MATH_ENABLED) mdxParser.use(remarkMath);
 
 async function fileExists(p) {
   try {
@@ -330,6 +341,62 @@ function lineOf(content, idx) {
   return content.slice(0, idx).split('\n').length;
 }
 
+const ASTRO_BASE = normalizeAstroBase(TOOLING_CONFIG.base);
+
+function authoredFormat(file) {
+  return extname(file).toLowerCase() === '.md' ? 'md' : 'mdx';
+}
+
+function collectAuthoredTargets(file, content) {
+  try {
+    return findAuthoredTargets(content, {
+      format: authoredFormat(file),
+      math: MATH_ENABLED,
+    });
+  } catch (error) {
+    const line = error?.line ?? error?.place?.start?.line ?? error?.position?.start?.line ?? 1;
+    const detail = String(error?.reason ?? error?.message ?? error).split('\n')[0];
+    fail(file, line, `Could not parse authored links as ${authoredFormat(file).toUpperCase()}: ${detail}`);
+    return [];
+  }
+}
+
+function validateAuthoredTargets(file, content, targets) {
+  for (const violation of targets) {
+    if (!rootTargetEscapesBase(violation.target, ASTRO_BASE)) continue;
+    const suggested = suggestBaseContainedTarget(violation.target, ASTRO_BASE);
+    fail(
+      file,
+      lineOf(content, violation.index),
+      `Authored ${violation.kind} ${JSON.stringify(violation.target)} escapes configured Astro base ` +
+        `${JSON.stringify(ASTRO_BASE)}. Use ${JSON.stringify(suggested)}, ` +
+        'import.meta.env.BASE_URL in JSX, or a base-aware component. ' +
+        'Validation does not rewrite authored URLs (#190).',
+    );
+  }
+}
+
+function validateInternalMarkdownLinks(file, content, targets) {
+  for (const authored of targets) {
+    if (authored.kind !== 'Markdown link destination') continue;
+    const pathname = rootTargetPathname(authored.target);
+    if (pathname === null) continue;
+    const baseRelativeTarget =
+      ASTRO_BASE !== '/' && (pathname === ASTRO_BASE || pathname.startsWith(`${ASTRO_BASE}/`))
+        ? pathname.slice(ASTRO_BASE.length) || '/'
+        : pathname;
+    const target = baseRelativeTarget.replace(/\/$/, '') || '/';
+    if (validTopLevelRoutes.has(`${target}/`) || validTopLevelRoutes.has(target)) continue;
+    const chMatch = target.match(/^\/chapters\/(.+)$/);
+    if (chMatch && validSlugs.has(chMatch[1])) continue;
+    warn(
+      file,
+      lineOf(content, authored.index),
+      `Internal link ${JSON.stringify(authored.target)} — target may not resolve (check spelling or route)`,
+    );
+  }
+}
+
 /**
  * Return a statically knowable n= value. Quoted strings and braced
  * string/numeric literals are safe to compare; identifiers, calls,
@@ -441,6 +508,13 @@ function siblingTargetCandidates(index, fragment) {
 for (const rel of chapterFiles) {
   const abs = join(CHAPTERS_DIR, rel);
   const content = await readFile(abs, 'utf8');
+  const authoredTargets = collectAuthoredTargets(rel, content);
+
+  // 10. Root-absolute authored targets under a non-root Astro base (#190).
+  //     Structural parsing covers Markdown link/image destinations, HTML
+  //     href/src, and decoded static JSX strings while excluding code examples.
+  validateAuthoredTargets(rel, content, authoredTargets);
+
   let bookLinks = [];
   if (content.includes('<BookLink')) {
     try {
@@ -477,14 +551,9 @@ for (const rel of chapterFiles) {
     }
   }
 
-  // 4. Internal markdown links resolve
-  for (const m of content.matchAll(RE_MD_LINK)) {
-    const target = m[1].replace(/\/$/, '');
-    if (validTopLevelRoutes.has(target + '/') || validTopLevelRoutes.has(target)) continue;
-    const chMatch = target.match(/^\/chapters\/(.+)$/);
-    if (chMatch && validSlugs.has(chMatch[1])) continue;
-    warn(rel, lineOf(content, m.index), `Internal link "${m[1]}" — target may not resolve (check spelling or route)`);
-  }
+  // 4. Internal Markdown links resolve. Reuse the structural authored-target
+  //    traversal so code examples and comments cannot create false warnings.
+  validateInternalMarkdownLinks(rel, content, authoredTargets);
 
   // 5. CodeRef path + line bounds (only when BOOK_REPO_ROOT set)
   if (REPO_ROOT) {
@@ -773,6 +842,11 @@ let questionsChecked = 0;
       const front = fm ? fm[1] : '';
       const qrel = `questions/${rel}`;
 
+      // Questions do not run the legacy link-resolution advisory, so keep the
+      // #190 root-base contract fully inert by parsing only for a non-root base.
+      const authoredTargets = ASTRO_BASE === '/' ? [] : collectAuthoredTargets(qrel, content);
+      validateAuthoredTargets(qrel, content, authoredTargets);
+
       const idMatch = front.match(/^id\s*:\s*["']?([^"'\n]+?)["']?\s*$/m);
       if (idMatch) {
         const id = idMatch[1].trim();
@@ -848,4 +922,4 @@ console.error(
     `(profile=${PROFILE}, number-style=${TOOLING_CONFIG.numberStyle}):`,
 );
 errors.forEach((e) => console.error(format(e)));
-process.exit(errors.length);
+process.exit(Math.min(errors.length, 255));