@brandon_m_behring/book-scaffold-astro 4.26.3 → 4.27.1

package/scripts/build-labels.mjs

@@ -12,14 +12,15 @@
  *
  * Kind-aware (#126): a `<Theorem kind="proposition">` resolves its display
  * WORD through the shared theorem-label vocabulary (`Proposition 8.1`), not a
- * kind-blind `Theorem 8.1`. The theorem family shares one counter (keyed by
- * the JSX component, as amsthm shares its counter), so numbers are unchanged.
+ * kind-blind `Theorem 8.1`. v4.27.0 (#175) lets defineBookConfig / defineStyle
+ * select shared (the historical default) or independent per-kind counters.
  *
  * The resulting map is consumed by XRef.astro via
  * `import.meta.glob('/src/data/labels.json', { eager: true })`.
  *
- * Per-chapter, per-type counter: each chapter resets the counter, so two
- * chapters can both have `Theorem 1` without colliding. The chapter
+ * Per-chapter counters: each chapter resets the sequence, so two chapters can
+ * both have `Theorem 1` without colliding. Labelable component families always
+ * have independent counters; theorem kinds share or split per numberStyle. The chapter
  * number comes from frontmatter:
  *   - tools profile: `chapter` field (number).
  *   - academic profile: `week` field (number).
@@ -46,6 +47,7 @@
 import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
 import { resolve, relative, join, basename, dirname } from 'node:path';
 import { readChaptersBase } from './walk-mdx.mjs';
+import { loadResolvedBookConfig } from './resolve-book-config.mjs';
 // #126: reuse the ONE kind vocabulary (theorem-label.ts → its own lean tsup
 // entry) so a <Theorem kind="proposition"> xref reads "Proposition N.M", not a
 // kind-blind "Theorem N.M" — and so an unknown/absent kind FAILS HERE (same
@@ -66,6 +68,9 @@ Env:
 
 Options:
   --help, -h          Print this message and exit (non-mutating).
+
+Numbering is read from defineBookConfig / defineStyle numberStyle. It defaults
+to shared when no scaffold integration can be resolved.
 `;
 
 if (process.argv.includes('--help') || process.argv.includes('-h')) {
@@ -182,6 +187,7 @@ async function walkChapters(dir) {
 
 async function main() {
   const cwd = process.cwd();
+  const { numberStyle } = await loadResolvedBookConfig(cwd);
   const chaptersDir = resolve(cwd, CHAPTERS_DIR);
   const files = await walkChapters(chaptersDir);
 
@@ -207,10 +213,6 @@ async function main() {
       const id = extractAttr(attrs, 'id');
       if (!id) continue;
 
-      // One shared counter per component (keyed by the JSX name, NOT the
-      // amsthm kind) — so theorem/proposition/lemma share a sequence exactly
-      // as they do under amsthm, and existing numbers never shift (#126).
-      counters[componentName] = (counters[componentName] ?? 0) + 1;
       foundInChapter += 1;
       totalIds += 1;
 
@@ -224,13 +226,16 @@ async function main() {
       // "no kind=" rather than the misleading kind="null".
       const labelOverride = extractAttr(attrs, 'label');
       let word;
+      let theoremKind;
       if (labelOverride == null) {
         if (componentName === 'Theorem') {
           try {
-            word = theoremLabel({
+            const resolvedLabel = theoremLabel({
               kind: extractAttr(attrs, 'kind') ?? undefined,
               type: extractAttr(attrs, 'type') ?? undefined,
-            }).fullLabel;
+            });
+            word = resolvedLabel.fullLabel;
+            theoremKind = resolvedLabel.kind;
           } catch (err) {
             throw new Error(
               `<Theorem id="${id}"> in ${relative(cwd, file)}: ${err.message}`,
@@ -241,13 +246,25 @@ async function main() {
         }
       }
 
+      // label= is a custom, unnumbered display and therefore does not consume
+      // either the historical shared sequence or a per-kind sequence. This
+      // keeps later auto-numbered entries stable when prose-only labels move.
+      const counterKey =
+        numberStyle === 'per-kind' && componentName === 'Theorem'
+          ? `Theorem/${theoremKind}`
+          : componentName;
+      if (labelOverride == null) {
+        counters[counterKey] = (counters[counterKey] ?? 0) + 1;
+      }
+
       // The bare counter string the heading reuses: Theorem.astro reads
       // `number` by id and renders it, so heading == xref by construction.
       // A `label=` override opts out of auto-numbering → number is null.
-      const number =
-        chapterNum != null
-          ? `${chapterNum}.${counters[componentName]}`
-          : String(counters[componentName]);
+      const number = labelOverride != null
+        ? null
+        : chapterNum != null
+          ? `${chapterNum}.${counters[counterKey]}`
+          : String(counters[counterKey]);
       const display = labelOverride ?? `${word} ${number}`;
 
       if (labels[id]) {
@@ -263,7 +280,7 @@ async function main() {
         // labels.json serves any deploy base (root or path-proxied series).
         href: `chapters/${slug}#${id}`,
         display,
-        number: labelOverride ? null : number,
+        number,
       };
     }
 
@@ -281,7 +298,7 @@ async function main() {
   process.stdout.write(
     `build-labels: ${totalIds} id${totalIds === 1 ? '' : 's'} across ` +
       `${chaptersWithIds} chapter${chaptersWithIds === 1 ? '' : 's'} → ` +
-      `${OUTPUT_PATH}\n`,
+      `${OUTPUT_PATH} (number-style=${numberStyle})\n`,
   );
 }
 

package/scripts/read-env.mjs

@@ -0,0 +1,25 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+/** Read a small dotenv-style file without mutating process.env. */
+export function readEnvFile(projectRoot = process.cwd()) {
+  try {
+    const out = {};
+    const source = readFileSync(resolve(projectRoot, '.env'), 'utf8');
+    for (const line of source.split(/\r?\n/)) {
+      const match = line.match(/^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*?)\s*$/);
+      if (!match) continue;
+      let value = match[2] ?? '';
+      if (
+        (value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))
+      ) {
+        value = value.slice(1, -1);
+      }
+      out[match[1]] = value;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}

package/scripts/resolve-book-config.mjs

@@ -0,0 +1,96 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfigFromFile } from 'vite';
+
+export const DEFAULT_TOOLING_CONFIG = Object.freeze({
+  preset: null,
+  numberStyle: 'shared',
+  integrationFound: false,
+});
+
+const ASTRO_CONFIG_NAMES = [
+  'astro.config.mjs',
+  'astro.config.ts',
+  'astro.config.js',
+  'astro.config.cjs',
+];
+const PRESETS = ['academic', 'tools', 'minimal', 'course-notes', 'research-portfolio'];
+
+function findAstroConfig(projectRoot) {
+  for (const name of ASTRO_CONFIG_NAMES) {
+    const path = resolve(projectRoot, name);
+    if (existsSync(path)) return path;
+  }
+  return null;
+}
+
+function assertNumberStyle(value, configPath) {
+  if (value !== 'shared' && value !== 'per-kind') {
+    throw new Error(
+      `book-scaffold tooling: ${configPath} resolved invalid numberStyle ` +
+        `${JSON.stringify(value)}; expected shared | per-kind.`,
+    );
+  }
+}
+
+function assertPreset(value, configPath) {
+  if (value != null && !PRESETS.includes(value)) {
+    throw new Error(
+      `book-scaffold tooling: ${configPath} resolved invalid preset ` +
+        `${JSON.stringify(value)}; expected ${PRESETS.join(' | ')}.`,
+    );
+  }
+}
+
+/**
+ * Evaluate the consumer's actual Astro config and read the scaffold
+ * integration's internal resolved metadata. Absence of a config/integration is
+ * a supported legacy shape and preserves shared numbering. Evaluation errors
+ * are deliberately not swallowed: tooling must not silently use wrong config.
+ */
+export async function loadResolvedBookConfig(projectRoot = process.cwd()) {
+  const configPath = findAstroConfig(projectRoot);
+  if (!configPath) return { ...DEFAULT_TOOLING_CONFIG };
+
+  let loaded;
+  try {
+    loaded = await loadConfigFromFile(
+      { command: 'build', mode: 'production', isSsrBuild: true, isPreview: false },
+      configPath,
+      projectRoot,
+      'silent',
+    );
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`book-scaffold tooling: failed to evaluate ${configPath}: ${detail}`, {
+      cause: error,
+    });
+  }
+
+  if (!loaded) {
+    throw new Error(`book-scaffold tooling: Vite did not return config for ${configPath}.`);
+  }
+
+  const integrations = Array.isArray(loaded.config?.integrations)
+    ? loaded.config.integrations.flat(Infinity)
+    : [];
+  const integration = integrations.find((candidate) => candidate?.name === 'book-scaffold-astro');
+  if (!integration) return { ...DEFAULT_TOOLING_CONFIG };
+
+  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 };
+  }
+
+  const numberStyle = metadata.numberStyle ?? 'shared';
+  assertNumberStyle(numberStyle, configPath);
+  assertPreset(metadata.preset, configPath);
+  return {
+    preset: metadata.preset ?? null,
+    numberStyle,
+    integrationFound: true,
+  };
+}

package/scripts/validate.mjs

@@ -14,7 +14,8 @@
  *   5. <CodeRef path="..." line={N} /> — when BOOK_REPO_ROOT set,
  *      path exists + line in bounds.
  *   6. <Theorem> — has a resolvable kind= (or legacy type=); else it would
- *      render an empty label and throw at build (#121).
+ *      render an empty label and throw at build (#121). An id'd theorem must
+ *      resolve in labels.json, and a literal n= must agree with that index.
  *   7. <BookLink book="…" to="…"> (#96) — both props present, and book= is a
  *      key in the consumer's siblingBooks registry (best-effort).
  *   8. Questions collection (#112) — each question's frontmatter `domain` is a
@@ -38,38 +39,11 @@
 import { readFile, access } from 'node:fs/promises';
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
 import { walkMdx, readChaptersBase, readBookSchemaConfig } from './walk-mdx.mjs';
-
-/**
- * Best-effort .env reader. Mirrors `readEnvFile` in src/types.ts; kept inline
- * here because scripts/ is shipped as plain JS without compiling src/.
- *
- * Closes #20 — validate.mjs previously skipped the .env fallback that
- * `resolveProfileWithSource` honors, so consumers who set BOOK_PROFILE in
- * .env (per the SKILL.md and scaffold's create-book defaults) saw the CLI
- * silently default to minimal, masking academic-profile errors.
- */
-function readEnvFile(path = '.env') {
-  try {
-    if (!existsSync(path)) return {};
-    const out = {};
-    for (const line of readFileSync(path, 'utf8').split(/\r?\n/)) {
-      const m = line.match(/^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*?)\s*$/);
-      if (!m) continue;
-      let val = m[2] ?? '';
-      if (
-        (val.startsWith('"') && val.endsWith('"')) ||
-        (val.startsWith("'") && val.endsWith("'"))
-      ) {
-        val = val.slice(1, -1);
-      }
-      out[m[1]] = val;
-    }
-    return out;
-  } catch {
-    return {};
-  }
-}
+import { readEnvFile } from './read-env.mjs';
+import { loadResolvedBookConfig } from './resolve-book-config.mjs';
 
 // --help / -h: non-mutating (closes #14).
 const USAGE = `Usage: book-scaffold validate [--preset <name>]
@@ -78,8 +52,8 @@ Pre-flight content validator. Checks Cite keys, XRef ids, Figure srcs,
 internal markdown links, and (when BOOK_REPO_ROOT is set) CodeRef paths.
 
 Options:
-  --preset <name>    academic | tools | minimal | course-notes
-                     (overrides BOOK_PRESET / BOOK_PROFILE env)
+  --preset <name>    academic | tools | minimal | course-notes | research-portfolio
+                     Legacy override when no scaffold integration is resolved.
   --help, -h         Print this message and exit (non-mutating).
 
 Env:
@@ -113,12 +87,20 @@ const CHAPTERS_DIR = await readChaptersBase(ROOT);
 const PUBLIC_DIR = resolve(ROOT, 'public');
 const DATA_DIR = resolve(ROOT, 'src/data');
 
-// Preset resolution (matches resolvePreset in src/types.ts):
-//   --preset flag > BOOK_PRESET env > BOOK_PROFILE env >
+let TOOLING_CONFIG;
+try {
+  TOOLING_CONFIG = await loadResolvedBookConfig(ROOT);
+} catch (error) {
+  process.stderr.write(`validate: fatal: ${error?.message ?? error}\n`);
+  process.exit(1);
+}
+
+// Preset resolution:
+//   composed Astro-config preset > --preset flag > BOOK_PRESET env > BOOK_PROFILE env >
 //   .env BOOK_PRESET > .env BOOK_PROFILE >
 //   defineBookSchemas({ preset }) in content.config.ts >
 //   defineBookSchemas({ profile }) in content.config.ts (alias) >
-//   'minimal'.
+//   warned v4 compatibility fallback 'minimal'.
 // .env fallback closes #20 — without it, consumers who set BOOK_PROFILE in
 // .env (the documented convenience in SKILL.md + create-book defaults) saw
 // the CLI silently default to minimal, hiding academic-profile errors.
@@ -126,16 +108,35 @@ const DATA_DIR = resolve(ROOT, 'src/data');
 // canonical v4.5+ defineBookSchemas({ preset, chaptersBase }) form had the
 // CLI silently default to minimal, hiding research-portfolio (and any
 // non-env-set) profile errors while astro build applied the correct settings.
-const dotenv = readEnvFile(resolve(ROOT, '.env'));
+const dotenv = readEnvFile(ROOT);
 const schemaConfig = await readBookSchemaConfig(ROOT);
-const PRESET =
+const PRESET_CANDIDATE =
+  TOOLING_CONFIG.preset ??
   presetFromFlag ??
   process.env.BOOK_PRESET ??
   process.env.BOOK_PROFILE ??
   dotenv.BOOK_PRESET ??
   dotenv.BOOK_PROFILE ??
-  schemaConfig.preset ??
-  'minimal';
+  schemaConfig.preset;
+const PRESETS = ['academic', 'tools', 'minimal', 'course-notes', 'research-portfolio'];
+if (presetFlagIdx >= 0 && !presetFromFlag) {
+  process.stderr.write('validate: --preset requires a value.\n');
+  process.exit(2);
+}
+if (PRESET_CANDIDATE && !PRESETS.includes(PRESET_CANDIDATE)) {
+  process.stderr.write(
+    `validate: preset must be one of ${PRESETS.join(' | ')} ` +
+      `(got ${JSON.stringify(PRESET_CANDIDATE)}).\n`,
+  );
+  process.exit(1);
+}
+const PRESET = PRESET_CANDIDATE ?? 'minimal';
+if (!PRESET_CANDIDATE) {
+  process.stderr.write(
+    "validate: no preset resolved; falling back to 'minimal' for v4 compatibility. " +
+      'This fallback will be removed in v5; configure a built-in style or BOOK_PRESET.\n',
+  );
+}
 // Alias kept for downstream message text only; the resolution above is canonical.
 const PROFILE = PRESET;
 const REPO_ROOT = process.env.BOOK_REPO_ROOT ?? null;
@@ -213,6 +214,37 @@ const warnings = [];
 const fail = (file, line, msg) => errors.push({ file, line, msg });
 const warn = (file, line, msg) => warnings.push({ file, line, msg });
 
+// ===== Self-heal missing generated artifacts (#186) =====
+// These files are intentionally gitignored. Direct `book-scaffold validate`
+// bypasses npm's prevalidate lifecycle, so rebuild each missing artifact before
+// loading it. Existing files remain untouched; child diagnostics and failures
+// are propagated verbatim instead of becoming downstream unknown-id noise.
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+function regenerate(scriptName, artifact) {
+  process.stdout.write(`validate: ${artifact} is missing — regenerating via ${scriptName} (#186)\n`);
+  const result = spawnSync(process.execPath, [join(scriptDir, scriptName)], {
+    cwd: ROOT,
+    env: process.env,
+    encoding: 'utf8',
+  });
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  if (result.error || result.status !== 0) {
+    const detail = result.error ? `: ${result.error.message}` : '';
+    process.stderr.write(
+      `validate: ${scriptName} failed (exit ${result.status ?? 1})${detail} — cannot self-heal.\n`,
+    );
+    process.exit(result.status ?? 1);
+  }
+}
+
+if (!existsSync(join(DATA_DIR, 'labels.json'))) {
+  regenerate('build-labels.mjs', 'src/data/labels.json');
+}
+if (!existsSync(join(DATA_DIR, 'references.json'))) {
+  regenerate('build-bib.mjs', 'src/data/references.json');
+}
+
 // ===== Load reference data (graceful when missing) =====
 async function loadJson(path) {
   try {
@@ -267,6 +299,29 @@ function lineOf(content, idx) {
   return content.slice(0, idx).split('\n').length;
 }
 
+/**
+ * Return a statically knowable n= value. Quoted strings and braced
+ * string/numeric literals are safe to compare; identifiers, calls,
+ * interpolation, and all other expressions are deliberately skipped.
+ */
+function literalTheoremNumber(attrs) {
+  const quoted = attrs.match(/\bn\s*=\s*(["'])(.*?)\1/);
+  if (quoted) return quoted[2];
+
+  const braced = attrs.match(/\bn\s*=\s*\{\s*([^}]*?)\s*\}/);
+  if (!braced) return null;
+  const expression = braced[1].trim();
+  const stringLiteral = expression.match(/^(["'`])([\s\S]*)\1$/);
+  if (stringLiteral) {
+    if (stringLiteral[1] === '`' && stringLiteral[2].includes('${')) return null;
+    return stringLiteral[2];
+  }
+  if (/^[+-]?(?:\d+(?:\.\d+)?|\.\d+)$/.test(expression)) {
+    return String(Number(expression));
+  }
+  return null;
+}
+
 // #96: best-effort siblingBooks registry keys from astro.config.mjs, so the
 // <BookLink> check can flag an unknown book= earlier than the component's
 // build-time throw. null = couldn't determine → membership not checked (the
@@ -359,13 +414,33 @@ for (const rel of chapterFiles) {
       );
     }
     const thmId = attrs.match(/\bid=["']([^"']+)["']/);
-    if (thmId && !/\blabel\s*=\s*["']/.test(attrs) && !labels[thmId[1]]) {
+    const hasLabelOverride = /\blabel\s*=/.test(attrs);
+    if (thmId && !hasLabelOverride && !labels[thmId[1]]) {
       fail(
         rel,
         lineOf(content, m.index),
         `<Theorem id="${thmId[1]}"> — not in labels.json; heading silently renders unnumbered. Run build:labels, or fix the id.`,
       );
     }
+    // #176: compare only literal n= values. Dynamic expressions cannot be
+    // evaluated reliably by this intentionally regex-based validator, and a
+    // label= override explicitly opts out of labels.json auto-numbering.
+    const explicitNumber = hasLabelOverride ? null : literalTheoremNumber(attrs);
+    const indexedNumber = thmId ? labels[thmId[1]]?.number : null;
+    if (
+      thmId &&
+      explicitNumber !== null &&
+      indexedNumber != null &&
+      explicitNumber !== String(indexedNumber)
+    ) {
+      fail(
+        rel,
+        lineOf(content, m.index),
+        `<Theorem id="${thmId[1]}" n="${explicitNumber}"> — labels.json numbers it ` +
+          `${indexedNumber}, and the rendered heading + every XRef use the index. ` +
+          'Drop the stale n= (auto-numbering wins) or re-run build:labels.',
+      );
+    }
   }
 
   // 7. BookLink (#96): structural (book= + to=) + best-effort registry membership.
@@ -544,46 +619,6 @@ let questionsChecked = 0;
   }
 }
 
-// ===== v4.6.0 (issue #77): missing-prereq re-framing =====
-//
-// When errors are downstream symptoms of a missing artifact (references.json
-// or labels.json), abort with ONE leading error pointing at the prereq
-// instead of printing 25 "Unknown bibkey" / "Unknown XRef" symptoms. Single
-// clean signal: fix the prereq. Per D12 of the v4.6.0 plan.
-{
-  if (PROFILE === 'academic') {
-    const refsPath = join(DATA_DIR, 'references.json');
-    const hasBibkeyErrors = errors.some((e) => /Unknown bibkey/.test(e.msg));
-    if (hasBibkeyErrors && !existsSync(refsPath)) {
-      console.error(
-        `\n✗ Validate cannot run: src/data/references.json is missing.\n\n` +
-          `This file is generated from bibliography.bib by 'npm run build:bib'.\n` +
-          `Run that first, OR adopt the prevalidate npm hook convention so\n` +
-          `'npm run validate' regenerates it automatically:\n\n` +
-          `  "prevalidate": "npm run build:bib && npm run build:labels --if-present"\n` +
-          `  "validate": "book-scaffold validate"\n\n` +
-          `See package/recipes/19-prevalidate-hook.md.\n`,
-      );
-      process.exit(1);
-    }
-  }
-  const labelsPath = join(DATA_DIR, 'labels.json');
-  // #126: also collapse <Theorem id> not-in-labels errors (they share the
-  // "not in labels.json" phrase) under the same missing-prereq message.
-  const hasXrefErrors = errors.some((e) => /not in labels\.json/.test(e.msg));
-  if (hasXrefErrors && !existsSync(labelsPath)) {
-    console.error(
-      `\n✗ Validate cannot run: src/data/labels.json is missing.\n\n` +
-        `This file is generated from <Theorem id="..."> and <Figure id="..."> markers\n` +
-        `in chapter MDX by 'npm run build:labels'. Run that first, OR adopt the\n` +
-        `prevalidate npm hook convention so 'npm run validate' regenerates it:\n\n` +
-        `  "prevalidate": "npm run build:bib && npm run build:labels --if-present"\n\n` +
-        `See package/recipes/19-prevalidate-hook.md.\n`,
-    );
-    process.exit(1);
-  }
-}
-
 // ===== Report =====
 const format = ({ file, line, msg }) => `  ${file}:${line}  ${msg}`;
 if (warnings.length > 0) {
@@ -592,9 +627,15 @@ if (warnings.length > 0) {
 }
 if (errors.length === 0) {
   const qNote = questionsChecked > 0 ? ` + ${questionsChecked} question(s)` : '';
-  console.log(`validate: ✓ ${chapterFiles.length} chapter(s)${qNote} checked (profile=${PROFILE}); no errors.`);
+  console.log(
+    `validate: ✓ ${chapterFiles.length} chapter(s)${qNote} checked ` +
+      `(profile=${PROFILE}, number-style=${TOOLING_CONFIG.numberStyle}); no errors.`,
+  );
   process.exit(0);
 }
-console.error(`validate: ✗ ${errors.length} error(s) in ${chapterFiles.length} chapter(s) (profile=${PROFILE}):`);
+console.error(
+  `validate: ✗ ${errors.length} error(s) in ${chapterFiles.length} chapter(s) ` +
+    `(profile=${PROFILE}, number-style=${TOOLING_CONFIG.numberStyle}):`,
+);
 errors.forEach((e) => console.error(format(e)));
 process.exit(errors.length);

package/src/lib/define-style.ts

@@ -27,7 +27,12 @@
  * for migration from the v3 `preset:` shorthand.
  */
 import type { AstroIntegration, AstroUserConfig } from 'astro';
-import type { BookPreset, ReleaseStatusConfig, RouteToggles } from '../types.js';
+import type {
+  BookPreset,
+  NumberStyle,
+  ReleaseStatusConfig,
+  RouteToggles,
+} from '../types.js';
 
 // ===== Branded nominal type =====
 
@@ -90,6 +95,9 @@ export interface Style {
   /** Profile that backs this style — determines schema + default routes + styles + KaTeX wiring. */
   readonly preset?: BookPreset;
 
+  /** Theorem-family numbering strategy; shallow override (last wins). */
+  readonly numberStyle?: NumberStyle;
+
   /** Book's deployed origin (sitemap, canonical, Pagefind). Required at composition end;
    *  optional inside a Style (so styles can omit it and consumers can provide per-book). */
   readonly site?: string;
@@ -118,10 +126,10 @@ export interface Style {
    *  scalar fields override. */
   readonly markdown?: AstroUserConfig['markdown'];
 
-  /** Deploy target — drives create-book's wrangler.toml shape.
-   *  - `'workers'`: Cloudflare Workers + Static Assets (default for academic/tools/minimal)
-   *  - `'pages'`: Cloudflare Pages (default for research-portfolio/course-notes)
-   *  Closes #50. */
+  /** Reserved legacy metadata. It is composed but has no runtime or
+   *  create-book effect: create-book chooses wrangler.toml from its CLI
+   *  preset before a consumer Style exists (#180).
+   *  @deprecated Inert in v4; scheduled for removal in v5. */
   readonly deploy?: 'pages' | 'workers';
   /**
    * v4.26.2 (#149; style inheritance fixed in v4.26.3): release-state
@@ -199,7 +207,7 @@ export function defineStyle(opts: StyleInput): Style {
  *   - Top-level `defineBookConfig` fields beat any style (handled in config.ts)
  *
  * Per-key merge strategy:
- *   - `preset`, `site`, `deploy`, `mdxComponentsModule`, `name`, `releaseStatus`
+ *   - `preset`, `numberStyle`, `site`, `deploy`, `mdxComponentsModule`, `name`, `releaseStatus`
  *     → shallow override (last defined wins; `releaseStatus: false` suppresses)
  *   - `routes` → per-route spread (each route key independently overridable)
  *   - `katexMacros` → per-macro spread (each macro key independently overridable)
@@ -221,6 +229,7 @@ export function composeStyles(styles: readonly Style[]): Style {
     // Shallow override for primitives + readonly-scalar fields.
     if (style.name !== undefined) merged.name = style.name;
     if (style.preset !== undefined) merged.preset = style.preset;
+    if (style.numberStyle !== undefined) merged.numberStyle = style.numberStyle;
     if (style.site !== undefined) merged.site = style.site;
     if (style.deploy !== undefined) merged.deploy = style.deploy;
     if (style.releaseStatus !== undefined) {

package/src/lib/nav-href.ts

@@ -29,11 +29,33 @@ export interface ChapterLike {
   data: Record<string, unknown>;
 }
 
-/** Normalize a base URL to exactly one trailing slash (`''` → `'/'`). */
-function normBase(baseUrl: string): string {
+/**
+ * Normalize a base URL to exactly one trailing slash (`''`/`undefined` → `'/'`).
+ *
+ * v4.27.0 (#182): promoted from this module's private helper to THE shared
+ * normalizer — 18 `.astro` files previously inlined the same normalization in
+ * three regex idioms. Astro does not guarantee a trailing slash on `base`
+ * (`'/foo'` is a documented form), so every `import.meta.env.BASE_URL` read
+ * must pass through here before href composition: `${normalizeBase(...)}chapters/`.
+ * Takes the base as a PARAMETER because src/lib ships pre-compiled in dist/,
+ * where Vite's import.meta.env replacement cannot reach (see exam-manifest.ts).
+ */
+export function normalizeBase(baseUrl: string | undefined): string {
   return (baseUrl || '/').replace(/\/*$/, '/');
 }
 
+/**
+ * The composing variant (#182): strip ALL trailing slashes (`'/'` → `''`,
+ * `'/foo/'` → `'/foo'`) for `${baseNoSlash(...)}/answers`-style templates
+ * where the literal supplies the slash (Rationale.astro's route detection).
+ */
+export function baseNoSlash(baseUrl: string | undefined): string {
+  return (baseUrl || '/').replace(/\/+$/, '');
+}
+
+/** Internal alias for the pre-#182 name. */
+const normBase = normalizeBase;
+
 /** Replace `:book` / `:slug` / `:route` / `:id` tokens; `\b` keeps each token
  *  whole, so order is irrelevant and `:id` never matches inside `:identifier`. */
 function fillTokens(pattern: string, tokens: Record<string, string>): string {

package/styles/layout.css

@@ -4,10 +4,10 @@
  *
  * 1. Page chrome at very top: theme toggle (top-right, position: fixed).
  *
- * 2. Optional left sidebar (Sidebar.astro). At ≥64rem (1024px), grid
- *    pins it to the left edge; below 1024px it's hidden (mobile pages
- *    don't carry the nav). Toggle per-page via Base.astro's `showSidebar`
- *    prop — default true; the landing page sets false.
+ * 2. Optional left sidebar (Sidebar.astro). At ≥80rem (1280px), grid
+ *    pins it to the left edge; below 1280px it's hidden and the mobile
+ *    nav drawer is the chapter nav (v4.26.0, #80). Toggle per-page via
+ *    Base.astro's `showSidebar` prop — default true; landing sets false.
  *
  * 3. Main content (.prose) — Tufte 2-column with sidenotes in right
  *    margin on desktop (≥48rem), inline on mobile (<48rem). See
@@ -225,15 +225,21 @@
 }
 
 /* ===== Mobile/tablet nav drawer (v4.26.0, #80) =====
- * Below the sidebar breakpoint (64rem) the left Sidebar is display:none — this
+ * Below the sidebar breakpoint (80rem — matching .layout-with-sidebar above and
+ * the controller's desktop auto-close) the left Sidebar is display:none — this
  * is the navigation in that range: a hamburger in the chrome row toggles a
  * slide-in drawer reusing NavContent (the same book-scoped nav source as the
  * sidebar). No-JS baseline: `:target` opens it (the toggle is <a href="#nav-drawer">);
  * the inline controller in Base.astro enhances it with focus-trap + ESC + body
- * scroll-lock. Hidden at ≥64rem, where the persistent sidebar is the nav. The
- * ≥64rem gutter-fit (sidenote/section-map overflow) is a separate fix. */
+ * scroll-lock. Hidden at ≥80rem, where the persistent sidebar is the nav. The
+ * ≥64rem gutter tier (sidenote/section-map floats) is a separate, lower breakpoint. */
 @media (min-width: 80rem) {
-  .nav-toggle,
+  /* #183: `.chrome-buttons .nav-toggle` (0,2,0), not bare `.nav-toggle` —
+   * Base.astro's global `.chrome-button { display: inline-flex }` ties a
+   * (0,1,0) selector and wins on cascade order, leaving the hamburger
+   * visible at desktop where it opens an invisible drawer and strands the
+   * body scroll-lock. Caught by drawer-interaction.spec.ts. */
+  .chrome-buttons .nav-toggle,
   .nav-drawer {
     display: none;
   }