@brandon_m_behring/book-scaffold-astro 4.29.0 → 4.31.0

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/build-figures.mjs

@@ -25,21 +25,22 @@
  *
  * v4.11.0 (closes #84): each generated SVG gets a post-export rewrite
  * (recolorSvg) that injects role="img" + a CSS-variable theming layer so one
- * SVG serves light + dark. Neutral fills/strokes are remapped to
- * var(--diagram-ink|paper|grid, <original>) via injected attribute-selector
- * rules (the original attribute stays as the fallback); saturated accent colors
- * are left untouched. A `%! no-theme` line in the source .tex opts a figure out.
+ * SVG serves light + dark. Known Warm–Tol semantic and Okabe–Ito categorical
+ * colors are mapped to var(--fig-*|--series-*, <original>); neutral paints map
+ * to var(--diagram-ink|paper|grid, <original>). Unknown saturated colors stay
+ * authored. A `%! no-theme` line in the source .tex opts a figure out.
  * <Figure> inlines local SVGs so they track the in-page [data-theme] toggle.
  *
  * Idempotent: skips when the target SVG is newer than the source PDF (and the
  * recolor itself is a no-op on an already-themed SVG, so re-runs after an
  * upgrade safely theme pre-existing figures).
- * Run on `prebuild` so Astro always sees fresh figures.
+ * Run explicitly with `npm run build:figures`; optional system tools keep this
+ * authoring pipeline out of the generated project's `prebuild` hook.
  *
  * Graceful skip: when pdftocairo / pdftoppm aren't on PATH (e.g. Cloudflare
  * build container), the script warns and exits 0. Committed SVGs/PNGs under
- * public/figures/ are served as-is. Local devs with poppler-utils regenerate
- * from PDFs on every `npm run dev`.
+ * public/figures/ are served as-is. Local authors with poppler-utils regenerate
+ * from PDFs when source figures change.
  */
 import { readdir, stat, mkdir } from 'node:fs/promises';
 import { existsSync, statSync, readFileSync, writeFileSync } from 'node:fs';
@@ -56,8 +57,10 @@ Figure pipeline. PDF -> SVG via pdftocairo (PNG fallback via pdftoppm at
 Graceful-skip if pdftocairo / pdftoppm not on PATH.
 
 Each SVG is rewritten to be accessible + dark-mode-aware: role="img" plus
-var(--diagram-ink|paper|grid, orig) fills (a "%! no-theme" line in the
-source .tex opts out). <Figure> inlines local SVGs so they track the theme.
+exact Warm–Tol/Okabe–Ito palette mappings and neutral
+var(--diagram-ink|paper|grid, orig) mappings. Use base color + separate opacity,
+not a pre-blended tint. A "%! no-theme" line in the source .tex opts out.
+<Figure> inlines local SVGs so they track the theme.
 
 Env:
   BOOK_FIGURES_PATH   Override figures source (default: figures/).
@@ -202,7 +205,7 @@ const NO_THEME_RE = /^\s*%!\s*no-theme\b/m;
 /**
  * v4.11.0 (#84): apply the theming rewrite to a generated SVG in place.
  * No-op (returns false) if the file is absent or recolorSvg leaves it unchanged
- * (already themed / nothing neutral to remap). Idempotent.
+ * (already themed / nothing themeable to remap). Idempotent.
  */
 function themeIfSvg(svgPath, optOut) {
   if (!existsSync(svgPath)) return false;

package/scripts/render-notebooks.mjs

@@ -16,7 +16,8 @@
  * canonical; the notebook is a code companion.
  *
  * Idempotent: skips when the target HTML is newer than the source .ipynb.
- * Run on `prebuild` so Astro always sees fresh notebook HTML.
+ * Run explicitly with `npm run build:notebooks`; optional system tools keep
+ * this authoring pipeline out of the generated project's `prebuild` hook.
  *
  * Style scoping: nbconvert's `basic` template emits HTML without nbviewer
  * chrome, but with embedded <style> tags. To prevent CSS bleed, each

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/sync-figure-tokens.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/** Regenerate or verify the manifest-owned block in styles/tokens.css. */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import {
+  FIGURE_TOKEN_BLOCK_END,
+  FIGURE_TOKEN_BLOCK_START,
+  renderFigureTokenCssBlock,
+} from '../src/lib/figure-palette.mjs';
+
+const TOKENS_PATH = fileURLToPath(new URL('../styles/tokens.css', import.meta.url));
+const args = new Set(process.argv.slice(2));
+const write = args.has('--write');
+if (args.size > 1 || (args.size === 1 && !write && !args.has('--check'))) {
+  console.error('Usage: node scripts/sync-figure-tokens.mjs [--check|--write]');
+  process.exit(2);
+}
+
+const css = readFileSync(TOKENS_PATH, 'utf8');
+const start = css.indexOf(FIGURE_TOKEN_BLOCK_START);
+const endStart = css.indexOf(FIGURE_TOKEN_BLOCK_END, start);
+if (start < 0 || endStart < 0) {
+  throw new Error('tokens.css is missing the generated figure-token block markers.');
+}
+const end = endStart + FIGURE_TOKEN_BLOCK_END.length;
+const expected = renderFigureTokenCssBlock();
+const actual = css.slice(start, end);
+
+if (write) {
+  if (actual === expected) {
+    console.log('sync-figure-tokens: tokens.css already current');
+  } else {
+    writeFileSync(TOKENS_PATH, css.slice(0, start) + expected + css.slice(end), 'utf8');
+    console.log('sync-figure-tokens: updated styles/tokens.css');
+  }
+} else if (actual !== expected) {
+  console.error(
+    'sync-figure-tokens: styles/tokens.css drifted from src/lib/figure-palette.mjs; ' +
+    'run npm run sync:figure-tokens --workspace package',
+  );
+  process.exit(1);
+} else {
+  console.log('sync-figure-tokens: tokens.css matches the palette manifest');
+}

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